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     @item ack (receipt acknowledgement)
  32     @end enumerate
  33 @item Niceness @tab
  34     unsigned integer @tab
  35     1-255, preferred packet @ref{Niceness, niceness} level
  36 @item Path length @tab
  37     unsigned integer @tab
  38     actual length of @emph{path} field's payload
  39 @item Path @tab
  40     255 byte, fixed length opaque data @tab
  41     Depending on packet's type, path holds:
  42     @itemize
  43     @item UTF-8 encoded destination path for file transfer
  44     @item UTF-8 encoded source path for file request
  45     @item UTF-8 encoded, zero byte separated, exec's arguments
  46     @item Node's id the transition packet must be relayed on
  47     @item Multicast area's id
  48     @item Packet's id (its @ref{MTH} hash)
  49     @end itemize
  50 @end multitable
  51
  52 Path has fixed size because of hiding its actual length -- it is
  53 valuable metadata. Payload is appended to the header -- it is not stored
  54 as XDR field, because XDR has no ability to pass more than 4 GiB of
  55 opaque data. Moreover most XDR libraries store fields in the memory in
  56 practice.
  57
  58 Depending on the packet's type, payload could store:
  59
  60 @itemize
  61 @item File contents
  62 @item Destination path for freq
  63 @item Optionally @url{https://facebook.github.io/zstd/, Zstandard}
  64     compressed exec body
  65 @item Whole encrypted packet we need to relay on
  66 @item Multicast area message wrap with another encrypted packet inside
  67 @item Nothing, if it is acknowledgement packet
  68 @end itemize
  69
  70 Also depending on packet's type, niceness level means:
  71
  72 @itemize
  73 @item Preferable niceness level for files sent by freq
  74 @item @env{$NNCP_NICE} variable's value passed during @ref{CfgExec} invocation.
  75 @end itemize
  76
  77 So plain packets can hold following paths and payloads:
  78
  79 @table @code
  80
  81 @item file
  82 @example
  83   +--------------- PATH ---------------+   +---- PAYLOAD ---+
  84  /                                      \ /                  \
  85 +----------------------------------------+---------------...--+
  86 | FILENAME  | 0x00 ... variable ... 0x00 |    FILE CONTENTS   |
  87 +----------------------------------------+---------------...--+
  88  \         /
  89    PATHLEN
  90 @end example
  91
  92 @item freq
  93 @example
  94   +--------------- PATH ---------------+   +---- PAYLOAD ---+
  95  /                                      \ /                  \
  96 +----------------------------------------+---------------...--+
  97 | FILENAME  | 0x00 ... variable ... 0x00 |       FILENAME     |
  98 +----------------------------------------+---------------...--+
  99  \         /
 100    PATHLEN
 101 @end example
 102
 103 @item exec
 104 @example
 105   +------------------------- PATH ----------------------------+   +---- PAYLOAD ---+
 106  /                                                             \ /                  \
 107 +---------------------------------------------------------------+---------------...--+
 108 |  HANDLE 0x00 | ARG0 0x00 ARG1 ...| 0x00 ... variable ... 0x00 |     ZSTD DATA      |
 109 +---------------------------------------------------------------+---------------...--+
 110  \                                /
 111   +-------- PATHLEN -------------+
 112 @end example
 113
 114 @item exec-fat
 115 @example
 116   +------------------------- PATH ----------------------------+   +---- PAYLOAD ---+
 117  /                                                             \ /                  \
 118 +---------------------------------------------------------------+---------------...--+
 119 |  HANDLE 0x00 | ARG0 0x00 ARG1 ...| 0x00 ... variable ... 0x00 |        DATA        |
 120 +---------------------------------------------------------------+---------------...--+
 121  \                                /
 122   +-------- PATHLEN -------------+
 123 @end example
 124
 125 @item trns
 126 @example
 127   +------- PATH ---------+   +---- PAYLOAD ---+
 128  /                        \ /                  \
 129 +--------------------------+---------------...--+
 130 |  NODE ID | 0x00 ... 0x00 |  ENCRYPTED PACKET  |
 131 +--------------------------+---------------...--+
 132  \        /
 133    PATHLEN
 134 @end example
 135
 136 @item area
 137 @example
 138   +------- PATH ---------+   +---- PAYLOAD ---+
 139  /                        \ /                  \
 140 +--------------------------+---------------...--+
 141 |  AREA ID | 0x00 ... 0x00 |  ENCRYPTED PACKET  |
 142 +--------------------------+---------------...--+
 143  \        /
 144    PATHLEN
 145 @end example
 146 See also @ref{Encrypted area, encrypted area packet}.
 147
 148 @item ack
 149 @example
 150   +------- PATH --------+
 151  /                       \
 152 +-------------------------+
 153 |  PKT ID | 0x00 ... 0x00 |
 154 +-------------------------+
 155  \       /
 156   PATHLEN
 157 @end example
 158
 159 @end table