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." 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="Grothhoff">
   <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="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>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,zk),
    where P is the generator of an elliptic curve, x is the private key and
    zk := x*P the corresponding public key.
    The keys are constructed using the Ed25519 ECC scheme as defined in
    <xref target="RFC8032" />.
    The public key "zk" is used to uniquely identify and refer to the zone and
    is thus called "zone key".
    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>
    <section anchor="rrecords_wire" numbered="true" toc="default">
      <name>Wire format</name>
   <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 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 size of the DATA field in bytes and in 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="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 and link to the DNS
     record type registry.
   </dd>
   <dt>FLAGS</dt>
   <dd>
     Resource record 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>
 <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 should never be encountered by a resolver
     for records resolved from the DHT.
   </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 for records resolved from the DHT.
   </dd>
 </dl>
</section>
<section anchor="gnsrecords_pkey" numbered="true" toc="default">
  <name>PKEY</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 anchor="gnsrecords_gns2dns" numbered="true" toc="default">
  <name>GNS2DNS</name>
  <t>The 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
      +-----+-----+-----+-----+-----+-----+-----+-----+
      |                   PUBLIC KEY                  |
      |                                               |
      |                                               |
      |                                               |
      +-----+-----+-----+-----+-----+-----+-----+-----+
      ]]></artwork>
    <!--        <postamble>which is a very simple example.</postamble>-->
  </figure>
</section>

<section anchor="gnsrecords_leho" numbered="true" toc="default">
  <name>LEHO</name>
  <t>The 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>
</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 zone key "zk" and the respective label of the contained records.
      Given a label, the DHT key "q" is derived as follows:
    </t>
    <section anchor="blinding" numbered="true" toc="default">
      <name>Key derivations</name>
      <artwork name="" type="" align="left" alt=""><![CDATA[
        PRK_h := HKDF-Extract ("key-derivation", zk)
        h := HKDF-Expand (PRK_h, label | "gns", 512 / 8)
        x_h := h*x mod p
        zk_h := h*zk mod p
        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 "x*P" as initial keying
          material.
        </dd>
        <dt>h</dt>
        <dd>
          is the HKDF expansion result. The expansion info is a concatenation of
          the label and string "gns".
        </dd>
        <dt>x</dt>
        <dd>
          is the private zone key as defined in <xref target="RFC8032" />.
        </dd>
        <dt>P</dt>
        <dd>
          is the base point of the curve Ed25519 as defined in
          <xref target="RFC8032" />.
        </dd>
        <dt>label</dt>
        <dd>
          under wich the resource records are published.
        </dd>
        <dt>x_h</dt>
        <dd>
          is a private key derived from the zone private key "x" using the
          keying material "h" (512 bit) and "p" is the group order as defined in
          <xref target="RFC8032" />.
        </dd>
        <dt>zk_h</dt>
        <dd>
          is a public key derived from the zone key "zk" using the keying
          material "h" (512 bit) and "p" is the group order as defined in
          <xref target="RFC8032" />.
        </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 "zk_h" corresponding to the
          derived private key "x_h".
        </dd>
      </dl>
    </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 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 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 "x_h" (see
          <xref target="publish" />).
        </dd>
        <dt>PUBLIC KEY</dt>
        <dd>
          The 256-bit ECC 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>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>
      <t>
        As per  <xref target="RFC8032" />, an ECDSA signature consists of a pair
        of integers, r and s:
      </t>
      <artwork name="" type="" align="left" alt=""><![CDATA[
        0     8     16    24    32    40    48    56
        +-----+-----+-----+-----+-----+-----+-----+-----+
        |                       r                       |
        |                                               |
        |                                               |
        |                                               |
        +-----+-----+-----+-----+-----+-----+-----+-----+
        |                       s                       |
        |                                               |
        |                                               |
        |                                               |
        +-----+-----+-----+-----+-----+-----+-----+-----+
        ]]></artwork>
    </section>
    <section numbered="true" toc="default">
      <name>Block data encryption and decryption</name>
      <t>
        A symmetric encryption scheme is used to en-/decrypt the "BDATA" field
        in a GNS record block. The keys are derived from the record label
        and the zone key "zk".
        The validity of "d" can be checked by computing "h" from "x_h" and
        label and verifying that "zk_h = h*zk". This step is mandatory to
        prevent spoofed records to be verified and decrypted correctly.
        The keying material "K" and initialization vector "IV" for the
        symmetric encryption/decryption are derived as follows:
      </t>
      <artwork name="" type="" align="left" alt=""><![CDATA[
        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>
      <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 in network byte order.
        </dd>
      </dl>
      <t>
        is followed by a set of resource records with the respective
        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="RFC8032" target="https://www.rfc-editor.org/info/rfc8032">
      <front>
        <title>Edwards-Curve Digital Signature Algorithm (EdDSA)</title>
        <author initials="S." surname="Josefsson" fullname="S. Josefsson">
          <organization/>
        </author>
        <author initials="I." surname="Liusvaara" fullname="I. Liusvaara">
          <organization/>
        </author>
        <date year="2017" month="January"/>
        <abstract>
          <t>
            This document describes elliptic curve signature scheme Edwards-curve Digital Signature Algorithm (EdDSA). The algorithm is instantiated with recommended parameters for the edwards25519 and edwards448 curves. An example implementation and test vectors are provided.
          </t>
        </abstract>
      </front>
      <seriesInfo name="RFC" value="8032"/>
      <seriesInfo name="DOI" value="10.17487/RFC8032"/>
    </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="RFC6979" target="https://www.rfc-editor.org/info/rfc6979">
      <front>
        <title>
          Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA)
        </title>
        <author initials="T." surname="Pornin" fullname="T. Pornin">
          <organization/>
        </author>
        <date year="2013" month="August"/>
        <abstract>
          <t>
            This document defines a deterministic digital signature generation procedure. Such signatures are compatible with standard Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA) digital signatures and can be processed with unmodified verifiers, which need not be aware of the procedure described therein. Deterministic signatures retain the cryptographic security features associated with digital signatures but can be more easily implemented in various environments, since they do not need access to a source of high-quality randomness.
          </t>
        </abstract>
      </front>
      <seriesInfo name="RFC" value="6979"/>
      <seriesInfo name="DOI" value="10.17487/RFC6979"/>
    </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>