commit a7c2f5e62fa036ac6f842e4703f2c8a14511bc26
parent 80faf5bfe2e4ad44594532b44a94adbfc98fa1ee
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Mon, 21 Aug 2023 16:36:46 +0200
Rename
Peer ID -> Peer public key
Peer Address -> Peer identity
Diffstat:
1 file changed, 62 insertions(+), 63 deletions(-)
diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
@@ -195,17 +195,17 @@
is a UTF-8 <xref target="RFC3629"/> URI
<xref target="RFC3986"/> which can be
used to contact a <em>peer</em>.
- An example of an addressing scheme used in
- this document is "r5n+ip+tcp", which refers to a standard TCP/IP socket
- connection. The "hier"-part of the URI must provide a suitable
+ In this document we use the example scheme for URIs.
+ It is expected that schemes refer suitable transport protocols
+ are used.
+ The "hier"-part of the URI must provide a suitable
address for the given addressing scheme.
The following are non-normative examples of <em>address</em> strings:
</t>
<figure title="Example Address URIs.">
<artwork name="" type="" align="left" alt=""><![CDATA[
-r5n+ip+udp://1.2.3.4:6789/
-r5n+quic://example.com/
-gnunet+tcp://12.3.4.5/
+example://1.2.3.4:6789/
+example://12.3.4.5/
]]></artwork>
</figure>
</dd>
@@ -274,7 +274,7 @@ gnunet+tcp://12.3.4.5/
<dt>Key</dt>
<dd>
512-bit identifier of a location in the DHT. Multiple <tt>Block</tt>s can be
- stored under the same <em>key</em>. A <em>peer address</em> is also a <tt>key</tt>.
+ stored under the same <em>key</em>. A <em>peer identity</em> is also a <tt>key</tt>.
In the context of "key-value stores" this
refers to "key" under which values (<em>blocks</em>) are stored.
</dd>
@@ -298,19 +298,15 @@ gnunet+tcp://12.3.4.5/
messages on behalf of other <em>peers</em> as needed by the <em>routing
algorithm</em>.
</dd>
- <!-- FIXME: this overloads the term 'address'. We should use 'Peer Identity'! -->
- <dt>Peer Address</dt>
+ <dt>Peer Identity</dt>
<dd>
- The <em>peer address</em> is the identifier used on the overlay
- to identify a <em>peer</em>. It is a SHA-512 hash of the <em>peer ID</em>.
+ The <em>peer identity</em> is the identifier used on the overlay
+ to identify a <em>peer</em>. It is a SHA-512 hash of the <em>peer public key</em>.
</dd>
- <!-- FIXME: this obscures the public key nature. We should use "Peer Public Key"! -->
- <dt>Peer ID</dt>
+ <dt>Peer Public Key</dt>
<dd>
- The <em>peer ID</em> is the public key which is used to authenticate
+ The <em>peer public key</em> is the key used to authenticate
a <em>peer</em> in the underlay.
- The <em>peer ID</em> is the public key of the corresponding
- Ed25519<xref target="ed25519" /> peer private key.
</dd>
<dt>Routing</dt>
<dd>
@@ -671,7 +667,7 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
the respective peer is considered for insertion into the routing table.
The routing table consists of an array of <tt>k</tt>-buckets. Each
<tt>k</tt>-bucket contains a list of <em>neighbors</em>.
- The i-th <tt>k</tt>-bucket stores neighbors whose peer IDs are
+ The i-th <tt>k</tt>-bucket stores neighbors whose peer public keys are
between distance 2<sup>i</sup> and 2<sup>i+1</sup> from the local peer.
System constraints will typically force an implementation to impose some
upper limit on the number of <em>neighbors</em> kept per <tt>k</tt>-bucket.
@@ -724,9 +720,9 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
</t>
<t>
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
+ <xref target="p2p_get"/> asking for blocks of type <tt>HELLO</tt> using its own peer identity
in the <tt>QUERY_HASH</tt> field of the message.
- The <tt>PEER_BF</tt> is initialized and set using the peers own peer address as well as the addresses
+ The <tt>PEER_BF</tt> is initialized and set using the peers own peer identity as well as the identities
of all currently connected <em>neighbors</em>. <!-- note: we mean the identities here! FIX with terminology... -->
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
@@ -773,14 +769,14 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
</t>
<t>
Any peer which is forwarding <tt>GetMessage</tt>s or <tt>PutMessage</tt>s
- (<xref target="p2p_messages"/>) adds its own peer ID to the
+ (<xref target="p2p_messages"/>) adds its own peer public key to the
peer Bloom filter.
This allows other peers to (probabilistically) exclude already
traversed peers when searching for the next hops in the routing table.
</t>
<t>
The peer Bloom filter follows the definition in <xref target="bloom_filters"/>.
- The set of elements <tt>E</tt> consists of of all possible 256-bit peer IDs.
+ The set of elements <tt>E</tt> consists of of all possible 256-bit peer public keys.
The mapping function <tt>M</tt> is defined as follows:
</t>
<t>
@@ -969,7 +965,7 @@ BEGIN
Whether initiated locally or received from a neighbor, an implementation
processes messages according to the wire formats and the required
validations detailed in the following sections.
- Where required, the local peer's ID is referred to as <tt>SELF</tt>.
+ Where required, the local peer public key is referred to as <tt>SELF</tt>.
</t>
<section anchor="message_components">
<name>Message components</name>
@@ -1043,7 +1039,7 @@ BEGIN
| |
| |
+-----+-----+-----+-----+-----+-----+-----+-----+
-| PRED PEER ID |
+| PRED PEER PUBLIC KEY |
| (32 bytes) |
| |
| |
@@ -1055,9 +1051,9 @@ BEGIN
<dt>SIGNATURE</dt>
<dd>
is a 64 byte EdDSA signature using the current hop's private
- key affirming the peer IDs of the previous and next hops.
+ key affirming the peer public keys of the previous and next hops.
</dd>
- <dt>PEER ID</dt>
+ <dt>PRED PEER PUBLIC KEY</dt>
<dd>
is the EdDSA public key of the previous peer on the path.
</dd>
@@ -1065,9 +1061,9 @@ BEGIN
<t>
An ordered list of path elements may be appended to any routed
<tt>PutMessage</tt>s or <tt>ResultMessage</tt>s.
- The last signature (after which the peer ID is omitted)
+ The last signature (after which the peer public key is omitted)
is created by the current hop only after the peer made its routing
- decision identifiying the successor peer. The peer ID is not
+ decision identifiying the successor peer. The peer public key is not
included after the last signature as it must be that of the sender of
the message. Similarly, the predecessor of the first element of
an untruncated path is not stated explicitly, as it must be ZERO.
@@ -1146,15 +1142,15 @@ BEGIN
<t>
A path may be truncated in which case the signature of the truncated
- path element is omitted leaving only the peer ID of the peer preceeding
+ path element is omitted leaving only the public key of the peer preceeding
the trunction which is required for the
verification of the subsequent path element signature.
Such a truncated path is indicated with the respective
truncated flag (<xref target="route_flags"/>).
- For truncated paths, the peer ID of the signer of the last path element is
+ For truncated paths, the peer public key of the signer of the last path element is
again omitted as it must be that of
the sender of the <tt>PutMesssage</tt> or <tt>ResultMessage</tt>. Similarly,
- the peer ID of the receiving peer used in the last path element is omitted as
+ the public key of the receiving peer used in the last path element is omitted as
it must be SELF.
The wire format of a truncated example path from peers B over C and D to E
(possibly still originating at A, but the origin is unknowable to E due to truncation)
@@ -1203,7 +1199,7 @@ BEGIN
<t>
The SIGNATURE field in a path element covers a 64-bit contextualization header, the
the block expiration, a hash of the block
- payload, as well as the predecessor peer ID and the peer ID of the
+ payload, as well as the predecessor peer public key and the peer public key of the
successor that the peer making the signature is routing the
message to. Thus, the signature made by SELF basically says that
SELF received the block payload from PEER PREDECESSOR and has forwarded
@@ -1263,12 +1259,12 @@ BEGIN
</dd>
<dt>PEER PREDECESSOR</dt>
<dd>
- the peer ID of the previous hop. If the signing peer initiated
+ the peer public key of the previous hop. If the signing peer initiated
the PUT, this field is set to all zeroes.
</dd>
<dt>PEER SUCCESSOR</dt>
<dd>
- the peer ID of the next hop (not of the signer).
+ the peer public key of the next hop (not of the signer).
</dd>
</dl>
</section>
@@ -1295,7 +1291,7 @@ BEGIN
<artwork name="" type="" align="left" alt=""><![CDATA[
0 8 16 24 32 40 48 56
+-----+-----+-----+-----+-----+-----+-----+-----+
-| MSIZE | MTYPE | RESERVED | URL_CTR |
+| MSIZE | MTYPE | RESERVED | NUM_ADDRS |
+-----+-----+-----+-----+-----+-----+-----+-----+
| SIGNATURE /
/ (64 bytes) |
@@ -1322,7 +1318,7 @@ BEGIN
<dd>
is a 16-bit field that must be zero.
</dd>
- <dt>URL_CTR</dt>
+ <dt>NUM_ADDRS</dt>
<dd>
is a 16-bit number that gives the total number of
addresses encoded in the ADDRESSES field.
@@ -1345,7 +1341,7 @@ BEGIN
</dd>
<dt>ADDRESSES</dt>
<dd>
- A sequence of exactly URL_CTR
+ A sequence of exactly NUM_ADDRS
addresses (<xref target="terminology"/>)
which can be used to contact the peer.
Each address <bcp14>MUST</bcp14> be 0-terminated.
@@ -1488,7 +1484,7 @@ BEGIN
<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 ID using <tt>BF-SET</tt>.
+ Modified by processing peers to include their own peer public key using <tt>BF-SET</tt>.
</dd>
<dt>BLOCK_KEY</dt>
<dd>
@@ -1571,7 +1567,7 @@ BEGIN
is invalid, the message <bcp14>MUST</bcp14> be discarded.
</li>
<li>
- The peer address of the sender peer <tt>P</tt> <bcp14>SHOULD</bcp14> be in <tt>PEER_BF</tt>.
+ The peer identity of the sender peer <tt>P</tt> <bcp14>SHOULD</bcp14> be in <tt>PEER_BF</tt>.
If not, the implementation <bcp14>MAY</bcp14> log an error, but <bcp14>MUST</bcp14> continue.
</li>
<li>
@@ -1598,7 +1594,7 @@ BEGIN
<li>
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 by using the peer address in <tt>BLOCK_KEY</tt>.
+ table by using the peer identity in <tt>BLOCK_KEY</tt>.
If the peer is not either already connected or the respective k-bucket is
not already full the peer <bcp14>MUST</bcp14> try to establish a
connection to the peer indicated in the <tt>HELLO</tt> block using
@@ -1617,17 +1613,20 @@ BEGIN
using <tt>ComputeOutDegree()</tt>.
The implementation <bcp14>SHOULD</bcp14> select up to this
number of peers to forward the message to using the function <tt>SelectPeer()</tt> (<xref target="routing_functions"/>)
- using the <tt>BLOCK_KEY</tt>, <tt>HOPCOUNT</tt>, an appropriate bloom filter (FIXME: PEER_BF?).
+ using the <tt>BLOCK_KEY</tt>, <tt>HOPCOUNT</tt>, and utilizing <tt>PEER_BF</tt> as Bloom filter.
+ For each selected peer <tt>PEER_BF</tt> is updated with that peer
+ in between calls to <tt>SelectPeer()</tt>.
The implementation <bcp14>MAY</bcp14>
forward to fewer or no peers in order to handle resource constraints
- such as limited bandwidth.
- For each selected peer with peer address <tt>P</tt> a dedicated <tt>PutMessage_P</tt>
+ such as limited bandwidth or simply if there are not suitable
+ peers.
+ For each selected peer with peer identity <tt>P</tt> a dedicated <tt>PutMessage_P</tt>
is created containing the original (and where applicable already updated) fields
of the received <tt>PutMessage</tt>.
- In each message the all selected addresses and the local peer <bcp14>MUST</bcp14> be added to the
+ In each message the all selected peer identities and the local peer identity <bcp14>MUST</bcp14> be added to the
<tt>PEER_BF</tt> and the <tt>HOPCOUNT</tt> is incremented by 1.
If the <tt>RecordRoute</tt> flag is set, a new path element is created using the
- predecessor peer ID and the signature of the current peer.
+ predecessor peer public key and the signature of the current peer.
The path element is added to the <tt>PUTPATH</tt> fields and the <tt>PATH_LEN</tt> field is incremented by 1.
When creating the path element signature, the successor must be set to the recipient peer <tt>P</tt> of the <tt>PutMessageP</tt>.
The successor in the new path element is the recipient peer <tt>P</tt> of Finally, the messages are sent using <tt>SEND(P, PutMessageP)</tt> each recipient.
@@ -1715,7 +1714,7 @@ BEGIN
<dd>
A peer Bloom filter to stop circular routes (see <xref target="routing_bloomfilter"/>).
Set by the initiator to include itself and all connected neighbors in the routing table.
- Modified by processing peers to include their own peer address.
+ Modified by processing peers to include their own peer identity.
</dd>
<dt>QUERY_HASH</dt>
<dd>
@@ -1783,7 +1782,7 @@ BEGIN
without validation.
</li>
<li>
- The peer address of the sender peer <tt>P</tt> <bcp14>SHOULD</bcp14> be in the
+ The peer identity of the sender peer <tt>P</tt> <bcp14>SHOULD</bcp14> be in the
<tt>PEER_BF</tt> Bloom filter. If not, the
implementation <bcp14>MAY</bcp14> log an error, but <bcp14>MUST</bcp14> continue.
</li>
@@ -1859,8 +1858,8 @@ BEGIN
forward to fewer or no peers in order to handle resource constraints
such as bandwidth.
The peer Bloom filter <tt>PEER_BF</tt> <bcp14>MUST</bcp14> be updated with the local
- peer address <tt>SELF</tt> for any forwarded message.
- For all peers with peer address <tt>P</tt> chosen to forward the message
+ peer identity <tt>SELF</tt> for any forwarded message.
+ For all peers with peer identity <tt>P</tt> chosen to forward the message
to, <tt>SEND(P, GetMessageP)</tt> is called. Here, <tt>GetMessageP</tt>
is the original message with the updated fields for <tt>HOPCOUNT</tt> (incremented
by 1), <tt>PEER_BF</tt> and <tt>RESULT_FILTER</tt>.
@@ -2065,7 +2064,7 @@ BEGIN
<li>
If the <tt>BTYPE</tt> of the message indicates a <tt>HELLO</tt> block, the
peer <bcp14>SHOULD</bcp14> be considered for the local routing
- table by using the peer address computed from the block using <tt>DeriveBlockKey</tt>.
+ table by using the peer identity computed from the block using <tt>DeriveBlockKey</tt>.
An implementation <bcp14>MAY</bcp14> choose to ignore the <tt>HELLO</tt>, for example
because the routing table or the respective k-bucket is already full.
If the peer is a suitable candidate for insertion, the local peer <bcp14>MUST</bcp14> try to establish a connection
@@ -2108,7 +2107,7 @@ BEGIN
</li>
<li>
If the <tt>RecordRoute</tt> flag is set in FLAGS,
- the local peer address <bcp14>MUST</bcp14> be appended to the <tt>GETPATH</tt>
+ the local peer identity <bcp14>MUST</bcp14> be appended to the <tt>GETPATH</tt>
of the message and the respective signature <bcp14>MUST</bcp14> be
set using the query origin as the <tt>PEER SUCCESSOR</tt> and the
response origin as the <tt>PEER PREDECESSOR</tt>. If the flag is not set,
@@ -2260,9 +2259,9 @@ BEGIN
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 <tt>HELLO</tt> together
+ contains the peer public key 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.
+ is the SHA-512 of the peer public key and thus the peer's identity in the DHT.
</t>
<t>
The <tt>HELLO</tt> block type wire format is illustrated in
@@ -2275,7 +2274,7 @@ BEGIN
<artwork name="" type="" align="left" alt=""><![CDATA[
0 8 16 24 32 40 48 56
+-----+-----+-----+-----+-----+-----+-----+-----+
-| PEER-ID |
+| PEER PUBLIC KEY |
| (32 byte) |
| |
| |
@@ -2297,9 +2296,9 @@ BEGIN
]]></artwork>
</figure>
<dl>
- <dt>PEER-ID</dt>
+ <dt>PEER PUBLIC KEY</dt>
<dd>
- is the Peer-ID of the peer which has generated this HELLO.
+ is the public key of the peer which has generated this HELLO.
</dd>
<dt>EXPIRATION</dt>
<dd>
@@ -2388,15 +2387,15 @@ BEGIN
<dt>DeriveBlockKey(Block) -> Key | NONE</dt>
<dd>
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.
+ hash the peer public key from the HELLO. The result of this function
+ is always the SHA-512 hash over the PEER PUBLIC KEY.
</dd>
<dt>ValidateBlockStoreRequest(Block)
-> BlockEvaluationResult</dt>
<dd>
To validate a block store request is to verify
the EdDSA <tt>SIGNATURE</tt> over the hashed <tt>ADDRESSES</tt>
- against the public key from the peer ID field.
+ against the public key from the PEER PUBLIC KEY field.
If the signature is valid BLOCK_VALID is returned.
Otherwise BLOCK_INVALID.
</dd>
@@ -2582,7 +2581,7 @@ BEGIN
</t>
<t>
An implementation <bcp14>MAY</bcp14> preserve blocks which are close
- to the local peer ID.
+ to the local peer public key.
</t>
<t>
An implementation <bcp14>MAY</bcp14> provide configurable storage
@@ -3013,7 +3012,7 @@ Type | Name | References | Description
</dd>
<dt>GET-Path:</dt>
<dd>
- is a signed path of the IDs of peers which the query
+ is a signed path of the public keys of peers which the query
traversed through the network. The DHT will try to make
the path available if the <tt>RecordRoute</tt> flag was set by
the application calling the PUT procedure. The reported
@@ -3021,7 +3020,7 @@ Type | Name | References | Description
</dd>
<dt>PUT-Path:</dt>
<dd>
- is a signed path of the IDs of peers which the
+ is a signed path of the public keys of peers which the
result message traversed. The DHT will try to make the
path available if the <tt>RecordRoute</tt> flag was set for the GET procedure.
The reported path may have been silently truncated from the beginning.
@@ -3082,7 +3081,7 @@ Type | Name | References | Description
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
- the <tt>Peer ID</tt>, a Base32-encoded EdDSA signature, and an expiration
+ the peer public key, 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 scheme of one of the peer's addresses and the value
@@ -3106,7 +3105,7 @@ maybe generate proper test vector.
</artwork>
</figure>
<t>
- It specifies that the peer with the ID "RH1M...6Y3G"
+ It specifies that the peer with the public key "RH1M...6Y3G"
is reachable via "udp" at 127.0.0.1 on port 2086 until
1647134480 seconds after the Epoch. Note that "udp"
here is underspecified and just used as a simple example.
