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 @url{https://cr.yp.to/chacha.html,
 107 ChaCha20} algorithm. Data is splitted on 128 KiB blocks. Each block is
 108 encrypted with increasing nonce counter. @url{https://blake2.net/,
 109 BLAKE2b-256} MAC is appended to the ciphertext.
 110
 111 After the headers comes an encrypted payload size and MAC of that size.
 112
 113 @multitable @columnfractions 0.2 0.3 0.5
 114 @headitem @tab XDR type @tab Value
 115 @item Size @tab
 116     unsigned hyper integer @tab
 117     Payload size.
 118 @end multitable
 119
 120 Next comes the actual encrypted payload with corresponding MAC.
 121
 122 Each node has static @strong{exchange} and @strong{signature} keypairs.
 123 When node A want to send encrypted packet to node B, it:
 124
 125 @enumerate
 126 @item generates ephemeral @url{http://cr.yp.to/ecdh.html, curve25519} keypair
 127 @item prepares structure for signing
 128 @item signs that structure using private
 129     @url{http://ed25519.cr.yp.to/, ed25519} signature key
 130 @item takes remote node's exchange public key and performs
 131     Diffie-Hellman computation on this remote static public key and
 132     private ephemeral one
 133 @item derived ephemeral key is used as a key input to
 134     @url{https://blake2.net/, BLAKE2Xb} XOF
 135 @item derives five session keys using output from the XOF above:
 136     @enumerate
 137     @item "Size" encryption (for ChaCha20) key
 138     @item "Size" authentication (for BLAKE2b-MAC) key
 139     @item Payload encryption key
 140     @item Payload authentication key
 141     @item Optional pad generation key (for ChaCha20)
 142     @end enumerate
 143 @item encrypts size, appends its ciphertext to the header
 144 @item appends MAC tag over that ciphertext
 145 @item encrypts and appends payload ciphertext
 146 @item appends MAC tag over that payload ciphertext
 147 @item possibly appends any kind of "junk" noise data to hide real
 148     payload's size from the adversary
 149 @end enumerate