commit e0b7c4a66155163ef8005ea1bd9d5db594390ec9
parent 811fe601faf9753db1dede2b8cf0d66bd0beafba
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Sun, 25 Dec 2022 23:45:56 +0900
tt for HELLO
Diffstat:
1 file changed, 45 insertions(+), 45 deletions(-)
diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
@@ -223,13 +223,13 @@ gnunet+tcp://12.3.4.5/
</dd>
<dt>HELLO block</dt>
<dd>
- A HELLO block is a block with a dedicated block type and is specified in this document.
- The HELLO block is used to store and retrieve Peer addresses.
- In this document, HELLO blocks are used by the peer discovery mechanism.
+ A <tt>HELLO</tt> block is a block with a dedicated block type and is specified in this document.
+ The <tt>HELLO</tt> block is used to store and retrieve Peer addresses.
+ In this document, <tt>HELLO</tt> blocks are used by the peer discovery mechanism.
</dd>
<dt>HELLO URL</dt>
<dd>
- HELLO URLs are URL-formatted HELLO blocks.
+ <tt>HELLO</tt> URLs are URL-formatted <tt>HELLO</tt> blocks.
They can used for out-of-band exchanges of peer information and are used for
address update signalling messages to neighbours.
</dd>
@@ -523,7 +523,7 @@ Connectivity | |Underlay| |Underlay|
local peer and that henceforth the peer may be reachable under this address.
This information is used to advertise
connectivity information about the local peer to other peers.
- <tt>A</tt> must be a URI suitable for inclusion in a HELLO payload
+ <tt>A</tt> must be a URI suitable for inclusion in a <tt>HELLO</tt> payload
<xref target="hello_block"/>.
</dd>
<dt>
@@ -679,10 +679,10 @@ Connectivity | |Underlay| |Underlay|
Furthermore, the Underlay <bcp14>SHOULD</bcp14> provide the implementation with one or more
addresses signalled through <tt>ADDRESS_ADDED</tt>. Zero addresses <bcp14>MAY</bcp14> be
provided if a peer can only establish outgoing connections and is otherwise unreachable.
- <!-- FIXME: What about HelloMessages? What is the distinction between HELLO blocks
- and HELLO messages? -->
+ <!-- FIXME: What about HelloMessages? What is the distinction between <tt>HELLO</tt> blocks
+ and <tt>HELLO</tt> messages? -->
The implementation periodically advertises all
- active addresses in a HELLO block <xref target="hello_block"/>.
+ active addresses in a <tt>HELLO</tt> block <xref target="hello_block"/>.
</t>
</section>
<section anchor="routing_bloomfilter">
@@ -1227,7 +1227,7 @@ BEGIN
it <bcp14>MAY</bcp14> disseminate those changes to neighbors using
<tt>HelloMessage</tt>s.
<!-- FIXME yesyes this is blabla and obvious when reading the processing section.
- In contrast to a HELLO block, a
+ In contrast to a <tt>HELLO</tt> block, a
<tt>HelloMessage</tt> does not contain the ID of
the peer the address information is about: in a
<tt>HelloMessage</tt>, the address information is always
@@ -1244,7 +1244,7 @@ BEGIN
a peer about the sender's available addresses. The
recipients use these messages to inform their respective
Underlays about ways to sustain the connections and to
- generate HELLO blocks (see <xref target="hello_block"/>)
+ generate <tt>HELLO</tt> blocks (see <xref target="hello_block"/>)
to answer peer discovery queries
from other peers.
</t>
@@ -1287,14 +1287,14 @@ BEGIN
is a 64 byte EdDSA signature using the sender's private
key affirming the information contained in the message.
The signature is signing exactly the same data that is being
- signed in a HELLO block as described in <xref target="hello_block"/>.
+ signed in a <tt>HELLO</tt> block as described in <xref target="hello_block"/>.
</dd>
<dt>EXPIRATION</dt>
<dd>
denotes the absolute 64-bit expiration date of the content.
The value specified is microseconds since midnight (0 hour),
January 1, 1970, but must be a multiple of one million
- (so that it can be represented in seconds in a HELLO URL).
+ (so that it can be represented in seconds in a <tt>HELLO</tt> URL).
Stored in network byte order.
</dd>
<dt>ADDRESSES</dt>
@@ -1323,9 +1323,9 @@ BEGIN
is in the future. If the signature is invalid, the message is discarded.
</li>
<li>
- The HELLO information is cached in the routing table until it expires,
+ The <tt>HELLO</tt> information is cached in the routing table until it expires,
the peer is removed from the routing table, or the information is replaced by another message from the peer.
- <!-- FIXME same problem as for HELLO blocks: We do not need to TRY_CONNECT here because we already have
+ <!-- FIXME same problem as for <tt>HELLO</tt> blocks: We do not need to TRY_CONNECT here because we already have
a connection, obviously. But we may want to TRY_CONNECT on the new addresses? Adding for now -->
The implementation <bcp14>MAY</bcp14> instruct the Underlay to connect to all now available addresses
using <tt>TRY_CONNECT</tt> in order to make the underlay aware of alternative addresses for this connection.
@@ -1553,12 +1553,12 @@ BEGIN
be stored locally in the block storage.
</li>
<li>
- If the <tt>BTYPE</tt> of the message indicates a HELLO block, the
+ If the <tt>BTYPE</tt> of the message indicates a <tt>HELLO</tt> block, the
peer <bcp14>MUST</bcp14> be considered for the local routing
table if the respective k-bucket is not yet full. In this case,
the local peer <bcp14>MUST</bcp14> try to establish a connection
- to the peer indicated in the HELLO block using the address information
- from the HELLO block and the Underlay function <tt>TRY_CONNECT</tt>.
+ to the peer indicated in the <tt>HELLO</tt> block using the address information
+ from the <tt>HELLO</tt> block and the Underlay function <tt>TRY_CONNECT</tt>.
<!-- FIXME: The above behaviour has a catch: If the implementation only connects to one
address from the hello using TRY_CONNECT, the Underlay also knows only about that connection
If that failes and PEER_DISCONNECT is called, this neighbor is dead.
@@ -1755,11 +1755,11 @@ BEGIN
</t>
<ol type="%c)">
<!-- FIXME: It is not clear that this is a fallthrough statement -->
- <!-- FIXME: Are HELLO blocks according to the spec stored in block storage but never looked for? -->
+ <!-- FIXME: Are <tt>HELLO</tt> blocks according to the spec stored in block storage but never looked for? -->
<li>
- If <tt>BTYPE</tt> indicates a request for a HELLO block or
+ If <tt>BTYPE</tt> indicates a request for a <tt>HELLO</tt> block or
<tt>ANY</tt>,
- the peer <bcp14>MUST</bcp14> consult its own HELLO as well as
+ the peer <bcp14>MUST</bcp14> consult its own <tt>HELLO</tt> as well as
the HELLOs it has cached for the
peers in its routing table instead of the local block
storage (while continuing to respect flags like
@@ -1998,12 +1998,12 @@ BEGIN
does not have to match the <tt>QUERY_HASH</tt>.
</li>
<li>
- If the <tt>BTYPE</tt> of the message indicates a HELLO block, the
+ If the <tt>BTYPE</tt> of the message indicates a <tt>HELLO</tt> block, the
peer <bcp14>MUST</bcp14> be considered for the local routing
table if the respective k-bucket is not yet full. In this case,
the local peer <bcp14>MUST</bcp14> try to establish a connection
- to the peer indicated in the HELLO block using the address information
- from the HELLO block. If a connection is established,
+ to the peer indicated in the <tt>HELLO</tt> block using the address information
+ from the <tt>HELLO</tt> block. If a connection is established,
the peer is added to the respective k-bucket of the routing table.
Note that the k-bucket <bcp14>MUST</bcp14> be determined by the
key computed using <tt>DeriveBlockKey</tt> and not by the <tt>QUERY_HASH</tt>.
@@ -2186,18 +2186,18 @@ BEGIN
<name>HELLO Blocks</name>
<t>
For bootstrapping and peer discovery, the DHT implementation uses
- its own block type called "HELLO". HELLO blocks are the only type
+ its own block type called "HELLO". <tt>HELLO</tt> blocks are the only type
of block that <bcp14>MUST</bcp14> be supported by every
R<sup>5</sup>N implementation. A block with this block type
- contains the peer ID of the peer that published the HELLO together
- with a set of addresses of this peer. The key of a HELLO block
+ contains the peer ID of the peer that published the <tt>HELLO</tt> together
+ with a set of addresses of this peer. The key of a <tt>HELLO</tt> block
is the SHA-512 of the peer ID and thus the peer's address in the DHT.
</t>
<t>
- The HELLO block type wire format is illustrated in
- <xref target="figure_hello"/>. A query for block of type HELLO <bcp14>MUST NOT</bcp14>
+ The <tt>HELLO</tt> block type wire format is illustrated in
+ <xref target="figure_hello"/>. A query for block of type <tt>HELLO</tt> <bcp14>MUST NOT</bcp14>
include extended query data (XQuery). Any implementation
- encountering a request for a HELLO with non-empty XQuery
+ encountering a request for a <tt>HELLO</tt> with non-empty XQuery
data <bcp14>MUST</bcp14> consider the request invalid and ignore it.
</t>
<figure anchor="figure_hello" title="The HELLO Block Format.">
@@ -2235,7 +2235,7 @@ BEGIN
denotes the absolute 64-bit expiration date of the content.
The value specified is microseconds since midnight (0 hour),
January 1, 1970, but must be a multiple of one million (so that it
- can be represented in seconds in a HELLO URL).
+ can be represented in seconds in a <tt>HELLO</tt> URL).
Stored in network byte order.
</dd>
<dt>ADDRESSES</dt>
@@ -2250,7 +2250,7 @@ BEGIN
<t>
is the signature of the HELLO.
It covers a 64-bit pseudo header
- derived from the information in the HELLO block.
+ derived from the information in the <tt>HELLO</tt> block.
The pseudo header includes
the expiration time, a constant that uniquely
identifies the purpose of the signature,
@@ -2299,24 +2299,24 @@ BEGIN
<dd>
a SHA-512 hash over the addresses in the HELLO.
H_ADDRS is generated over the ADDRESSES field
- as provided in the HELLO block using SHA-512 <xref target="RFC4634"/>.
+ as provided in the <tt>HELLO</tt> block using SHA-512 <xref target="RFC4634"/>.
</dd>
</dl>
</dd>
</dl>
<t>
- The HELLO block functions <bcp14>MUST</bcp14> be implemented
+ The <tt>HELLO</tt> block functions <bcp14>MUST</bcp14> be implemented
as follows:
</t>
<dl>
<dt>ValidateBlockQuery(Key, XQuery)
-> RequestEvaluationResult</dt>
<dd>
- To validate a block query for a HELLO is to simply check that the XQuery is empty. If it is empty, REQUEST_VALID ist returned. Otherwise, REQUEST_INVALID.
+ To validate a block query for a <tt>HELLO</tt> is to simply check that the XQuery is empty. If it is empty, REQUEST_VALID ist returned. Otherwise, REQUEST_INVALID.
</dd>
<dt>DeriveBlockKey(Block) -> Key | NONE</dt>
<dd>
- To derive a block key for a HELLO is to simply
+ To derive a block key for a <tt>HELLO</tt> is to simply
hash the peer ID from the HELLO. The result of this function
is always the SHA-512 hash over the PEER-ID.
</dd>
@@ -2333,15 +2333,15 @@ BEGIN
<dd>
<t>
<!-- FIXME: I do not understand this. Isn't the element set E known
- for HELLO blocks? Isn't it H_ADDRS XOR MUTATOR? -->
- The RESULT_FILTER for HELLO blocks is implemented using a
+ for <tt>HELLO</tt> blocks? Isn't it H_ADDRS XOR MUTATOR? -->
+ The RESULT_FILTER for <tt>HELLO</tt> blocks is implemented using a
Bloom filter following the definition from <xref target="bloom_filters"/>
and consists of a variable number of buckets <tt>L</tt>.
<tt>L</tt> depends on the number of elements <tt>|E|</tt> known to be filtered at the
initiator.
<!-- FIXME: Minimum space for used for what? There is no example given anywhere in the
spec how this becomes relevant. Again, this is not some abstract block,
- but specifically a HELLO (see above). -->
+ but specifically a <tt>HELLO</tt> (see above). -->
If <tt>|E|</tt> is zero, the size <tt>L</tt> is set to 32 bits to provide some minimum
space (to be used by peers when forwarding the request after
returning local results).
@@ -2354,7 +2354,7 @@ BEGIN
The elements used in the Bloom filter
consist of an XOR between the <tt>H_ADDRS</tt> field (as computed using
SHA-512 over the <tt>ADDRESSES</tt>) and the SHA-512
- hash of the <tt>MUTATOR</tt> field from a given HELLO block.
+ hash of the <tt>MUTATOR</tt> field from a given <tt>HELLO</tt> block.
The mapping function M(<tt>H_ADDRS XOR MUTATOR</tt>) is defined as follows:
</t>
<t>
@@ -2365,8 +2365,8 @@ BEGIN
This resulting byte string is interpreted as k=16 32-bit
integers in network byte order which are used to set and check the bucket bits in
<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 bucket field <tt>HELLO_BF</tt> containing <tt>B</tt>
- to create the result filter for a HELLO block:
+ The 32-bit Mutator is prepended to the L-bit Bloom filter bucket field <tt>HELLO_BF</tt> containing <tt>B</tt>
+ to create the result filter for a <tt>HELLO</tt> block:
</t>
<figure anchor="hello_rf" title="The HELLO Block Result Filter.">
<artwork name="" type="" align="left" alt=""><