doc/multicast.texi

   1 @node Multicast
   2 @cindex multicast area
   3 @unnumbered Multicast areas
   4
   5 NNCP has ability to multicast packets: send single packet to multiple
   6 recipients, which also can send it further to others. It can also be
   7 called echomail (like in FidoNet networks) or newsgroup (like in Usenet
   8 networks).
   9
  10 @anchor{Area}
  11 Each multicast group is identified by so-called @strong{area}. Area
  12 consists of private/public Curve25519 keypairs for @ref{Encrypted area,
  13 packets encryption}, identity (BLAKE2b-256 hash of the public key) and
  14 possible subscribers. Areas are created with @command{@ref{nncp-cfgnew}}
  15 command.
  16
  17 You can make either file or exec transmissions to the areas. Those
  18 ordinary file/exec packets are double wrapped in:
  19
  20 @itemize
  21 @item encrypted packet, securing the actual packet contents from
  22 participants not having area's keypairs (but still being able to relay
  23 that encrypted packet to the others)
  24 @item area packet, containing area's identity, telling that tossing node
  25 can should it to the subscribers further
  26 @end itemize
  27
  28 @vindex MsgHash
  29 Area's message identity (@code{MsgHash}) is the hash of the encrypted
  30 packet header. Because the area packet, containing the encrypted packet,
  31 is relayed as-is without any modifications, that area message's hash
  32 will be the same on each node it reaches.
  33
  34 @ref{nncp-toss, Tosser}'s algorithm of processing the area packet is
  35 following:
  36
  37 @itemize
  38 @item check is it known area's identity (@code{AREA}).
  39     Fail/skip if it is unknown
  40 @item hash encrypted packet's header, getting the @code{MsgHash}
  41 @item for each area's subscribers:
  42     @itemize
  43     @item check if that message was already seen (sent or received from)
  44         before by the destination node: check existence of
  45         @file{SPOOL/NODE/area/AREA/MsgHash} file. Skip that node if
  46         it exists
  47     @item if subscriber's node is not the one we received the packet
  48         from, then create outgoing encrypted packet to it, with that
  49         area packet inside
  50     @item create corresponding @file{MsgHash} file
  51     @item "rewind" the outer encrypted file to the beginning and repeat
  52         the whole cycle again, while all of subscribers will "seen" that
  53         area's message.
  54
  55         Expensive signature verification and shared key computation
  56         procedures are skipped in the following cycles -- only symmetric
  57         cryptography will be in use, having negligible CPU resource
  58         consumption.
  59     @end itemize
  60 @item check if we have seen that area's message before by looking at
  61     @file{SPOOL/SELF/area/AREA/MsgHash}. If so, remove the packet,
  62     because it is just a ordinary possible duplicate, finish its processing
  63 @item check if we have got corresponding area's private key. If no key
  64     exists, then remove the packet, finish its processing -- we just
  65     relay it further without being able to read it
  66 @item look if area's encrypted packet's sender is known to us. If
  67     neither it is known, nor we have @code{allow-unknown} configuration
  68     option set for that area, then fail
  69 @item otherwise start decryption procedure, possibly ignoring the
  70     sender's signature verification if it is unknown
  71 @item fed the decrypted contents to the toss-procedure as an ordinary
  72     plain packet, receiving files or exec calls
  73 @item mark area's message as the seen one, remove the packet, finish
  74     processing
  75 @end itemize
  76
  77 Because outgoing packets creation for each subscriber can be time and
  78 (disk) resource consuming, we can suddenly fail. It would be bad if we
  79 will loose the possibility to retry the multicasting process again. So
  80 we have got to save somehow outgoing area's message in permanent
  81 storage, while outgoing copies are created. That is why the initial (not
  82 relaying) message to the area is sent to the @strong{self} and processed
  83 by the @ref{nncp-toss, tosser} to create necessary outgoing message
  84 copies. Because message to myself is also encrypted, area's message is
  85 encrypted and secured and noone sees plaintext @code{MsgHash}, knowing
  86 that you either originated or have that message on the disk.
  87
  88 For example we have got 4 nodes participating in the single area and
  89 let's send file to that area from the @code{nodeA}:
  90
  91 @example
  92 nodeA -> subs: ["nodeB", "nodeD"]
  93 nodeB -> subs: ["nodeC", "nodeD", "nodeA"], no keys
  94 nodeC -> subs: ["nodeB"]
  95 nodeD -> subs: ["nodeA", "nodeB"]
  96 @end example
  97
  98 @example
  99 A -- B -- C
 100 \   /
 101  \ /
 102   D
 103 @end example
 104
 105 @example
 106 $ nncp-file nodelist-20210704.rec.zst area:nodelist-updates:
 107 $ nncp-toss -node self
 108 @end example
 109
 110 @enumerate
 111 @item
 112 @command{@ref{nncp-file}} creates an encrypted packet with area packet and
 113 encrypted packet inside it, with our own @code{self} node as a recipient
 114 (in the @file{SPOOL/SELF/tx} directory). It also creates the
 115 @file{SPOOL/SELF/area/AREA/MsgHash} file.
 116
 117 @item
 118 @command{@ref{nncp-toss}} sees @file{tx/} file and "opens" it, applying the
 119 area message tossing procedure as described above. That will create
 120 outgoing packets in @file{SPOOL/nodeB/tx} and @file{SPOOL/nodeD/tx}
 121 directories with @file{SPOOL/nodeB/area/AREA/MsgHash}
 122 @file{SPOOL/nodeD/area/AREA/MsgHash} files. Because we already have
 123 @file{SPOOL/SELF/area/AREA/MsgHash}, that packet is removed then.
 124
 125 @item
 126 When @code{nodeB} receives the encrypted packet, it sees the area one
 127 inside. It copies/relays it to the @code{nodeC} and @code{nodeD}. It can
 128 not read area's message because it lacks the keys.
 129
 130 @item
 131 @code{nodeC} does not relay it to anyone. Just stores
 132 @file{nodelist-20210704.rec.zst} in the incoming directory.
 133
 134 @item
 135 @code{nodeD} receives packets from both @code{nodeA} and @code{nodeB}.
 136 Only one of them processed, and other is ignored because corresponding
 137 @file{MsgHash} file will exist.
 138
 139 If @code{nodeD} will receive packet from the @code{nodeB} first, it will
 140 relay it to the @code{nodeA} also, that will silently remove it when
 141 tossing, because it was already seen.
 142
 143 @item
 144 When @code{nodeC} sends message to the area, then @code{nodeA} will
 145 receive it twice from @code{nodeB} and @code{nodeD}, ignoring one of
 146 them during tossing.
 147
 148 @end enumerate