doc/pkt/plain.texi

   1 @node Plain
   2 @cindex plain packet
   3 @section Plain packet
   4
   5 Plain packet contains either the whole file, or file request (freq), or
   6 transition packet or exec message. It is called "plain", because it
   7 contains plaintext, but plain packets would never be stored on your hard
   8 drive.
   9
  10 @verbatim
  11             HEADER
  12 +--------------------------------------+--...---+
  13 | MAGIC | TYPE | NICE | PATHLEN | PATH | PAYLOAD|
  14 +--------------------------------------+--...---+
  15 @end verbatim
  16
  17 @multitable @columnfractions 0.2 0.3 0.5
  18 @headitem @tab XDR type @tab Value
  19 @item Magic number @tab
  20     8-byte, fixed length opaque data @tab
  21     @verb{|N N C P P 0x00 0x00 0x03|}
  22 @item Payload type @tab
  23     unsigned integer @tab
  24     @enumerate 0
  25     @item file (file transmission)
  26     @item freq (file request)
  27     @item exec (compressed exec)
  28     @item trns (transition)
  29     @item exec-fat (uncompressed exec)
  30     @item area (@ref{Multicast, multicast} area message)
  31     @end enumerate
  32 @item Niceness @tab
  33     unsigned integer @tab
  34     1-255, preferred packet @ref{Niceness, niceness} level
  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     Depending on packet's type, path holds:
  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, zero byte separated, exec's arguments
  45     @item Node's id the transition packet must be relayed on
  46     @item Multicast area's id
  47     @end itemize
  48 @end multitable
  49
  50 Path has fixed size because of hiding its actual length -- it is
  51 valuable metadata. Payload is appended to the header -- it is not stored
  52 as XDR field, because XDR has no ability to pass more than 4 GiB of
  53 opaque data. Moreover most XDR libraries store fields in the memory in
  54 practice.
  55
  56 Depending on the packet's type, payload could store:
  57
  58 @itemize
  59 @item File contents
  60 @item Destination path for freq
  61 @item Optionally @url{https://facebook.github.io/zstd/, Zstandard}
  62     compressed exec body
  63 @item Whole encrypted packet we need to relay on
  64 @item Multicast area message wrap with another encrypted packet inside
  65 @end itemize
  66
  67 Also depending on packet's type, niceness level means:
  68
  69 @itemize
  70 @item Preferable niceness level for files sent by freq
  71 @item @env{$NNCP_NICE} variable's value passed during @ref{CfgExec} invocation.
  72 @end itemize
  73
  74 So plain packets can hold following paths and payloads:
  75
  76 @table @code
  77
  78 @item file
  79 @example
  80   +--------------- PATH ---------------+   +---- PAYLOAD ---+
  81  /                                      \ /                  \
  82 +----------------------------------------+---------------...--+
  83 | FILENAME  | 0x00 ... variable ... 0x00 |    FILE CONTENTS   |
  84 +----------------------------------------+---------------...--+
  85  \         /
  86    PATHLEN
  87 @end example
  88
  89 @item freq
  90 @example
  91   +--------------- PATH ---------------+   +---- PAYLOAD ---+
  92  /                                      \ /                  \
  93 +----------------------------------------+---------------...--+
  94 | FILENAME  | 0x00 ... variable ... 0x00 |       FILENAME     |
  95 +----------------------------------------+---------------...--+
  96  \         /
  97    PATHLEN
  98 @end example
  99
 100 @item exec
 101 @example
 102   +------------------------- PATH ----------------------------+   +---- PAYLOAD ---+
 103  /                                                             \ /                  \
 104 +---------------------------------------------------------------+---------------...--+
 105 |  HANDLE 0x00 | ARG0 0x00 ARG1 ...| 0x00 ... variable ... 0x00 |     ZSTD DATA      |
 106 +---------------------------------------------------------------+---------------...--+
 107  \                                /
 108   +-------- PATHLEN -------------+
 109 @end example
 110
 111 @item exec-fat
 112 @example
 113   +------------------------- PATH ----------------------------+   +---- PAYLOAD ---+
 114  /                                                             \ /                  \
 115 +---------------------------------------------------------------+---------------...--+
 116 |  HANDLE 0x00 | ARG0 0x00 ARG1 ...| 0x00 ... variable ... 0x00 |        DATA        |
 117 +---------------------------------------------------------------+---------------...--+
 118  \                                /
 119   +-------- PATHLEN -------------+
 120 @end example
 121
 122 @item trns
 123 @example
 124   +------- PATH ---------+   +---- PAYLOAD ---+
 125  /                        \ /                  \
 126 +--------------------------+---------------...--+
 127 |  NODE ID | 0x00 ... 0x00 |  ENCRYPTED PACKET  |
 128 +--------------------------+---------------...--+
 129  \        /
 130    PATHLEN
 131 @end example
 132
 133 @item area
 134 @example
 135   +------- PATH ---------+   +---- PAYLOAD ---+
 136  /                        \ /                  \
 137 +--------------------------+---------------...--+
 138 |  AREA ID | 0x00 ... 0x00 |  ENCRYPTED PACKET  |
 139 +--------------------------+---------------...--+
 140  \        /
 141    PATHLEN
 142 @end example
 143 See also @ref{Encrypted area, encrypted area packet}.
 144
 145 @end table