path: root/draft-schanzen-gns.xml

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE rfc SYSTEM "rfc2629-xhtml.ent" [
<!ENTITY RFC3986 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
<!ENTITY RFC3629 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3629.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-00" 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 Specification
    </title>
    <seriesInfo name="Internet-Draft" value="draft-schanzen-gns-00"/>
    <author fullname="Martin Schanzenbach" initials="M.S." 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>
    <date day="23" month="July" year="2019"/>
    <!-- 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>
        This document contains the GNU Name System (GNS) technical specification
        for secure, censorship-resistant and decentralised name resolution.
      </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>

      </t>
    </section>
    <section anchor="zones" numbered="true" toc="default">
      <name>Zones</name>
      <t>
        A zone in GNS is defined by a public/private ECC key pair (x,x*P),
        where P is the generator of an elliptic curve, x is the private key and
        x*P the corresponding public key.
        The keys are constructed using the Curve25519 ECC scheme as defined in
        <xref target="RFC7748" />.
        The public key "x*P" is used to uniquely identify and refer to the zone.
        Records published in the zone are signed using a private key derived
        from the private key "x" as described in <xref target="publish" />.
      </t>
    </section>
    <section anchor="rrecords" numbered="true" toc="default">
      <name>Resource records</name>
      <t>
        A GNS resource record holds the data of a specific record in a zone.
        The resource record wire 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 expiration date of the record.
          In microseconds since midnight (0 hour), January 1, 1970 in network
          byte order.
        </dd>
        <dt>DATA SIZE</dt>
        <dd>
          The resource record data length in bytes and network byte order.
        </dd>
        <dt>TYPE</dt>
        <dd>
          The resource record type. This type can be one of the GNS resource
          records as defined in <xref target="gnsrecords" /> or a DNS record
          type as defined in <xref target="RFC1035" /> or any of the
          complementary standardized DNS resource record types.
        </dd>
        <dt>FLAGS</dt>
        <dd>
          Resource record flags. Flags are defined in <xref target="flags" />.
        </dd>
        <dt>DATA</dt>
        <dd>
          The resource record data payload. The contents are defined by the
          respective type of the resource record.
        </dd>
      </dl>
      <section anchor="flags" numbered="true" toc="default">
        <name>Flags</name>
        <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 |   /    | 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 not be used unless all (other)
            records with an absolute expiration time have expired.
          </dd>
          <dt>EXPREL</dt>
          <dd>
            The expiration time value of the record is a relative time and not
            an absolute time. This flag can be ignored by a resolver.
          </dd>
          <dt>PRIVATE</dt>
          <dd>
            This is a private record of this peer and it should thus not be
            handed out to other peers. This flag should never be encountered by
            a resolver.
          </dd>
        </dl>
      </section>
      <section anchor="gnsrecords" numbered="true" toc="default">
        <name>GNS resource record types</name>

        <t>The 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>
      </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).
        Resource records are grouped by their respective labels and published
        together in a single block in the DHT.
        A resource records block is published under a key which is derived from
        the respective label of the contained records.
        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", x*P)
        h := HKDF-Expand (PRK_h, label | "gns", 512 / 8)
        d := h*x mod p
        q := SHA512 (d*P)
        ]]></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>h</dt>
        <dd>
          is key material retrieved using an HKDF using the string
          "key-derivation" as salt and the public key "x*P" as initial keying
          material. The label and string "gns" are concatenated and used in the
          HKDF expansion phase.
        </dd>
        <dt>d</dt>
        <dd>
          is a private key derived from the zone key "x" using the keying
          material "h" (512 bit) and "p" is a prime as defined in
          <xref target="RFC7748" />.
        </dd>
        <dt>q</dt>
        <dd>
          Is the DHT key under which the resource records block is published.
          It is the SHA512 hash over the public key "d*P" corresponding to the
          derived private key "d".
        </dd>
      </dl>
      <section anchor="wire" numbered="true" toc="default">
        <name>Resource records block</name>
        <t>
          GNS records are grouped by their labels are published as a single
          block in the DHT.
          The contained resource records are encrypted using a symmetric
          encryption scheme.
          A GNS resource records block 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                   |
            |                                               |
            |                                               |
            |                                               |
            +-----+-----+-----+-----+-----+-----+-----+-----+
            |       BDATA SIZE      |       PURPOSE         |
            +-----+-----+-----+-----+-----+-----+-----+-----+
            |                   EXPIRATION                  |
            +-----+-----+-----+-----+-----+-----+-----+-----+
            |                    BDATA                      /
            /                                               /
            /                                               |
            +-----+-----+-----+-----+-----+-----+-----+-----+
            ]]></artwork>
        </figure>
        <t>where:</t>
        <dl>
          <dt>SIGNATURE</dt>
          <dd>
            A 512-bit ECDSA signature. This field contains a 512-bit ECDSA
            signature over the data following the PUBLIC KEY field.
            The signature is create using the derived private key "d".
          </dd>
          <dt>PUBLIC KEY</dt>
          <dd>
            The 256-bit ECC public key "d*P" to be used to verify SIGNATURE.
          </dd>
          <dt>BDATA SIZE</dt>
          <dd>
            A 32-bit value containing the length of the following data (PURPOSE,
            EXPIRATION, BDATA) in network byte order.
          </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>
            The resource records block expiration time. This is the expiration
            time of the resource record contained within this block with the
            smallest expiration time.
            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 "BDATA SIZE".
          </dd>
        </dl>
      </section>
      <section numbered="true" toc="default">
        <name>Block data encryption</name>
        <t>
          Given a GNS record block a symmetric encryption scheme is used to
          en-/decrypt "BDATA". The keys are derived from the record label
          and a public key "d*P", where "d" is an ECDSA private key and "P"
          is the EC generator. "d" is derived from the private key "x" of a GNS
          zone.
          Both label and public key and "x*P" are implicity known by a GNS
          resolver while "d*P" is provided within the resource records block.
          The keying material "K" and initialization vector "IV"
          are derived as follows:
        </t>
        <artwork name="" type="" align="left" alt=""><![CDATA[
          PRK_h := HKDF-Extract ("key-derivation", x*P)
          h := HKDF-Expand (PRK_h, l | "gns", 512 / 8)
          d := h*x mod p
          PRK_kiv := HKDF-Extract (d*P, l)
          K := HKDF-Expand (PRK_kiv, "gns-aes-ctx-key", 512 / 8);
          IV := HKDF-Expand (PRK_kiv, "gns-aes-ctx-iv", 256 / 8)
          ]]></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.
          The output keying material is 64 octets (512 bit) for the symmetric
          keys and 32 octets (256 bit) for the initialization vector.
          We divide the resulting keying material "K" into a 256-bit AES key
          "Kaes" and a 256-bit TWOFISH key "Ktwo":
        </t>
        <figure anchor="figure_hkdf_keys">
          <artwork name="" type="" align="left" alt=""><![CDATA[
            0     8     16    24    32    40    48    56
            +-----+-----+-----+-----+-----+-----+-----+-----+
            |                    AES KEY (Kaes)             |
            |                                               |
            |                                               |
            |                                               |
            +-----+-----+-----+-----+-----+-----+-----+-----+
            |                  TWOFISH KEY (Ktwo)           |
            |                                               |
            |                                               |
            |                                               |
            +-----+-----+-----+-----+-----+-----+-----+-----+
            ]]></artwork>
          <!--        <postamble>which is a very simple example.</postamble>-->
        </figure>
        <t>
          Similarly, we divide "IV" into a 128-bit initialization vector IVaes
          and a 128-bit initialization vector IVtwo:
        </t>
        <figure anchor="figure_hkdf_ivs">
          <artwork name="" type="" align="left" alt=""><![CDATA[
            0     8     16    24    32    40    48    56
            +-----+-----+-----+-----+-----+-----+-----+-----+
            |                    AES IV (IVaes)             |
            |                                               |
            +-----+-----+-----+-----+-----+-----+-----+-----+
            |                  TWOFISH IV (IVtwo)           |
            |                                               |
            +-----+-----+-----+-----+-----+-----+-----+-----+
            ]]></artwork>
          <!--        <postamble>which is a very simple example.</postamble>-->
        </figure>

        <t>
          The symmetric keys and IVs are used for a AES+TWOFISH combined
          cipher. Both ciphers are used in Cipher FeedBack (CFB) mode.
        </t>
        <artwork name="" type="" align="left" alt=""><![CDATA[
          RDATA := AES(Kaes, IVaes, TWOFISH(Ktwo, IVtwo, BDATA))
          BDATA := TWOFISH(Ktwo, IVtwo, AES(Kaes, IVaes, RDATA))
          ]]></artwork>
        <t>
          The decrypted RDATA has the following format:
        </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           /
            +-----+-----+-----+-----+                       /
            /                                               /
            /                                               /
            /                                               /
            ]]></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 resource records which are
            following.
          </dd>
        </dl>
        <t>
          is followed by a set of resource records with the respective wire
          formats defined in <xref target="rrecords" />.
        </t>
      </section>
    </section>
    <section anchor="encoding" numbered="true" toc="default">
      <name>Internationalization and Character Encoding</name>
      <t>
        TODO
      </t>
    </section>
    <section anchor="security" numbered="true" toc="default">
      <name>Security Considerations</name>
      <t>
        TODO
      </t>
    </section>
    <section anchor="resolution" numbered="true" toc="default">
      <name>Record Resolution</name>
      <t>
        TODO
      </t>
    </section>
    <section anchor="revocation" numbered="true" toc="default">
      <name>Namespace Revocation</name>
      <t>
        TODO
      </t>
    </section>
    <section anchor="iana" numbered="true" toc="default">
      <name>IANA Considerations</name>
      <t>
        This will be fun
      </t>
    </section>
    <!-- iana -->
  </middle>
  <back>
    <references>
      <name>Normative References</name>
      <reference anchor="RFC5869" target="https://www.rfc-editor.org/info/rfc5869">
        <front>
          <title>
            HMAC-based Extract-and-Expand Key Derivation Function (HKDF)
          </title>
          <author initials="H." surname="Krawczyk" fullname="H. Krawczyk">
            <organization/>
          </author>
          <author initials="P." surname="Eronen" fullname="P. Eronen">
            <organization/>
          </author>
          <date year="2010" month="May"/>
          <abstract>
            <t>
              This document specifies a simple Hashed Message Authentication Code (HMAC)-based key derivation function (HKDF), which can be used as a building block in various protocols and applications. The key derivation function (KDF) is intended to support a wide range of applications and requirements, and is conservative in its use of cryptographic hash functions. This document is not an Internet Standards Track specification; it is published for informational purposes.
            </t>
          </abstract>
        </front>
        <seriesInfo name="RFC" value="5869"/>
        <seriesInfo name="DOI" value="10.17487/RFC5869"/>
      </reference>
      <reference anchor="RFC7748" target="https://www.rfc-editor.org/info/rfc7748">
        <front>
          <title>Elliptic Curves for Security</title>
          <author initials="A." surname="Langley" fullname="A. Langley">
            <organization/>
          </author>
          <author initials="M." surname="Hamburg" fullname="M. Hamburg">
            <organization/>
          </author>
          <author initials="S." surname="Turner" fullname="S. Turner">
            <organization/>
          </author>
          <date year="2016" month="January"/>
          <abstract>
            <t>
              This memo specifies two elliptic curves over prime fields that offer a high level of practical security in cryptographic applications, including Transport Layer Security (TLS). These curves are intended to operate at the ~128-bit and ~224-bit security level, respectively, and are generated deterministically based on a list of required properties.
            </t>
          </abstract>
        </front>
        <seriesInfo name="RFC" value="7748"/>
        <seriesInfo name="DOI" value="10.17487/RFC7748"/>
      </reference>
      <reference anchor="RFC1035" target="https://www.rfc-editor.org/info/rfc1035">
        <front>
          <title>Domain names - implementation and specification</title>
          <author initials="P.V." surname="Mockapetris" fullname="P.V. Mockapetris">
            <organization/>
          </author>
          <date year="1987" month="November"/>
          <abstract>
            <t>
              This RFC is the revised specification of the protocol and format used in the implementation of the Domain Name System. It obsoletes RFC-883. This memo documents the details of the domain name client - server communication.
            </t>
          </abstract>
        </front>
        <seriesInfo name="STD" value="13"/>
        <seriesInfo name="RFC" value="1035"/>
        <seriesInfo name="DOI" value="10.17487/RFC1035"/>
      </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>