lsd0001

draft-schanzen-gns-01.xml (81998B)

---

 <?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">
 <!ENTITY RFC2119 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
 <!ENTITY RFC2782 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2782.xml">
 <!ENTITY RFC3629 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3629.xml">
 <!ENTITY RFC3826 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3826.xml">
 <!ENTITY RFC3912 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3912.xml">
 <!ENTITY RFC5869 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5869.xml">
 <!ENTITY RFC5890 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5890.xml">
 <!ENTITY RFC5891 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5891.xml">
 <!ENTITY RFC6781 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6781.xml">
 <!ENTITY RFC6895 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6895.xml">
 <!ENTITY RFC6979 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6979.xml">
 <!ENTITY RFC7748 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7748.xml">
 <!ENTITY RFC8032 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8032.xml">
 <!ENTITY RFC8126 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8126.xml">
 ]>
 <?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
 <?rfc strict="yes" ?>
 <?rfc toc="yes" ?>
 <?rfc symrefs="yes"?>
 <?rfc sortrefs="yes" ?>
 <?rfc compact="yes" ?>
 <?rfc subcompact="no" ?>
 <rfc xmlns:xi="http://www.w3.org/2001/XInclude" category="info" docName="draft-schanzen-gns-01" ipr="trust200902" obsoletes="" updates="" submissionType="IETF" xml:lang="en" version="3">
  <!-- xml2rfc v2v3 conversion 2.26.0 -->
  <front>
   <title abbrev="The GNU Name System">
    The GNU Name System
   </title>
   <seriesInfo name="Internet-Draft" value="draft-schanzen-gns-01"/>
   <author fullname="Martin Schanzenbach" initials="M." surname="Schanzenbach">
    <organization>GNUnet e.V.</organization>
    <address>
     <postal>
      <street>Boltzmannstrasse 3</street>
      <city>Garching</city>
      <code>85748</code>
      <country>DE</country>
     </postal>
     <email>schanzen@gnunet.org</email>
    </address>
   </author>
   <author fullname="Christian Grothoff" initials="C." surname="Grothoff">
    <organization>Berner Fachhochschule</organization>
    <address>
     <postal>
      <street>Hoeheweg 80</street>
      <city>Biel/Bienne</city>
      <code>2501</code>
      <country>CH</country>
     </postal>
     <email>grothoff@gnunet.org</email>
    </address>
   </author>
   <author fullname="Bernd Fix" initials="B." surname="Fix">
    <organization>GNUnet e.V.</organization>
    <address>
     <postal>
      <street>Boltzmannstrasse 3</street>
      <city>Garching</city>
      <code>85748</code>
      <country>DE</country>
     </postal>
     <email>fix@gnunet.org</email>
    </address>
   </author>
 
   <!-- Meta-data Declarations -->
   <area>General</area>
   <workgroup>Independent Stream</workgroup>
   <keyword>name systems</keyword>
   <abstract>
    <t>This document contains the GNU Name System (GNS) technical specification.</t>
   </abstract>
  </front>
  <middle>
    <section anchor="introduction" numbered="true" toc="default">
      <name>Introduction</name>
      <t>
        The Domain Name System (DNS) is a unique distributed database and a vital
        service for most Internet applications. While DNS is distributed, it
        relies on centralized, trusted registrars to provide globally unique
        names. As the awareness of the central role DNS plays on the Internet
        rises, various institutions are using their power (including legal means)
        to engage in attacks on the DNS, thus threatening the global availability
        and integrity of information on the Internet.
      </t>
      <t>
        DNS was not designed with security as a goal. This makes it very
        vulnerable, especially to attackers that have the technical capabilities
        of an entire nation state at their disposal.
        This specification describes a censorship-resistant, privacy-preserving
        and decentralized name system: The GNU Name System (GNS). It is designed
        to provide a secure alternative to DNS, especially when censorship or
        manipulation is encountered. GNS can bind names to any kind of
        cryptographically secured token, enabling it to double in some respects as
        even as an alternative to some of today’s Public Key Infrastructures, in
        particular X.509 for the Web.
      </t>
      <t>
        This document contains the GNU Name System (GNS) technical specification
        of the GNU Name System <xref target="GNS" />, a fully decentralized and censorship-resistant
        name system. GNS provides a privacy-enhancing alternative to the Domain
        Name System (DNS). The design of GNS incorporates the capability to
        integrate and coexist with DNS. GNS is based on the principle of a petname
        system and builds on ideas from the Simple Distributed Security
        Infrastructure (SDSI), addressing a central issue with the decentralized
        mapping of secure identifiers to memorable names: namely the impossibility
        of providing a global, secure and memorable mapping without a trusted
        authority. GNS uses the transitivity in the SDSI design to replace the
        trusted root with secure delegation of authority thus making petnames
        useful to other users while operating under a very strong adversary model.
      </t>
      <t>
        This document defines the normative wire format of resource records, resolution processes,
        cryptographic routines and security considerations for use by implementors.
      </t>
      <t>
        The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
        NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
        "OPTIONAL" in this document are to be interpreted as described
        in <xref target="RFC2119"/>.
      </t>
      <t>
 
      </t>
    </section>
    <section anchor="zones" numbered="true" toc="default">
      <name>Zones</name>
      <t>
        A zone in GNS is defined by a public/private ECDSA key pair (d,zk),
        where d is the private key and zk the corresponding public key.
        GNS employs the curve parameters of the twisted edwards representation
        of Curve25519 <xref target="RFC7748" /> (a.k.a. edwards25519)
        with the ECDSA scheme (<xref target="RFC6979" />).
        In the following, we use the following naming convention for our
        cryptographic primitives:
      </t>
      <dl>
        <dt>d</dt>
        <dd>
          is a 256-bit ECDSA private key.
          In GNS, records are signed using a key derived from "d" as described in
          <xref target="publish" />.
        </dd>
        <dt>p</dt>
        <dd>
          is the prime of edwards25519 as defined in <xref target="RFC7748" />, i.e.
          2^255 - 19.
        </dd>
        <dt>B</dt>
        <dd>
          is the group generator (X(P),Y(P)) of edwards25519 as defined in
         <xref target="RFC7748" />.
        </dd>
        <dt>L</dt>
        <dd>
          is the prime-order subgroup of edwards25519 in <xref target="RFC7748" />.
        </dd>
        <dt>zk</dt>
        <dd>
          is the ECDSA public key corresponding to d. It is defined in
          <xref target="RFC6979" /> as the curve point d*B where B is the group
          generator of the elliptic curve. The public key is used to uniquely
          identify a GNS zone and is referred to as the "zone key".
        </dd>
      </dl>
    </section>
    <section anchor="rrecords" numbered="true" toc="default">
      <name>Resource Records</name>
      <t>
        A GNS implementor MUST provide a mechanism to create and manage resource
        records for local zones. A local zone is established by creating a zone
        key pair. Records may be added to each zone, hence a (local) persistency
        mechanism for resource records and zones must be provided.
        This local zone database is used by the GNS resolver implementation
        and to publish record information.
      </t>
      <t>
        A GNS resource record holds the data of a specific record in a zone.
        The resource record format is defined as follows:
      </t>
      <figure anchor="figure_gnsrecord">
        <artwork name="" type="" align="left" alt=""><![CDATA[
 0     8     16    24    32    40    48    56
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |                   EXPIRATION                  |
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |       DATA SIZE       |          TYPE         |
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |           FLAGS       |        DATA           /
 +-----+-----+-----+-----+                       /
 /                                               /
 /                                               /
          ]]></artwork>
        <!--        <postamble>which is a very simple example.</postamble>-->
      </figure>
      <t>where:</t>
      <dl>
        <dt>EXPIRATION</dt>
        <dd>
          denotes the absolute 64-bit expiration date of the record.
          In microseconds since midnight (0 hour), January 1, 1970 in network
          byte order.
        </dd>
        <dt>DATA SIZE</dt>
        <dd>
          denotes the 32-bit size of the DATA field in bytes and in network byte
          order.
        </dd>
        <dt>TYPE</dt>
        <dd>
          is the 32-bit resource record type. This type can be one of the GNS resource
          records as defined in <xref target="rrecords" /> or a DNS record
          type as defined in <xref target="RFC1035" /> or any of the
          complementary standardized DNS resource record types. This value must be
          stored in network byte order. Note that values
          below 2^16 are reserved for allocation via IANA (<xref target="RFC6895" />).
        </dd>
        <dt>FLAGS</dt>
        <dd>
          is a 32-bit resource record flags field (see below).
        </dd>
        <dt>DATA</dt>
        <dd>
          the variable-length resource record data payload. The contents are defined
          by the
          respective type of the resource record.
        </dd>
      </dl>
      <t>
        Flags indicate metadata surrounding the resource record. A flag
        value of 0 indicates that all flags are unset. The following
        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|    /   |
 ------+--------+--------+--------+--------+--------+
          ]]></artwork>
        <!--        <postamble>which is a very simple example.</postamble>-->
      </figure>
      <t>
        where:
      </t>
      <dl>
        <dt>SHADOW</dt>
        <dd>
          If this flag is set, this record should be ignored by resolvers unless all (other)
          records of the same record type have expired.  Used to allow zone publishers to
          facilitate good performance when records change by allowing them to put future
          values of records into the DHT. This way, future values can propagate and may be
          cached before the transition becomes active.
        </dd>
        <dt>EXPREL</dt>
        <dd>
          The expiration time value of the record is a relative time (still in microseconds)
          and not an absolute time. This flag should never be encountered by a resolver
          for records obtained from the DHT, but might be present when a resolver looks up
          private records of a zone hosted locally.
        </dd>
        <dt>
          SUPPL
        </dt>
        <dd>
          This is a supplemental record. It is provided in addition to the
          other records. This flag indicates that this record is not explicitly
          managed alongside the other records under the respective name but
          may be useful for the application. This flag should only be encountered
          by a resolver for records obtained from the DHT.
        </dd>
        <dt>PRIVATE</dt>
        <dd>
          This is a private record of this peer and it should thus not be
          published in the DHT.  Thus, this flag should never be encountered by
          a resolver for records obtained from the DHT.
          Private records should still be considered just like
          regular records when resolving labels in local zones.
        </dd>
      </dl>
      <section anchor="gnsrecords_numbers" numbered="true" toc="default">
        <name>Record Types</name>
        <t>
          A registry of GNS Record Types is described in Section 10.  The
          registration policy for this registry is "First Come First Served", as
          described in <xref target="RFC8126"/>.  When requesting new entries, careful
          consideration of the following criteria is strongly advised:
          FIXME: ausdenken was wir da gerne haetten.
        </t>
      </section>
      <section anchor="gnsrecords_pkey" numbered="true" toc="default">
        <name>PKEY</name>
        <t>In GNS, a delegation of a label to a zone is represented through a PKEY
          record. 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>
        <figure anchor="figure_pkeyrecord">
          <artwork name="" type="" align="left" alt=""><![CDATA[
 0     8     16    24    32    40    48    56
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |                   PUBLIC KEY                  |
 |                                               |
 |                                               |
 |                                               |
 +-----+-----+-----+-----+-----+-----+-----+-----+
            ]]></artwork>
          <!--        <postamble>which is a very simple example.</postamble>-->
        </figure>
        <t>
          where:
        </t>
        <dl>
          <dt>PUBLIC KEY</dt>
          <dd>
            A 256-bit ECDSA zone key.
          </dd>
        </dl>
      </section>
      <section anchor="gnsrecords_gns2dns" numbered="true" toc="default">
        <name>GNS2DNS</name>
        <t>It is possible to delegate a label back into DNS through a GNS2DNS record.
          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>
        <figure anchor="figure_gns2dnsrecord">
          <artwork name="" type="" align="left" alt=""><![CDATA[
 0     8     16    24    32    40    48    56
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |                    DNS NAME                   |
 /                                               /
 /                                               /
 |                                               |
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |                 DNS SERVER NAME               |
 /                                               /
 /                                               /
 |                                               |
 +-----------------------------------------------+
            ]]></artwork>
          <!--        <postamble>which is a very simple example.</postamble>-->
        </figure>
        <t>
          where:
        </t>
        <dl>
          <dt>DNS NAME</dt>
          <dd>
            The name to continue with in DNS (0-terminated).
          </dd>
          <dt>DNS SERVER NAME</dt>
          <dd>
            The DNS server to use. May be an IPv4/IPv6 address in dotted decimal
            form or a DNS name. It may also be a relative GNS name ending with a
            "+" top-level domain. The value is UTF-8 encoded (also for DNS names)
            and 0-terminated.
          </dd>
        </dl>
      </section>
 
      <section anchor="gnsrecords_leho" numbered="true" toc="default">
        <name>LEHO</name>
        <t>Legacy hostname records can be used by applications that are expected
          to supply a DNS name on the application layer. The most common use case
          is HTTP virtual hosting, which as-is would not work with GNS names as
          those may not be globally unique.
 
          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>
        <figure anchor="figure_lehorecord">
          <artwork name="" type="" align="left" alt=""><![CDATA[
 0     8     16    24    32    40    48    56
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |                 LEGACY HOSTNAME               |
 /                                               /
 /                                               /
 |                                               |
 +-----+-----+-----+-----+-----+-----+-----+-----+
            ]]></artwork>
          <!--        <postamble>which is a very simple example.</postamble>-->
        </figure>
        <t>
          where:
        </t>
        <dl>
          <dt>LEGACY HOSTNAME</dt>
          <dd>
            A UTF-8 string (which is not 0-terminated) representing the legacy hostname.
          </dd>
        </dl>
        <t>
          NOTE: If an application uses a LEHO value in an HTTP request header
          (e.g. "Host:" header) it must be converted to a punycode representation
          <xref target="RFC5891" />.
        </t>
      </section>
      <section anchor="gnsrecords_nick" numbered="true" toc="default">
        <name>NICK</name>
        <t>
          Nickname records can be used by zone administrators to publish an
          indication on what label this zone prefers to be referred to.
          This is a suggestion to other zones what label to use when creating a
          PKEY (<xref target="gnsrecords_pkey" />) record containing this zone's
          public zone key.
          This record SHOULD only be stored under the empty label "@" but MAY be
          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:
        </t>
        <figure anchor="figure_nickrecord">
          <artwork name="" type="" align="left" alt=""><![CDATA[
 0     8     16    24    32    40    48    56
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |                  NICKNAME                     |
 /                                               /
 /                                               /
 |                                               |
 +-----+-----+-----+-----+-----+-----+-----+-----+
            ]]></artwork>
          <!--        <postamble>which is a very simple example.</postamble>-->
        </figure>
        <t>
          where:
        </t>
        <dl>
          <dt>NICKNAME</dt>
          <dd>
            A UTF-8 string (which is not 0-terminated) representing the preferred
            label of the zone. This string MUST NOT include a "." character.
          </dd>
        </dl>
      </section>
      <section anchor="gnsrecords_box" numbered="true" toc="default">
        <name>BOX</name>
        <t>
          In GNS, every "." in a name delegates to another zone, and
          GNS lookups are expected to return all of the required useful
          information in one record set.  This is incompatible with the
          special labels used by DNS for SRV and TLSA records.  Thus, GNS
          defines the BOX record format to box up SRV and TLSA records and
          include them in the record set of the label they are associated
          with.  For example, a
          TLSA record for "_https._tcp.example.org" will be stored in the record set of
          "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:
        </t>
        <figure anchor="figure_boxrecord">
          <artwork name="" type="" align="left" alt=""><![CDATA[
 0     8     16    24    32    40    48    56
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |   PROTO   |    SVC    |       TYPE            |
 +-----------+-----------------------------------+
 |                 RECORD DATA                   |
 /                                               /
 /                                               /
 |                                               |
 +-----+-----+-----+-----+-----+-----+-----+-----+
            ]]></artwork>
          <!--        <postamble>which is a very simple example.</postamble>-->
        </figure>
        <t>
          where:
        </t>
        <dl>
          <dt>PROTO</dt>
          <dd>
            the 16-bit protocol number, e.g. 6 for tcp. In network byte order.
          </dd>
          <dt>SVC</dt>
          <dd>
            the 16-bit service value of the boxed record, i.e. the port number.
            In network byte order.
          </dd>
          <dt>TYPE</dt>
          <dd>
            is the 32-bit record type of the boxed record. In network byte order.
          </dd>
          <dt>RECORD DATA</dt>
          <dd>
            is a variable length field containing the "DATA" format of TYPE as
            defined for the respective TYPE in DNS.
          </dd>
        </dl>
      </section>
      <section anchor="gnsrecords_vpn" numbered="true" toc="default">
        <name>VPN</name>
        <t>
          A VPN DATA entry has the following format:</t>
        <figure anchor="figure_vpnrecord">
          <artwork name="" type="" align="left" alt=""><![CDATA[
 0     8     16    24    32    40    48    56
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |          HOSTING PEER PUBLIC KEY              |
 |                (256 bits)                     |
 |                                               |
 |                                               |
 +-----------+-----------------------------------+
 |   PROTO   |    SERVICE  NAME                  |
 +-----------+                                   +
 /                                               /
 /                                               /
 |                                               |
 +-----+-----+-----+-----+-----+-----+-----+-----+
            ]]></artwork>
          <!--        <postamble>which is a very simple example.</postamble>-->
        </figure>
        <t>
          where:
        </t>
        <dl>
          <dt>HOSTING PEER PUBLIC KEY</dt>
          <dd>
            is a 256-bit EdDSA public key identifying the peer hosting the
            service.
          </dd>
          <dt>PROTO</dt>
          <dd>
            the 16-bit protocol number, e.g. 6 for TCP. In network byte order.
          </dd>
          <dt>SERVICE NAME</dt>
          <dd>
            a shared secret used to identify the service at the hosting peer,
            used to derive the port number requird to connect to the service.
            The service name MUST be a 0-terminated UTF-8 string.
          </dd>
        </dl>
      </section>
    </section>
 
    <section anchor="publish" numbered="true" toc="default">
      <name>Publishing Records</name>
      <t>
        GNS resource records are published in a distributed hash table (DHT).
        We assume that a DHT provides two functions: GET(key) and PUT(key,value).
        In GNS, resource records are grouped by their respective labels,
        encrypted and published together in a single resource records block
        (RRBLOCK) in the DHT under a key "q": PUT(q, RRBLOCK).
        The key "q" which is derived from the zone key "zk" and the respective
        label of the contained records.
      </t>
      <section anchor="blinding" numbered="true" toc="default">
        <name>Key Derivations</name>
        <t>
          Given a label, the DHT key "q" is derived as follows:
        </t>
        <artwork name="" type="" align="left" alt=""><![CDATA[
 PRK_h := HKDF-Extract ("key-derivation", zk)
 h := HKDF-Expand (PRK_h, label | "gns", 512 / 8)
 d_h := h * d mod L
 zk_h := h mod L * zk
 q := SHA512 (zk_h)
          ]]></artwork>
        <t>
          We use a hash-based key derivation function (HKDF) as defined in
          <xref target="RFC5869" />. We use HMAC-SHA512 for the extraction
          phase and HMAC-SHA256 for the expansion phase.
        </t>
        <dl>
          <dt>PRK_h</dt>
          <dd>
            is key material retrieved using an HKDF using the string
            "key-derivation" as salt and the public zone key "zk" as initial
            keying material.
          </dd>
          <dt>h</dt>
          <dd>
            is the 512-bit HKDF expansion result. The expansion info input is a
            concatenation of the label and string "gns".
          </dd>
          <dt>d</dt>
          <dd>
            is the 256-bit private zone key as defined in <xref target="zones" />.
          </dd>
          <dt>label</dt>
          <dd>is a UTF-8 string under which the resource records are published.
          </dd>
          <dt>d_h</dt>
          <dd>
            is a 256-bit private key derived from the "d" using the
            keying material "h".
          </dd>
          <dt>zk_h</dt>
          <dd>
            is a 256-bit public key derived from the zone key "zk" using the
            keying material "h".
          </dd>
          <dt>L</dt>
          <dd>
            is the prime-order subgroup as defined in <xref target="zones" />.
          </dd>
          <dt>q</dt>
          <dd>
            Is the 512-bit DHT key under which the resource records block is
            published.
            It is the SHA512 hash over the public key "zk_h" corresponding to the
            derived private key "d_h".
          </dd>
        </dl>
        <t>
          We point out that the multiplication of "zk" with "h" is a point multiplication,
          while the multiplication of "d" with "h" is a scalar multiplication.
        </t>
      </section>
      <section anchor="wire" numbered="true" toc="default">
        <name>Resource Records Block</name>
        <t>
          GNS records are grouped by their labels and published as a single
          block in the DHT. The grouped record sets MAY be paired with any
          number of supplemental records. Supplemental records must have the
          supplemental flag set (See <xref target="rrecords"/>).
          The contained resource records are encrypted using a symmetric
          encryption scheme.
          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:
        </t>
        <figure anchor="figure_record_block">
          <artwork name="" type="" align="left" alt=""><![CDATA[
 0     8     16    24    32    40    48    56
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |                   SIGNATURE                   |
 |                                               |
 |                                               |
 |                                               |
 |                                               |
 |                                               |
 |                                               |
 |                                               |
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |                  PUBLIC KEY                   |
 |                                               |
 |                                               |
 |                                               |
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |         SIZE          |       PURPOSE         |
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |                   EXPIRATION                  |
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |                    BDATA                      /
 /                                               /
 /                                               |
 +-----+-----+-----+-----+-----+-----+-----+-----+
            ]]></artwork>
        </figure>
        <t>where:</t>
        <dl>
          <dt>SIGNATURE</dt>
          <dd>
            A 512-bit ECDSA deterministic signature compliant with
            <xref target="RFC6979" />. The signature is computed over the data
            following the PUBLIC KEY field.
            The signature is created using the derived private key "d_h" (see
            <xref target="publish" />).
          </dd>
          <dt>PUBLIC KEY</dt>
          <dd>
            is the 256-bit public key "zk_h" to be used to verify SIGNATURE. The
            wire format of this value is defined in <xref target="RFC8032" />,
            Section 5.1.5.
          </dd>
          <dt>SIZE</dt>
          <dd>
            A 32-bit value containing the length of the signed data following the
            PUBLIC KEY field in network byte order. This value always includes the
            length of the fields SIZE (4), PURPOSE (4) and EXPIRATION (8) in
            addition to the length of the BDATA.  While a 32-bit value is used,
            implementations MAY refuse to publish blocks beyond a certain
            size significantly below 4 GB. However, a minimum block size of
            62 kilobytes MUST be supported.
            <!-- See GNUNET_CONSTANTS_MAX_BLOCK_SIZE -->
          </dd>
          <dt>PURPOSE</dt>
          <dd>
            A 32-bit signature purpose flag. This field MUST be 15 (in network
            byte order).
          </dd>
          <dt>EXPIRATION</dt>
          <dd>
            Specifies when the RRBLOCK expires and the encrypted block
            SHOULD be removed from the DHT and caches as it is likely stale.
            However, applications MAY continue to use non-expired individual
            records until they expire.  The value MUST be set to the
            expiration time of the resource record contained within this block with the
            smallest expiration time.
            If a records block includes shadow records, then the maximum
            expiration time of all shadow records with matching type and the
            expiration times of the non-shadow records is considered.
            This is a 64-bit absolute date in microseconds since midnight
            (0 hour), January 1, 1970 in network byte order.
          </dd>
          <dt>BDATA</dt>
          <dd>
            The encrypted resource records with a total size of SIZE - 16.
          </dd>
        </dl>
      </section>
      <section anchor="recordencryption" numbered="true" toc="default">
        <name>Record Data Encryption and Decryption</name>
        <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:
        </t>
        <figure anchor="figure_rdata">
          <artwork name="" type="" align="left" alt=""><![CDATA[
 0     8     16    24    32    40    48    56
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |     RR COUNT          |        EXPIRA-        /
 +-----+-----+-----+-----+-----+-----+-----+-----+
 /         -TION         |       DATA SIZE       |
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |         TYPE          |          FLAGS        |
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |                      DATA                     /
 /                                               /
 /                                               |
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |                   EXPIRATION                  |
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |       DATA SIZE       |          TYPE         |
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |           FLAGS       |        DATA           /
 +-----+-----+-----+-----+                       /
 /                       +-----------------------/
 /                       |                       /
 +-----------------------+                       /
 /                     PADDING                   /
 /                                               /
            ]]></artwork>
          <!--        <postamble>which is a very simple example.</postamble>-->
        </figure>
        <t>where:</t>
        <dl>
          <dt>RR COUNT</dt>
          <dd>
            A 32-bit value containing the number of variable-length resource
            records which are
            following after this field in network byte order.
          </dd>
          <dt>EXPIRATION, DATA SIZE, TYPE, FLAGS and DATA</dt>
          <dd>
            These fields were defined
            in the resource record format in <xref target="rrecords" />.
            There MUST be a total of RR COUNT of these resource records
            present.
          </dd>
          <dt>PADDING</dt>
          <dd>
            The padding MUST contain the value 0 in all octets.
            The padding MUST ensure that the size of the RDATA WITHOUT the RR
            COUNT field is a power of two.
            As a special exception, record sets with (only) a PKEY record type
            are never padded. Note that a record set with a PKEY record MUST NOT
            contain other records.
          </dd>
 
        </dl>
        <t>
          The symmetric keys and initialization vectors are derived from the
          record label and the zone key "zk". For decryption of the resource
          records block payload, the key material "K" and initialization vector
          "IV" for the symmetric cipher are derived as follows:
        </t>
        <!-- OLD VERSION
        PRK_kiv := HKDF-Extract (zk, label)
        K := HKDF-Expand (PRK_kiv, "gns-aes-ctx-key", 512 / 8);
        IV := HKDF-Expand (PRK_kiv, "gns-aes-ctx-iv", 256 / 8)
        -->
        <artwork name="" type="" align="left" alt=""><![CDATA[
 PRK_k := HKDF-Extract ("gns-aes-ctx-key", zk)
 PRK_iv := HKDF-Extract ("gns-aes-ctx-iv", zk)
 K := HKDF-Expand (PRK_k, label, 512 / 8);
 IV := HKDF-Expand (PRK_iv, label, 256 / 8)
          ]]></artwork>
        <t>
          HKDF is a hash-based key derivation function as defined in
          <xref target="RFC5869" />. Specifically, HMAC-SHA512 is used for the
          extraction phase and HMAC-SHA256 for the expansion phase.
          The output keying material is 64 octets (512 bit) for the symmetric
          keys and 32 octets (256 bit) for the initialization vectors.
          We divide the resulting keying material "K" into a 256-bit AES
          <xref target="RFC3826" /> key
          and a 256-bit TWOFISH <xref target="TWOFISH" /> key:
        </t>
        <figure anchor="figure_hkdf_keys">
          <artwork name="" type="" align="left" alt=""><![CDATA[
 0     8     16    24    32    40    48    56
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |                    AES KEY                    |
 |                                               |
 |                                               |
 |                                               |
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |                  TWOFISH KEY                  |
 |                                               |
 |                                               |
 |                                               |
 +-----+-----+-----+-----+-----+-----+-----+-----+
            ]]></artwork>
          <!--        <postamble>which is a very simple example.</postamble>-->
        </figure>
        <t>
          Similarly, we divide "IV" into a 128-bit initialization vector
          and a 128-bit initialization vector:
        </t>
        <figure anchor="figure_hkdf_ivs">
          <artwork name="" type="" align="left" alt=""><![CDATA[
 0     8     16    24    32    40    48    56
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |                    AES IV                     |
 |                                               |
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |                  TWOFISH IV                   |
 |                                               |
 +-----+-----+-----+-----+-----+-----+-----+-----+
            ]]></artwork>
          <!--        <postamble>which is a very simple example.</postamble>-->
        </figure>
 
        <t>
          The keys and IVs are used for a CFB128-AES-256 and
          CFB128-TWOFISH-256 chained symmetric cipher. Both ciphers are used in
          Cipher FeedBack (CFB) mode <xref target="RFC3826" />.
        </t>
        <artwork name="" type="" align="left" alt=""><![CDATA[
 RDATA := AES(K[0:31], IV[0:15],
              TWOFISH(K[32:63], IV[16:31], BDATA))
 BDATA := TWOFISH(K[32:63], IV[16:31],
                  AES(K[0:31], IV[0:15], RDATA))
          ]]></artwork>
      </section>
    </section>
    <section anchor="encoding" numbered="true" toc="default">
      <name>Internationalization and Character Encoding</name>
      <t>
        All labels in GNS are encoded in UTF-8 <xref target="RFC3629" />.
        This does not include any DNS names found in DNS records, such as CNAME
        records, which are internationalized through the IDNA specifications
        <xref target="RFC5890" />.
      </t>
    </section>
    <section anchor="resolution" numbered="true" toc="default">
      <name>Name Resolution</name>
      <t>
        Names in GNS are resolved by recursively querying the DHT record storage.
        In the following, we define how resolution is initiated and each
        iteration in the resolution is processed.
      </t>
      <t>
        GNS resolution of a name must start in a given starting zone indicated using
        a zone public key.
        Details on how the starting zone may be determined is discussed in
        <xref target="governance" />.
      </t>
      <t>
        When GNS name resolution is requested, a desired record type MAY be
        provided by the client.
        The GNS resolver will use the desired record type to guide
        processing, for example by providing conversion of VPN records to A
        or AAAA records, if that is desired.
 
        However, filtering of record sets according to the required record
        types MUST still be done by the client after the resource record set
        is retrieved.
      </t>
        <section anchor="recursion" numbered="true" toc="default">
          <name>Recursion</name>
          <t>
            In each step of the recursive name resolution, there is an
            authoritative zone zk and a name to resolve. The name may be empty.
            Initially, the authoritative zone is the start zone. If the name
            is empty, it is interpreted as the apex label "@".
          </t>
          <t>
            From here, the following steps are recursively executed, in order:
          </t>
          <ol>
            <li>Extract the right-most label from the name to look up.</li>
            <li>Calculate q using the label and zk as defined in
            <xref target="blinding" />.</li>
            <li>Perform a DHT query GET(q) to retrieve the RRBLOCK.</li>
            <li>Verify and process the RRBLOCK and decrypt the BDATA contained
              in it as defined in <xref target="recordencryption" />.</li>
          </ol>
          <t>
            Upon receiving the RRBLOCK from the DHT, apart from verifying the
            provided signature, the resolver MUST check that the authoritative
            zone key was used to sign the record:
            The derived zone key "h*zk" MUST match the public key provided in
            the RRBLOCK, otherwise the RRBLOCK MUST be ignored and the DHT lookup
            GET(q) MUST continue.
          </t>
        </section>
        <section anchor="record_processing" numbered="true" toc="default">
          <name>Record Processing</name>
    <t>
            Record processing occurs at the end of a single recursion. We assume
            that the RRBLOCK has been cryptographically verified and decrypted.
            At this point, we must first determine if we have received a valid
            record set in the context of the name we are trying to resolve:
          </t>
    <ol>
          <li>
            Case 1:
            If the remainder of the name to resolve is empty and the record set
            does not consist of a PKEY, CNAME or DNS2GNS record, the record set
            is the result and the recursion is concluded.
          </li>
    <li>
      Case 2:
      If the name to be resolved is of the format
      "_SERVICE._PROTO" and the record set contains one or more matching BOX
      records, the records in the BOX records are the result and the recusion
      is concluded (<xref target="box_processing" />).
    </li>
          <li>
            Case 3:
            If the remainder of the name to resolve is not empty and
      does not match the "_SERVICE._PROTO" syntax, then the current record set
            MUST consist of a single PKEY record (<xref target="pkey_processing" />),
            a single CNAME record (<xref target="cname_processing" />),
            or one or more GNS2DNS records (<xref target="gns2dns_processing" />),
            which are processed as described in the respective sections below.
            The record set may include any number of supplemental records.
            Otherwise, resolution fails
            and the resolver MUST return an empty record set.
 
      Finally, after the recursion terminates, the client preferences
      for the record type SHOULD be considered. If a VPN record is found
      and the client requests an A or AAAA record, the VPN record
      SHOULD be converted (<xref target="vpn_processing" />)
      if possible.
    </li>
    </ol>
          <section anchor="pkey_processing" numbered="true" toc="default">
            <name>PKEY</name>
            <t>
              When the resolver encounters a PKEY record and the remainder of
              the name is not empty, resolution continues
              recursively with the remainder of the name in the
              GNS zone specified in the PKEY record.
            </t>
            <t>
              If the remainder of the name to resolve is empty and we have
              received a record set containing only a single PKEY record, the
              recursion is continued with the PKEY as authoritative zone and
              the empty apex label "@" as remaining name, except in the case
              where the desired record type is PKEY, in which case the PKEY
              record is returned and the resolution is concluded without
              resolving the empty apex label.
            </t>
          </section>
          <section anchor="gns2dns_processing" numbered="true" toc="default">
            <name>GNS2DNS</name>
            <t>
              When a resolver encounters one or more GNS2DNS records and the remaining name
              is empty and the desired record type is GNS2DNS, the GNS2DNS
              records are returned.
            </t>
            <t>
              Otherwise, it is expected that the resolver first resolves the
              IP(s) of the specified DNS name server(s). GNS2DNS records MAY
              contain numeric IPv4 or IPv6 addresses, allowing the resolver to
              skip this step.
              The DNS server names may themselves be names in GNS or DNS.
              If the DNS server name ends in ".+", the rest of the name is to be
              interpreted relative to the zone of the GNS2DNS record.
              If the DNS server name ends in ".&lt;Base32(zk)&gt;", the DNS
              server name is to be resolved against the GNS zone zk.
            </t>
            <t>
              Multiple GNS2DNS records may be stored under the same label,
              in which case the resolver MUST try all of them.
              The resolver MAY try them in any order or even in parallel.
              If multiple GNS2DNS records are present, the DNS name MUST be
              identical for all of them, if not the resolution fails and an
              emtpy record set is returned as the record set is invalid.
            </t>
            <t>
              Once the IP addresses of the DNS servers have been determined,
              the DNS name from the GNS2DNS record is appended
              to the remainder of the name to be resolved, and
              resolved by querying the DNS name server(s).  As the DNS servers
              specified are possibly authoritative DNS servers, the GNS resolver MUST
              support recursive resolution and MUST NOT delegate this to the
              authoritative DNS servers.
              The first successful recursive name resolution result
              is returned to the client.
              In addition, the resolver returns the queried DNS name as a
              supplemental LEHO record (<xref target="gnsrecords_leho" />) with a
              relative expiration time of one hour.
            </t>
      <t>
        GNS resolvers SHOULD offer a configuration
        option to disable DNS processing to avoid information leakage
        and provide a consistent security profile for all name resolutions.
        Such resolvers would return an empty record set upon encountering
        a GNS2DNS record during the recursion. However, if GNS2DNS records
        are encountered in the record set for the apex and a GNS2DNS record
        is expicitly requested by the application, such records MUST
        still be returned, even if DNS support is disabled by the
        GNS resolver configuration.
      </t>
          </section>
          <section anchor="cname_processing" numbered="true" toc="default">
            <name>CNAME</name>
            <t>
              If a CNAME record is encountered, the canonical name is
              appended to the remaining name, except if the remaining name
              is empty and the desired record type is CNAME, in which case
              the resolution concludes with the CNAME record.
              If the canonical name ends in ".+",
              resolution continues in GNS with the new name in the
              current zone.  Otherwise, the resulting name is resolved via the
              default operating system name resolution process.
              This may in turn again trigger a GNS resolution process depending
              on the system configuration.
              <!-- Note: this permits non-DNS resolvers to be triggered via NSS! -->
            </t>
            <t>
              The recursive DNS resolution process may yield a CNAME as well
              which in turn may either point into the DNS or GNS namespace
              (if it ends in a ".&lt;Base32(zk)&gt;").
              In order to prevent infinite loops, the resolver MUST
              implement loop detections or limit the number of recursive
              resolution steps.
              If the last CNAME was a DNS name, the resolver returns the DNS name
              as a supplemental LEHO record (<xref target="gnsrecords_leho" />)
              with a relative expiration time of one hour.
        <!-- Note: Martin: do we actually implement this in GNS today?
       Seems rather tricky to detect if we go via NSS... -->
            </t>
          </section>
          <section anchor="box_processing" numbered="true" toc="default">
            <name>BOX</name>
            <t>
              When a BOX record is received, a GNS resolver must unbox it if the
              name to be resolved continues with "_SERVICE._PROTO".
              Otherwise, the BOX record is to be left untouched. This way, TLSA
              (and SRV) records do not require a separate network request, and
              TLSA records become inseparable from the corresponding address
              records.
            </t>
          </section>
          <section anchor="vpn_processing" numbered="true" toc="default">
            <name>VPN</name>
            <t>
        At the end of the recursion,
              if the queried record type is either A or AAAA and the retrieved
              record set contains at least one VPN record, the resolver SHOULD
              open a tunnel and return the IPv4 or IPv6 tunnel address,
              respectively.
              The type of tunnel depends on the contents of the VPN record data.
              The VPN record MUST be returned if the resolver implementation
              does not support setting up a tunnnel.
            </t>
          </section>
          <section anchor="nick_processing" numbered="true" toc="default">
            <name>NICK</name>
            <t>
              NICK records are only relevant to the recursive resolver
              if the record set in question is the final result which is to
              be returned to the client. The encountered NICK records may either
              be supplemental (see <xref target="rrecords"/>) or
              non-supplemental.
              If the NICK record is supplemental, the resolver only returns the
              record set if one of the non-supplemental records matches the
              queried record type.
            </t>
            <t>
              The differentiation between a supplemental and non-supplemental
              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
           "alice.doe" and is published under the empty label along with an A
           record. The NICK record should be interpreted as: The zone defined by
           "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
        label "alice" along with an A record. The NICK record should be
        interpreted as: The zone defined by "doe" wants to be referred to as
        "john". This distinction is likely useful for other records published as
        supplemental.
       </t>
 
 
          </section>
        </section>
      </section>
      <section anchor="revocation" numbered="true" toc="default">
        <name>Zone Revocation</name>
        <t>
          Whenever a recursive resolver encounters a new GNS zone, it MUST
          check against the local revocation list whether the respective
          zone key has been revoked.  If the zone key was revoked, the
          resolution MUST fail with an empty result set.
        </t>
        <t>
          In order to revoke a zone key, a signed revocation object SHOULD be
          published.
          This object MUST be signed using the private zone key.
          The revocation object is flooded in the overlay network. To prevent
          flooding attacks, the revocation message MUST contain a proof of work
          (PoW).
          The revocation message including the PoW MAY be calculated
          ahead of time to support timely revocation.
        </t>
        <t>
          For all occurences below, "Argon2id" is the Password-based Key
          Derivation Function as defined in <xref target="Argon2" />. For the
          PoW calculations the algorithm is instantiated with the
          following parameters:
        </t>
        <dl>
          <dt>S</dt>
          <dd>The salt. Fixed 16-octet string: "GnsRevocationPow".</dd>
          <dt>t</dt>
          <dd>Number of iterations: 3</dd>
          <dt>m</dt>
          <dd>Memory size in KiB: 1024</dd>
          <dt>T</dt>
          <dd>Output length of hash in bytes: 64</dd>
          <dt>p</dt>
          <dd>Parallelization parameter: 1</dd>
          <dt>v</dt>
          <dd>Algorithm version: 0x13</dd>
          <dt>y</dt>
          <dd>Algorithm type (Argon2id): 2</dd>
          <dt>X</dt><dd>Unused</dd>
          <dt>K</dt><dd>Unused</dd>
        </dl>
        <t>
          The following is the message string "P" on which the PoW is
          calculated:
        </t>
        <figure anchor="figure_revocation">
          <artwork name="" type="" align="left" alt=""><![CDATA[
 0     8     16    24    32    40    48    56
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |                      POW                      |
 +-----------------------------------------------+
 |                   TIMESTAMP                   |
 +-----------------------------------------------+
 |                  PUBLIC KEY                   |
 |                                               |
 |                                               |
 |                                               |
 +-----+-----+-----+-----+-----+-----+-----+-----+
            ]]></artwork>
        </figure>
        <t>where:</t>
        <dl>
          <dt>POW</dt>
          <dd>
            A 64-bit solution to the PoW. In network byte order.
          </dd>
          <dt>TIMESTAMP</dt>
          <dd>
            denotes the absolute 64-bit date when the revocation was computed.
            In microseconds since midnight (0 hour), January 1, 1970 in network
            byte order.
          </dd>
          <dt>PUBLIC KEY</dt>
          <dd>
            is the 256-bit public key "zk" of the zone which is being revoked and
            the key to be used to verify SIGNATURE. The
            wire format of this value is defined in <xref target="RFC8032" />,
            Section 5.1.5.
          </dd>
        </dl>
        <t>
          Traditionally, PoW schemes require to find a "POW" such that
          at least D leading zeroes are found in the hash result.
          D is then referred to as the "difficulty" of the PoW.
          In order to reduce the variance in time it takes to calculate the
          PoW, we require that a number "Z" different PoWs must be
          found that on average have "D" leading zeroes.
        </t>
        <t>
          The resulting proofs may then published and disseminated. The concrete
          dissemination and publication methods are out of scope of this
          document. Given an average difficulty of "D", the proofs have an
          expiration time of EPOCH. With each additional bit difficulty, the
          lifetime of the proof is prolonged for another EPOCH.
          Consequently, by calculating a more difficult PoW, the lifetime of the
          proof can be increased on demand by the zone owner.
        </t>
        <t>
          The parameters are defined as follows:
        </t>
        <dl>
          <dt>Z</dt>
          <dd>The number of PoWs required is fixed at 32.</dd>
          <dt>D</dt>
          <dd>The difficulty is fixed at 25.</dd>
          <dt>EPOCH</dt>
          <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:
        </t>
        <figure anchor="figure_revocationdata">
          <artwork name="" type="" align="left" alt=""><![CDATA[
 0     8     16    24    32    40    48    56
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |                   TIMESTAMP                   |
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |                      TTL                      |
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |                     POW_0                     |
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |                       ...                     |
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |                     POW_Z-1                   |
 +-----------------------------------------------+
 |                   SIGNATURE                   |
 |                                               |
 |                                               |
 |                                               |
 |                                               |
 |                                               |
 |                                               |
 |                                               |
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |                  PUBLIC KEY                   |
 |                                               |
 |                                               |
 |                                               |
 +-----+-----+-----+-----+-----+-----+-----+-----+
            ]]></artwork>
        </figure>
        <t>where:</t>
        <dl>
          <dt>TIMESTAMP</dt>
          <dd>
            denotes the absolute 64-bit date when the revocation was computed.
            In microseconds since midnight (0 hour), January 1, 1970 in network
            byte order. This is the same value as the timestamp used in the
            individual PoW calculations.
          </dd>
          <dt>TTL</dt>
          <dd>
            denotes the relative 64-bit time to live of of the record in
            microseconds also in network byte order. This field is informational
            for a verifier. The verifier may discard revocation if the TTL
            indicates that it is already expired. However, the actual TTL of the
            revocation must be determined by examining the leading zeros in the
            proof of work calculation.
          </dd>
          <dt>POW_i</dt>
          <dd>
            The values calculated as part of the PoW, in network byte order.
            Each POW_i MUST be unique in the set of POW values.
            To facilitate fast verification
            of uniqueness, the POW values must be given in strictly
            monotonically increasing order in the message.
          </dd>
          <dt>SIGNATURE</dt>
          <dd>
            A 512-bit ECDSA deterministic signature compliant with
            <xref target="RFC6979" /> over the public zone zk of the zone
            which is revoked and corresponds to the key used in the PoW.
            The signature is created using the private zone key "d" (see
            <xref target="zones" />).
          </dd>
          <dt>PUBLIC KEY</dt>
          <dd>
            is the 256-bit public key "zk" of the zone which is being revoked and
            the key to be used to verify SIGNATURE. The
            wire format of this value is defined in <xref target="RFC8032" />,
            Section 5.1.5.
          </dd>
        </dl>
       <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:
        </t>
        <figure anchor="figure_revsigwithpseudo">
          <artwork name="" type="" align="left" alt=""><![CDATA[
 0     8     16    24    32    40    48    56
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |         SIZE (0x30)   |       PURPOSE (0x03)  |
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |                  PUBLIC KEY                   |
 |                                               |
 |                                               |
 |                                               |
 +-----+-----+-----+-----+-----+-----+-----+-----+
 |                   TIMESTAMP                   |
 +-----+-----+-----+-----+-----+-----+-----+-----+
            ]]></artwork>
        </figure>
        <t>where:</t>
        <dl>
          <dt>SIZE</dt>
          <dd>
            A 32-bit value containing the length of the signed data in bytes
            (48 bytes) in network byte order.
          </dd>
          <dt>PURPOSE</dt>
          <dd>
            A 32-bit signature purpose flag. This field MUST be 3 (in network
            byte order).
          </dd>
          <dt>PUBLIC KEY / TIMESTAMP</dt>
          <dd>Both values as defined in the revocation data object above.</dd>
        </dl>
        <t>
          In order to verify a revocation the following steps must be taken,
          in order:
        </t>
        <ol>
          <li>The current time MUST be between TIMESTAMP and
            TIMESTAMP+TTL.</li>
          <li>The signature MUST match the public key.</li>
          <li>The set of POW values MUST NOT contain duplicates.</li>
          <li>The average number of leading zeroes resulting from the provided
            POW values D' MUST be greater than D.</li>
          <li>The validation period (TTL) of the revocation is calculated as
            (D'-D) * EPOCH * 1.1. The EPOCH is extended by
            10% in order to deal with unsynchronized clocks.
            The TTL added on top of the TIMESTAMP yields the
            expiration date.</li>
        </ol>
      </section>
      <section anchor="governance" numbered="true" toc="default">
        <name>Determining the Root Zone and Zone Governance</name>
        <t>
          The resolution of a GNS name must start in a given start zone
          indicated to the resolver using any public zone key.
          The local resolver may have a local start zone configured/hard-coded
          which points to a local or remote start zone key.
          A resolver client may also determine the start zone from the
          suffix of the name given for resolution or using information
    retrieved out of band.
          The governance model of any zone is at the sole discretion
          of the zone owner. However, the choice of start zone(s) is at the sole
          discretion of the local system administrator or user.
        </t>
        <t>
          This is an important distinguishing factor from the Domain Name System
          where root zone governance is centralized at the Internet Corporation
          for Assigned Names and Numbers (ICANN).
          In DNS terminology, GNS roughly follows the idea of a hyper-hyper
    local root zone deployment, with the difference that it is not
    expected that all deployments use the same local root zone.
        </t>
        <t>
          In the following, we give examples how a local client resolver SHOULD
          discover the start zone.  The process given is not exhaustive and
          clients MAY suppliement it with other mechanisms or ignore it if the
    particular application requires a different process.
        </t>
        <t>
          GNS clients SHOULD first try to interpret the top-level domain of
          a GNS name as a zone key.
          For example. if the top-level domain is a Base32-encoded public zone
          key "zk", the root zone of the resolution process is implicitly given
          by the name:
        </t>
        <artwork name="" type="" align="left" alt=""><![CDATA[
 Example name: www.example.<Base32(zk)>
 => Root zone: zk
 => Name to resolve from root zone: www.example
          ]]></artwork>
        <t>
          In GNS, users MAY own and manage their own zones.
          Each local zone SHOULD be associated with a single GNS label,
    but users MAY choose to use longer names consisting of
    multiple labels.
          If the name of a locally managed zone matches the suffix
    of the name to be resolved,
    resolution SHOULD start from the respective local zone:
        </t>
        <artwork name="" type="" align="left" alt=""><![CDATA[
 Example name: www.example.org
 Local zones:
 fr = (d0,zk0)
 gnu = (d1,zk1)
 com = (d2,zk2)
 ...
 => Entry zone: zk1
 => Name to resolve from entry zone: www.example
          ]]></artwork>
        <t>
          Finally, additional "suffix to zone" mappings MAY be configured.
          Suffix to zone key mappings SHOULD be configurable through a local
          configuration file or database by the user or system administrator.
          The suffix MAY consist of multiple GNS labels concatenated with a
          ".". If multiple suffixes match the name to resolve, the longest
          matching suffix MUST BE used. The suffix length of two results
          cannot be equal, as this would indicate a misconfiguration.
    If both a locally managed zone and a configuration entry exist
    for the same suffix, the locally managed zone MUST have priority.
        </t>
        <artwork name="" type="" align="left" alt=""><![CDATA[
 Example name: www.example.org
 Local suffix mappings:
 gnu = zk0
 example.org = zk1
 example.com = zk2
 ...
 => Entry zone: zk1
 => Name to resolve from entry zone: www
          ]]></artwork>
      </section>
      <section anchor="security" numbered="true" toc="default">
        <name>Security Considerations</name>
        <section anchor="security_crypto" numbered="true" toc="default">
          <name>Cryptography</name>
          <t>
            The security of cryptographic systems depends on both the strength of
            the cryptographic algorithms chosen and the strength of the keys used
            with those algorithms.  The security also depends on the engineering
            of the protocol used by the system to ensure that there are no
            non-cryptographic ways to bypass the security of the overall system.
          </t>
          <t>
            This document concerns itself with the selection of cryptographic
            algorithms for use in GNS.
            The algorithms identified in this document are not known to be
            broken (in the cryptographic sense) at the current time, and
            cryptographic research so far leads us to believe that they are
            likely to remain secure into the foreseeable future.  However, this
            isn't necessarily forever, and it is expected that new revisions of
            this document will be issued from time to time to reflect the current
            best practices in this area.
          </t>
          <t>
            GNS uses ECDSA over Curve25519. This is an unconventional choice,
            as ECDSA is usually used with other curves.  However, traditional
            ECDSA curves are problematic for a range of reasons described in
            the Curve25519 and EdDSA papers.  Using EdDSA directly is also
            not possible, as a hash function is used on the private key which
            destroys the linearity that the GNU Name System depends upon.
            We are not aware of anyone suggesting that using Curve25519 instead
            of another common curve of similar size would lower the security of
            ECDSA.  GNS uses 256-bit curves because that way the encoded (public)
            keys fit into a single DNS label, which is good for usability.
          </t>
          <t>
            In terms of crypto-agility, whenever the need for an updated cryptographic
            scheme arises to replace ECDSA over Curve25519 it may simply be introduced
            through a new record type. Such a new record type may then replace
            the PKEY record type for future records. The old record type remains
            and zones can iteratively migrate to the updated zone keys.
          </t>
        </section>
        <section anchor="security_abuse" numbered="true" toc="default">
          <name>Abuse mitigation</name>
          <t>
            GNS names are UTF-8 strings. Consequently, GNS faces similar issues
            with respect to name spoofing as DNS does for internationalized
            domain names.
            In DNS, attackers may register similar sounding or looking
            names (see above) in order to execute phishing attacks.
            GNS zone administrators must take into account this attack vector and
            incorporate rules in order to mitigate it.
          </t>
          <t>
            Further, DNS can be used to combat illegal content on the internet
            by having the respective domains seized by authorities.
            However, the same mechanisms can also be abused in order to impose
            state censorship, which ist one of the motivations behind GNS.
            Hence, such a seizure is, by design, difficult to impossible in GNS.
            In particular, GNS does not support WHOIS (<xref target="RFC3912" />).
          </t>
        </section>
        <section anchor="security_keymanagement" numbered="true" toc="default">
          <name>Zone management</name>
          <t>
            In GNS, zone administrators need to manage and protect their zone
            keys. Once a zone key is lost it cannot be recovered. Once it is
            compromised it cannot be revoked (unless a revocation message was
            pre-calculated and is still available).
            Zone administrators, and for GNS this includes end-users, are
            required to responsibly and dilligently protect their cryptographic
            keys.  Offline signing is in principle possible, but GNS does not
            support separate zone signing and key-signing keys
            (as in <xref target="RFC6781" />) in order to provide usable security.
          </t>
          <t>
            Similarly, users are required to manage their local root zone.
            In order to ensure integrity and availability or names, users must
            ensure that their local root zone information is not compromised or
            outdated.
            It can be expected that the processing of zone revocations and an
            initial root zone is provided with a GNS client implementation
            ("drop shipping").
            Extension and customization of the zone is at the full discretion of
            the user.
          </t>
        </section>
        <section anchor="security_dht" numbered="true" toc="default">
          <name>Impact of underlying DHT</name>
          <t>
            This document does not specifiy the properties of the underlying
            distributed hash table (DHT) which is required by any GNS
            implementation. For implementors, it is important to note that
            the properties of the DHT are directly inherited by the
            GNS implementation. This includes both security as well as
            other non-functional properties such as scalability and performance.
            Implementors should take great care when selecting or implementing
            a DHT for use in a GNS implementation.
            DHTs with string security and performance guarantees exist
            <xref target="R5N"/>.
            It should also be taken into consideration that GNS implementations
            which build upon different DHT overlays are unlikely to be
            interoperable with each other.
          </t>
        </section>
        <section anchor="security_rev" numbered="true" toc="default">
          <name>Revocations</name>
          <t>
            Zone administrators are advised to pre-generate zone revocations
            and securely store the revocation information in case the zone
            key is lost, compromised or replaced in the furture.
            Pre-calculated revocations may become invalid due to expirations
            or protocol changes such as epoch adjustments.
            Consequently, implementors and users must make precautions in order
            to manage revocations accordingly.
          </t>
          <t>
            Revocation payloads do NOT include a 'new' key for key replacement.
            Inclusion of such a key would have two major disadvantages:
          </t>
          <t>
            If revocation is used after a private key was compromised,
            allowing key replacement would be dangerous: if an
            adversary took over the private key, the adversary could then
            broadcast a revocation with a key replacement. For the replacement,
            the compromised owner would have no chance to issue even a
            revocation. Thus, allowing a revocation message to replace a private
            key makes dealing with key compromise situations worse.
          </t>
          <t>
            Sometimes, key revocations are used with the objective of changing
            cryptosystems. Migration to another cryptosystem by replacing keys
            via a revocation message would only be secure as long as both
            cryptosystems are still secure against forgery. Such a planned,
            non-emergency migration to another cryptosystem should be done by
            running zones for both ciphersystems in parallel for a while. The
            migration would conclude by revoking the legacy zone key only once
            it is deemed no longer secure, and hopefully after most users have
            migrated to the replacement.
          </t>
        </section>
      </section>
      <section anchor="gana" numbered="true" toc="default">
        <name>GANA Considerations</name>
        <t>
          GANA is requested to create an "GNU Name System Record Types" registry.
          The registry shall record for each entry:
        </t>
        <ul>
          <li>Name: The name of the record type (case-insensitive ASCII
            string, restricted to alphanumeric characters</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>
          <li>Contact: Optionally, the contact information of a person to contact for
            further information</li>
          <li>References: Optionally, references describing the record type
            (such as an RFC)</li>
        </ul>
        <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:
        </t>
        <figure anchor="figure_rrtypenums">
          <artwork name="" type="" align="left" alt=""><![CDATA[
 Number | Name    | Contact | References | Description
 -------+---------+---------+------------+-------------------------
 65536  | PKEY    | N/A     | [This.I-D] | GNS zone delegation
 65537  | NICK    | N/A     | [This.I-D] | GNS zone nickname
 65538  | LEHO    | N/A     | [This.I-D] | GNS legacy hostname
 65539  | VPN     | N/A     | [This.I-D] | VPN resolution
 65540  | GNS2DNS | N/A     | [This.I-D] | Delegation to DNS
 65541  | BOX     | N/A     | [This.I-D] | Boxed record
            ]]></artwork>
        </figure>
        <t>
          GANA is requested to amend the "GNUnet Signature Purpose" registry
          as follows:
        </t>
        <figure anchor="figure_purposenums">
          <artwork name="" type="" align="left" alt=""><![CDATA[
 Purpose | Name            | References | Description
 --------+-----------------+------------+--------------------------
   3     | GNS_REVOCATION  | [This.I-D] | GNS zone key revocation
  15     | GNS_RECORD_SIGN | [This.I-D] | GNS record set signature
            ]]></artwork>
        </figure>
      </section>
      <!-- gana -->
      <section>
        <name>Test Vectors</name>
        <t>
          The following represents a test vector for a record set with a DNS
          record of type "A" as well as a GNS record of type "PKEY"
          under the label "test".
        </t>
        <artwork name="" type="" align="left" alt="">
          <![CDATA[
 Zone private key (d, little-endian scalar):
 3015471ecb45455b5e9df50ff416b3d53aa6db6cafec858449f788142d091d41
 
 Zone public key (zk):
 bf06e687a291a509b6326bb6394dd6ed3ff9e5eb78ea5752ed0eba0807023a33
 
 Label: test
 RRCOUNT: 2
 
 Record #0
 EXPIRATION: 1590482415557079
 DATA_SIZE: 4
 TYPE: 1
 FLAGS: 0
 DATA:
 01020304
 
 Record #1
 EXPIRATION: 1590482415557079
 DATA_SIZE: 32
 TYPE: 65536
 FLAGS: 2
 DATA:
 814fbb06b17f4ecf
 d098700619179f9d
 4aef24465bd6958a
 e4ed01cd024b1856
 
 RDATA:
 0005a6890b6699d7
 0000000400000001
 0000000001020304
 0005a6890b6699d7
 0000002000010000
 00000002814fbb06
 b17f4ecfd0987006
 19179f9d4aef2446
 5bd6958ae4ed01cd
 024b185600000000
 0000000000000000
 0000000000000000
 0000000000000000
 0000000000000000
 0000000000000000
 0000000000000000
 
 BDATA:
 9f471611a5c06fc2
 c9ad33f642dd315c
 f8fc675aed23e8a1
 d19a5bad657557fe
 6e1d50709860593e
 5376c30f6f22daac
 5293986b7444476d
 b8f289f5537da168
 dc81cba256d8401b
 642dbe6a24346e11
 9148ade8acb4d5e5
 cef5eb5ad1e3b95d
 d143123d387b8df0
 ba4e2d75a9eb94a4
 f3250b975fee90e9
 558bb9e1e009ca46
 b7a066dd
 
 RRBLOCK:
 08180a871b910ade
 a1125a1030d0f269
 069e5731c90ad0d0
 cfa10bf61b3f0c79
 0833b515d4c746e6
 4a7261947bfb6429
 21200bb97a96292d
 6abefab1197f7e4e
 b399c628a71d3627
 d64a2bd66080f64d
 91c0120ab14601d8
 18de23c8da82b80b
 000000940000000f
 0005a6890b6699d7
 9f471611a5c06fc2
 c9ad33f642dd315c
 f8fc675aed23e8a1
 d19a5bad657557fe
 6e1d50709860593e
 5376c30f6f22daac
 5293986b7444476d
 b8f289f5537da168
 dc81cba256d8401b
 642dbe6a24346e11
 9148ade8acb4d5e5
 cef5eb5ad1e3b95d
 d143123d387b8df0
 ba4e2d75a9eb94a4
 f3250b975fee90e9
 558bb9e1e009ca46
 b7a066dd
            ]]>
        </artwork>
        <t>
          The following is an example revocation for a zone:
        </t>
        <artwork name="" type="" align="left" alt="">
          <![CDATA[
 Zone private key (d, little-endian scalar):
 90ea2a95cb9ef482b45817dc45b805cae00f387022a065a3674f41ad15173c63
 
 Zone public key (zk):
 4ac1e51d9a585a9ad9fb0dfac2be100aee83f0cc79c4c5ea8f3eb8afd9092fa5
 
 Difficulty (5 base difficulty + 2 epochs): 7
 
 Proof:
 0005a5fd368978f4
 0000395d1827c000
 e23f657bc47ec853
 e23f657bc47ec9d8
 e23f657bc47ecaec
 e23f657bc47ecb29
 e23f657bc47ecc00
 e23f657bc47ecc79
 e23f657bc47ece83
 e23f657bc47ecfc6
 e23f657bc47ecfc8
 e23f657bc47ecfd5
 e23f657bc47ed02b
 e23f657bc47ed03b
 e23f657bc47ed0ff
 e23f657bc47ed241
 e23f657bc47ed264
 e23f657bc47ed2e5
 e23f657bc47ed343
 e23f657bc47ed348
 e23f657bc47ed45e
 e23f657bc47ed480
 e23f657bc47ed49a
 e23f657bc47ed564
 e23f657bc47ed565
 e23f657bc47ed5b6
 e23f657bc47ed5de
 e23f657bc47ed5e0
 e23f657bc47ed77f
 e23f657bc47ed800
 e23f657bc47ed80c
 e23f657bc47ed817
 e23f657bc47ed82c
 e23f657bc47ed8a6
 0396020c831a5405
 cee6c38842209191
 c8db799dbe81e0dc
 f6dbd4f91c257ae2
 0079e7fd1cd31cc2
 4cd9a52831d5ec30
 f10e22e5a6dd9065
 18746cfce2095610
 4ac1e51d9a585a9a
 d9fb0dfac2be100a
 ee83f0cc79c4c5ea
 8f3eb8afd9092fa5
          ]]>
        </artwork>
      </section>
    </middle>
    <back>
      <references>
        <name>Normative References</name>
 
        &RFC1034;
        &RFC1035;
        &RFC2782;
        &RFC2119;
        &RFC3629;
        &RFC3826;
        &RFC3912;
        &RFC5869;
        &RFC5890;
        &RFC5891;
        &RFC6781;
        &RFC6895;
        &RFC6979;
        &RFC7748;
        &RFC8032;
        &RFC8126;
 
        <reference anchor="TWOFISH">
          <front>
            <title>
              The Twofish Encryptions Algorithm: A 128-Bit Block Cipher, 1st Edition
            </title>
            <author initials="B." surname="Schneier" fullname="B. Schneier">
              <organization/>
            </author>
            <date year="1999" month="March"/>
          </front>
        </reference>
        <reference anchor="GNS" target="https://doi.org/10.1007/978-3-319-12280-9_9">
          <front>
            <title>A Censorship-Resistant, Privacy-Enhancing and Fully Decentralized Name System</title>
           <author initials="M." surname="Wachs" fullname="Matthias Wachs">
             <organization>Technische Universität München</organization>
           </author>
 
           <author initials="M." surname="Schanzenbach" fullname="Martin Schanzenbach">
             <organization>Technische Universität München</organization>
           </author>
 
           <author initials="C." surname="Grothoff"
             fullname="Christian Grothoff">
           <organization>Technische Universität München</organization>
           </author>
            <date year="2014"/>
          </front>
        </reference>
       <reference anchor="R5N" target="https://doi.org/10.1109/ICNSS.2011.6060022">
          <front>
            <title>R5N: Randomized recursive routing for restricted-route networks</title>
           <author initials="N. S." surname="Evans" fullname="Nathan S. Evans">
             <organization>Technische Universität München</organization>
           </author>
 
           <author initials="C." surname="Grothoff"
             fullname="Christian Grothoff">
           <organization>Technische Universität München</organization>
           </author>
            <date year="2011"/>
          </front>
        </reference>
 
 
        <reference anchor="Argon2" target="https://datatracker.ietf.org/doc/draft-irtf-cfrg-argon2/">
          <front>
            <title>The memory-hard Argon2 password hash and proof-of-work function</title>
           <author initials="A." surname="Biryukov" fullname="Alex Biryukov">
             <organization>University of Luxembourg</organization>
           </author>
 
           <author initials="D." surname="Dinu" fullname="Daniel Dinu">
             <organization>University of Luxembourg</organization>
           </author>
 
           <author initials="D." surname="Khovratovich"
             fullname="Dmitry Khovratovich">
             <organization>ABDK Consulting</organization>
           </author>
           <author initials="S." surname="Josefsson"
             fullname="Simon Josefsson">
             <organization>SJD AB</organization>
           </author>
            <date year="2020" month="March"/>
            <abstract>
              <t>
                This document describes the Argon2 memory-hard function for
       password hashing and proof-of-work applications.  We provide an
       implementer-oriented description with
       test vectors.  The purpose is to simplify adoption of Argon2 for
       Internet protocols.  This document is a product of the Crypto Forum Research Group (CFRG)
        in the IRTF.
              </t>
            </abstract>
          </front>
        </reference>
        <!--    <reference anchor="ISO20022">
          <front>
          <title>ISO 20022 Financial Services - Universal financial industry message scheme</title>
          <author>
          <organization>International Organization for Standardization</organization>
          <address>
          <uri>http://www.iso.ch</uri>
          </address>
          </author>
          <date month="May" year="2013"/>
          </front>
        </reference>-->
      </references>
      <!-- Change Log
        v00 2017-07-23  MS   Initial version
      -->
    </back>
  </rfc>