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 0x03|}
  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 XDR has no ability to pass more than 4 GiB of
  54 opaque data. Moreover most XDR libraries store fields in the memory in
  55 practice.
  56
  57 Depending on the packet's type, payload could store:
  58
  59 @itemize
  60 @item File contents
  61 @item Destination path for freq
  62 @item @url{https://facebook.github.io/zstd/, Zstandard} compressed exec body
  63 @item Whole encrypted packet we need to relay on
  64 @end itemize
  65
  66 Also depending on packet's type, niceness level means:
  67
  68 @itemize
  69 @item Preferable niceness level for files sent by freq
  70 @item @env{NNCP_NICE} variable's value passed during @ref{CfgExec} invocation.
  71 @end itemize
  72
  73 @node Encrypted
  74 @section Encrypted packet
  75
  76 Encrypted packets are the only files found in spools, in exchangeable
  77 storages and that are synchronized between TCP daemons.
  78
  79 Each encrypted packet has the following header:
  80
  81 @verbatim
  82   +------------ HEADER --------------------+   +------------- ENCRYPTED -------------+
  83  /                                          \ /                                       \
  84 +--------------------------------------------+------+---------+----------...---+------+
  85 | MAGIC | NICE | SENDER | RCPT | EPUB | SIGN | SIZE | BLOCK 0 | BLOCK 1  ...   | JUNK |
  86 +-------------------------------------/------\------+---------+----------...---+------+
  87                                      /        \
  88                       +-------------------------------------+
  89                       | MAGIC | NICE | SENDER | RCPT | EPUB |
  90                       +-------------------------------------+
  91 @end verbatim
  92
  93 @multitable @columnfractions 0.2 0.3 0.5
  94 @headitem @tab XDR type @tab Value
  95 @item Magic number @tab
  96     8-byte, fixed length opaque data @tab
  97     @verb{|N N C P E 0x00 0x00 0x04|}
  98 @item Niceness @tab
  99     unsigned integer @tab
 100     1-255, packet @ref{Niceness, niceness} level
 101 @item Sender @tab
 102     32-byte, fixed length opaque data @tab
 103     Sender node's id
 104 @item Recipient @tab
 105     32-byte, fixed length opaque data @tab
 106     Recipient node's id
 107 @item Exchange public key @tab
 108     32-byte, fixed length opaque data @tab
 109     Ephemeral curve25519 public key
 110 @item Signature @tab
 111     64-byte, fixed length opaque data @tab
 112     ed25519 signature for that packet's header
 113 @end multitable
 114
 115 Signature is calculated over all previous fields.
 116
 117 All following encryption is done in AEAD mode using
 118 @url{https://cr.yp.to/chacha.html, ChaCha20}-@url{https://en.wikipedia.org/wiki/Poly1305, Poly1305}
 119 algorithms. Data is splitted on 128 KiB blocks. Each block is encrypted with
 120 increasing nonce counter.
 121
 122 Authenticated and encrypted size come after the header:
 123
 124 @multitable @columnfractions 0.2 0.3 0.5
 125 @headitem @tab XDR type @tab Value
 126 @item Size @tab
 127     unsigned hyper integer @tab
 128     Payload size.
 129 @end multitable
 130
 131 Then comes the actual payload.
 132
 133 Each node has static @strong{exchange} and @strong{signature} keypairs.
 134 When node A want to send encrypted packet to node B, it:
 135
 136 @enumerate
 137 @item generates ephemeral @url{http://cr.yp.to/ecdh.html, curve25519} keypair
 138 @item prepares structure for signing
 139 @item signs that structure using private
 140     @url{http://ed25519.cr.yp.to/, ed25519} signature key
 141 @item takes remote node's exchange public key and performs
 142     Diffie-Hellman computation on this remote static public key and
 143     private ephemeral one
 144 @item derive the keys:
 145     @enumerate
 146     @item initialize @url{https://blake2.net/, BLAKE2Xb} XOF with
 147     derived ephemeral key and 96-byte output length
 148     @item feed @verb{|N N C P E 0x00 0x00 0x04|} magic number to XOF
 149     @item read 32-bytes of "size" AEAD encryption key
 150     @item read 32-bytes of payload AEAD encryption key
 151     @item optionally read 32-bytes pad generation key
 152     @end enumerate
 153 @item encrypts size, appends its authenticated ciphertext to the header
 154 @item encrypts payload, appends its authenticated ciphertext
 155 @item possibly appends any kind of "junk" noise data to hide real
 156     payload's size from the adversary (generated using XOF with
 157     unlimited output length)
 158 @end enumerate