doc/pkt.texi

   1 @node Packet
   2 @unnumbered Packet format
   3
   4 All packets are
   5 @url{https://en.wikipedia.org/wiki/External_Data_Representation,
   6 XDR}-encoded structures.
   7
   8 @menu
   9 * Plain packet: Plain.
  10 * Encrypted packet: Encrypted.
  11 @end menu
  12
  13 @node Plain
  14 @section Plain packet
  15
  16 Plain packet contains either the whole file, or file request (freq), or
  17 transition packet or email message. It is called "plain", because it
  18 contains plaintext, but plain packets would never be stored on your hard
  19 drive.
  20
  21 @verbatim
  22             HEADER
  23 +-------------------------------+--...---+
  24 | MAGIC | TYPE | PATHLEN | PATH | PAYLOAD|
  25 +-------------------------------+--...---+
  26 @end verbatim
  27
  28 @multitable @columnfractions 0.2 0.3 0.5
  29 @headitem  @tab XDR type @tab Value
  30 @item Magic number @tab
  31     8-byte, fixed length opaque data @tab
  32     @verb{|NNCPP0x00x00x01|}
  33 @item Payload type @tab
  34     unsigned integer @tab
  35     0 (file), 1 (freq), 2 (mail), 3 (transition)
  36 @item Path length @tab
  37     unsigned integer @tab
  38     actual length of following field's payload
  39 @item Path @tab
  40     255 byte, fixed length opaque data @tab
  41     @itemize
  42     @item UTF-8 encoded destination path for file transfer
  43     @item UTF-8 encoded source path for file request
  44     @item UTF-8 encoded, space separated, email recipients list
  45     @item Node id the transition packet must be relayed on
  46     @end itemize
  47 @end multitable
  48
  49 Path has fixed size because of hiding its actual length -- it is
  50 valuable metadata. Payload is appended to the header -- it is not stored
  51 as XDR field, because most XDR libraries will store all that data in the
  52 memory.
  53
  54 Depending on the packet's type, payload could store:
  55
  56 @itemize
  57 @item File contents
  58 @item Destination path for freq
  59 @item @url{http://zlib.net/, zlib} compressed email
  60 @item Whole encrypted packet we need to relay on
  61 @end itemize
  62
  63 @node Encrypted
  64 @section Encrypted packet
  65
  66 Encrypted packets are the only files found in spools, in exchangeable
  67 storages and that are synchronized between TCP daemons.
  68
  69 Each encrypted packet has the following header:
  70
  71 @verbatim
  72   +--------------- HEADER ----------+   +-------- ENCRYPTED --------+
  73  /                                   \ /                             \
  74 +-------------------------------------+------------+----...-----------+------+
  75 | MAGIC | NICE | SENDER | EPUB | SIGN | SIZE | MAC | CIPHERTEXT | MAC | JUNK |
  76 +------------------------------/------\------------+----...-----------+------+
  77                               /        \
  78                +-------------------------------------+
  79                | MAGIC | NICE | RCPT | SENDER | EPUB |
  80                +-------------------------------------+
  81 @end verbatim
  82
  83 @multitable @columnfractions 0.2 0.3 0.5
  84 @headitem  @tab XDR type @tab Value
  85 @item Magic number @tab
  86     8-byte, fixed length opaque data @tab
  87     @verb{|NNCPE0x00x00x01|}
  88 @item Niceness @tab
  89     unsigned integer @tab
  90     1-255, packet @ref{Niceness, niceness} level
  91 @item Sender @tab
  92     32-byte, fixed length opaque data @tab
  93     Sender node's id
  94 @item Exchange public key @tab
  95     32-byte, fixed length opaque data @tab
  96     Ephemeral curve25519 public key
  97 @item Signature @tab
  98     64-byte, fixed length opaque data @tab
  99     ed25519 signature for that packet's header
 100 @end multitable
 101
 102 Signature is calculated over the following structure:
 103
 104 @itemize
 105 @item Magic number
 106 @item Niceness
 107 @item Recipient (32-byte recipient node's id)
 108 @item Sender
 109 @item Exchange public key
 110 @end itemize
 111
 112 All following encryption is done using
 113 @url{https://www.schneier.com/academic/twofish/, Twofish} algorithm with
 114 256-bit key in
 115 @url{https://en.wikipedia.org/wiki/Counter_mode#Counter_.28CTR.29, CTR}
 116 mode of operation with zero initialization vector (because each
 117 encrypted packet has ephemeral exchange key). @url{https://blake2.net/,
 118 BLAKE2b-256} MAC is appended to the ciphertext.
 119
 120 After the headers comes an encrypted payload size and MAC of that size.
 121
 122 @multitable @columnfractions 0.2 0.3 0.5
 123 @headitem  @tab XDR type @tab Value
 124 @item Size @tab
 125     unsigned hyper integer @tab
 126     @verb{|NNCPE0x00x00x01|}
 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 derived ephemeral key is used as an input to
 144     @url{https://en.wikipedia.org/wiki/HKDF, HKDF}-BLAKE2b-256 KDF
 145 @item derives four session keys using
 146     @url{https://en.wikipedia.org/wiki/HKDF, HKDF}-BLAKE2b-256 KDF:
 147     @enumerate
 148     @item "Size" encryption (for Twofish) key
 149     @item "Size" authentication (for BLAKE2b-MAC) key
 150     @item Payload encryption key
 151     @item Payload authentication key
 152     @end enumerate
 153 @item encrypts size, appends its ciphertext to the header
 154 @item appends MAC tag over that ciphertext
 155 @item encrypts and appends payload ciphertext
 156 @item appends MAC tag over that payload ciphertext
 157 @item possibly appends any kind of "junk" noise data to hide real
 158     payload's size from the adversary
 159 @end enumerate