doc/pkt.texi

   1 @node Packet
   2 @unnumbered Packet format
   3
   4 All packets are
   5 @url{https://en.wikipedia.org/wiki/External_Data_Representation,
   6 XDR}-encoded structures.
   7
   8 @menu
   9 * Plain packet: Plain.
  10 * Encrypted packet: Encrypted.
  11 @end menu
  12
  13 @node Plain
  14 @section Plain packet
  15
  16 Plain packet contains either the whole file, or file request (freq), or
  17 transition packet or email message. It is called "plain", because it
  18 contains plaintext, but plain packets would never be stored on your hard
  19 drive.
  20
  21 @verbatim
  22             HEADER
  23 +-------------------------------+--...---+
  24 | MAGIC | TYPE | PATHLEN | PATH | PAYLOAD|
  25 +-------------------------------+--...---+
  26 @end verbatim
  27
  28 @multitable @columnfractions 0.2 0.3 0.5
  29 @headitem  @tab XDR type @tab Value
  30 @item Magic number @tab
  31     8-byte, fixed length opaque data @tab
  32     @code{NNCPP0x10x00x00}
  33 @item Payload type @tab
  34     unsigned integer @tab
  35     0 (file), 1 (freq), 2 (mail), 3 (transition)
  36 @item Path length @tab
  37     unsigned integer @tab
  38     actual length of following field's payload
  39 @item Path @tab
  40     255 byte, fixed length opaque data @tab
  41     @itemize
  42     @item UTF-8 encoded destination path for file transfer
  43     @item UTF-8 encoded source path for file request
  44     @item UTF-8 encoded, space separated, email recipients list
  45     @item Node id the transition packet must be relayed on
  46     @end itemize
  47 @end multitable
  48
  49 Path has fixed size because of hiding its actual length -- it is
  50 valuable metadata. Payload is appended to the header -- it is not stored
  51 as XDR field, because most XDR libraries will store all that data in the
  52 memory.
  53
  54 Depending on the packet's type, payload could store:
  55
  56 @itemize
  57 @item File contents
  58 @item Destination path for freq
  59 @item @url{http://zlib.net/, zlib} compressed email
  60 @item Whole encrypted packet we need to relay on
  61 @end itemize
  62
  63 @node Encrypted
  64 @section Encrypted packet
  65
  66 Encrypted packets are the only files found in spools, in exchangeable
  67 storages and that are synchronized between TCP daemons.
  68
  69 Each encrypted packet has the following header:
  70
  71 @verbatim
  72                     HEADER
  73 +--------------------------------------------+-------...--------+
  74 | MAGIC | NICE | SENDER | EPUB | SIGN | SIZE | CIPHERTEXT | MAC |
  75 +------------------------------/------\------+-------...--------+
  76                               /        \
  77              +--------------------------------------------+
  78              | MAGIC | NICE | RCPT | SENDER | EPUB | SIZE |
  79              +--------------------------------------------+
  80 @end verbatim
  81
  82 @multitable @columnfractions 0.2 0.3 0.5
  83 @headitem  @tab XDR type @tab Value
  84 @item Magic number @tab
  85     8-byte, fixed length opaque data @tab
  86     @code{NNCPE0x10x00x00}
  87 @item Niceness @tab
  88     unsigned integer @tab
  89     1-255, packet @ref{Niceness, niceness} level
  90 @item Sender @tab
  91     32-byte, fixed length opaque data @tab
  92     Sender node's id
  93 @item Exchange public key @tab
  94     32-byte, fixed length opaque data @tab
  95     Ephemeral curve25519 public key
  96 @item Signature @tab
  97     64-byte, fixed length opaque data @tab
  98     ed25519 signature for that packet's header
  99 @item Size @tab
 100     unsigned hyper integer @tab
 101     Encrypted payload size
 102 @end multitable
 103
 104 Signature is calculated over the following structure:
 105
 106 @itemize
 107 @item Magic number
 108 @item Niceness
 109 @item Recipient (32-byte recipient node's id)
 110 @item Sender
 111 @item Exchange public key
 112 @item Size
 113 @end itemize
 114
 115 Actual encrypted payload comes after that header. Payload is encrypted
 116 using @url{https://www.schneier.com/academic/twofish/, Twofish}
 117 algorithm with 256-bit key in
 118 @url{https://en.wikipedia.org/wiki/Counter_mode#Counter_.28CTR.29, CTR}
 119 mode of operation with zero initialization vector (because each
 120 encrypted packet has ephemeral exchange key). Ciphertext's length is
 121 equal to plaintext. @url{https://blake2.net/, BLAKE2b-256} MAC is
 122 appended to the ciphertext.
 123
 124 Each node has static @strong{exchange} and @strong{signature} keypairs.
 125 When node A want to send encrypted packet to node B, it:
 126
 127 @enumerate
 128 @item generates ephemeral @url{http://cr.yp.to/ecdh.html, curve25519} keypair
 129 @item prepares structure for signing (underlying payload size must be
 130 already known)
 131 @item signs that structure using private @url{http://ed25519.cr.yp.to/,
 132 ed25519} signature key
 133 @item takes remote node's exchange public key and performs
 134 Diffie-Hellman computation on this remote static public key and private
 135 ephemeral one
 136 @item derived ephemeral key used as an input to
 137 @url{https://en.wikipedia.org/wiki/HKDF, HKDF}-BLAKE2b-256 key
 138 derivation function
 139 @item two 256-bit keys are derived from it for using with Twofish and
 140 BLAKE2b-MAC functions
 141 @item Twofish encryption is performed over the plaintext and
 142 BLAKE2b-MACing is performed over the ciphertext. Ciphertext and MAC tag
 143 go after header.
 144 @end enumerate