[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[lsd0004] branch master updated: -formatting, plus make sure block funct
|
From: |
gnunet |
|
Subject: |
[lsd0004] branch master updated: -formatting, plus make sure block functions are nicely integrated with message processing text |
|
Date: |
Sat, 12 Mar 2022 01:24:04 +0100 |
This is an automated email from the git hooks/post-receive script.
grothoff pushed a commit to branch master
in repository lsd0004.
The following commit(s) were added to refs/heads/master by this push:
new a42ff25 -formatting, plus make sure block functions are nicely
integrated with message processing text
a42ff25 is described below
commit a42ff2589ab8805118296e3c28d07b34682cc14f
Author: Christian Grothoff <grothoff@gnunet.org>
AuthorDate: Sat Mar 12 01:23:50 2022 +0100
-formatting, plus make sure block functions are nicely integrated with
message processing text
---
draft-schanzen-r5n.xml | 140 ++++++++++++++++++++++++++++---------------------
1 file changed, 81 insertions(+), 59 deletions(-)
diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
index be26f96..19f5768 100644
--- a/draft-schanzen-r5n.xml
+++ b/draft-schanzen-r5n.xml
@@ -845,7 +845,7 @@ bchar = *(ALPHA / DIGIT)
<section anchor="routing_bloomfilter">
<name>Peer Bloom Filter</name>
<t>
- As DHT GET and PUT messages traverse a random path through the
network for the
+ As DHT <tt>GetMessage</tt>s and <tt>PutMessage</tt>s traverse a
random path through the network for the
first N hops, it is essential that routing loops are avoided.
In R<sup>5</sup>N, a Bloom filter is used as part of the routing
metadata in
messages. The Bloom filter is updates at each hop with the hops
@@ -856,7 +856,7 @@ bchar = *(ALPHA / DIGIT)
</t>
<t>
The peer Bloom filter is used to prevent circular routes.
- Any peer which is forwarding GET or PUT messages
+ 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
peer Bloom filter.
This allows other peers to (probabilistically) exclude already
@@ -959,8 +959,8 @@ bchar = *(ALPHA / DIGIT)
<dd>
This bit indicates that each peer along the way should process the
request.
If the bit is not set, peers only route the message and do not
- look for answers in their local storage (for GET) or cache the
- block in their local storage (for PUT or RESULT).
+ look for answers in their local storage (for <tt>GetMessage</tt>s)
or cache the
+ block in their local storage (for <tt>PutMessage</tt>s or
<tt>ResultMessage</tt>s).
</dd>
<dt>1: RecordRoute</dt>
<dd>
@@ -986,7 +986,7 @@ bchar = *(ALPHA / DIGIT)
A Path Element represents a hop in the path a message has taken
through the network.
An ordered list of Path Elements may be appended to any routed
- PUT or RESULT message.
+ <tt>PutMessage</tt>s or <tt>ResultMessage</tt>s.
A Path Element identifies a peer on the path.
The Path Element is signed by the next peer on the path after
the next peer made its routing decision.
@@ -1290,7 +1290,7 @@ bchar = *(ALPHA / DIGIT)
</dd>
<dt>BLOCK_KEY</dt>
<dd>
- The key under which the PUT request wants to store content
+ The key under which the <tt>PutMessage</tt> wants to store
content
under.
</dd>
<dt>PUTPATH</dt>
@@ -1320,16 +1320,22 @@ bchar = *(ALPHA / DIGIT)
<li>
If the <tt>BTYPE</tt> is not supported by the implementation,
no validation of the block payload is performed and processing
- continues at (4).
- Else, the block <bcp14>MUST</bcp14> be validated as defined in
(3).
+ continues at (5).
+ Else, the block <bcp14>MUST</bcp14> be validated as defined in
(3) and (4).
</li>
<li>
- The block payload of the message is evaluated according
- to the <tt>BTYPE</tt> using the respective
- <tt>ValidateBlockStoreRequest</tt> procedure
- as described in <xref target="block_functions"/>.
- If the block payload is invalid or does not match the key,
- it <bcp14>MUST</bcp14> be discarded.
+ The message is evaluated using the block validation functions
matching
+ the <tt>BTYPE</tt>. First, the client attempts to
+ derive the key using the respective <tt>DeriveBlockKey</tt>
procedure
+ as described in <xref target="block_functions"/>. If a key can be
+ derived and does not match, the message <bcp14>MUST</bcp14> be
discarded.
+ </li>
+ <li>
+ Next, the <tt>ValidateBlockStoreRequest</tt> procedure for the
<tt>BTYPE</tt>
+ as described in <xref target="block_functions"/> is used to
+ validate the block payload. If a key could not be derived in
the previous step, the
+ key from the request is used for validation. If the block payload
+ 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>.
@@ -1459,12 +1465,12 @@ bchar = *(ALPHA / DIGIT)
<name>Result Bloom Filter</name>
<t>
The result Bloom filter is used to indicate to other peers which
results
- are not of interest when processing a GET message
+ are not of interest when processing a <tt>GetMessage</tt>
(<xref target="p2p_get"/>).
- Any peer which is processing GET messages and has a result
+ Any peer which is processing <tt>GetMessage</tt>s and has a result
which matches the query key <bcp14>MUST</bcp14> check the result
Bloom filter
and only send a reply message if the result does not test positive
- under the result Bloom filter. Before forwarding the GET message,
the
+ under the result Bloom filter. Before forwarding the
<tt>GetMessage</tt>, the
result Bloom filter <bcp14>MUST</bcp14> be updated to filter out
all results
already returned by the local peer.
</t>
@@ -1485,7 +1491,7 @@ bchar = *(ALPHA / DIGIT)
value is set by the peer initiating the GET request, and changed
every time the GET request is repeated by the initiator. Peers
forwarding GET requests <bcp14>MUST</bcp14> not change the
- mutator value included in the GET message as they could not
+ mutator value included in the <tt>GetMessage</tt> as they could not
recalculate the Bloom filter with the new mutator value.
</t>
<t>
@@ -1516,14 +1522,14 @@ bchar = *(ALPHA / DIGIT)
against the
requested <tt>BTYPE</tt> as defined by its respective
<tt>ValidateBlockQuery</tt> procedure.
+ If validation
+ function yields <tt>REQUEST_INVALID</tt>, the message
<bcp14>MUST</bcp14> be discarded.
If the <tt>BTYPE</tt> is not supported, the message
<bcp14>MUST</bcp14>
- be forwarded without query validation.
- However, If the <tt>BTYPE</tt> is supported and the
<tt>XQUERY</tt>
- is malformed, the message <bcp14>MUST</bcp14> be discarded.
+ be forwarded.
</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
+ <tt>PEER_BF</tt> Bloom filter. If not, the
implementation <bcp14>MAY</bcp14> log an error, but
<bcp14>MUST</bcp14> continue.
</li>
<li>
@@ -1569,14 +1575,14 @@ bchar = *(ALPHA / DIGIT)
highest priority among competing transmissions.
</t>
<t>
- If the BTYPE is supported and <tt>ValidateBlockReply</tt> for
the given
+ If the <tt>BTYPE</tt> is supported and
<tt>ValidateBlockReply</tt> for the given
query has yielded a status of <tt>FILTER_LAST</tt>, processing
<bcp14>MUST</bcp14> end and not continue with forwarding of
the request to other peers.
</t>
</li>
<li>
- Given the value in REPL_LVL, the number of peers to forward to
+ Given the value in <tt>REPL_LVL</tt>, the number of peers to
forward to
<bcp14>MUST</bcp14> be calculated
(FIXME: as above, we need to describe here how to calulate
NUM-FORWARD-peerS).
If there is at least one
@@ -1584,7 +1590,7 @@ bchar = *(ALPHA / DIGIT)
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 peer Bloom filter <tt>PEER_BF</tt> <bcp14>MUST</bcp14> be
updated with the local
peer address <tt>SELF</tt>.
For all peers with peer address <tt>P'</tt> chosen to forward
the message
to, <tt>SEND(P', GetMessage')</tt> is called. Here,
<tt>GetMessage'</tt>
@@ -1651,13 +1657,15 @@ bchar = *(ALPHA / DIGIT)
<dt>PUTPATH_L</dt>
<dd>
is a 16-bit number indicating the length of the PUT path recorded
- in PUTPATH. As PUTPATH is optional, this value may be zero.
+ in <tt>PUTPATH</tt>. As <tt>PUTPATH</tt> is optional, this value
may be zero
+ even if the message has traversed several peers.
In network byte order.
</dd>
<dt>GET_PATH_LEN</dt>
<dd>
is a 16-bit number indicating the length of the GET path recorded
- in GETPATH. As PUTPATH is optional, this value may be zero.
+ in <tt>GETPATH</tt>. As <tt>GETPATH</tt> is optional, this value
may be zero
+ even if the message has traversed several peers.
In network byte order.
</dd>
<dt>EXPIRATION</dt>
@@ -1668,18 +1676,18 @@ bchar = *(ALPHA / DIGIT)
</dd>
<dt>QUERY_HASH</dt>
<dd>
- the query hash corresponding to the GET message which
+ the query hash corresponding to the <tt>GetMessage</tt> which
caused this reply message to be sent.
</dd>
<dt>PUTPATH</dt>
<dd>
the variable-length PUT path.
- The path consists of a list of PATH_LEN Path Elements.
+ The path consists of a list of <tt>PUT_PATH_LEN</tt> Path
Elements.
</dd>
<dt>GETPATH</dt>
<dd>
the variable-length PUT path.
- The path consists of a list of PATH_LEN Path Elements.
+ The path consists of a list of <tt>GET_PATH_LEN</tt> Path
Elements.
</dd>
<dt>BLOCK</dt>
<dd>
@@ -1696,25 +1704,29 @@ bchar = *(ALPHA / DIGIT)
</t>
<ol>
<li>
- The <tt>EXPIRATION</tt> field is evaluated.
+ First, the <tt>EXPIRATION</tt> field is evaluated.
If the message is expired, it <bcp14>MUST</bcp14> be discarded.
</li>
<li>
- If the BTYPE is supported, then the <tt>BLOCK</tt>
+ If the <tt>BTYPE</tt> is supported, then the <tt>BLOCK</tt>
<bcp14>MUST</bcp14> be validated against the
- requested BTYPE. To do this, the peer attempts to compute the
- key using <tt>DeriveBlockKey</tt>. If the result is "fail", the
- message <bcp14>MUST</bcp14> be discarded. Note that the result
- "none" does not count as a failure. The computed key also
- does not have to match the <tt>QUERY_HASH</tt> at this time.
+ requested <tt>BTYPE</tt>. To do this, the peer attempts to
compute the
+ key using <tt>DeriveBlockKey</tt>. Note that the computed key
+ does not have to match the <tt>QUERY_HASH</tt>. Next, the peer
+ checks that the block is valid using
<tt>ValidateBlockStoreRequest</tt>
+ using the derived key if it is available. If the derived key is
+ <tt>NONE</tt>, the query hash is passed to
<tt>ValidateBlockStoreRequest</tt>
+ instead of a key. If the
+ result is <tt>BLOCK_INVALID</tt>, the message <bcp14>MUST</bcp14>
be
+ discarded.
</li>
<li>
- If the sender of the message is already found in the
- GETPATH, the path <bcp14>MUST</bcp14> be truncated at this
position.
+ If the sender of the message is already found on the
+ <tt>GETPATH</tt>, the path <bcp14>MUST</bcp14> be truncated at
this position.
The implementation <bcp14>MAY</bcp14> log a warning in such a
case.
</li>
<li>
- If the MTYPE of the message indicates a HELLO block, the
+ If the <tt>MTYPE</tt> of the message indicates a HELLO 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
@@ -1730,27 +1742,37 @@ bchar = *(ALPHA / DIGIT)
</t>
<ol type="%c)">
<li>
- If the BTYPE is supported, result block <bcp14>MUST</bcp14>
+ If the approximate flag was not set in the query and the
<tt>BTYPE</tt> allowed the
+ implementation to compute the key from the block, the
computed key must
+ exactly match the <tt>QUERY_HASH</tt>, otherwise the result
does
+ not match the pending query and processing continues with the
next pending query.
+ </li>
+ <li>
+ If the <tt>BTYPE</tt> is supported, result block
<bcp14>MUST</bcp14>
be validated against the specific query using
- the respective <tt>ValidateBlockReply</tt> function.
+ the respective <tt>FilterBlockResult</tt> function, possibly
updating
+ the result Bloom filter of the query in the process.
</li>
<li>
- If the BTYPE is not supported, filtering of exact duplicate
+ If the <tt>BTYPE</tt> is not supported, filtering of exact
duplicate
replies <bcp14>MUST</bcp14> still be performed before
forwarding
- the reply. Such duplicate filtering <bcp14>MAY</bcp14> be
implemented
+ the reply.
+ Such duplicate filtering <bcp14>MAY</bcp14> be implemented
probabilistically, for example using a Bloom filter.
- </li>
- <li>
- If the approximate flag was not set in the query and the
BTYPE allowed the
- implementation to compute the key from the block, the
computed key must
- exactly match the QUERY_HASH.
+ The result of this duplicate filtering is always either
+ <tt>FILTER_MORE</tt> or <tt>FILTER_DUPLICATE</tt>.
</li>
</ol>
<t>
- If all of the above are satisfied, the result is forwarded to
the
- origin of the query. Furthermore, the implementation
<bcp14>SHOULD</bcp14>
- cache RESULT messages if the DemultiplexEverywhere flag was set
on any
- of queries that the RESULT provided a new valid answer to.
+ If the result is either <tt>FILTER_MORE</tt> or
<tt>FILTER_LAST</tt>,
+ the result is forwarded to the origin of the query. If the
result
+ was <tt>FILTER_LAST</tt>, the query is removed from the list of
pending
+ queries.
+ Furthermore, the implementation <bcp14>SHOULD</bcp14>
+ cache data from <tt>ResultMessage</tt>s if the
<tt>DemultiplexEverywhere</tt> flag was set on any
+ of queries that the <tt>ResultMessage</tt> provided a new valid
answer to.
+ An implementation <bcp14>MAY</bcp14> even cache results even if
they did not
+ match any pending query.
</t>
</li>
</ol>
@@ -1771,7 +1793,7 @@ bchar = *(ALPHA / DIGIT)
<t>
Applications can and should define their own block types.
The block type determines the format and handling of the block
- payload by peers in PUT and RESULT messages.
+ payload by peers in <tt>PutMessage</tt>s and <tt>ResultMessage</tt>s.
Block types <bcp14>MUST</bcp14> be registered with GANA
(see <xref target="gana_block_type"/>).
</t>
@@ -1810,7 +1832,7 @@ bchar = *(ALPHA / DIGIT)
<dd>
is used to synthesize the block key from the block payload as
part of <tt>PutMessage</tt> and <tt>ResultMessage</tt>
processing.
- A return value of "NONE" implies that this block type does not
+ The special return value of <tt>NONE</tt> implies that this block
type does not
permit deriving the key from the block. A Key may be returned
for a block that is ill-formed.
</dd>
@@ -2002,14 +2024,14 @@ gnunet+tcp://12.3.4.5/ \
</t>
<t>
To validate a block store request is to verify
- the EdDSA SIGNATURE over the hashed ADDRESSES
+ the EdDSA <tt>SIGNATURE</tt> over the hashed <tt>ADDRESSES</tt>
against the public key from the peer ID field.
</t>
<t>
To filter results of HELLO blocks
using the result Bloom filter, the
- H_ADDRS field (as computed using SHA-512 over
- the ADDRESSES) is concatenated with the mutator.
+ <tt>H_ADDRS</tt> field (as computed using SHA-512 over
+ the <tt>ADDRESSES</tt>) is concatenated with the mutator.
The resulting value is then hashed into the
result Bloom filter. Consequently, HELLOs with
completely identical sets of addresses will be
@@ -2035,7 +2057,7 @@ gnunet+tcp://12.3.4.5/ \
Stores a block under the specified key. If an block with identical
payload exists already under the same key, the meta data should
be set to the maximum expiration time of both blocks and use the
- corresponding PUTPATH of that version of the block.
+ corresponding <tt>PUTPATH</tt> of that version of the block.
</dd>
<dt>Lookup(Key) -> List of Blocks</dt>
<dd>
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [lsd0004] branch master updated: -formatting, plus make sure block functions are nicely integrated with message processing text,
gnunet <=