src/vsl.h

Go to the documentation of this file.

/*
 * Copyright 2006, Internet2
 * Legal conditions are in file LICENSE
 * (MD5 = c434f2e53b8089d8b4d0172c7ce07360).
 */

/**
 * @file   vsl.h
 * @author Nikolaus Rath
 * @brief  Common headers for the VSL API
 *
 **/


#ifndef VSL_H
#define VSL_H

#include "vsl_api.h"
#include <stdio.h>
#include <stdbool.h>
#include <stdlib.h>
#include <string.h>

//! Log message
#define LOG(...) do { if (debug != NULL) { \
                     fprintf(debug, "[ %-15s ] ", __func__); \
                     fprintf(debug, __VA_ARGS__); \
                     fprintf(debug, "\n"); \
                     fflush(debug); \
                 } } while (false)

//! Log failure and return from function, preserving errno
#define LOGFAIL(ERR, ...) do { \
    int err = errno; \
    LOG(__VA_ARGS__); \
    errno = err; \
    return (ERR); \
} while (false)


//! Internal error in library code, log and abort
#define LOGFATAL(...) do { \
    if (debug == NULL) \
        debug = stderr; \
        fprintf(debug, "internal error in %s, %s line %d:\n", __func__, __FILE__, __LINE__); \
        fprintf(debug, __VA_ARGS__); \
        fprintf(debug, "\n"); \
        fflush(debug); \
        abort(); \
    } while (false)

//! Call function, escalate a nonzero return value
#define TRY(S)   do { int ret; if ( (ret = (S)) != 0 ) return ret; } while (false)

//! \brief To print VSL Keys in hex
/** Usage: \code printf(KEY_STR, KEY_VEC); \endcode */
#define KEY_STR       "%.2hhX%.2hhX-%.2hhX%.2hhX-%.2hhX%.2hhX-%.2hhX%.2hhX-" \
                      "%.2hhX%.2hhX-%.2hhX%.2hhX-%.2hhX%.2hhX-%.2hhX%.2hhX"

//! \brief To print VSL Keys in hex
/** Usage: \code printf(KEY_STR, KEY_VEC); \endcode */
#define KEY_VEC(K) \
   (K)[0], (K)[1], (K)[2], (K)[3], (K)[4], (K)[5], (K)[6], (K)[7], \
   (K)[8], (K)[9], (K)[10], (K)[11], (K)[12], (K)[13], (K)[14], (K)[15]


/*
 * VSL packet types:
 */
//! VSL data packet
#define P_DATA        0x00


/**
 * Magic bytes in the VSL packet header
 **/
//! Length of the magic VSL packet header prefix
#define P_MAGIC_SIZE 4
//! Fill a VSL packet header prefix
#define FILL_MAGIC(X) do { (X)[0] = 'V'; (X)[1] = 'S'; (X)[2] = 'L'; (X)[3] = '1'; } while(0)
//! Check a VSL packet header prefix
#define CHECK_MAGIC(X) ((X)[0] == 'V' && (X)[1] == 'S' && (X)[2] == 'L' && (X)[3] == '1')

//! VSL Connection Status
/**
 * Lower 5 bits indicate whether the socket is
 * waiting for a specific pending event
 **/
typedef enum {
    C_WAIT_FD_R=1,
    C_WAIT_FD_W=2,
    C_WAIT_VFD_R=4,
    C_WAIT_VFD_W=8,
    C_WAIT_PID=16,
    C_INITIALIZED = (1 << 5),
    C_ESTABLISHED = (2 << 5),
    C_SSH_FORKED = (3 << 5),
    C_SSH_WROTE_SEC = (4 << 5),
    C_SSH_VF_CON = (5 << 5),
} connstat_t;

//! Get precise status
#define CONSTAT(X)   (X >> 5) << 5

//! Get pending event
#define CONWAIT(X)   (X & 0x1F)

//! VSL packet header
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;

//! Size of the packet header without aligning
#define PHEAD_SIZE (sizeof(uint64_t)+\
                    VSL_MACLEN+\
                    P_MAGIC_SIZE+\
                    sizeof(char)+\
                    sizeof(uint32_t))



#endif


/**
 * \page vsl VFER SECURITY LAYER (VSL) SPECIFICATION
 *
 *
 * \section handshake 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:
 *
 * \subsection sshm 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:
 *   \dontinclude vsl_ssh.c
 *   \skip struct ssh_msg_secret
 *   \until }
 *   \a magic is a char array describing the protocoll version and has
 *   to be set to \c 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:
 *   \dontinclude vsl_ssh.c
 *   \skip struct ssh_msg_port
 *   \until }
 *   \a magic is a char array describing the protocoll version and has
 *   to be set to \c VSL1 (not zero terminated). \a 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.
 *
 * \subsection cr 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.
 *
 * \section keygen 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(\a secret || "SRVAUT"), where \a
 *   secret is the the shared secret.
 *
 * - An authentication key to send packets from server to client. This
 *   key is generated as SHA256(\a secret || "CLTAUT"), where \a
 *   secret is the the shared secret.
 *
 * - An encryption key to send packets from server to client. This
 *   key is generated as MD5(\a secret || "SRVENC"), where \a
 *   secret is the the shared secret.
 *
 * - An encryption key to send packets from client to server. This
 *   key is generated as MD5(\a secret || "CLTENC"), where \a
 *   secret is the the shared secret.
 *
 * \a a || \a b means that \a a and \a b are concatenated. All the
 * strings are \b not \c @\0 terminated.
 *
 * \section enc Packet Encryption
 *
 * Each VSL packet has a header with the structure:
 * \dontinclude vsl.h
 * \skip phead_t
 * \until }
 * followed by \a datalen bytes of data. VSL packets are send as
 * VFER datagrams. All integer values are in network byte order.
 *
 * \subsection send Sending a Data Packet
 *
 * If a message \a msg is to be send, the procedure is as follows:
 * - a packet is created containing the described header followed
 *   by \a msg.
 * - \a magic is set to \c "VSL1" (not \c @\0 terminated)
 * - \a type is set to #P_DATA
 * - \a datalen is set to the length of \a 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.
 * - \a hash is set to a string of 0 bytes.
 * - \a 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 \a datalen), is encrypted
 *   using AES-128 in CTR mode. The initial (128 bit) counter is set
 *   to \a msgnr << 64. The used key is the encryption key (either
 *   for server to client or client to server messages)
 * - \a hash is set to the MAC calculated by Poly1305-AES
 *   (http://cr.yp.to/mac.html) from (\a key, \a packet). \a key is the
 *   authentication key (either for client to server or for server to
 *   client packets) and \a packet is the complete packet, including
 *   \a hash itself, which is still set to 0.
 * - the packet is send using the underlying VFER connection.
 *
 * \subsection recv Receiving a Data Packet
 *
 * If a packet \a pkg has been received, the procedure to obtain
 * the message \a 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 \a msg. Splitting can always be done since the header
 *   has a fixed size.
 * - assert: \a magic is set to \c "VSL1" (not \c @\0 terminated)
 * - assert: \a type is set to #P_DATA
 * - assert: \a 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).
 * - \a hash is copied to \a hash_o. In the packet, \a hash is then
 *   set to 0.
 * - assert: \a hash_o is identical to
 *   Poly1305-AES(\a key, \a packet) (see http://cr.yp.to/mac.html). \a
 *   key is the authentication key (either for client to server or for
 *   server to client packets) and \a packet is the complete packet,
 *   where \a 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 \a
 *   msgnr << 64. The used key is the encryption key (either for
 *   server to client or client to server messages)
 * - the message \a msg is returned.
 *
 **/


/*
 * Local Variables:
 * compile-command: "cd ..; make tests file_xfer"
 * compilation-search-path: ("..")
 * End:
 */

---