doc/pkt.texi

   1 @node Packet
   2 @unnumbered Packet format
   3
   4 All packets are
   5 @url{https://tools.ietf.org/html/rfc4506, XDR}-encoded structures.
   6
   7 @menu
   8 * Plain packet: Plain.
   9 * Encrypted packet: Encrypted.
  10 @end menu
  11
  12 @node Plain
  13 @section Plain packet
  14
  15 Plain packet contains either the whole file, or file request (freq), or
  16 transition packet or email message. It is called "plain", because it
  17 contains plaintext, but plain packets would never be stored on your hard
  18 drive.
  19
  20 @verbatim
  21             HEADER
  22 +-------------------------------+--...---+
  23 | MAGIC | TYPE | PATHLEN | PATH | PAYLOAD|
  24 +-------------------------------+--...---+
  25 @end verbatim
  26
  27 @multitable @columnfractions 0.2 0.3 0.5
  28 @headitem @tab XDR type @tab Value
  29 @item Magic number @tab
  30     8-byte, fixed length opaque data @tab
  31     @verb{|N N C P P 0x00 0x00 0x01|}
  32 @item Payload type @tab
  33     unsigned integer @tab
  34     0 (file), 1 (freq), 2 (mail), 3 (transition)
  35 @item Path length @tab
  36     unsigned integer @tab
  37     actual length of @emph{path} field's payload
  38 @item Path @tab
  39     255 byte, fixed length opaque data @tab
  40     @itemize
  41     @item UTF-8 encoded destination path for file transfer
  42     @item UTF-8 encoded source path for file request
  43     @item UTF-8 encoded, space separated, email recipients list
  44     @item Node's id the transition packet must be relayed on
  45     @end itemize
  46 @end multitable
  47
  48 Path has fixed size because of hiding its actual length -- it is
  49 valuable metadata. Payload is appended to the header -- it is not stored
  50 as XDR field, because most XDR libraries will store all that data in the
  51 memory.
  52
  53 Depending on the packet's type, payload could store:
  54
  55 @itemize
  56 @item File contents
  57 @item Destination path for freq
  58 @item @url{http://zlib.net/, zlib} compressed email
  59 @item Whole encrypted packet we need to relay on
  60 @end itemize
  61
  62 @node Encrypted
  63 @section Encrypted packet
  64
  65 Encrypted packets are the only files found in spools, in exchangeable
  66 storages and that are synchronized between TCP daemons.
  67
  68 Each encrypted packet has the following header:
  69
  70 @verbatim
  71   +------------ HEADER -------------+   +-------- ENCRYPTED --------+
  72  /                                   \ /                             \
  73 +--------------------------------------------+------------+----...-----------+------+
  74 | MAGIC | NICE | SENDER | RCPT | EPUB | SIGN | SIZE | MAC | CIPHERTEXT | MAC | JUNK |
  75 +-------------------------------------/------\------------+----...-----------+------+
  76                                      /        \
  77                       +-------------------------------------+
  78                       | MAGIC | NICE | SENDER | RCPT | EPUB |
  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     @verb{|N N C P E 0x00 0x00 0x01|}
  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 Recipient @tab
  94     32-byte, fixed length opaque data @tab
  95     Recipient node's id
  96 @item Exchange public key @tab
  97     32-byte, fixed length opaque data @tab
  98     Ephemeral curve25519 public key
  99 @item Signature @tab
 100     64-byte, fixed length opaque data @tab
 101     ed25519 signature for that packet's header
 102 @end multitable
 103
 104 Signature is calculated over all previous fields.
 105
 106 All following encryption is done using
 107 @url{https://www.schneier.com/academic/twofish/, Twofish} algorithm with
 108 256-bit key in
 109 @url{https://en.wikipedia.org/wiki/Counter_mode#Counter_.28CTR.29, CTR}
 110 mode of operation with zero initialization vector (because each
 111 encrypted packet has ephemeral exchange key). @url{https://blake2.net/,
 112 BLAKE2b-256} MAC is appended to the ciphertext.
 113
 114 After the headers comes an encrypted payload size and MAC of that size.
 115
 116 @multitable @columnfractions 0.2 0.3 0.5
 117 @headitem @tab XDR type @tab Value
 118 @item Size @tab
 119     unsigned hyper integer @tab
 120     Payload size.
 121 @end multitable
 122
 123 Next comes the actual encrypted payload with corresponding MAC.
 124
 125 Each node has static @strong{exchange} and @strong{signature} keypairs.
 126 When node A want to send encrypted packet to node B, it:
 127
 128 @enumerate
 129 @item generates ephemeral @url{http://cr.yp.to/ecdh.html, curve25519} keypair
 130 @item prepares structure for signing
 131 @item signs that structure using private
 132     @url{http://ed25519.cr.yp.to/, 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
 135     private ephemeral one
 136 @item derived ephemeral key is used as an input to
 137     @url{https://en.wikipedia.org/wiki/HKDF, HKDF}-BLAKE2b-256 KDF
 138 @item derives four session keys using
 139     @url{https://en.wikipedia.org/wiki/HKDF, HKDF}-BLAKE2b-256 KDF:
 140     @enumerate
 141     @item "Size" encryption (for Twofish) key
 142     @item "Size" authentication (for BLAKE2b-MAC) key
 143     @item Payload encryption key
 144     @item Payload authentication key
 145     @end enumerate
 146 @item encrypts size, appends its ciphertext to the header
 147 @item appends MAC tag over that ciphertext
 148 @item encrypts and appends payload ciphertext
 149 @item appends MAC tag over that payload ciphertext
 150 @item possibly appends any kind of "junk" noise data to hide real
 151     payload's size from the adversary
 152 @end enumerate