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 exec 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 | NICE | 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 (exec), 3 (transition)
  35 @item Niceness @tab
  36     unsigned integer @tab
  37     1-255, preferred packet @ref{Niceness, niceness} level
  38 @item Path length @tab
  39     unsigned integer @tab
  40     actual length of @emph{path} field's payload
  41 @item Path @tab
  42     255 byte, fixed length opaque data @tab
  43     @itemize
  44     @item UTF-8 encoded destination path for file transfer
  45     @item UTF-8 encoded source path for file request
  46     @item UTF-8 encoded, zero byte separated, exec's arguments
  47     @item Node's id the transition packet must be relayed on
  48     @end itemize
  49 @end multitable
  50
  51 Path has fixed size because of hiding its actual length -- it is
  52 valuable metadata. Payload is appended to the header -- it is not stored
  53 as XDR field, because most XDR libraries will store all that data in the
  54 memory.
  55
  56 Depending on the packet's type, payload could store:
  57
  58 @itemize
  59 @item File contents
  60 @item Destination path for freq
  61 @item @url{http://zlib.net/, zlib} compressed exec body
  62 @item Whole encrypted packet we need to relay on
  63 @end itemize
  64
  65 Also depending on packet's type, niceness level means:
  66
  67 @itemize
  68 @item Preferable niceness level for files sent by freq
  69 @item @env{NNCP_NICE} variable's value passed during @ref{CfgExec} invocation.
  70 @end itemize
  71
  72 @node Encrypted
  73 @section Encrypted packet
  74
  75 Encrypted packets are the only files found in spools, in exchangeable
  76 storages and that are synchronized between TCP daemons.
  77
  78 Each encrypted packet has the following header:
  79
  80 @verbatim
  81   +------------ HEADER --------------------+   +-------- ENCRYPTED --------+
  82  /                                          \ /                             \
  83 +--------------------------------------------+------------+----...-----------+------+
  84 | MAGIC | NICE | SENDER | RCPT | EPUB | SIGN | SIZE | MAC | CIPHERTEXT | MAC | JUNK |
  85 +-------------------------------------/------\------------+----...-----------+------+
  86                                      /        \
  87                       +-------------------------------------+
  88                       | MAGIC | NICE | SENDER | RCPT | EPUB |
  89                       +-------------------------------------+
  90 @end verbatim
  91
  92 @multitable @columnfractions 0.2 0.3 0.5
  93 @headitem @tab XDR type @tab Value
  94 @item Magic number @tab
  95     8-byte, fixed length opaque data @tab
  96     @verb{|N N C P E 0x00 0x00 0x03|}
  97 @item Niceness @tab
  98     unsigned integer @tab
  99     1-255, packet @ref{Niceness, niceness} level
 100 @item Sender @tab
 101     32-byte, fixed length opaque data @tab
 102     Sender node's id
 103 @item Recipient @tab
 104     32-byte, fixed length opaque data @tab
 105     Recipient node's id
 106 @item Exchange public key @tab
 107     32-byte, fixed length opaque data @tab
 108     Ephemeral curve25519 public key
 109 @item Signature @tab
 110     64-byte, fixed length opaque data @tab
 111     ed25519 signature for that packet's header
 112 @end multitable
 113
 114 Signature is calculated over all previous fields.
 115
 116 All following encryption is done using @url{https://cr.yp.to/chacha.html,
 117 ChaCha20} algorithm. Data is splitted on 128 KiB blocks. Each block is
 118 encrypted with increasing nonce counter. @url{https://blake2.net/,
 119 BLAKE2b-256} MAC is appended to the ciphertext.
 120
 121 After the headers comes an encrypted payload size and MAC of that size.
 122
 123 @multitable @columnfractions 0.2 0.3 0.5
 124 @headitem @tab XDR type @tab Value
 125 @item Size @tab
 126     unsigned hyper integer @tab
 127     Payload size.
 128 @end multitable
 129
 130 Next comes the actual encrypted payload with corresponding MAC.
 131
 132 Each node has static @strong{exchange} and @strong{signature} keypairs.
 133 When node A want to send encrypted packet to node B, it:
 134
 135 @enumerate
 136 @item generates ephemeral @url{http://cr.yp.to/ecdh.html, curve25519} keypair
 137 @item prepares structure for signing
 138 @item signs that structure using private
 139     @url{http://ed25519.cr.yp.to/, ed25519} signature key
 140 @item takes remote node's exchange public key and performs
 141     Diffie-Hellman computation on this remote static public key and
 142     private ephemeral one
 143 @item derive the keys:
 144     @enumerate
 145     @item initialize @url{https://blake2.net/, BLAKE2Xb} XOF with
 146     derived ephemeral key and 224-byte output length
 147     @item feed @verb{|N N C P E 0x00 0x00 0x03|} magic number to XOF
 148     @item read 32-bytes of "size" encryption key (for ChaCha20)
 149     @item read 64-bytes of "size" authentication key (for BLAKE2b-MAC)
 150     @item read 32-bytes of payload encryption key
 151     @item read 64-bytes of payload authentication key
 152     @item optionally read 32-bytes pad generation key (for ChaCha20)
 153     @end enumerate
 154 @item encrypts size, appends its ciphertext to the header
 155 @item appends MAC tag over that ciphertext
 156 @item encrypts and appends payload ciphertext
 157 @item appends MAC tag over that payload ciphertext
 158 @item possibly appends any kind of "junk" noise data to hide real
 159     payload's size from the adversary
 160 @end enumerate