VFER SECURITY LAYER (VSL) SPECIFICATION

Handshake

The handshake establishes a shared secret between server and client. This secret is used in the key generation phase to generate session keys which are then used for encryption and verification of messages. The shared secret is generated using random data and has a length of VSL_KEYLEN bytes.

The following methods are available to share the secret:

SSH Starting Mode

• the client connects to the server host using ssh and starts the server process. Path of the executable and neccessary arguments have to be supplied to the client API function.

• The client generates the shared secret and writes it into stdin of the ssh and thereby also the server process.

The message has the following format:

struct ssh_msg_secret {
    char magic[P_MAGIC_SIZE];
    unsigned char secret[VSL_KEYLEN];
};

magic is a char array describing the protocoll version and has to be set to VSL1 (not zero terminated).

• The server process reads the key, initializes a vfer socket to listen on a free port and prints the port number to stdout.

The message has the following format:

struct ssh_msg_port {
    char magic[P_MAGIC_SIZE];
    uint32_t port;
};

magic is a char array describing the protocoll version and has to be set to VSL1 (not zero terminated). port is in network byte order.

• The client reads the port number from the ssh connection and initiates a vfer connection to the port.

• When the server has accepted the connection, it daemonizes so that the ssh connection is closed.

• The client waits for the ssh connection to close.

• Server and client generate session keys from the shared secret and set up VSL sockets using the VFER connection as the transport layer.

Note:

To prevent deadlocks, the server must not try to write anything to stderr or stdout before it has read the shared secret from stdin.

The server process has to exit with one of the following return codes:

• 0 if the vfer connection was established and the fork for daemonization successfull.
• VSL_PERM if there is a permanent error
• VSL_TEMP if there is a temporary error

If the server encouters an error, it can additionally write a descriptive message of up to 512 bytes to stderr. This has to be done before daemonization.

Challenge Response Mode

In challenge response mode, the entire authentication is done over an existing vfer connection. First, a shared secret is established using Diffie-Hellman key exchange. The secure channel is then used to ask the client for a username and a password. The login data is then checked by the server using a function supplied by the application developer.

Session Key Generation

The session keys are generated from the shared secret. There are 4 different session keys derived for each VSL connection:

• An authentication key to send packets from server to client. This key is generated as SHA256(secret || "SRVAUT"), where secret is the the shared secret.

• An authentication key to send packets from server to client. This key is generated as SHA256(secret || "CLTAUT"), where secret is the the shared secret.

• An encryption key to send packets from server to client. This key is generated as MD5(secret || "SRVENC"), where secret is the the shared secret.

• An encryption key to send packets from client to server. This key is generated as MD5(secret || "CLTENC"), where secret is the the shared secret.

a || b means that a and b are concatenated. All the strings are not \0 terminated.

Packet Encryption

Each VSL packet has a header with the structure:

typedef struct phead_t {
    uint64_t msgnr;             //!< Packet number
    unsigned char hash[VSL_MACLEN];      //!< MAC
    char magic[P_MAGIC_SIZE];   //!< Packet header prefix
    char type;                  //!< Packet type
    uint32_t datalen;           //!< Length of payload data
} phead_t;

followed by datalen bytes of data. VSL packets are send as VFER datagrams. All integer values are in network byte order.

Sending a Data Packet

If a message msg is to be send, the procedure is as follows:

• a packet is created containing the described header followed by msg.
• magic is set to "VSL1" (not \0 terminated)
• type is set to P_DATA
• datalen is set to the length of msg. The maximum length is 2^30 bytes (1 GB) (due to the used Poly1305 MAC algorithm) or the maximum size of a vfer frame, whatever value is smaller.
• hash is set to a string of 0 bytes.
• msgnr is set to the number of the last sent message plus 1 (for each VSL connection, both client and server store the numbers of the last received and last sent message). If msgnr overflows, no more messages can be send.
• the body of the packet (length datalen), is encrypted using AES-128 in CTR mode. The initial (128 bit) counter is set to msgnr << 64. The used key is the encryption key (either for server to client or client to server messages)
• hash is set to the MAC calculated by Poly1305-AES (http://cr.yp.to/mac.html) from (key, packet). key is the authentication key (either for client to server or for server to client packets) and packet is the complete packet, including hash itself, which is still set to 0.
• the packet is send using the underlying VFER connection.

Receiving a Data Packet

If a packet pkg has been received, the procedure to obtain the message msg is as follows (the packet is dropped if any of the assertions fail):

• the packet is split into the described packet header and the message msg. Splitting can always be done since the header has a fixed size.
• assert: magic is set to "VSL1" (not \0 terminated)
• assert: type is set to P_DATA
• assert: msgnr is larger than the number of the last message received (for each VSL connection, both client and server store the numbers of the last received and last sent message).
• hash is copied to hash_o. In the packet, hash is then set to 0.
• assert: hash_o is identical to Poly1305-AES(key, packet) (see http://cr.yp.to/mac.html). key is the authentication key (either for client to server or for server to client packets) and packet is the complete packet, where hash has been set to 0.
• the packet body, is decrypted using AES-128 in CTR mode. The initial (128 bit) counter is set to msgnr << 64. The used key is the encryption key (either for server to client or client to server messages)
• the message msg is returned.

---