commit 3767ef4116a2fc47aa64fd4da5ae159dea4be4b8
parent 3324e16553dad65fc44ee96986051cfdd44cec88
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Sat, 26 Mar 2022 13:05:59 +0100
example flows
Diffstat:
1 file changed, 222 insertions(+), 81 deletions(-)
diff --git a/draft-schanzen-gns.xml b/draft-schanzen-gns.xml
@@ -1,4 +1,4 @@
-<?xml version='1.0' encoding='utf-8'?
+<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE rfc SYSTEM "rfc2629-xhtml.ent" [
<!ENTITY RFC1034 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.1034.xml">
<!ENTITY RFC1035 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.1035.xml">
@@ -197,6 +197,12 @@
the recursive name resolution logic defined in
<xref target="resolution"/>.
</dd>
+ <dt>Zone Master</dt>
+ <dd>
+ The zone master is the part of the GNS implementation which implements
+ local zone management and publication as defined in
+ <xref target="publish"/>.
+ </dd>
<dt>Name</dt>
<dd>
A name in GNS is a domain name as defined in <xref target="RFC8499"/>
@@ -220,8 +226,8 @@
The apex label, label separator and the extension label have
special purposes in the resolution protocol which are defined
in the rest of the document.
- Zone administrators <bcp14>MAY</bcp14> disallow certain labels that may be easily
- confused with other labels through registration policies.
+ Zone administrators <bcp14>MAY</bcp14> disallow certain labels that
+ might be easily confused with other labels through registration policies.
</dd>
<dt>Apex Label</dt>
<dd>
@@ -251,12 +257,12 @@
<dt>Top-Level Domain</dt>
<dd>
The rightmost part of a GNS name is a GNS Top-Level Domain (TLD).
- A GNS TLD may consist of one or more labels.
+ A GNS TLD can consist of one or more labels.
Unlike DNS Top-Level Domains (defined in <xref target="RFC8499"/>),
GNS does not expect all users to use the same global root zone. Instead,
with the exception of Zone Top-Level Domains (see below),
GNS TLDs are typically part of the configuration of the local resolver
- (see <xref target="governance"/>), and may thus not be globally unique.
+ (see <xref target="governance"/>), and might thus not be globally unique.
</dd>
<dt>Zone</dt>
<dd>
@@ -298,6 +304,14 @@
A zTLD label sequence can only be distinguished from ordinary TLD label sequences
by attempting to decode the labels into a zone type and zone key.
</dd>
+ <dt>Start Zone</dt>
+ <dd>
+ In order to resolve any given GNS name an initial start zone must be
+ determined for this name.
+ The start zone may already be explicitly defined through a zTLD.
+ Otherwise, it is determined through a local suffix-to-zone mapping
+ (see <xref target="governance"/>).
+ </dd>
<dt>Resource Record</dt>
<dd>
A GNS resource record is the information associated with a label in a
@@ -310,7 +324,7 @@
<section anchor="overview" numbered="true" toc="default">
<name>Overview</name>
<t>
- In GNS, any user may create and manage one or more cryptographically
+ In GNS, any user can create and manage one or more cryptographically
secured zones (<xref target="zones"/>).
Zones are uniquely identified by a zone key.
Zone contents are signed using blinded private keys and
@@ -354,26 +368,26 @@
</t>
<figure anchor="figure_arch_publish" title="An example diagram of two hosts publishing GNS zones.">
<artwork name="" type="" align="left" alt=""><![CDATA[
- Local Host | Distributed | Remote Host
- | Storage |
- | |
- | +--------+ |
- | / /| |
- +---------+ Publish | +--------+ | | Publish +---------+
- | | Zones | | | | | Zones | |
- | GNS |----------|->| Public | |<-|----------| GNS |
- | | | | Zones | | | | |
- +---------+ | | |/ | +---------+
- A | +--------+ | A
- | | | |
- +---------+ | | +---------+
- / | /| | | / | /|
- +---------+ | | | +---------+ |
- | | | | | | | |
- | Local | | | | | Local | |
- | Zones | | | | | Zones | |
- | |/ | | | |/
- +---------+ | | +---------+
+ Local Host | Remote | Remote Host
+ | Storage |
+ | |
+ | +---------+ |
+ | / /| |
+ Publish | +---------+ | | Publish
+ +---------+ Records | | | | | Records +---------+
+ | Zone |----------|->| Record | |<-|----------| Zone |
+ | Master | | | Storage | | | | Master |
+ +---------+ | | |/ | +---------+
+ A | +---------+ | A
+ | | | |
+ +---------+ | | +---------+
+ / | /| | | / | /|
+ +---------+ | | | +---------+ |
+ | | | | | | | |
+ | Local | | | | | Local | |
+ | Zones | | | | | Zones | |
+ | |/ | | | |/
+ +---------+ | | +---------+
]]></artwork>
</figure>
<t>
@@ -396,27 +410,27 @@
</t>
<figure anchor="figure_arch_resolv" title="High-level view of the GNS resolution process.">
<artwork name="" type="" align="left" alt=""><![CDATA[
- Local Host | Distributed
- | Storage
- |
- | +--------+
- | / /|
- | +--------+ |
-+-----------+ Name +---------+ Recursive | | | |
-| | Lookup | | Resolution | | Public | |
-|Application|----------| GNS |-------------|->| Zones | |
-| |<---------| |<------------|--| |/
-+-----------+ Results +---------+ Intermediate| +--------+
- A Results |
- | |
- +---------+ |
- / | /| |
- +---------+ | |
- | | | |
- | Start | | |
- | Zones | | |
- | |/ |
- +---------+ |
+ Local Host | Remote
+ | Storage
+ |
+ | +---------+
+ | / /|
+ | +---------+ |
++-----------+ Name +----------+ Recursive | | | |
+| | Lookup | | Resolution | | Record | |
+|Application|----------| Resolver |-------------|->| Storage | |
+| |<---------| |<------------|--| |/
++-----------+ Results +----------+ Intermediate| +---------+
+ A Results |
+ | |
+ +---------+ |
+ / | /| |
+ +---------+ | |
+ | | | |
+ | Start | | |
+ | Zones | | |
+ | |/ |
+ +---------+ |
]]></artwork>
</figure>
@@ -1705,17 +1719,17 @@ GET(key) -> value
</t>
<figure anchor="figure_storage_publish" title="Management and publication of local zones in the distributed storage.">
<artwork name="" type="" align="left" alt=""><![CDATA[
- Local Host | Distributed
+ Local Host | Remote
| Storage
|
- | +--------+
- | / /|
- | +--------+ |
-+-----------+ +---------+ | | | |
-| | | |PUT(q, RRBLOCK) | | Public | |
-| User | | GNS |----------------|->| Zones | |
-| | | | | | |/
-+-----------+ +---------+ | +--------+
+ | +---------+
+ | / /|
+ | +---------+ |
++-----------+ | | | |
+| | +---------+PUT(q, RRBLOCK) | | Record | |
+| User | | Zone |----------------|->| Storage | |
+| | | Master | | | |/
++-----------+ +---------+ | +---------+
| A |
| | Zone records |
| | grouped by label |
@@ -1963,31 +1977,30 @@ q := SHA-512 (ZKDF(zk, label))
</t>
<figure anchor="figure_resolution" title="The recursive GNS resolution process.">
<artwork name="" type="" align="left" alt=""><![CDATA[
- Local Host | Distributed
- | Storage
- |
- | +--------+
- | / /|
- | +--------+ |
-+-----------+ (1) Name +---------+ | | | |
-| | Lookup | | (3a) GET(q) | | Public | |
-|Application|----------| GNS |-------------------|->| Zones | |
-| |<---------| |<------------------|--| |/
-+-----------+ (4) +---------+ (3b) RRBLOCK | +--------+
- Records A |
- | |
- | |
- (2) Determination of | |
- Start Zone | |
- | |
- +---------+ |
- / | /| |
- +---------+ | |
- | | | |
- | Start | | |
- | Zones | | |
- | |/ |
- +---------+ |
+ Local Host | Remote
+ | Storage
+ |
+ | +---------+
+ | / /|
+ | +---------+ |
++-----------+ (1) Name +----------+ | | | |
+| | Lookup | | (3a) GET(q) | | Record | |
+|Application|----------| Resolver |---------------|->| Storage | |
+| |<---------| |<--------------|--| |/
++-----------+ (4) +----------+ (3b) RRBLOCK | +---------+
+ Records A |
+ | |
+ (2) Determination of | |
+ Start Zone | |
+ | |
+ +---------+ |
+ / | /| |
+ +---------+ | |
+ | | | |
+ | Start | | |
+ | Zones | | |
+ | |/ |
+ +---------+ |
]]></artwork>
</figure>
<section anchor="governance" numbered="true" toc="default">
@@ -3148,6 +3161,134 @@ Value Symbol Symbol
</figure>
</section>
<section>
+ <name>Example flows</name>
+ <section>
+ <name>AAAA Example Resolution</name>
+ <figure anchor="figure_resolution_ex_aaaa" title="Example resolution of an IPv6 address.">
+ <artwork name="" type="" align="left" alt=""><![CDATA[
+ Local Host | Remote
+ | Storage
+ |
+ | +---------+
+ | / /|
+ | +---------+ |
++-----------+ (1) +----------+ | | | |
+| | | | (4,6) | | Record | |
+|Application|----------| Resolver |---------------|->| Storage | |
+| |<---------| |<--------------|--| |/
++-----------+ (8) +----------+ (5,7) | +---------+
+ A |
+ | |
+ (2,3) | |
+ | |
+ | |
+ +---------+ |
+ / v /| |
+ +---------+ | |
+ | | | |
+ | Start | | |
+ | Zones | | |
+ | |/ |
+ +---------+ |
+ ]]></artwork>
+ </figure>
+ <ol>
+ <li>Lookup AAAA record for name: www.example.gns.</li>
+ <li>Determine start zone for www.example.gns.</li>
+ <li>Start zone: zk0 - Remainder: www.example.</li>
+ <li>Calculate q0=SHA512(ZKDF(zk0, "example")) and initiate GET(q0).</li>
+ <li>Retrieve and decrypt RRBLOCK consisting of a single PKEY record containing zk1.</li>
+ <li>Calculate q1=SHA512(ZKDF(zk1, "www")) and initiate GET(q1).</li>
+ <li>Retrieve RRBLOCK consisting of a single AAAA record containing the IPv6 address 2001:db8::1.</li>
+ <li>Return record set to application</li>
+ </ol>
+ </section>
+ <section>
+ <name>REDIRECT Example Resolution</name>
+ <figure anchor="figure_resolution_ex_redir" title="Example resolution of an IPv6 address with redirect.">
+ <artwork name="" type="" align="left" alt=""><![CDATA[
+ Local Host | Remote
+ | Storage
+ |
+ | +---------+
+ | / /|
+ | +---------+ |
++-----------+ (1) +----------+ | | | |
+| | | | (4,6,8) | | Record | |
+|Application|----------| Resolver |----------------|->| Storage | |
+| |<---------| |<---------------|--| |/
++-----------+ (10) +----------+ (5,7,9) | +---------+
+ A |
+ | |
+ (2,3) | |
+ | |
+ | |
+ +---------+ |
+ / v /| |
+ +---------+ | |
+ | | | |
+ | Start | | |
+ | Zones | | |
+ | |/ |
+ +---------+ |
+ ]]></artwork>
+ </figure>
+ <ol>
+ <li>Lookup AAAA record for name: www.example.tld.</li>
+ <li>Determine start zone for www.example.tld.</li>
+ <li>Start zone: zk0 - Remainder: www.example.</li>
+ <li>Calculate q0=SHA512(ZKDF(zk0, "example")) and initiate GET(q0).</li>
+ <li>Retrieve and decrypt RRBLOCK consisting of a single REDIRECT record containing zk1.</li>
+ <li>Calculate q1=SHA512(ZKDF(zk1, "www")) and initiate GET(q1).</li>
+ <li>Retrieve and decrypt RRBLOCK consisting of a single REDIRECT record containing www2.+.</li>
+ <li>Calculate q2=SHA512(ZKDF(zk1, "www2")) and initiate GET(q2).</li>
+ <li>Retrieve and decrypt RRBLOCK consisting of a single AAAA record containing the IPv6 address 2001:db8::1.</li>
+ <li>Return record set to application.</li>
+ </ol>
+ </section>
+ <section>
+ <name>GNS2DNS Example Resolution</name>
+ <figure anchor="figure_resolution_ex_gnsdns" title="Example resolution of an IPv6 address with DNS handover.">
+ <artwork name="" type="" align="left" alt=""><![CDATA[
+ Local Host | Remote
+ | Storage
+ |
+ | +---------+
+ | / /|
+ | +---------+ |
++-----------+ (1) +----------+ | | | |
+| | | | (4) | | Record | |
+|Application|----------| Resolver |------------------|->| Storage | |
+| |<---------| |<-----------------|--| |/
++-----------+ (8) +----------+ (5) | +---------+
+ A A |
+ | | (6,7) |
+ (2,3) | +----------+ |
+ | | |
+ | v |
+ +---------+ +------------+ |
+ / v /| | System DNS | |
+ +---------+ | | resolver | |
+ | | | +------------+ |
+ | Start | | |
+ | Zones | | |
+ | |/ |
+ +---------+ |
+ ]]></artwork>
+ </figure>
+ <ol>
+ <li>Lookup AAAA record for name: www.example.gnu</li>
+ <li>Determine start zone for www.example.gnu.</li>
+ <li>Start zone: zk0 - Remainder: www.example.</li>
+ <li>Calculate q0=SHA512(ZKDF(zk0, "example")) and initiate GET(q0).</li>
+ <li>Retrieve and decrypt RRBLOCK consisting of a single GNS2DNS record containing the name example.com and the DNS server IPv4 address 192.0.2.1.</li>
+ <li>Use system resolver to lookup an AAAA record for the DNS name www.example.com.</li>
+ <li>Retrieve a DNS reply consisting of a single AAAA record containing the IPv6 address 2001:db8::1.</li>
+ <li>Return record set to application.</li>
+ </ol>
+ </section>
+ </section>
+ <section>
<name>Test Vectors</name>
<t>
The following are test vectors for the Base32GNS encoding used for zTLDs.
