[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[lsd0004] branch master updated (4b01724 -> e0b7c4a)
|
From: |
gnunet |
|
Subject: |
[lsd0004] branch master updated (4b01724 -> e0b7c4a) |
|
Date: |
Sun, 25 Dec 2022 15:46:12 +0100 |
This is an automated email from the git hooks/post-receive script.
martin-schanzenbach pushed a change to branch master
in repository lsd0004.
from 4b01724 More on connectivity management
new 811fe60 More connectivity description
new e0b7c4a tt for HELLO
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
draft-schanzen-r5n.xml | 156 +++++++++++++++++++++++++------------------------
1 file changed, 81 insertions(+), 75 deletions(-)
diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
index 9495cbf..e5b8218 100644
--- 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>
@@ -586,28 +586,15 @@ Connectivity | |Underlay| |Underlay|
<section anchor="routing_table">
<name>Routing Table</name>
<t>
+ Whenever a <tt>PEER_CONNECTED</tt> signal is received from the
Underlay,
+ the respective peer is considered for insertion into the routing
table.
The routing table consists of an array of k-buckets. Each
k-bucket contains a list of neighbors.
The i-th k-bucket stores neighbors whose peer IDs are between
distance 2^i and 2^(i+1) from the local peer.
System constraints will typically force an implementation to impose
some
upper limit on the number of neighbors kept per k-bucket.
- </t>
- <t>
- Initially, the implementation depends upon either the Underlay
providing at
- least one initial connection to a peer (signalled through
- <tt>PEER_CONNECTED</tt>), or the application/end-user providing at
- least one working HELLO which is then in turn used to call
<tt>TRY_CONNECT</tt>
- on the Underlay.
- This is commonly achieved through the configuration of hardcoded
bootstrap peers
- or bootstrap servers either for the Underlay or the R<sup>5</sup>N
implementation.
- While details on how the first connection is established
<bcp14>MAY</bcp14>
- depend on the specific implementation, this <bcp14>SHOULD</bcp14>
usually be done
- by an out-of-band exchange of the information from a HELLO block.
- <!-- FIXME: Is this really an encoding of a block? It seems to me
that "HELLO"
- is not properly defined.
- FIXME: Should? Isn't this part of the HelloMessage? -->
- For this, section <xref target="hello_url"/> specifies a URL format
for encoding HELLO
- blocks as text strings which <bcp14>SHOULD</bcp14> be supported by
implementations.
+ Upon insertion, the implementation <bcp14>MUST</bcp14> call
+ <tt>HOLD</tt> on the respective connection.
</t>
<t>
Implementations <bcp14>SHOULD</bcp14> try to keep at least
@@ -635,32 +622,51 @@ Connectivity | |Underlay| |Underlay|
<section anchor="find_peer">
<name>Peer Discovery</name>
<t>
- To build its routing table, a peer will send out requests
- asking for blocks of type HELLO using its own location as the key,
- but filtering all of its neighbors via the Bloom filter described
- in <xref target="result_filter"/>.
- These requests <bcp14>MUST</bcp14> use the FindApproximate and
DemultiplexEverywhere
- flags. FindApproximate will ensure that other peers will reply
- with keys they merely consider close-enough, while
DemultiplexEverywhere
+ Initially, the implementation depends upon either the Underlay
providing at
+ least one initial connection to a peer (signalled through
+ <tt>PEER_CONNECTED</tt>), or the application/end-user providing at
+ least one working <tt>HELLO</tt> which is then in turn used to call
<tt>TRY_CONNECT</tt>
+ on the Underlay in order to trigger a subsequent
<tt>PEER_CONNECTED</tt> signal
+ from the Underlay.
+ This is commonly achieved through the configuration of hardcoded
bootstrap peers
+ or bootstrap servers either for the Underlay or the R<sup>5</sup>N
implementation.
+ While details on how the first connection is established
<bcp14>MAY</bcp14>
+ depend on the specific implementation, this <bcp14>SHOULD</bcp14>
usually be done
+ by an out-of-band exchange of the information from a <tt>HELLO</tt>
block.
+ <!-- FIXME: Is this really an encoding of a block? It seems to me
that "HELLO"
+ is not properly defined.
+ FIXME: Should? Isn't this part of the HelloMessage? -->
+ For this, section <xref target="hello_url"/> specifies a URL format
for encoding HELLO
+ blocks as text strings which <bcp14>SHOULD</bcp14> be supported by
implementations.
+ </t>
+ <t>
+ <!-- FIXME REPL_LVL unclear, RF_SIZE unclear -->
+ To discover peers for its routing table, a peer will initiate
<tt>GetMessage</tt> requests
+ <xref target="p2p_get"/> asking for blocks of type <tt>HELLO</tt>
using its own peer address as
+ <tt>QUERY_HASH</tt>, filtering all of its neighbors via the Bloom
filter described
+ in <xref target="result_filter"/> and <xref target="hello_block"/>.
+ These requests <bcp14>MUST</bcp14> use the <tt>FindApproximate</tt>
and <tt>DemultiplexEverywhere</tt>
+ flags. <tt>FindApproximate</tt> will ensure that other peers will
reply
+ with keys they merely consider close-enough, while
<tt>DemultiplexEverywhere</tt>
will cause each peer on the path to respond, which is likely to yield
- HELLOs of peers that are useful somewhere in the routing table.
+ <tt>HELLO</tt> s of peers that are useful somewhere in the routing
table.
</t>
<t>
<!-- This here sais that this is a mandatory functionality. in
HelloMessage it
sais RECOMMENDED -->
To facilitate peer discovery, each peer <bcp14>MUST</bcp14>
broadcast its own
- HELLO message to all peers in the routing table periodically.
+ <tt>HELLO</tt> message to all peers in the routing table
periodically.
The specific frequency <bcp14>MAY</bcp14> depend on available
bandwidth
but <bcp14>SHOULD</bcp14> be a fraction of the expiration period.
- Whenever a peer receives such a HELLO message from another peer that
is
+ Whenever a peer receives such a <tt>HELLO</tt> message from
another peer that is
already in the routing table, it must cache it as long as that peer
is in its routing table
- (or until the HELLO expires) and serve it in response to
+ (or until the <tt>HELLO</tt> expires) and serve it in response to
<!-- FIXME wat is a Peer Discovery request??
- maybe a HELLO GET request?
+ maybe a <tt>HELLO</tt> GET request?
-->
Peer Discovery requests.
Details about the format of the
- HELLO message are given in <xref target="p2p_hello_wire"/>.
+ <tt>HELLO</tt> message are given in <xref target="p2p_hello_wire"/>.
</t>
<t>
The frequency of advertisement and peer discovery messages
@@ -673,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">
@@ -1221,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
@@ -1238,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>
@@ -1281,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>
@@ -1317,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.
@@ -1547,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.
@@ -1749,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
@@ -1992,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>.
@@ -2180,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.">
@@ -2229,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>
@@ -2244,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,
@@ -2293,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>
@@ -2327,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).
@@ -2348,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>
@@ -2359,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=""><![CDATA[
@@ -2403,7 +2409,7 @@ BEGIN
false-positives.
</t>
<t>
- HELLO result filters can be merged if the
+ <tt>HELLO</tt> result filters can be merged if the
Bloom filters have the same size and
<tt>MUTATOR</tt> by setting all bits to 1 that are
set in either Bloom filter. This is done whenever
@@ -2414,7 +2420,7 @@ BEGIN
<dt>FilterResult(Block, Key, RF, XQuery) ->
(FilterEvaluationResult, RF')</dt>
<dd>
The <tt>H_ADDRS</tt> field is XORed with the SHA-512
- hash of the <tt>MUTATOR</tt> field from the HELLO block and the
resulting
+ hash of the <tt>MUTATOR</tt> field from the <tt>HELLO</tt> block
and the resulting
value is checked against the Bloom filter in RF.
Consequently, HELLOs with completely identical sets of
addresses will be filtered and FILTER_DUPLICATE is returned.
@@ -2991,7 +2997,7 @@ Type | Name | References | Description
<section anchor="hello_url">
<name>HELLO URLs</name>
<t>
- The general format of a HELLO URL uses "gnunet://"
+ The general format of a <tt>HELLO</tt> URL uses "gnunet://"
as the scheme, followed by "hello/" for the name
of the GNUnet subsystem, followed by "/"-separated values
with the GNS Base32 encoding (<xref target="I-D.schanzen-gns"/>) of
@@ -3032,7 +3038,7 @@ maybe generate proper test vector.
DHT Underlay.
</t>
<t>
- The general syntax of HELLO URLs specified using
+ The general syntax of <tt>HELLO</tt> URLs specified using
Augmented Backus-Naur Form (ABNF) of <xref target="RFC5234"/> is:
</t>
<figure>
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.
- [lsd0004] branch master updated (4b01724 -> e0b7c4a),
gnunet <=