2 @unnumbered Packet format
5 @url{https://tools.ietf.org/html/rfc4506, XDR}-encoded structures.
9 * Encrypted packet: Encrypted.
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
22 +--------------------------------------+--...---+
23 | MAGIC | TYPE | NICE | PATHLEN | PATH | PAYLOAD|
24 +--------------------------------------+--...---+
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
34 0 (file), 1 (freq), 2 (exec), 3 (transition)
37 1-255, preferred packet @ref{Niceness, niceness} level
38 @item Path length @tab
40 actual length of @emph{path} field's payload
42 255 byte, fixed length opaque data @tab
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
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
56 Depending on the packet's type, payload could store:
60 @item Destination path for freq
61 @item @url{https://facebook.github.io/zstd/, Zstandard} compressed exec body
62 @item Whole encrypted packet we need to relay on
65 Also depending on packet's type, niceness level means:
68 @item Preferable niceness level for files sent by freq
69 @item @env{NNCP_NICE} variable's value passed during @ref{CfgExec} invocation.
73 @section Encrypted packet
75 Encrypted packets are the only files found in spools, in exchangeable
76 storages and that are synchronized between TCP daemons.
78 Each encrypted packet has the following header:
81 +------------ HEADER --------------------+ +------------- ENCRYPTED -------------+
83 +--------------------------------------------+------+---------+----------...---+------+
84 | MAGIC | NICE | SENDER | RCPT | EPUB | SIGN | SIZE | BLOCK 0 | BLOCK 1 ... | JUNK |
85 +-------------------------------------/------\------+---------+----------...---+------+
87 +-------------------------------------+
88 | MAGIC | NICE | SENDER | RCPT | EPUB |
89 +-------------------------------------+
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 0x04|}
99 1-255, packet @ref{Niceness, niceness} level
101 32-byte, fixed length opaque data @tab
104 32-byte, fixed length opaque data @tab
106 @item Exchange public key @tab
107 32-byte, fixed length opaque data @tab
108 Ephemeral curve25519 public key
110 64-byte, fixed length opaque data @tab
111 ed25519 signature for that packet's header
114 Signature is calculated over all previous fields.
116 All following encryption is done in AEAD mode using
117 @url{https://cr.yp.to/chacha.html, ChaCha20}-@url{https://en.wikipedia.org/wiki/Poly1305, Poly1305}
118 algorithms. Data is splitted on 128 KiB blocks. Each block is encrypted with
119 increasing nonce counter.
121 Authenticated and encrypted size come after the header:
123 @multitable @columnfractions 0.2 0.3 0.5
124 @headitem @tab XDR type @tab Value
126 unsigned hyper integer @tab
130 Then comes the actual payload.
132 Each node has static @strong{exchange} and @strong{signature} keypairs.
133 When node A want to send encrypted packet to node B, it:
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:
145 @item initialize @url{https://blake2.net/, BLAKE2Xb} XOF with
146 derived ephemeral key and 96-byte output length
147 @item feed @verb{|N N C P E 0x00 0x00 0x04|} magic number to XOF
148 @item read 32-bytes of "size" AEAD encryption key
149 @item read 32-bytes of payload AEAD encryption key
150 @item optionally read 32-bytes pad generation key
152 @item encrypts size, appends its authenticated ciphertext to the header
153 @item encrypts payload, appends its authenticated ciphertext
154 @item possibly appends any kind of "junk" noise data to hide real
155 payload's size from the adversary (generated using XOF with
156 unlimited output length)