commit 994cad1bde263d0960a14480269690451c65e8c9
parent 2a57f25ac1e1309c0df8d1f729ed84b8e591c4d5
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Sat, 4 Dec 2021 14:14:20 +0100
figures
Diffstat:
1 file changed, 62 insertions(+), 45 deletions(-)
diff --git 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>
