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 | EPUB | SIGN | SIZE | MAC | CIPHERTEXT | MAC | JUNK |
  75 +------------------------------/------\------------+----...-----------+------+
  76                               /        \
  77                +-------------------------------------+
  78                | MAGIC | NICE | RCPT | SENDER | 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 Exchange public key @tab
  94     32-byte, fixed length opaque data @tab
  95     Ephemeral curve25519 public key
  96 @item Signature @tab
  97     64-byte, fixed length opaque data @tab
  98     ed25519 signature for that packet's header
  99 @end multitable
 100
 101 Signature is calculated over the following structure:
 102
 103 @itemize
 104 @item Magic number
 105 @item Niceness
 106 @item Recipient (32-byte recipient node's id)
 107 @item Sender
 108 @item Exchange public key
 109 @end itemize
 110
 111 All following encryption is done using
 112 @url{https://www.schneier.com/academic/twofish/, Twofish} algorithm with
 113 256-bit key in
 114 @url{https://en.wikipedia.org/wiki/Counter_mode#Counter_.28CTR.29, CTR}
 115 mode of operation with zero initialization vector (because each
 116 encrypted packet has ephemeral exchange key). @url{https://blake2.net/,
 117 BLAKE2b-256} MAC is appended to the ciphertext.
 118
 119 After the headers comes an encrypted payload size and MAC of that size.
 120
 121 @multitable @columnfractions 0.2 0.3 0.5
 122 @headitem @tab XDR type @tab Value
 123 @item Size @tab
 124     unsigned hyper integer @tab
 125     Payload size.
 126 @end multitable
 127
 128 Next comes the actual encrypted payload with corresponding MAC.
 129
 130 Each node has static @strong{exchange} and @strong{signature} keypairs.
 131 When node A want to send encrypted packet to node B, it:
 132
 133 @enumerate
 134 @item generates ephemeral @url{http://cr.yp.to/ecdh.html, curve25519} keypair
 135 @item prepares structure for signing
 136 @item signs that structure using private
 137     @url{http://ed25519.cr.yp.to/, ed25519} signature key
 138 @item takes remote node's exchange public key and performs
 139     Diffie-Hellman computation on this remote static public key and
 140     private ephemeral one
 141 @item derived ephemeral key is used as an input to
 142     @url{https://en.wikipedia.org/wiki/HKDF, HKDF}-BLAKE2b-256 KDF
 143 @item derives four session keys using
 144     @url{https://en.wikipedia.org/wiki/HKDF, HKDF}-BLAKE2b-256 KDF:
 145     @enumerate
 146     @item "Size" encryption (for Twofish) key
 147     @item "Size" authentication (for BLAKE2b-MAC) key
 148     @item Payload encryption key
 149     @item Payload authentication key
 150     @end enumerate
 151 @item encrypts size, appends its ciphertext to the header
 152 @item appends MAC tag over that ciphertext
 153 @item encrypts and appends payload ciphertext
 154 @item appends MAC tag over that payload ciphertext
 155 @item possibly appends any kind of "junk" noise data to hide real
 156     payload's size from the adversary
 157 @end enumerate