doc/transport.texi

   1 @node Transport
   2 @section Transport protocol
   3
   4 @verbatim
   5 TAG || ENCRYPTED || NONCE <-- PACKET
   6  ^         ^          ^
   7  |         |          |
   8  |         |          +------------+
   9  |         |                       |
  10  |         +------------+          |
  11  |                      |          |
  12  +-->AUTH(AUTH_KEY, ENCRYPTED || NONCE)
  13                         ^          ^
  14                         |          |
  15 +-----------------------+          |
  16 |                                  |
  17 |                   +--------------+
  18 |                   |
  19 +--> ENCRYPT(KEY, NONCE, PAYLOAD)
  20                     ^       ^
  21                     |       |
  22                     |       +--> SIZE || DATA [|| NOISE]
  23                     |
  24                     +--> PRP(PRP_KEY, SERIAL)
  25 @end verbatim
  26
  27 @code{SERIAL} is message's serial number. Odds are reserved for
  28 client(->server) messages, evens for server(->client) messages.
  29
  30 @code{PRP} is XTEA block cipher algorithm used here as PRP (pseudo
  31 random permutation function) to obfuscate @code{SERIAL}. Plaintext
  32 @code{SERIAL} state is kept in peers internal state, but encrypted
  33 before transmission.
  34
  35 XTEA's encryption key is the first 128-bit of Salsa20's output with
  36 established common key and zero nonce (message nonces start from 1).
  37
  38 @verbatim
  39 PRP_KEY = ENCRYPT(KEY, 0, 128-bit)
  40 @end verbatim
  41
  42 @code{ENCRYPT} is Salsa20 stream cipher, with established session
  43 @code{KEY} and obfuscated @code{SERIAL} used as a nonce. 512 bit of
  44 Salsa20's output is ignored and only remaining is XORed with ther data,
  45 encrypting it.
  46
  47 @code{SIZE} is big-endian @emph{uint16} storing length of the
  48 @code{DATA}.
  49
  50 @code{NOISE} is optional. It is just some junk data, intended to fill up
  51 packet to MTU size. This is useful for concealing payload packets length.
  52
  53 @code{AUTH} is Poly1305 authentication function. First 256 bits of
  54 Salsa20's output are used as a one-time key for @code{AUTH}.
  55
  56 @verbatim
  57 AUTH_KEY = ENCRYPT(KEY, NONCE, 256 bit)
  58 @end verbatim
  59
  60 To prevent replay attacks we must remember received @code{SERIAL}s and
  61 drop when receiving duplicate ones.