doc/pkt/encrypted.texi

   1 @node Encrypted
   2 @section Encrypted packet
   3
   4 Encrypted packets are the only files found in spools, in exchangeable
   5 storages and that are synchronized between TCP daemons.
   6
   7 Each encrypted packet has the following header:
   8
   9 @verbatim
  10   +------------ HEADER --------------------+   +------------- ENCRYPTED -------------+
  11  /                                          \ /                                       \
  12 +--------------------------------------------+------+---------+----------...---+------+
  13 | MAGIC | NICE | SENDER | RCPT | EPUB | SIGN | SIZE | BLOCK 0 | BLOCK 1  ...   | JUNK |
  14 +-------------------------------------/------\------+---------+----------...---+------+
  15                                      /        \
  16                       +-------------------------------------+
  17                       | MAGIC | NICE | SENDER | RCPT | EPUB |
  18                       +-------------------------------------+
  19 @end verbatim
  20
  21 @multitable @columnfractions 0.2 0.3 0.5
  22 @headitem @tab XDR type @tab Value
  23 @item Magic number @tab
  24     8-byte, fixed length opaque data @tab
  25     @verb{|N N C P E 0x00 0x00 0x05|}
  26 @item Niceness @tab
  27     unsigned integer @tab
  28     1-255, packet @ref{Niceness, niceness} level
  29 @item Sender @tab
  30     32-byte, fixed length opaque data @tab
  31     Sender node's id
  32 @item Recipient @tab
  33     32-byte, fixed length opaque data @tab
  34     Recipient node's id
  35 @item Exchange public key @tab
  36     32-byte, fixed length opaque data @tab
  37     Ephemeral curve25519 public key
  38 @item Signature @tab
  39     64-byte, fixed length opaque data @tab
  40     ed25519 signature for that packet's header over all previous fields.
  41 @end multitable
  42
  43 All following encryption is done in AEAD mode using
  44 @url{https://cr.yp.to/chacha.html, ChaCha20}-@url{https://en.wikipedia.org/wiki/Poly1305, Poly1305}
  45 algorithms. Authenticated data is BLAKE3-256 hash of the unsigned
  46 portion of the header (the same data used in the signature). Size is
  47 XDR-encoded unsigned hyper integer, carrying the payload size, encrypted
  48 as a single AEAD-block (with the tag) independently from the following
  49 blocks. It is encoded with the zero nonce.
  50
  51 Payload with possible padding is divided on 128 KiB blocks blocks. They
  52 are encrypted with the same authenticated data and increasing big-endian
  53 64-bit nonce, starting at 1.
  54
  55 Each node has static @strong{exchange} and @strong{signature} keypairs.
  56 When node A want to send encrypted packet to node B, it:
  57
  58 @enumerate
  59 @item generates ephemeral @url{http://cr.yp.to/ecdh.html, curve25519} keypair
  60 @item prepares structure for signing
  61 @item signs that structure using private
  62     @url{http://ed25519.cr.yp.to/, ed25519} signature key
  63 @item takes remote node's exchange public key and performs
  64     Diffie-Hellman computation on this remote static public key and
  65     private ephemeral one
  66 @item derives 32-bytes AEAD encryption key with BLAKE3 derivation
  67     function. Source key is the derived ephemeral key. Context is
  68     @verb{|N N C P E 0x00 0x00 0x05|} magic number
  69 @item calculates authenticated data: it is BLAKE3-256 hash of the
  70     unsigned header (same used for signing)
  71 @item encrypts size, appends its authenticated ciphertext to the header
  72     (with authenticated data, nonce=0)
  73 @item encrypts each payload block, appending its authenticated ciphertext
  74     (with authenticated data, nonce starting at 1, increasing with each block)
  75 @item possibly appends any kind of "junk" noise data to hide real
  76     payload's size from the adversary (generated using BLAKE3 XOF, with
  77     the key derived from the ephemeral one and context string of
  78     @verb{|N N C P E 0x00 0x00 0x05 <SP> P A D|})
  79 @end enumerate