Remote command execution

[nncp.git] / doc / pkt.texi

diff --git a/doc/pkt.texi b/doc/pkt.texi
index f577506b9bd4a672350bf1e074c2cb19b47a0018..b1c2c38b37cb5d7ad0f2254645d6e8120b94b1e8 100644 (file)
--- a/doc/pkt.texi
+++ b/doc/pkt.texi
@@ -13,15 +13,15 @@ All packets are
 @section Plain packet
 
 Plain packet contains either the whole file, or file request (freq), or
-transition packet or email message. It is called "plain", because it
+transition packet or exec message. It is called "plain", because it
 contains plaintext, but plain packets would never be stored on your hard
 drive.
 
 @verbatim
             HEADER
-+-------------------------------+--...---+
-| MAGIC | TYPE | PATHLEN | PATH | PAYLOAD|
-+-------------------------------+--...---+
++--------------------------------------+--...---+
+| MAGIC | TYPE | NICE | PATHLEN | PATH | PAYLOAD|
++--------------------------------------+--...---+
 @end verbatim
 
 @multitable @columnfractions 0.2 0.3 0.5
@@ -31,7 +31,10 @@ drive.
     @verb{|N N C P P 0x00 0x00 0x01|}
 @item Payload type @tab
     unsigned integer @tab
-    0 (file), 1 (freq), 2 (mail), 3 (transition)
+    0 (file), 1 (freq), 2 (exec), 3 (transition)
+@item Niceness @tab
+    unsigned integer @tab
+    1-255, preferred packet @ref{Niceness, niceness} level
 @item Path length @tab
     unsigned integer @tab
     actual length of @emph{path} field's payload
@@ -40,7 +43,7 @@ drive.
     @itemize
     @item UTF-8 encoded destination path for file transfer
     @item UTF-8 encoded source path for file request
-    @item UTF-8 encoded, space separated, email recipients list
+    @item UTF-8 encoded, zero byte separated, exec's arguments
     @item Node's id the transition packet must be relayed on
     @end itemize
 @end multitable
@@ -55,10 +58,17 @@ Depending on the packet's type, payload could store:
 @itemize
 @item File contents
 @item Destination path for freq
-@item @url{http://zlib.net/, zlib} compressed email
+@item @url{http://zlib.net/, zlib} compressed exec body
 @item Whole encrypted packet we need to relay on
 @end itemize
 
+Also depending on packet's type, niceness level means:
+
+@itemize
+@item Preferable niceness level for files sent by freq
+@item @env{NNCP_NICE} variable's value passed during @ref{CfgExec} invocation.
+@end itemize
+
 @node Encrypted
 @section Encrypted packet
 
@@ -68,8 +78,8 @@ storages and that are synchronized between TCP daemons.
 Each encrypted packet has the following header:
 
 @verbatim
-  +------------ HEADER -------------+   +-------- ENCRYPTED --------+
- /                                   \ /                             \
+  +------------ HEADER --------------------+   +-------- ENCRYPTED --------+
+ /                                          \ /                             \
 +--------------------------------------------+------------+----...-----------+------+
 | MAGIC | NICE | SENDER | RCPT | EPUB | SIGN | SIZE | MAC | CIPHERTEXT | MAC | JUNK |
 +-------------------------------------/------\------------+----...-----------+------+
@@ -130,15 +140,16 @@ When node A want to send encrypted packet to node B, it:
 @item takes remote node's exchange public key and performs
     Diffie-Hellman computation on this remote static public key and
     private ephemeral one
-@item derived ephemeral key is used as a key input to
-    @url{https://blake2.net/, BLAKE2Xb} XOF
-@item derives five session keys using output from the XOF above:
+@item derive the keys:
     @enumerate
-    @item "Size" encryption (for ChaCha20) key
-    @item "Size" authentication (for BLAKE2b-MAC) key
-    @item Payload encryption key
-    @item Payload authentication key
-    @item Optional pad generation key (for ChaCha20)
+    @item initialize @url{https://blake2.net/, BLAKE2Xb} XOF with
+    derived ephemeral key and 224-byte output length
+    @item feed @verb{|N N C P E 0x00 0x00 0x03|} magic number to XOF
+    @item read 32-bytes of "size" encryption key (for ChaCha20)
+    @item read 64-bytes of "size" authentication key (for BLAKE2b-MAC)
+    @item read 32-bytes of payload encryption key
+    @item read 64-bytes of payload authentication key
+    @item optionally read 32-bytes pad generation key (for ChaCha20)
     @end enumerate
 @item encrypts size, appends its ciphertext to the header
 @item appends MAC tag over that ciphertext