commit 0a3305a9165d840dfbcca4d12a9e818f9eb6cebb
parent b396a9e51a1c3650c7cda056d6dd01b61b35a095
Author: Christian Grothoff <christian@grothoff.org>
Date: Sat, 13 Jul 2024 09:39:45 +0200
English and style fixes
Diffstat:
1 file changed, 94 insertions(+), 97 deletions(-)
diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
@@ -985,7 +985,7 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
The element <tt>e</tt> is the peer public key which is hashed using SHA-512.
The resulting 512-bit peer identity is interpreted as an array of k=16
32-bit integers in network byte order which are used to set and check the bits
- in <tt>B</tt> using <tt>BF-SET</tt> and <tt>BF-TEST</tt>.
+ in <tt>B</tt> using <tt>BF-SET()</tt> and <tt>BF-TEST()</tt>.
</t>
<t>
We note that the peer Bloom filter may exclude peers due to false-postive
@@ -1522,14 +1522,14 @@ BEGIN
</dd>
<dt>VERSION</dt>
<dd>
- is a 16-bit field that indicates the version of the HelloMessage. Must be zero.
- In the future, this may be used to extend or update the HelloMessage format.
+ is a 16-bit field that indicates the version of the <tt>HelloMessage</tt>. Must be zero.
+ In the future, this may be used to extend or update the <tt>HelloMessage</tt> format.
</dd>
<dt>NUM_ADDRS</dt>
<dd>
- is a 16-bit number that gives the total number of
- addresses encoded in the ADDRESSES field.
- In network byte order.
+ is a 16-bit number in network byte order that gives the
+ total number of addresses encoded in the
+ <tt>ADDRESSES</tt> field.
</dd>
<dt>SIGNATURE</dt>
<dd>
@@ -1599,13 +1599,19 @@ BEGIN
<name>PutMessage</name>
<t>
<tt>PutMessages</tt> are used to store information at other
- peers in the DHT. Any API which allows applications to
- initiate <tt>PutMessages</tt> needs to provide sufficient,
+ peers in the DHT. Any application-facing API which allows
+ applications to initiate <tt>PutMessages</tt> to store data
+ in the DHT needs to receive sufficient, possibly
implementation-specific information to construct the initial
- <tt>PutMessage</tt>. For example, implementations
- supporting multiple applications and blocks will have block
- type and message flag parameters in addition to the actual
- data payload and key.
+ <tt>PutMessage</tt>. In general, application-facing APIs
+ supporting multiple applications and block types need to be
+ given the block type (<tt>BTYPE</tt>) and message
+ <tt>FLAGS</tt> in addition to the actual <tt>BLOCK</tt>
+ payload. The <tt>BLOCK_KEY</tt> could be provided
+ explicitly, or in some cases might be derived using the
+ <tt>DeriveBlockKey()</tt> function from the block type
+ specific operations defined in <xref
+ target="block_functions"/>.
</t>
<section anchor="p2p_put_wire">
<name>Wire Format</name>
@@ -1643,17 +1649,16 @@ BEGIN
</dd>
<dt>MTYPE</dt>
<dd>
- is the 16-bit message type. Read-only.
- It must be set to
- the value 146 in network byte order as defined in the GANA "GNUnet Message Type" registry <xref target="gana_message_type"/>.
+ is the 16-bit message type. Read-only. It must be set
+ to the value 146 in network byte order as defined in the
+ GANA "GNUnet Message Type" registry <xref
+ target="gana_message_type"/>.
</dd>
<dt>BTYPE</dt>
<dd>
- is a 32-bit block type.
- The block type indicates the content
- type of the payload.
- Set by the initiator. Read-only.
- In network byte order.
+ is a 32-bit block type in network byte order. The block
+ type indicates the content type of the payload. Set by
+ the initiator. Read-only.
</dd>
<dt>VER</dt>
<dd>
@@ -1667,40 +1672,40 @@ BEGIN
</dd>
<dt>HOPCOUNT</dt>
<dd>
- is a 16-bit number indicating how many hops this message has
- traversed to far.
- Set by the initiator to 0.
- Incremented by processing peers.
- In network byte order.
+ is a 16-bit number in network byte order indicating how
+ many hops this message has traversed to far. Set by the
+ initiator to 0. <bcp14>MUST</bcp14> be incremented by 1
+ by each peer before forwarding the request.
</dd>
<dt>REPL_LVL</dt>
<dd>
- is a 16-bit number indicating the desired replication level of
- the data.
- Set by the initiator. Read-only.
- In network byte order.
+ is a 16-bit number in network byte order indicating the
+ desired replication level of the data. Set by the
+ initiator. Read-only.
</dd>
<dt>PATH_LEN</dt>
<dd>
- is a 16-bit number indicating the number of path elements
- recorded in PUTPATH.
- As PUTPATH is optional, this value may be zero.
- If the PUTPATH is enabled, set initially to 0 by the initiator.
- Incremented by processing peers.
- In network byte order.
+ is a 16-bit number in network byte order indicating the
+ number of path elements recorded in <tt>PUTPATH</tt>. As <tt>PUTPATH</tt>
+ is optional, this value may be zero. If the <tt>PUTPATH</tt> is
+ enabled, set initially to 0 by the initiator. Updated
+ by processing peers to match the path length in the
+ message.
</dd>
<dt>EXPIRATION</dt>
<dd>
- denotes the absolute 64-bit expiration date of the content.
- Set by the initiator. Read-only.
- In microseconds since midnight (0 hour), January 1, 1970 in network
- byte order.
+ denotes the absolute 64-bit expiration date of the
+ content in microseconds since midnight (0 hour), January
+ 1, 1970 in network byte order. Set by the
+ initiator. Read-only.
</dd>
<dt>PEER_BF</dt>
<dd>
- A peer Bloom filter to stop circular routes (see <xref target="routing_bloomfilter"/>).
- Set by the initiator to contain the local peer and all neighbors it is forwarded to.
- Modified by processing peers to include their own peer public key using <tt>BF-SET</tt>.
+ A peer Bloom filter to stop circular routes (see <xref
+ target="routing_bloomfilter"/>). Set by the initiator
+ to contain the local peer and all neighbors it is
+ forwarded to. Modified by processing peers to include
+ their own peer public key using <tt>BF-SET()</tt>.
</dd>
<dt>BLOCK_KEY</dt>
<dd>
@@ -1710,29 +1715,28 @@ BEGIN
</dd>
<dt>TRUNCATED ORIGIN</dt>
<dd>
- is only provided if the TRUNCATED flag
- is set in FLAGS. If present, this is
- the public key of the peer just before
- the first entry on the PUTPATH and the
- first peer on the PUTPATH is not the
- actual origin of the message. Thus, to
- verify the first signature on the PUTPATH,
- this public key must be used. Note that
- due to the truncation, this last hop
- cannot be verified to exist.
- Value is modified by processing peers.
+ is only provided if the <tt>Truncated</tt> flag is set
+ in <tt>FLAGS</tt>. If present, this is the public key of
+ the peer just before the first entry on the
+ <tt>PUTPATH</tt> and the first peer on the
+ <tt>PUTPATH</tt> is not the actual origin of the
+ message. Thus, to verify the first signature on the
+ <tt>PUTPATH</tt>, this public key must be used. Note
+ that due to the truncation, this last hop cannot be
+ verified to exist. Value is modified by processing
+ peers.
</dd>
<dt>PUTPATH</dt>
<dd>
- the variable-length PUT path.
- The path consists of a list of PATH_LEN path elements.
+ the variable-length <tt>PUT</tt> path.
+ The path consists of a list of <tt>PATH_LEN</tt> path elements.
Set by the initiator to 0.
Incremented by processing peers.
</dd>
<dt>LAST HOP SIGNATURE</dt>
<dd>
- is only provided if the RECORD ROUTE flag
- is set in FLAGS. If present, this is
+ is only provided if the <tt>RecordRoute</tt> flag
+ is set in <tt>FLAGS</tt>. If present, this is
an EdDSA signature <xref target="ed25519"/> by the sender of this message
(using the same format as the signatures in PUTPATH)
affirming that the sender forwarded the message from
@@ -1911,25 +1915,21 @@ BEGIN
</dd>
<dt>HOPCOUNT</dt>
<dd>
- is a 16-bit number indicating how many hops this message has
- traversed to far.
- Set by the initiator to 0.
- Incremented by processing peers.
- In network byte order.
+ is a 16-bit number in network byte order indicating how
+ many hops this message has traversed to far. Set by the
+ initiator to 0. Incremented by processing peers.
</dd>
<dt>REPL_LVL</dt>
<dd>
- is a 16-bit number indicating the desired replication level of
- the data.
- Set by the initiator. Read-only.
- In network byte order.
+ is a 16-bit number in network byte order indicating the
+ desired replication level of the data. Set by the
+ initiator. Read-only.
</dd>
<dt>RF_SIZE</dt>
<dd>
- is a 16-bit number indicating the length of the
- result filter RESULT_FILTER.
- Set by the initiator. Read-only.
- In network byte order.
+ is a 16-bit number in network byte order indicating the
+ length of the result filter RESULT_FILTER. Set by the
+ initiator. Read-only.
</dd>
<dt>PEER_BF</dt>
<dd>
@@ -2140,10 +2140,9 @@ BEGIN
</dd>
<dt>BTYPE</dt>
<dd>
- is a 32-bit block type field. The block type indicates the content
- type of the payload.
+ is a 32-bit block type field in network byte order. The
+ block type indicates the content type of the payload.
Set by the initiator. Read-only.
- In network byte order.
</dd>
<dt>RESERVED</dt>
<dd>
@@ -2169,22 +2168,22 @@ BEGIN
</dd>
<dt>PUTPATH_L</dt>
<dd>
- is a 16-bit number indicating the number of path elements recorded
- in <tt>PUTPATH</tt>. As <tt>PUTPATH</tt> is optional, this value may be zero
- even if the message has traversed several peers.
- Set by the initiator to the <tt>PATH_LEN</tt> of the <tt>PutMessage</tt>
- from which the block originated.
+ is a 16-bit number in network byte order indicating the
+ number of path elements recorded in <tt>PUTPATH</tt>. As
+ <tt>PUTPATH</tt> is optional, this value may be zero
+ even if the message has traversed several peers. Set by
+ the initiator to the <tt>PATH_LEN</tt> of the
+ <tt>PutMessage</tt> from which the block originated.
Modified by processing peers in case of path truncation.
- In network byte order.
</dd>
<dt>GETPATH_L</dt>
<dd>
- is a 16-bit number indicating the number of path elements
- recorded in <tt>GETPATH</tt>. As <tt>GETPATH</tt> is optional, this value may be zero
- even if the message has traversed several peers.
- Set by the initiator to 0.
- Modified by processing peers.
- In network byte order.
+ is a 16-bit number in network byte order indicating the
+ number of path elements recorded in <tt>GETPATH</tt>. As
+ <tt>GETPATH</tt> is optional, this value may be zero
+ even if the message has traversed several peers.
+ <bcp14>MUST</bcp14> be set to 0 by the initiator.
+ Modified by processing peers to match the path length in the message.
</dd>
<dt>EXPIRATION</dt>
<dd>
@@ -2204,17 +2203,15 @@ BEGIN
</dd>
<dt>TRUNCATED ORIGIN</dt>
<dd>
- is only provided if the TRUNCATED flag
- is set in FLAGS. If present, this is
- the public key of the peer just before
- the first entry on the PUTPATH and the
- first peer on the PUTPATH is not the
- actual origin of the message. Thus, to
- verify the first signature on the PUTPATH,
- this public key must be used. Note that
- due to the truncation, this last hop
- cannot be verified to exist.
- Set by processing peers.
+ is only provided if the <tt>Truncated</tt> flag is set
+ in <tt>FLAGS</tt>. If present, this is the public key of
+ the peer just before the first entry on the
+ <tt>PUTPATH</tt> and the first peer on the
+ <tt>PUTPATH</tt> is not the actual origin of the
+ message. Thus, to verify the first signature on the
+ <tt>PUTPATH</tt>, this public key must be used. Note
+ that due to the truncation, this last hop cannot be
+ verified to exist. Set by processing peers.
</dd>
<dt>PUTPATH</dt>
<dd>
@@ -2652,7 +2649,7 @@ BEGIN
<tt>M</tt> is an identity function and returns the 512-bit XOR result unmodified.
This resulting byte string is interpreted as k=16 32-bit
integers in network byte order which are used to set and check the bits in
- <tt>B</tt> using <tt>BF-SET</tt> and <tt>BF-TEST</tt>.
+ <tt>B</tt> using <tt>BF-SET()</tt> and <tt>BF-TEST()</tt>.
The 32-bit Mutator is prepended to the L-bit Bloom filter field <tt>HELLO_BF</tt> containing <tt>B</tt>
to create the result filter for a <tt>HELLO</tt> block:
</t>
