commit 4bc268fe86e04d5cde8176655d06b8ac92bc898b
parent bc291e7e85d2e8cfd3a9c1bd5d36a25df7a9e7b6
Author: Christian Grothoff <grothoff@gnunet.org>
Date: Fri, 11 Mar 2022 02:50:18 +0100
bootstrap editing, capitalize Bloom, add descripton of HELLO URIs
Diffstat:
1 file changed, 90 insertions(+), 28 deletions(-)
diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
@@ -7,6 +7,7 @@
<!ENTITY RFC3826 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3826.xml">
<!ENTITY RFC3986 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
<!ENTITY RFC4634 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4634.xml">
+<!ENTITY RFC5234 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5234.xml">
<!ENTITY RFC5869 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5869.xml">
<!ENTITY RFC5890 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5890.xml">
<!ENTITY RFC5891 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5891.xml">
@@ -617,17 +618,17 @@ Connectivity | |Underlay| |Underlay|
and message transmission.
</t>
</section>
- <section>
+ <section anchor="bootstrapping">
<name>Bootstrapping</name>
<t>
- Initially, the implementation depends upon either the Underlay to provide 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 to the DHT or the Underlay for bootstrapping.
+ 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 to the DHT for bootstrapping.
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.
- For this, section TBD specifies a URL format for encoding HELLO
+ by an out-of-band exchange of the information from a HELLO block.
+ 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>
@@ -637,26 +638,86 @@ Connectivity | |Underlay| |Underlay|
<xref target="routing_table"/>.
</t>
<t>
- Further, the Underlay must provide the implementation with one or more
- addresses signalled through <tt>ADDRESS_ADDED</tt>.
- The implementation then proceeds to periodically advertise all
+ 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.
+ The implementation periodically advertises all
active addresses in a HELLO block <xref target="hello_block"/>.
</t>
<t>
- In order to find more close peers in the network, an
- implementation <bcp14>MUST</bcp14> now periodically send find peer messages
+ In order to fill its routing table by finding close peers in the network, an
+ implementation <bcp14>MUST</bcp14> now periodically send peer discovery messages
<xref target="find_peer"/>.
</t>
<t>
- In both cases the frequency of advertisements and peer discovery
- <bcp14>MAY</bcp14> be adapted according to network conditions, connected peers,
- workload of the system and other factors which are at the discretion of
+ The frequency of advertisement and peer discovery messages
+ <bcp14>MAY</bcp14> be adapted according to network conditions,
+ the set of already connected neighbours,
+ the workload of the system and other factors which are at the discretion of
the developer.
</t>
<t>
- Any implementation encountering a HELLO GET request initially
- sends its own peer address.
+ Any implementation encountering a HELLO GET request <bcp14>MUST</bcp14> respond
+ with its own HELLO block except if that block is
+ filtered by the request's result filter (see <xref target="result_bloomfilter"/>).
+ Implementations <bcp14>MAY</bcp14> respond
+ with additional valid HELLO blocks of other peers with keys
+ closest to the key of the GET request. A HELLO block is "valid"
+ if it is non-expired, has a non-empty set of addresses, and
+ is not excluded by the result filter. "closest" is defined
+ by considering the distances between the request's key and the
+ peer addresses of all of the valid HELLO blocks known at the local node.
</t>
+ <section anchor="hello_url">
+ <name>HELLO URLs</name>
+ <t>
+ The general format of a HELLO 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 (described in FIXME: reference to GNS draft) of
+ the <tt>Peer ID</tt>, a Base32-encoded EdDSA signature, and an expiration
+ time in seconds since the UNIX Epoch in decimal format.
+ After this a "?" begins a list of key-value pairs where the key
+ is the URI schema of one of the peer's addresses and the value
+ is the URL-escaped payload of the address URI without the "://".
+ </t>
+ <t>
+ For example, consider the URL
+"""
+gnunet://hello/RH1M20EPK834M6MHZ72G3CMBSF3ECKNY4W0T9VAQP9Z7SZEM6Y3G/
+NGRTAH6RA04X467CGCH7M7CEXR5F9CV5HTZFK0G9BWETY3CCE2QWGVT4WA7JN5M9HMWG
+60A00R71F1PJP8N5628EKGHHBAGA7M8JW30/1647134480?udp=127.0.0.1%3A2086
+"""
+ It specifies that the peer with the ID "RH1M...6Y3G"
+ is reachable via "udp" at 127.0.0.1 on port 2086 until
+ 1647134480 seconds after the Epoch.
+ FIXME: signature is invalid, generate proper test vector.
+ </t>
+ <t>
+ The general syntax of HELLO URLs specified using
+ Augmented Backus-Naur Form (ABNF) of <xref target="RFC5234"/> is:
+ </t>
+ <figure>
+ <artwork type="abnf"><![CDATA[
+ hello-URL = "gnunet://hello/" meta [ "?" addrs ]
+ meta = pid "/" sig "/" exp
+ pid = *bchar
+ sig = *bchar
+ exp = *DIGIT
+ addrs = addr *( "&" addr )
+ addr = addr-name "=" addr-value
+ addr-name = scheme
+ addr-value = *pchar
+ bchar = *(ALPHA / DIGIT)
+ ]]>
+ </artwork>
+ </figure>
+ <t>
+ 'scheme' is defined in <xref target="RFC3986" /> in Section 3.1.
+ 'pchar' is defined in <xref target="RFC3986" />, Appendix A.
+ </t>
+ </section>
</section>
<section anchor="routing" numbered="true" toc="default">
<name>Routing</name>
@@ -681,20 +742,20 @@ Connectivity | |Underlay| |Underlay|
<section anchor="routing_bloomfilter">
<name>Peer Bloom Filter</name>
<t>
- The peer bloom filter is used to prevent circular routes.
+ The peer Bloom filter is used to prevent circular routes.
Any peer which is forwarding GET or PUT messages
(<xref target="p2p_messages"/>) adds its own peer ID to the
- message bloom filter.
+ message Bloom filter.
This allows other peers to lookup next hops while excluding already
traversed peers (<xref target="routing_table"/>).
</t>
<t>
- The bloom filter is a 128-bit field.
+ The Bloom filter is a 128-bit field.
It is initially empty, consisting only of zeroes.
There are two functions which can be invoked on the Bloom filter:
BF-SET(bf, e) and BF-TEST(bf, e) where "e" is an element which is to
be added to the Bloom filter or queried against the set.
- Any bloom filter uses k=16 different hash functions each of which is
+ Any Bloom filter uses k=16 different hash functions each of which is
defined as follows:
</t>
</section>
@@ -860,21 +921,21 @@ Connectivity | |Underlay| |Underlay|
<section anchor="result_bloomfilter">
<name>Result Bloom Filter</name>
<t>
- The result bloom filter is used to indicate to a peer which results
+ The result Bloom filter is used to indicate to a peer which results
are not of interest when processing a GET message
(<xref target="p2p_get"/>).
Any peer which is processing GET messages and has a result
- which matches the query key <bcp14>MUST</bcp14> check the result bloom filter
+ which matches the query key <bcp14>MUST</bcp14> check the result Bloom filter
and only send a reply message if the block key is not in the
- bloom filter set.
+ Bloom filter set.
</t>
<t>
- The bloom filter is a 128-bit field.
+ The Bloom filter is a 128-bit field.
It is initially empty, consisting only of zeroes.
There are two functions which can be invoked on the Bloom filter:
BF-SET(bf, e) and BF-TEST(bf, e) where "e" is an element which is to
be added to the Bloom filter or queried against the set.
- Any bloom filter uses k=16 different hash functions each of which is
+ Any Bloom filter uses k=16 different hash functions each of which is
defined as follows:
</t>
</section>
@@ -1341,7 +1402,7 @@ Connectivity | |Underlay| |Underlay|
</li>
<li>
The peer address of the sender peer <tt>P</tt> <bcp14>SHOULD</bcp14> be in the
- PEER_BF bloom filter. If not, the
+ PEER_BF Bloom filter. If not, the
implementation <bcp14>MAY</bcp14> log an error, but <bcp14>MUST</bcp14> continue.
</li>
<li>
@@ -1392,7 +1453,7 @@ Connectivity | |Underlay| |Underlay|
number of peers to forward the message to. The implementation <bcp14>MAY</bcp14>
forward to fewer or no peers in order to handle resource constraints
such as bandwidth.
- The message bloom filter PEER_BF <bcp14>MUST</bcp14> be updated with the local
+ The message Bloom filter PEER_BF <bcp14>MUST</bcp14> be updated with the local
peer address <tt>N</tt>.
For all peers with peer address <tt>P'</tt> chosen to forward the message
to, <tt>SEND(P', PutMessage)</tt> is called.
@@ -1975,6 +2036,7 @@ Purpose | Name | References | Description
&RFC3629;
&RFC3986;
&RFC4634;
+ &RFC5234;
&RFC6940;
&RFC8126;
&RFC8174;
