stalk

A peer-to-peer encrypted protocol at the application layer (over TCP), using spack for structured message passing.

The purpose of this protocol is mostly for myself to learn to implement something of this type, but I will hopefully be using it for other things (academically, I don’t trust my own crypto use) as well.

Disclaimer

This is pre-alpha level. Do not use this for anything serious.

API

The API is a message-based API, so the programmer builds spack packets and those then get sent over the wire, the serialization is hidden from the programmer.

Another note on connections: this protocol is being built with the idea of using it in a key-value store in the future, as well as in conjoinment with a Kerberos-like authentication system. Therefore, if you play your cards right, you should never have to authenticate insecurely (vulnerable to mitm), but I wanted to offer the functionality.

Functions

(listener host port handler)

Listen for connections at host, on the given port.

You must pass handler, which is a function which takes one argument, a stalk:connection with which you can manage the connection.

There’s an example debug-handler in stalk.lisp to show an example of printing objects to *debug-io* as they arrive.

(connect host port &key (identity *default-identity*) server-identity)

Create a connection to host on port, attempting to connect with identity, connecting to server-identity. At project load, *default-identity* will be attempted to be loaded from /.spack/id_pub and /.spack/id_priv. If server-identity is omitted, a handshake is done without verifying the authenticity of the server.

The function returns a stalk-connection class. If the server you try to connect to’s identity does not check out, then will error out.

If identity is not provided, no authentication is done, and the handshake is thus vulnerable to MITM attacks.

Otherwise, there is a Diffie-Hellman key exchange with curve25519 signed with RSA 2048-bit that is done to authenticate the server as well as to allow for an AES-256 (OFB) channel to be opened.

Better Failure Handling

(send spack connection)

This is a message based protocol, unlike TCP, which is a bytestream-based one. To use it, create a spack object, push the objects on it you want to be delivered as a unit, and this will send them down the wire serialized and encrypted.

(flush connection)

Force the currently sent elements down the pipeline and out the socket. If you don’t do this, I don’t know if they’ll ever send (or at least not until you enqueue a ton of them up)

Classes

stalk-connection

This is the catch-all class for connections from one node to another.

Slots

• host
  • Host with which you’re communicating
• port
  • Self-explanatory
• peer-identity
  • An identity class (seen below) for the peer of the connection
• identity
  • Your identity in the connection
• socket
  • A usocket-stream-socket that you’re transmitting over
• cipher
  • The ironclad:cipher used during your connections

identity

Slots

• pubkey
  • An ironclad:public-key.
• privkey
  • Kinda self-explanatory, no?
• keysize
  • This isn’t particularly required, and I don’t believe it is exposed in the library :^)