doc/pkt/plain.texi

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