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 Each packet has the following header:
  22
  23 @verbatim
  24             HEADER
  25 +-------------------------------+--...---+
  26 | MAGIC | TYPE | PATHLEN | PATH | PAYLOAD|
  27 +-------------------------------+--...---+
  28 @end verbatim
  29
  30 @multitable @columnfractions 0.2 0.3 0.5
  31 @headitem  @tab XDR type @tab Value
  32
  33 @item Magic number @tab
  34   8-byte, fixed length opaque data @tab
  35   @code{NNCPP0x10x00x00}
  36
  37 @item Payload type @tab
  38   unsigned integer @tab
  39   0 (file), 1 (freq), 2 (mail), 3 (transition)
  40
  41 @item Path length @tab
  42   unsigned integer @tab
  43   actual length of following field's payload
  44
  45 @item Path @tab
  46   255 byte, fixed length opaque data @tab
  47   @itemize
  48   @item UTF-8 encoded destination path for file transfer
  49   @item UTF-8 encoded source path for file request
  50   @item UTF-8 encoded, space separated, email recipients list
  51   @item Node id the transition packet must be relayed on
  52   @end itemize
  53
  54 @end multitable
  55
  56 Path has fixed size because of hiding its actual length -- it is
  57 valuable metadata.
  58
  59 Actual payload comes after that header to the very end:
  60
  61 @itemize
  62 @item File contents
  63 @item Destination path for freq
  64 @item @url{http://zlib.net/, zlib} compressed email
  65 @item Whole encrypted packet we need to relay on
  66 @end itemize
  67
  68 @node Encrypted
  69 @section Encrypted packet
  70
  71 Encrypted packets are the only files found in spools, in exchangeable
  72 storages and that are synchronized between TCP daemons.
  73
  74 Each encrypted packet has the following header:
  75
  76 @verbatim
  77                     HEADER
  78 +--------------------------------------------+-------...--------+
  79 | MAGIC | NICE | SENDER | EPUB | SIGN | SIZE | CIPHERTEXT | MAC |
  80 +------------------------------/------\------+-------...--------+
  81                               /        \
  82              +--------------------------------------------+
  83              | MAGIC | NICE | RCPT | SENDER | EPUB | SIZE |
  84              +--------------------------------------------+
  85 @end verbatim
  86
  87 @multitable @columnfractions 0.2 0.3 0.5
  88 @headitem  @tab XDR type @tab Value
  89
  90 @item Magic number @tab
  91   8-byte, fixed length opaque data @tab
  92   @code{NNCPE0x10x00x00}
  93
  94 @item Niceness @tab
  95   unsigned integer @tab
  96   1-255, packet niceness level, its priority.
  97   Lower value means higher precedence
  98
  99 @item Sender @tab
 100   32-byte, fixed length opaque data @tab
 101   Sender node's id
 102
 103 @item Exchange public key @tab
 104   32-byte, fixed length opaque data @tab
 105   Ephemeral curve25519 public key
 106
 107 @item Signature @tab
 108   64-byte, fixed length opaque data @tab
 109   ed25519 signature for that encrypted packet
 110
 111 @item Size @tab
 112   unsigned hyper integer @tab
 113   Encrypted payload size
 114
 115 @end multitable
 116
 117 Signature is calculated over the following structure:
 118
 119 @itemize
 120 @item Magic number
 121 @item Niceness
 122 @item Recipient (32-byte recipient node's id)
 123 @item Sender
 124 @item Exchange public key
 125 @item Size
 126 @end itemize
 127
 128 Actual encrypted payload comes after that header. Payload is encrypted
 129 using @url{https://www.schneier.com/academic/twofish/, Twofish}
 130 algorithm with 256-bit key in
 131 @url{https://en.wikipedia.org/wiki/Counter_mode#Counter_.28CTR.29, CTR}
 132 mode of operation with zero initialization vector (because each
 133 encrypted packet has ephemeral exchange key). Ciphertext's length is
 134 equal to plaintext. @url{https://blake2.net/, BLAKE2b-256} MAC is
 135 appended to the ciphertext.
 136
 137 Each node has static @strong{exchange} and @strong{signature} keypairs.
 138 When node A want to send encrypted packet to node B, it:
 139
 140 @enumerate
 141 @item generates ephemeral @url{http://cr.yp.to/ecdh.html, curve25519} keypair
 142 @item prepares structure for signing (underlying payload size must be
 143 already known)
 144 @item signs that structure using private @url{http://ed25519.cr.yp.to/,
 145 ed25519} signature key
 146 @item takes remote node's exchange public key and performs
 147 Diffie-Hellman computation on this remote static public key and private
 148 ephemeral one
 149 @item derived ephemeral key used as an input to
 150 @url{https://en.wikipedia.org/wiki/HKDF, HKDF}-BLAKE2b-256 key
 151 derivation function
 152 @item two 256-bit keys are derived from it for using with Twofish and
 153 BLAKE2b-MAC functions
 154 @item Twofish encryption and BLAKE2b-MACing is performed over the
 155 plaintext. Ciphertext and MAC tag are appended to the header
 156 @end enumerate