-rearrange; add block functions to hello

1 files changed, 60 insertions, 35 deletions

diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
index e31d9fa..a5af834 100644
--- a/draft-schanzen-r5n.xml
+++ b/draft-schanzen-r5n.xml
@@ -1650,13 +1650,7 @@ BEGIN
                   If <tt>FLAGS</tt> indicate a <tt>FindApproximate</tt> request,
                   the peer <bcp14>SHOULD</bcp14> try to respond with the closest block it
                   has that is not filtered by the
-                  <tt>RESULT_BF</tt>.  However, implementations also <bcp14>MUST</bcp14>
-                  <!-- FIXME MSC: I suggest NOT normatively defining such a consideration -> security consideration -->
-                  avoid an exhaustive search of their database, as there could be
-                  cases where too many local results are filtered by the result 
-                  filter. To avoid denial of service attacks, implementations
-                  <bcp14>MUST</bcp14> thus ensure that the cost of evaluating any
-                  such query is reasonably small.                 
+                  <tt>RESULT_BF</tt>.
                 </li>
                 <li>
                   Else, the peer <bcp14>MUST</bcp14> respond if it has a valid block
@@ -2142,18 +2136,33 @@ gnunet+tcp://12.3.4.5/ \
           </dl>
             </dd>
           </dl>
-          <t>
-            To validate a block query for a HELLO is to simply check that the XQuery is empty.
-          </t>
-          <t>
-            To derive a block key for a HELLO is to simply
-            hash the peer ID from the HELLO.
-          </t>
-          <t>
-            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.
+          <t>
+            The HELLO block functions <bcp14>MUST</bcp14> be implemented
+            as follows:
           </t>
+          <dl>
+          <dt>ValidateBlockQuery(Key, XQuery)
+                -&gt; 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.
+          </dd>
+          <dt>DeriveBlockKey(Block) -&gt; Key | NONE</dt>
+          <dd>
+            To derive a block key for a HELLO is to simply
+            hash the peer ID from the HELLO. The result of this function
+            is always: FIXME what hash
+          </dd>
+          <dt>ValidateBlockStoreRequest(Block)
+                -&gt; 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.
+            If the signature is valid BLOCK_VALID is returned.
+            Otherwise BLOCK_INVALID.
+          </dd>
+          <dt>SetupResultFilter(FilterSize, Mutator) -&gt; RF</dt>
+          <dd>
           <t>
             The RESULT_FILTER for HELLO blocks is implemented using a
       Bloom filter.
@@ -2207,21 +2216,6 @@ gnunet+tcp://12.3.4.5/ \
             match, subsequent requests are likely to not have the same 
             false-positives.
           </t>
-
-          <t>
-            To filter results of HELLO blocks using the Bloom filter, the
-            <tt>H_ADDRS</tt> field (as computed using SHA-512 over
-            the <tt>ADDRESSES</tt>) and XORed with the SHA-512
-            hash of the <tt>MUTATOR</tt> (in network byte order).
-            The resulting value is then used when hashing into the
-            Bloom filter as described in <xref target="bloom_filters" />. 
-            Consequently, HELLOs with completely identical sets of 
-            addresses will be filtered, but any small variation in the set of
-            addresses will cause the block to no longer be
-            filtered (with high probability).  The
-            function thus always returns either
-            <tt>FILTER_MORE</tt> or <tt>FILTER_DUPLICATE</tt>.
-          </t>
           <t>
             HELLO result filters can be merged if the 
             Bloom filters have the same size and
@@ -2229,7 +2223,23 @@ gnunet+tcp://12.3.4.5/ \
             set in either Bloom filter.  This is done whenever
             a peer receives a query with the same <tt>MUTATOR</tt>,
             predecessor and Bloom filter size.
-          </t>    
+          </t>
+          </dd>
+            <dt>FilterResult(Block, Key, RF, XQuery) -&gt; (FilterEvaluationResult, RF')</dt>
+            <dd>
+              To filter results of HELLO blocks using the Bloom filter, the
+             <tt>H_ADDRS</tt> field (as computed using SHA-512 over
+             the <tt>ADDRESSES</tt>) and XORed with the SHA-512
+             hash of the <tt>MUTATOR</tt> (in network byte order).
+             The resulting value is then used when hashing into the
+             Bloom filter as described in <xref target="bloom_filters" />. 
+             Consequently, HELLOs with completely identical sets of 
+             addresses will be filtered and FILTER_DUPLICATE is returned.
+             Any small variation in the set of addresses will cause the block
+             to no longer be filtered (with high probability) and
+             FILTER_MORE is returned.
+            </dd>
+          </dl>
         </section>
         <section>
         <name>Persistence</name>
@@ -2348,7 +2358,22 @@ gnunet+tcp://12.3.4.5/ \
         <tt>REPL_LVL</tt> to a maximum of 16. This imposes
         an upper limit on bandwidth amplification an attacker
         may achieve for a given network size and topology.  
-      </t>
+</t>
+      <section>
+        <name>Approximate Result Filtering</name>
+        <t>
+          When a FindApproximate request is encountered, a peer will try to
+          respond with the closest block it has that is not filtered by the
+          result bloom filter.
+          Implementations <bcp14>MUST</bcp14> ensure that
+          the cost of evaluating any such query is reasonably small.
+          For example, implementations <bcp14>MAY</bcp14> consider to
+          avoid an exhaustive search of their database.
+          Not doing so can lead to denial of service attacks as there
+          could be cases where too many local results are
+          filtered by the result filter.
+        </t>
+      </section>
     </section>
     <section anchor="iana" numbered="true" toc="default">
       <name>IANA Considerations</name>