[lsd0001] branch master updated: figures

[gnunet]

This is an automated email from the git hooks/post-receive script.

martin-schanzenbach pushed a commit to branch master
in repository lsd0001.

The following commit(s) were added to refs/heads/master by this push:
     new 994cad1  figures
994cad1 is described below

commit 994cad1bde263d0960a14480269690451c65e8c9
Author: Martin Schanzenbach <schanzen@gnunet.org>
AuthorDate: Sat Dec 4 14:14:20 2021 +0100

    figures
---
 draft-schanzen-gns.xml | 107 ++++++++++++++++++++++++++++---------------------
 1 file changed, 62 insertions(+), 45 deletions(-)

diff --git a/draft-schanzen-gns.xml b/draft-schanzen-gns.xml
index 281b5a0..30ebc75 100644
--- a/draft-schanzen-gns.xml
+++ b/draft-schanzen-gns.xml
@@ -164,8 +164,8 @@
        where "d" is the private key and "zk" the corresponding public key
        in the public key cipher identified by the "ztype".
        The contents of a zone are cryptographically signed before
-       being published a distributed hash table (DHT).
-       Records are grouped by their label and encrypted (<xref 
target="recordencryption"/>)
+       being published in a distributed hash table (DHT).
+       Records are grouped by their label, and encrypted (<xref 
target="recordencryption"/>)
        using an encryption key derived from the label and the zone public key.
        Instead of the zone private key "d", the signature MUST
        be created using a blinded public/private key pair "d'" and "zk'".
@@ -218,7 +218,7 @@
        </dd>
      </dl>
      <t>
-       The "zid" wire format is defined as follows:
+         For the "zid" wire format see Figure <xref target="figure_zid"/>.
      </t>
      <figure anchor="figure_zid">
        <artwork name="" type="" align="left" alt=""><![CDATA[
@@ -229,8 +229,8 @@
 /                                               /
 /                                               /
          ]]></artwork>
-       <!--        <postamble>which is a very simple example.</postamble>-->
      </figure>
+     <t>The zid Wire Format.</t>
      <t>
        For the string representation of the "zid", we use a base-32 encoding
        "StringEncode".
@@ -333,7 +333,7 @@ zTLD := zkl[126:129].zkl[63:125].zkl[0:62]
      </t>
      <t>
        A GNS resource record holds the data of a specific record in a zone.
-       The resource record format is defined as follows:
+       The resource record format is defined in Figure <xref 
target="figure_gnsrecord"/>.
      </t>
      <figure anchor="figure_gnsrecord">
        <artwork name="" type="" align="left" alt=""><![CDATA[
@@ -348,8 +348,8 @@ zTLD := zkl[126:129].zkl[63:125].zkl[0:62]
 /                                               /
 /                                               /
          ]]></artwork>
-       <!--        <postamble>which is a very simple example.</postamble>-->
      </figure>
+     <t>The Resource Record Wire Format.</t>
      <t>where:</t>
      <dl>
        <dt>EXPIRATION</dt>
@@ -387,18 +387,18 @@ zTLD := zkl[126:129].zkl[63:125].zkl[0:62]
      </dl>
      <t>
        Flags indicate metadata surrounding the resource record. A flag
-       value of 0 indicates that all flags are unset. The following
+       value of 0 indicates that all flags are unset. Figure <xref 
target="figure_flag"/>
        illustrates the flag distribution in the 32-bit flag value of a
        resource record:</t>
      <figure anchor="figure_flag">
        <artwork name="" type="" align="left" alt=""><![CDATA[
-... 5       4         3        2        1        0
-------+--------+--------+--------+--------+--------+
-/ ... | SHADOW | EXPREL | SUPPL  | PRIVATE|    /   |
-------+--------+--------+--------+--------+--------+
+ 0        1        2        3        4        5...
++--------+--------+--------+--------+--------+----
+|RESERVED|PRIVATE |SUPPL   |EXPREL  | SHADOW | ...
++--------+--------+--------+--------+--------+----
          ]]></artwork>
-       <!--        <postamble>which is a very simple example.</postamble>-->
      </figure>
+     <t>The Resource Record Flag Wire Format.</t>
      <t>
        where:
      </t>
@@ -456,7 +456,9 @@ zTLD := zkl[126:129].zkl[63:125].zkl[0:62]
          A PKEY resource record contains the public key of the zone to
          delegate to.
          A PKEY record MUST be the only record under a label. No other
-         records are allowed. A PKEY DATA entry has the following format:</t>
+         records are allowed. The PKEY DATA entry wire format can be found
+         found in Figure <xref target="figure_pkeyrecord"/>.
+       </t>
        <figure anchor="figure_pkeyrecord">
          <artwork name="" type="" align="left" alt=""><![CDATA[
 0     8     16    24    32    40    48    56
@@ -467,8 +469,8 @@ zTLD := zkl[126:129].zkl[63:125].zkl[0:62]
 |                                               |
 +-----+-----+-----+-----+-----+-----+-----+-----+
            ]]></artwork>
-         <!--        <postamble>which is a very simple example.</postamble>-->
        </figure>
+       <t>The PKEY Wire Format.</t>
        <t>
          where:
        </t>
@@ -594,7 +596,8 @@ NONCE := HKDF-Expand (PRK_n, label, 32 / 8)
          The block counter is a 32-bit integer value in network byte order.
          The initialization vector is the expiration time of the
          resource record block in network byte order.
-         The resulting counter ("IV") wire format is as follows:
+         The resulting counter ("IV") wire format can be found in Figure
+         <xref target="figure_hkdf_ivs_pkey"/>.
        </t>
        <figure anchor="figure_hkdf_ivs_pkey">
          <artwork name="" type="" align="left" alt=""><![CDATA[
@@ -609,6 +612,7 @@ NONCE := HKDF-Expand (PRK_n, label, 32 / 8)
 +-----+-----+-----+-----+
            ]]></artwork>
        </figure>
+       <t>The Block Counter Wire Format.</t>
      </section>
 
      <section anchor="gnsrecords_edkey" numbered="true" toc="default">
@@ -621,7 +625,9 @@ NONCE := HKDF-Expand (PRK_n, label, 32 / 8)
          An EDKEY resource record contains the public key of the zone to
          delegate to.
          A EDKEY record MUST be the only record under a label. No other
-         records are allowed. A EDKEY DATA entry has the following format:</t>
+           records are allowed. The EDKEY DATA entry wire format
+         is illustrated in Figure <xref target="figure_edkeyrecord"/>.
+       </t>
        <figure anchor="figure_edkeyrecord">
          <artwork name="" type="" align="left" alt=""><![CDATA[
 0     8     16    24    32    40    48    56
@@ -632,8 +638,8 @@ NONCE := HKDF-Expand (PRK_n, label, 32 / 8)
 |                                               |
 +-----+-----+-----+-----+-----+-----+-----+-----+
            ]]></artwork>
-         <!--        <postamble>which is a very simple example.</postamble>-->
        </figure>
+       <t>The EDKEY DATA Wire Format.</t>
        <t>
          where:
        </t>
@@ -810,7 +816,8 @@ NONCE := HKDF-Expand (PRK_n, label, 32 / 8)
            The nonce is combined with an 8 byte initialization vector.
            The initialization vector is the expiration time of the
            resource record block in network byte order.
-           The resulting counter ("IV") wire format is as follows:
+           The resulting counter ("IV") wire format is illustrated in Figure
+           <xref target="figure_hkdf_ivs_edkey"/>.
          </t>
          <figure anchor="figure_hkdf_ivs_edkey">
            <artwork name="" type="" align="left" alt=""><![CDATA[
@@ -824,8 +831,9 @@ NONCE := HKDF-Expand (PRK_n, label, 32 / 8)
 |       EXPIRATION      |
 |                       |
 +-----+-----+-----+-----+
-           ]]></artwork>
+             ]]></artwork>
        </figure>
+       <t>The Counter Block Initialization Vector</t>
 
        </section>
 
@@ -835,7 +843,7 @@ NONCE := HKDF-Expand (PRK_n, label, 32 / 8)
          The resource record contains a DNS name for the resolver to continue 
with
          in DNS followed by a DNS server. Both names are in the format defined 
in
          <xref target="RFC1034" /> for DNS names.
-         A GNS2DNS DATA entry has the following format:</t>
+           A GNS2DNS DATA entry is illustrated in Figure <xref 
target="figure_gns2dnsrecord"/>.</t>
        <figure anchor="figure_gns2dnsrecord">
          <artwork name="" type="" align="left" alt=""><![CDATA[
 0     8     16    24    32    40    48    56
@@ -851,8 +859,8 @@ NONCE := HKDF-Expand (PRK_n, label, 32 / 8)
 |                                               |
 +-----------------------------------------------+
            ]]></artwork>
-         <!--        <postamble>which is a very simple example.</postamble>-->
        </figure>
+       <t> The GNS2DNS DATA Wire Format</t>
        <t>
          where:
        </t>
@@ -880,7 +888,7 @@ NONCE := HKDF-Expand (PRK_n, label, 32 / 8)
 
          A LEHO resource record is expected to be found together in a single
          resource record with an IPv4 or IPv6 address.
-         A LEHO DATA entry has the following format:</t>
+         A LEHO DATA entry is illustrated in Figure <xref 
target="figure_lehorecord"/>.</t>
        <figure anchor="figure_lehorecord">
          <artwork name="" type="" align="left" alt=""><![CDATA[
 0     8     16    24    32    40    48    56
@@ -891,8 +899,8 @@ NONCE := HKDF-Expand (PRK_n, label, 32 / 8)
 |                                               |
 +-----+-----+-----+-----+-----+-----+-----+-----+
            ]]></artwork>
-         <!--        <postamble>which is a very simple example.</postamble>-->
        </figure>
+       <t> The LEHO DATA Wire Format.</t>
        <t>
          where:
        </t>
@@ -920,7 +928,7 @@ NONCE := HKDF-Expand (PRK_n, label, 32 / 8)
          returned with record sets under any label as a supplemental record.
          <xref target="nick_processing"/> details how a resolver must process
          supplemental and non-supplemental NICK records.
-         A NICK DATA entry has the following format:
+         A NICK DATA entry is illustrated in Figure <xref 
target="figure_nickrecord"/>.
        </t>
        <figure anchor="figure_nickrecord">
          <artwork name="" type="" align="left" alt=""><![CDATA[
@@ -932,8 +940,8 @@ NONCE := HKDF-Expand (PRK_n, label, 32 / 8)
 |                                               |
 +-----+-----+-----+-----+-----+-----+-----+-----+
            ]]></artwork>
-         <!--        <postamble>which is a very simple example.</postamble>-->
        </figure>
+       <t>The NICK DATA Wire Format.</t>
        <t>
          where:
        </t>
@@ -959,7 +967,7 @@ NONCE := HKDF-Expand (PRK_n, label, 32 / 8)
          "example.org" as a BOX record with service (SVC) 443 (https) and 
protocol (PROTO) 6
          (tcp) and record TYPE "TLSA".
          For reference, see also <xref target="RFC2782" />.
-         A BOX DATA entry has the following format:
+           A BOX DATA entry is illustrated in Figure <xref 
target="figure_boxrecord"/>.
        </t>
        <figure anchor="figure_boxrecord">
          <artwork name="" type="" align="left" alt=""><![CDATA[
@@ -973,8 +981,8 @@ NONCE := HKDF-Expand (PRK_n, label, 32 / 8)
 |                                               |
 +-----+-----+-----+-----+-----+-----+-----+-----+
            ]]></artwork>
-         <!--        <postamble>which is a very simple example.</postamble>-->
        </figure>
+       <t>The BOX DATA Wire Format.</t>
        <t>
          where:
        </t>
@@ -1002,7 +1010,9 @@ NONCE := HKDF-Expand (PRK_n, label, 32 / 8)
      <section anchor="gnsrecords_vpn" numbered="true" toc="default">
        <name>VPN</name>
        <t>
-         A VPN DATA entry has the following format:</t>
+           A VPN DATA entry wire format is illustrated in Figure
+         <xref target="figure_vpnrecord"/>.
+       </t>
        <figure anchor="figure_vpnrecord">
          <artwork name="" type="" align="left" alt=""><![CDATA[
 0     8     16    24    32    40    48    56
@@ -1019,8 +1029,8 @@ NONCE := HKDF-Expand (PRK_n, label, 32 / 8)
 |                                               |
 +-----+-----+-----+-----+-----+-----+-----+-----+
            ]]></artwork>
-         <!--        <postamble>which is a very simple example.</postamble>-->
        </figure>
+       <t>The VPN DATA Wire Format.</t>
        <t>
          where:
        </t>
@@ -1090,7 +1100,8 @@ q := SHA512 (HDKD-Public(zk, label))
          A GNS implementation must publish RRBLOCKs
          in accordance to the properties and recommendations of the underlying
          DHT. This may include a periodic refresh publication.
-         A GNS RRBLOCK has the following format:
+         The GNS RRBLOCK wire format is illustrated in Figure
+         <xref target="figure_record_block"/>.
        </t>
        <figure anchor="figure_record_block">
          <artwork name="" type="" align="left" alt=""><![CDATA[
@@ -1117,6 +1128,7 @@ q := SHA512 (HDKD-Public(zk, label))
 +-----+-----+-----+-----+-----+-----+-----+-----+
            ]]></artwork>
        </figure>
+       <t>The RRBLOCK Wire Format.</t>
        <t>where:</t>
        <dl>
          <dt>ZONE TYPE</dt>
@@ -1177,7 +1189,8 @@ q := SHA512 (HDKD-Public(zk, label))
        <t>
          A symmetric encryption scheme is used to encrypt the resource records
          set RDATA into the BDATA field of a GNS RRBLOCK.
-         The wire format of the RDATA looks as follows:
+         The wire format of the RDATA is illustrated in Figure
+         <xref target="figure_rdata"/>.
        </t>
        <figure anchor="figure_rdata">
          <artwork name="" type="" align="left" alt=""><![CDATA[
@@ -1205,8 +1218,8 @@ q := SHA512 (HDKD-Public(zk, label))
 /                     PADDING                   /
 /                                               /
            ]]></artwork>
-         <!--        <postamble>which is a very simple example.</postamble>-->
        </figure>
+       <t>The RDATA Wire Format.</t>
        <t>where:</t>
        <dl>
          <dt>RR COUNT</dt>
@@ -1485,14 +1498,12 @@ q := SHA512 (HDKD-Public(zk, label))
              NICK record allows the client to match the record to the
              authoritative zone. Consider the following example:
            </t>
-       <figure>
          <artwork name="" type="" align="left" alt=""><![CDATA[
 Query: alice.example (type=A)
 Result:
 A: 192.0.2.1
 NICK: eve
          ]]></artwork>
-        </figure>
         <t>
           In this example, the returned NICK record is non-supplemental.
           For the client, this means that the NICK belongs to the zone
@@ -1501,14 +1512,12 @@ NICK: eve
           "alice.doe" wants to be referred to as "eve".
           In contrast, consider the following:
         </t>
-       <figure>
          <artwork name="" type="" align="left" alt=""><![CDATA[
 Query: alice.example (type=AAAA)
 Result:
 AAAA: 2001:DB8::1
 NICK: john (Supplemental)
          ]]></artwork>
-     </figure>
      <t>
        In this case, the NICK record is marked as supplemental. This means that
        the NICK record belongs to the zone "doe" and is published under the
@@ -1565,8 +1574,8 @@ NICK: john (Supplemental)
          <dt>K</dt><dd>Unused</dd>
        </dl>
        <t>
-         The following is the message string "P" on which the PoW is
-         calculated:
+         Figure <xref target="figure_revocation"/> illustrates the wire format
+         of the message string "P" on which the PoW is calculated.
        </t>
        <figure anchor="figure_revocation">
          <artwork name="" type="" align="left" alt=""><![CDATA[
@@ -1583,6 +1592,7 @@ NICK: john (Supplemental)
 +-----+-----+-----+-----+-----+-----+-----+-----+
            ]]></artwork>
        </figure>
+       <t>The Wire Format of the PoW Message String.</t>
        <t>where:</t>
        <dl>
          <dt>POW</dt>
@@ -1632,8 +1642,8 @@ NICK: john (Supplemental)
          <dd>A single epoch is fixed at 365 days.</dd>
        </dl>
        <t>
-         Given that proof has been found, a revocation data object is defined
-         as follows:
+         The revocation message wire format is illustrated in Figure
+         <xref target="figure_revocationdata"/>.
        </t>
        <figure anchor="figure_revocationdata">
          <artwork name="" type="" align="left" alt=""><![CDATA[
@@ -1661,6 +1671,7 @@ NICK: john (Supplemental)
 +-----+-----+-----+-----+-----+-----+-----+-----+
            ]]></artwork>
        </figure>
+       <t>The Revocation Message Wire Format.</t>
        <t>where:</t>
        <dl>
          <dt>TIMESTAMP</dt>
@@ -1708,7 +1719,8 @@ NICK: john (Supplemental)
       <t>
          The signature over the public key covers a 32-bit pseudo header
          conceptually prefixed to the public key. The pseudo header includes
-         the key length and signature purpose:
+        the key length and signature purpose. The wire format is illustrated
+        in Figure <xref target="figure_revsigwithpseudo"/>.
        </t>
        <figure anchor="figure_revsigwithpseudo">
          <artwork name="" type="" align="left" alt=""><![CDATA[
@@ -1725,6 +1737,7 @@ NICK: john (Supplemental)
 +-----+-----+-----+-----+-----+-----+-----+-----+
            ]]></artwork>
        </figure>
+       <t>The Wire Format of the Revocation Data for Signing.</t>
        <t>where:</t>
        <dl>
          <dt>SIZE</dt>
@@ -2011,7 +2024,8 @@ example.com = zk2
        </t>
        <ul>
          <li>Name: The name of the record type (case-insensitive ASCII
-           string, restricted to alphanumeric characters</li>
+           string, restricted to alphanumeric characters. For zone delegation
+       records, the assigned number represents the ztype value of the 
zone.</li>
          <li>Number: 32-bit, above 65535</li>
          <li>Comment: Optionally, a brief English text describing the purpose 
of
            the record type (in UTF-8)</li>
@@ -2023,11 +2037,12 @@ example.com = zk2
        <t>
          The registration policy for this sub-registry is "First Come First
          Served", as described in <xref target="RFC8126"/>.
-         GANA is requested to populate this registry as follows:
+         GANA is requested to populate this registry as listed in Figure
+         <xref target="figure_rrtypenums"/>.
        </t>
        <figure anchor="figure_rrtypenums">
          <artwork name="" type="" align="left" alt=""><![CDATA[
-ztype  | Name    | Contact | References | Description
+Number | Name    | Contact | References | Description
 -------+---------+---------+------------+-------------------------
 65536  | PKEY    | N/A     | [This.I-D] | GNS zone delegation (PKEY)
 65537  | NICK    | N/A     | [This.I-D] | GNS zone nickname
@@ -2038,9 +2053,10 @@ ztype  | Name    | Contact | References | Description
 
            ]]></artwork>
        </figure>
+       <t>The GANA Resource Record Registry.</t>
        <t>
          GANA is requested to amend the "GNUnet Signature Purpose" registry
-         as follows:
+           as illustrated in Figure <xref target="figure_purposenums"/>.
        </t>
        <figure anchor="figure_purposenums">
          <artwork name="" type="" align="left" alt=""><![CDATA[
@@ -2050,6 +2066,7 @@ Purpose | Name            | References | Description
  15     | GNS_RECORD_SIGN | [This.I-D] | GNS record set signature
            ]]></artwork>
        </figure>
+       <t>Requested Changes in the GANA GNUnet Signature Purpose Registry.</t>
      </section>
      <!-- gana -->
      <section>

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.