lsd0003

commit b4ddc907cae414fae25b58a2691eca020942785b
parent 036b23cf20287d2f41856d594617b68efb3af9b8
Author: Elias Summermatter <elias.summermatter@seccom.ch>
Date:   Wed,  6 Jan 2021 13:59:21 +0100

Added some descriptions to messages

Diffstat:
M
draft-summermatter-set-union.xml
 | 
161
++++++++++++++++++++++++++++++++++++++++++++++++++++++-------------------------

1 file changed, 110 insertions(+), 51 deletions(-)
diff --git a/draft-summermatter-set-union.xml b/draft-summermatter-set-union.xml
@@ -753,11 +753,11 @@
                     <dl>
                         <dt>MSG SIZE</dt>
                         <dd>
-                            is a 16-bit unsigned integer in network byte order (BIG ENDIAN) which describes the the message size.
+                            is 16-bit unsigned integer in network byte order witch describes the message size in bytes and the header is included.
                         </dd>
                         <dt>MSG TYPE</dt>
                         <dd>
-                            is a 16-bit unsigned integer in network byte order (BIG ENDIAN) with the value as registered in GANA
+                            the type of SETU_P2P_OPERATION_REQUEST as registered in <xref target="gana" format="title" /> in network byte order.
                         </dd>
                         <dt>OPERATION TYPE</dt>
                         <dd>
@@ -803,7 +803,7 @@
                         <artwork name="" type="" align="left" alt=""><![CDATA[
         0     8     16    24    32    40    48    56
         +-----+-----+-----+-----+-----+-----+-----+-----+
-        |  MSG SIZE |  MSG TYPE |ORDER| PAD1|    PAD2   |
+        |  MSG SIZE |  MSG TYPE |ORDER|       PAD       |
         +-----+-----+-----+-----+-----+-----+-----+-----+
         |         OFFSET        |          SALT         |
         +-----+-----+-----+-----+-----+-----+-----+-----+
@@ -818,24 +818,20 @@
                     <dl>
                         <dt>MSG SIZE</dt>
                         <dd>
-                            is a 16-bit unsigned integer in network byte order (BIG ENDIAN) which describes the the message size.
+                            is 16-bit unsigned integer in network byte order witch describes the message size in bytes and the header is included.
                         </dd>
                         <dt>MSG TYPE</dt>
                         <dd>
-                            is a 16-bit unsigned integer in network byte order (BIG ENDIAN) with the value as registered in GANA
+                            the type of SETU_P2P_REQUEST_IBF as registered in <xref target="gana" format="title" /> in network byte order.
                         </dd>
                         <dt>ORDER</dt>
                         <dd>
                             is a 8-bit unsigned integer which signals the order of the IBF. The order of the IBF
                             is defined as the logarithm of the number of buckets of the IBF.
                         </dd>
-                        <dt>PAD1  ### PAD1 und 2 zusammen nehmen</dt>
+                        <dt>PAD</dt>
                         <dd>
-                            is 8-bit always set to zero
-                        </dd>
-                        <dt>PAD2</dt>
-                        <dd>
-                            is 16-bit always set to zero
+                            is 24-bit always set to zero
                         </dd>
                         <dt>OFFSET</dt>
                         <dd>
@@ -884,6 +880,9 @@
                         state after receiving a <em><xref target="messages_done" format="title" /></em> message from the remote peer, in this
                         case the client changes to the <strong>Finished</strong> state as soon as all demands for elements have been satisfied.
                     </t>
+                    <t>
+                        This message is exclusively send in the <xref target="modeofoperation_individual-elements" format="title" />.
+                    </t>
                 </section>
                 <section anchor="messages_elements_structure" numbered="true" toc="default">
                     <name>Structure</name>
@@ -904,13 +903,11 @@
                     <dl>
                         <dt>MSG SIZE</dt>
                         <dd>
-                            # is 16-bit unsigned integer in network byte order witch describes the message size in bytes and the header is mitgezählt.
-                            is a 16-bit unsigned integer in network byte order (BIG ENDIAN) which describes the the message size.
+                            is 16-bit unsigned integer in network byte order witch describes the message size in bytes and the header is included.
                         </dd>
                         <dt>MSG TYPE</dt>
                         <dd>
-                            the value of .... as registerd in [GANA] in network byt order
-                            is a 16-bit unsigned integer in network byte order (BIG ENDIAN) with the value as registered in GANA # Symbolischer name von gana hinzufügen
+                            the type of SETU_P2P_ELEMENTS as registered in <xref target="gana" format="title" /> in network byte order.
                         </dd>
                         <dt>E TYPE</dt>
                         <dd>
@@ -944,10 +941,17 @@
                 <section anchor="messages_offer_description" numbered="true" toc="default">
                     <name>Description</name>
                     <t>
-                        The offer message tells the other peer which hashes match a given IBF key.
-                        This is needed to enable the peer to send a demand for a element that is missing
-                        in the set.
-
+                        The offer message answers an <em><xref target="messages_inquiry" format="title" /></em> message
+                        and transmits the full hash of an element that has been requested by the other peer.
+                        This full hash enables the other peer to check if the element is not in his set and
+                        eventually send a <em><xref target="messages_demand" format="title" /></em> message for that a element.
+                    </t>
+                    <t>
+                        The offer is sent and received only in the <strong>Active Decoding</strong> and in the <strong>Passive Decoding</strong>
+                        state.
+                    </t>
+                    <t>
+                        This message is exclusively send in the <xref target="modeofoperation_individual-elements" format="title" />.
                     </t>
                 </section>
                 <section anchor="messages_offer_structure" numbered="true" toc="default">
@@ -956,7 +960,7 @@
                         <artwork name="" type="" align="left" alt=""><![CDATA[
         0     8     16    24    32    40    48    56
         +-----+-----+-----+-----+-----+-----+-----+-----+
-        |  MSG SIZE |  MSG TYPE |  GNUNET HASH
+        |  MSG SIZE |  MSG TYPE |         HASH
         +-----+-----+-----+-----+
         /                                               /
         /                                               /
@@ -967,13 +971,13 @@
                     <dl>
                         <dt>MSG SIZE</dt>
                         <dd>
-                            is a 16-bit unsigned integer in network byte order (BIG ENDIAN) which describes the the message size.
+                            is 16-bit unsigned integer in network byte order witch describes the message size in bytes and the header is included.
                         </dd>
                         <dt>MSG TYPE</dt>
                         <dd>
-                            is a 16-bit unsigned integer in network byte order (BIG ENDIAN) with the value as registered in GANA
+                            the type of SETU_P2P_OFFER as registered in <xref target="gana" format="title" /> in network byte order.
                         </dd>
-                        <dt>HASH ### Replace GNUENT HASH durch HASH</dt>
+                        <dt>HASH</dt>
                         <dd>
                             is a SHA 512-bit hash of the element that is requested with a inquiry message.
                         </dd>
@@ -988,7 +992,14 @@
                 <section anchor="messages_inquiry_description" numbered="true" toc="default">
                     <name>Description</name>
                     <t>
-                        The Inquiry message tells the other peer to send an offer containing the element hash for the given Key of the IBF.
+                        The Inquiry message is exclusively send by the active peer in <strong>Active Decoding</strong> state
+                        to request the full hash of an element that is missing in the active peers set. This is normally answered
+                        by the passive peer with <em><xref target="messages_offer" format="title" /></em> message.
+                    </t>
+                    <t>
+                        This message is exclusively send in the <xref target="modeofoperation_individual-elements" format="title" />.
+                    </t>
+                    <t>
                         NOTE: HERE IS AN IMPLEMENTATION BUG UNNECESSARY 32-BIT PADDING!
                     </t>
                 </section>
@@ -1009,11 +1020,11 @@
                     <dl>
                         <dt>MSG SIZE</dt>
                         <dd>
-                            is a 16-bit unsigned integer in network byte order (BIG ENDIAN) which describes the the message size.
+                            is 16-bit unsigned integer in network byte order witch describes the message size in bytes and the header is included.
                         </dd>
                         <dt>MSG TYPE</dt>
                         <dd>
-                            is a 16-bit unsigned integer in network byte order (BIG ENDIAN) with the value as registered in GANA
+                            the type of SETU_P2P_INQUIRY as registered in <xref target="gana" format="title" /> in network byte order.
                         </dd>
                         <dt>IBF KEY</dt>
                         <dd>
@@ -1029,7 +1040,14 @@
                 <section anchor="messages_demand_description" numbered="true" toc="default">
                     <name>Description</name>
                     <t>
-                        The Demand message requests the whole element for a defined Hash from the other peer
+                        The demand message is sent in the <strong>Active Decoding</strong> and in the <strong>Passive Decoding</strong>
+                        state. It is a answer to a received <em><xref target="messages_offer" format="title" /></em> message
+                        and its send if the element described in the <em><xref target="messages_offer" format="title" /></em> message
+                        is missing in the peers set. In the normal workflow the answer to the demand message is an
+                        <em><xref target="messages_elements" format="title" /></em> message.
+                    </t>
+                    <t>
+                        This message is exclusively send in the <xref target="modeofoperation_individual-elements" format="title" />.
                     </t>
                 </section>
                 <section anchor="messages_demand_structure" numbered="true" toc="default">
@@ -1038,7 +1056,7 @@
                         <artwork name="" type="" align="left" alt=""><![CDATA[
         0     8     16    24    32    40    48    56
         +-----+-----+-----+-----+-----+-----+-----+-----+
-        |  MSG SIZE |  MSG TYPE |  GNUNET HASH
+        |  MSG SIZE |  MSG TYPE |          HASH
         +-----+-----+-----+-----+
         /                                               /
         /                                               /
@@ -1049,15 +1067,15 @@
                     <dl>
                         <dt>MSG SIZE</dt>
                         <dd>
-                            is a 16-bit unsigned integer in network byte order (BIG ENDIAN) which describes the the message size.
+                            is 16-bit unsigned integer in network byte order witch describes the message size in bytes and the header is included.
                         </dd>
                         <dt>MSG TYPE</dt>
                         <dd>
-                            is a 16-bit unsigned integer in network byte order (BIG ENDIAN) with the value as registered in GANA
+                            the type of SETU_P2P_DEMAND as registered in <xref target="gana" format="title" /> in network byte order.
                         </dd>
-                        <dt>GNUNET HASH</dt>
+                        <dt>HASH</dt>
                         <dd>
-                            is a 512-bit GNUNET Hash of the element that is demanded.
+                            is a 512-bit Hash of the element that is demanded.
                         </dd>
                     </dl>
                 </section>
@@ -1069,7 +1087,11 @@
                 <section anchor="messages_done_description" numbered="true" toc="default">
                     <name>Description</name>
                     <t>
-                        The done message signals to the other peer that set operation is done
+                        The done message is send when all <em><xref target="messages_demand" format="title" /></em> messages
+                        have been successfully satisfied and the set is complete synchronized.
+                    </t>
+                    <t>
+                        This message is exclusively send in the <xref target="modeofoperation_individual-elements" format="title" />.
                     </t>
                 </section>
                 <section anchor="messages_done_structure" numbered="true" toc="default">
@@ -1087,11 +1109,11 @@
                     <dl>
                         <dt>MSG SIZE</dt>
                         <dd>
-                            is a 16-bit unsigned integer in network byte order (BIG ENDIAN) which describes the the message size.
+                            is 16-bit unsigned integer in network byte order witch describes the message size in bytes and the header is included.
                         </dd>
                         <dt>MSG TYPE</dt>
                         <dd>
-                            is a 16-bit unsigned integer in network byte order (BIG ENDIAN) with the value as registered in GANA
+                            the type of SETU_P2P_DONE as registered in <xref target="gana" format="title" /> in network byte order.
                         </dd>
                     </dl>
                 </section>
@@ -1103,7 +1125,12 @@
                 <section anchor="messages_full_done_description" numbered="true" toc="default">
                     <name>Description</name>
                     <t>
-                        Signals to the other peer that all elements of the set have been sent.
+                        The full done message sent in the <xref target="modeofoperation_full-sync" format="title" /> sent
+                        to signal that all remaining elements of the set have been sent. The message is received and sent in in the
+                        <strong>Full Sending</strong> and in the <strong>Full Receiving</strong> state. When the full done message is received
+                        in <strong>Full Sending</strong> state the peer changes directly into <strong>Finished</strong> state. In
+                        <strong>Full Receiving</strong> state receiving a full done message initiates sending of
+                        the remaining elements that are missing in the set of the other peer.
                     </t>
                 </section>
                 <section anchor="messages_full_done_structure" numbered="true" toc="default">
@@ -1121,11 +1148,11 @@
                     <dl>
                         <dt>MSG SIZE</dt>
                         <dd>
-                            is a 16-bit unsigned integer in network byte order (BIG ENDIAN) which describes the the message size.
+                            is 16-bit unsigned integer in network byte order witch describes the message size in bytes and the header is included.
                         </dd>
                         <dt>MSG TYPE</dt>
                         <dd>
-                            is a 16-bit unsigned integer in network byte order (BIG ENDIAN) with the value as registered in GANA
+                            the type of SETU_P2P_FULL_DONE as registered in <xref target="gana" format="title" /> in network byte order.
                         </dd>
                     </dl>
                 </section>
@@ -1137,7 +1164,15 @@
                 <section anchor="messages_request_full_description" numbered="true" toc="default">
                     <name>Description</name>
                     <t>
-                        Initiates a full sync and tells the other peer to send all elements.
+                        The request full message is sent by the initiating peer in <strong>Expect SE</strong> state to the receiving peer if
+                        the operation mode "<xref target="modeofoperation_full-sync" format="title" />" is
+                        determined as the better <xref target="modeofoperation" format="title" /> and the set size of the initiating peer is smaller
+                        than the set size of the receiving peer. The initiating peer changes after sending the request full message into
+                        <strong>Full Receiving</strong> state.
+                    </t>
+                    <t>
+                        The receiving peer can receive the request full message in the <strong>Expecting IBF</strong>, afterwards the receiving peer
+                        starts sending his complete set in <xref target="messages_full_element" format="title" /> messages to the initiating peer.
                     </t>
                 </section>
                 <section anchor="messages_request_full_structure" numbered="true" toc="default">
@@ -1155,23 +1190,32 @@
                     <dl>
                         <dt>MSG SIZE</dt>
                         <dd>
-                            is a 16-bit unsigned integer in network byte order (BIG ENDIAN) which describes the the message size.
+                            is 16-bit unsigned integer in network byte order witch describes the message size in bytes and the header is included.
                         </dd>
                         <dt>MSG TYPE</dt>
                         <dd>
-                            is a 16-bit unsigned integer in network byte order (BIG ENDIAN) with the value as registered in GANA
+                            the type of SETU_P2P_REQUEST_FULL as registered in <xref target="gana" format="title" /> in network byte order.
                         </dd>
                     </dl>
                 </section>
             </section>
 
             <section anchor="messages_se" numbered="true" toc="default">
-                <name>Strata Estimator / SE</name>
+                <name>Strata Estimator</name>
 
                 <section anchor="messages_se_description" numbered="true" toc="default">
                     <name>Description</name>
                     <t>
-                        The Strata Estimator message contains the strata estimator.
+                        The strata estimator is sent by the receiving peer at the start of the protocol right after the
+                        <xref target="messages_operation_request" format="title" /> message has been received.
+                    </t>
+                    <t>
+                        The strata estimator is used to estimate the difference between the two sets as described in section <xref target="se" format="counter" />.
+                    </t>
+                    <t>
+                        When the initiating peer receives the strata estimator the peer decides which <xref target="modeofoperation" format="title" /> to use
+                        for the synchronization. Depending on the size of set difference and the <xref target="modeofoperation" format="title" /> the initiating peer
+                        changes into <strong>Full Sending</strong>, <strong>Full Receiving</strong> or <strong>Passive Decoding</strong> state.
                     </t>
                 </section>
                 <section anchor="messages_se_structure" numbered="true" toc="default">
@@ -1193,11 +1237,11 @@
                     <dl>
                         <dt>MSG SIZE</dt>
                         <dd>
-                            is a 16-bit unsigned integer in network byte order (BIG ENDIAN) which describes the the message size.
+                            is 16-bit unsigned integer in network byte order witch describes the message size in bytes and the header is included.
                         </dd>
                         <dt>MSG TYPE</dt>
                         <dd>
-                            is a 16-bit unsigned integer in network byte order (BIG ENDIAN) with the value as registered in GANA
+                            the type of SETU_P2P_SE as registered in <xref target="gana" format="title" /> in network byte order.
                         </dd>
                         <dt>SETSIZE</dt>
                         <dd>
@@ -1212,13 +1256,17 @@
             </section>
 
             <section anchor="messages_sec" numbered="true" toc="default">
-                <name>Strata Estimator Compressed / SEC</name>
+                <name>Strata Estimator Compressed</name>
 
                 <section anchor="messages_sec_description" numbered="true" toc="default">
                     <name>Description</name>
                     <t>
-                        The Strata Estimator Compressed is the same message as the Strata Estimator message but the
-                        field "SE-SLICES" is with gzip compressed and the MSG TYPE is 565.
+                        The Strata estimator can be compressed with gzip to improve performance. For
+                        details see section <xref target="performance" format="title" />.
+                    </t>
+                    <t>
+                        Since the content of the message is the same as the uncompressed Strata Estimator, the details
+                        aren't repeated here for more information see section <xref target="messages_se" format="counter" />.
                     </t>
                 </section>
             </section>
@@ -1230,7 +1278,18 @@
                 <section anchor="messages_full_element_description" numbered="true" toc="default">
                     <name>Description</name>
                     <t>
-                        The Full Element message sends a set of elements because of a peer full sync operation mode.
+                        The full element message is the equivalent of the <xref target="messages_elements" format="title" /> message in
+                        the <xref target="modeofoperation_full-sync" format="title" />. It contains a complete element that is missing
+                        in the set of the peer that receives this message.
+                    </t>
+                    <t>
+                        The full element message is exclusively sent in the transitions <strong>Expecting IBF</strong> -> <strong>Full Receiving</strong> and
+                        <strong>Full Receiving</strong> -> <strong>Finished</strong>. The message is only received in the <strong> Full Sending</strong> and
+                        <strong>Full Receiving</strong> state.
+                    </t>
+                    <t>
+                        After the last full element messages has been sent the <xref target="messages_full_done" format="title" /> message
+                        is sent to conclude the full synchronisation of the element sending peer.
                     </t>
                 </section>
                 <section anchor="messages_full_element_structure" numbered="true" toc="default">
@@ -1252,11 +1311,11 @@
                     <dl>
                         <dt>MSG SIZE</dt>
                         <dd>
-                            is a 16-bit unsigned integer in network byte order (BIG ENDIAN) which describes the the message size.
+                            is 16-bit unsigned integer in network byte order witch describes the message size in bytes and the header is included.
                         </dd>
                         <dt>MSG TYPE</dt>
                         <dd>
-                            is a 16-bit unsigned integer in network byte order (BIG ENDIAN) with the value as registered in GANA
+                            the type of SETU_P2P_REQUEST_FULL_ELEMENT as registered in <xref target="gana" format="title" /> in network byte order.
                         </dd>
                         <dt>E TYPE</dt>
                         <dd>