path: root/draft-schanzen-gns.txt

Independent Stream                                       M. Schanzenbach
Internet-Draft                                              C. Grothhoff
Intended status: Informational                                    B. Fix
Expires: 24 January 2020                                     GNUnet e.V.
                                                            23 July 2019


                   The GNU Name System Specification
                         draft-schanzen-gns-00

Abstract

   This document contains the GNU Name System (GNS) technical
   specification.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on 24 January 2020.

Copyright Notice

   Copyright (c) 2019 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents (https://trustee.ietf.org/
   license-info) in effect on the date of publication of this document.
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.  Code Components
   extracted from this document must include Simplified BSD License text
   as described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Simplified BSD License.






Schanzenbach, et al.     Expires 24 January 2020                [Page 1]

Internet-Draft             The GNU Name System                 July 2019


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Zones . . . . . . . . . . . . . . . . . . . . . . . . . . . .   2
   3.  Resource records  . . . . . . . . . . . . . . . . . . . . . .   2
     3.1.  Wire format . . . . . . . . . . . . . . . . . . . . . . .   3
     3.2.  PKEY  . . . . . . . . . . . . . . . . . . . . . . . . . .   4
     3.3.  GNS2DNS . . . . . . . . . . . . . . . . . . . . . . . . .   4
     3.4.  LEHO  . . . . . . . . . . . . . . . . . . . . . . . . . .   5
   4.  Publishing records  . . . . . . . . . . . . . . . . . . . . .   5
     4.1.  Key derivations . . . . . . . . . . . . . . . . . . . . .   5
     4.2.  Resource records block  . . . . . . . . . . . . . . . . .   6
     4.3.  Block data encryption and decryption  . . . . . . . . . .   8
   5.  Internationalization and Character Encoding . . . . . . . . .  10
   6.  Security Considerations . . . . . . . . . . . . . . . . . . .  10
   7.  Record Resolution . . . . . . . . . . . . . . . . . . . . . .  10
   8.  Namespace Revocation  . . . . . . . . . . . . . . . . . . . .  10
   9.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  11
   10. Test Vectors  . . . . . . . . . . . . . . . . . . . . . . . .  11
   11. Normative References  . . . . . . . . . . . . . . . . . . . .  11
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  12

1.  Introduction

   This document contains the GNU Name System (GNS) technical
   specification for secure, censorship-resistant and decentralised name
   resolution.

   This document defines the normative wire format of resource records,
   resolution processes, cryptographic routines and security
   considerations for use by implementors.


2.  Zones

   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 [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
   Section 4.

3.  Resource records






Schanzenbach, et al.     Expires 24 January 2020                [Page 2]

Internet-Draft             The GNU Name System                 July 2019


3.1.  Wire format

   A GNS resource record holds the data of a specific record in a zone.
   The resource record format is defined as follows:

        0     8     16    24    32    40    48    56
        +-----+-----+-----+-----+-----+-----+-----+-----+
        |                   EXPIRATION                  |
        +-----+-----+-----+-----+-----+-----+-----+-----+
        |       DATA SIZE       |          TYPE         |
        +-----+-----+-----+-----+-----+-----+-----+-----+
        |           FLAGS       |        DATA           /
        +-----+-----+-----+-----+                       /
        /                                               /
        /                                               /
        /                                               |
        +-----+-----+-----+-----+-----+-----+-----+-----+

                                  Figure 1

   where:

   EXPIRATION  Denotes the absolute expiration date of the record.  In
      microseconds since midnight (0 hour), January 1, 1970 in network
      byte order.

   DATA SIZE  The size of the DATA field in bytes and in network byte
      order.

   TYPE  The resource record type.  This type can be one of the GNS
      resource records as defined in Section 3 or a DNS record type as
      defined in [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.

   FLAGS  Resource record flags.

   DATA  The resource record data payload.  The contents are defined by
      the respective type of the resource record.

   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:






Schanzenbach, et al.     Expires 24 January 2020                [Page 3]

Internet-Draft             The GNU Name System                 July 2019


        ... 5       4         3        2        1        0
        ------+--------+--------+--------+--------+--------+
        / ... | SHADOW | EXPREL |   /    | PRIVATE|    /   |
        ------+--------+--------+--------+--------+--------+

                                  Figure 2

   where:

   SHADOW  If this flag is set, this record should not be used unless
      all (other) records with an absolute expiration time have expired.

   EXPREL  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.

   PRIVATE  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.

3.2.  PKEY

   In GNS, a delegation of a label to a zone is represented througha
   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 labels are allows.  The a PKEY DATA entry has the
   following format:

         0     8     16    24    32    40    48    56
         +-----+-----+-----+-----+-----+-----+-----+-----+
         |                   PUBLIC KEY                  |
         |                                               |
         |                                               |
         |                                               |
         +-----+-----+-----+-----+-----+-----+-----+-----+

                                  Figure 3

3.3.  GNS2DNS

   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 [RFC1034] for DNS names.  If a resolver encounters
   a GNS2DNS record it is expected that it first resolves the IP(s) of
   the DNS servers using DNS.  Then, the encountered DNS name is
   resolved by querying the name server(s).  The a GNS2DNS DATA entry
   has the following format:



Schanzenbach, et al.     Expires 24 January 2020                [Page 4]

Internet-Draft             The GNU Name System                 July 2019


         0     8     16    24    32    40    48    56
         +-----+-----+-----+-----+-----+-----+-----+-----+
         |                    DNS NAME                   |
         /                                               /
         /                                               /
         |                                               |
         +-----+-----+-----+-----+-----+-----+-----+-----+
         |                 DNS SERVER NAME               |
         /                                               /
         /                                               /
         |                                               |
         +-----------------------------------------------+

                                  Figure 4

3.4.  LEHO

   As names in GNS are not globally unique, established practices such
   as virtual hosting do not apply directly.  In order to support such
   use cases, GNS support a legacy hostname record which can be used by
   applications (e.g.  HTTP clients) in order to provide the necessary
   information.  The resource record contains a string which is not
   0-terminated representing the legacy hostname to use.  It 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:

         0     8     16    24    32    40    48    56
         +-----+-----+-----+-----+-----+-----+-----+-----+
         |                 LEGACY HOSTNAME               |
         /                                               /
         /                                               /
         |                                               |
         +-----+-----+-----+-----+-----+-----+-----+-----+

                                  Figure 5

4.  Publishing records

   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:

4.1.  Key derivations





Schanzenbach, et al.     Expires 24 January 2020                [Page 5]

Internet-Draft             The GNU Name System                 July 2019


           PRK_h := HKDF-Extract ("key-derivation", zk)
           h := HKDF-Expand (PRK_h, label, 512 / 8)
           x_h := h*x mod p
           zk_h := h*zk mod p
           q := SHA512 (zk_h)

   We use a hash-based key derivation function (HKDF) as defined in
   [RFC5869].  We use HMAC-SHA512 for the extraction phase and HMAC-
   SHA256 for the expansion phase.

   PRK_h  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.

   h  is the HKDF expansion result.  The expansion info is a
      concatenation of the label and string "gns".

   x  is the private zone key as defined in [RFC8032].

   P  is the base point of the curve Ed25519 as defined in [RFC8032].

   label  under wich the resource records are published.

   x_h  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 [RFC8032].

   zk_h  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
      [RFC8032].

   q  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".

4.2.  Resource records block

   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:










Schanzenbach, et al.     Expires 24 January 2020                [Page 6]

Internet-Draft             The GNU Name System                 July 2019


             0     8     16    24    32    40    48    56
             +-----+-----+-----+-----+-----+-----+-----+-----+
             |                   SIGNATURE                   |
             |                                               |
             |                                               |
             |                                               |
             |                                               |
             |                                               |
             |                                               |
             |                                               |
             +-----+-----+-----+-----+-----+-----+-----+-----+
             |                  PUBLIC KEY                   |
             |                                               |
             |                                               |
             |                                               |
             +-----+-----+-----+-----+-----+-----+-----+-----+
             |       BDATA SIZE      |       PURPOSE         |
             +-----+-----+-----+-----+-----+-----+-----+-----+
             |                   EXPIRATION                  |
             +-----+-----+-----+-----+-----+-----+-----+-----+
             |                    BDATA                      /
             /                                               /
             /                                               |
             +-----+-----+-----+-----+-----+-----+-----+-----+

                                  Figure 6

   where:

   SIGNATURE  A 512-bit ECDSA deterministic signature compliant with
      [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 Section 4).

   PUBLIC KEY  The 256-bit ECC public key "zk_h" to be used to verify
      SIGNATURE.  The wire format of this value is defined in [RFC8032],
      Section 5.1.5.

   BDATA SIZE  A 32-bit value containing the length of the following
      data (PURPOSE, EXPIRATION, BDATA) in network byte order.

   PURPOSE  A 32-bit signature purpose flag.  This field MUST be 15 (in
      network byte order).

   EXPIRATION  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




Schanzenbach, et al.     Expires 24 January 2020                [Page 7]

Internet-Draft             The GNU Name System                 July 2019


      in microseconds since midnight (0 hour), January 1, 1970 in
      network byte order.

   BDATA  The encrypted resource records with a total size of "BDATA
      SIZE".

   As per [RFC8032], an ECDSA signature consists of a pair of integers,
   r and s:

           0     8     16    24    32    40    48    56
           +-----+-----+-----+-----+-----+-----+-----+-----+
           |                       r                       |
           |                                               |
           |                                               |
           |                                               |
           +-----+-----+-----+-----+-----+-----+-----+-----+
           |                       s                       |
           |                                               |
           |                                               |
           |                                               |
           +-----+-----+-----+-----+-----+-----+-----+-----+

4.3.  Block data encryption and decryption

   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:

           PRK_k := HKDF-Extract ("gns-aes-ctx-key", zk)
           PRK_iv := HKDF-Extract ("gns-aes-ctx-iv", zk)
           K := HKDF-Expand (PRK_k, l, 512 / 8);
           IV := HKDF-Expand (PRK_iv, l, 256 / 8)

   We use a hash-based key derivation function (HKDF) as defined in
   [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":







Schanzenbach, et al.     Expires 24 January 2020                [Page 8]

Internet-Draft             The GNU Name System                 July 2019


             0     8     16    24    32    40    48    56
             +-----+-----+-----+-----+-----+-----+-----+-----+
             |                    AES KEY (Kaes)             |
             |                                               |
             |                                               |
             |                                               |
             +-----+-----+-----+-----+-----+-----+-----+-----+
             |                  TWOFISH KEY (Ktwo)           |
             |                                               |
             |                                               |
             |                                               |
             +-----+-----+-----+-----+-----+-----+-----+-----+

                                  Figure 7

   Similarly, we divide "IV" into a 128-bit initialization vector IVaes
   and a 128-bit initialization vector IVtwo:

             0     8     16    24    32    40    48    56
             +-----+-----+-----+-----+-----+-----+-----+-----+
             |                    AES IV (IVaes)             |
             |                                               |
             +-----+-----+-----+-----+-----+-----+-----+-----+
             |                  TWOFISH IV (IVtwo)           |
             |                                               |
             +-----+-----+-----+-----+-----+-----+-----+-----+

                                  Figure 8

   The symmetric keys and IVs are used for a AES+TWOFISH combined
   cipher.  Both ciphers are used in Cipher FeedBack (CFB) mode.

           RDATA := AES(Kaes, IVaes, TWOFISH(Ktwo, IVtwo, BDATA))
           BDATA := TWOFISH(Ktwo, IVtwo, AES(Kaes, IVaes, RDATA))

   The decrypted RDATA has the following format:















Schanzenbach, et al.     Expires 24 January 2020                [Page 9]

Internet-Draft             The GNU Name System                 July 2019


             0     8     16    24    32    40    48    56
             +-----+-----+-----+-----+-----+-----+-----+-----+
             |     RR COUNT          |        EXPIRA-        /
             +-----+-----+-----+-----+-----+-----+-----+-----+
             /         -TION         |       DATA SIZE       |
             +-----+-----+-----+-----+-----+-----+-----+-----+
             |         TYPE          |          FLAGS        |
             +-----+-----+-----+-----+-----+-----+-----+-----+
             |                      DATA                     /
             /                                               /
             /                                               |
             +-----+-----+-----+-----+-----+-----+-----+-----+
             |                   EXPIRATION                  |
             +-----+-----+-----+-----+-----+-----+-----+-----+
             |       DATA SIZE       |          TYPE         |
             +-----+-----+-----+-----+-----+-----+-----+-----+
             |           FLAGS       |        DATA           /
             +-----+-----+-----+-----+                       /
             /                                               /
             /                                               /
             /                                               /

                                  Figure 9

   where:

   RR COUNT  A 32-bit value containing the number of resource records
      which are following in network byte order.

   is followed by a set of resource records with the respective formats
   defined in Section 3.

5.  Internationalization and Character Encoding

   TODO

6.  Security Considerations

   TODO

7.  Record Resolution

   TODO

8.  Namespace Revocation

   TODO




Schanzenbach, et al.     Expires 24 January 2020               [Page 10]

Internet-Draft             The GNU Name System                 July 2019


9.  IANA Considerations

   This will be fun

10.  Test Vectors


   SEED=0f388abc49f99b8675555ad33c3b586a9e06f0f60f6caadeee6fd12226ac2474
   LABEL="home"
   D(private_scalar)=7450f71def6411e0ab0e6a1dfd1d9ccd0eaf71952494ccf51b85ffac5db093c8
   PK(public_key)=23d89a29da0f6808c6b6d5e59cdd6a6fcf3e2bb006f466d5423a935d6b4d7e10
   SK(private_key)=SEED||PK
   H(derived_factor)=071efca7db2850bd6f354ebfe38c5bbfd6ba2f805cd8d3b54edd7f3dd0730d1a
   H*PK(derived_pk)=9f27ad25b5954a467bc65a676b7a6d23b2ef300f7fc70058059e7f29e594b5c1
   QUERY=d18e5efff7646f9c87db4ff5e98df8f53d57b7a813271a488fd84e9e4ecae92636ab831bd17cd7e6c879d04e8a91b55570a94a6fef9ecf3c70207f69a4a8387a
   AES_KEY=033e97f17570004effe7e1b75b167668a3e0c320b7660eef0718d0aaa779164
   AES_IV=b052ae34fac578e9c7e400e712359621
   2FISH_KEY=db5211605614363a4c2e23d96c9b1d3188a1b7cb85802db10ac7cc3f763c1670
   AES_IV=bc63e4b6f47a7254e4f4ff06d263f9d5
   DATA_PLAIN=000000010005af87005b9140000000170000000f00000000000a046d61696c0a686f692d706f6c6c6f69036f726700000000000000000000000000000000000000000000000000
   DATA_ENCRYPED=5fb6552e3959ff9fd80c1b0213dc7ef1f6edb016df693226f0d46dc04a34265bf6eaf8e945a7685dc94913835e03d695d1e307d6e4ce210bf0983af61346c69e69b2c636300fbf
   SIGNED_DATA=000000570000000f0005af87005b9140||DATA_ENCRYPTED
   SIGNATURE=0f560541fb3900c3459efcba85e006a99122725baa1fb50b6ec6210eb815caba0663c95eb9ca1863b13c9320e8637a1168abebc4b916f4fff5bf62aa8d2d56b8

11.  Normative References

   [RFC1034]  Mockapetris, P., "Domain names - concepts and facilities",
              STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987,
              <https://www.rfc-editor.org/info/rfc1034>.

   [RFC1035]  Mockapetris, P., "Domain names - implementation and
              specification", STD 13, RFC 1035, DOI 10.17487/RFC1035,
              November 1987, <https://www.rfc-editor.org/info/rfc1035>.

   [RFC5869]  Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand
              Key Derivation Function (HKDF)", RFC 5869,
              DOI 10.17487/RFC5869, May 2010,
              <https://www.rfc-editor.org/info/rfc5869>.

   [RFC6979]  Pornin, T., "Deterministic Usage of the Digital Signature
              Algorithm (DSA) and Elliptic Curve Digital Signature
              Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979, August
              2013, <https://www.rfc-editor.org/info/rfc6979>.

   [RFC8032]  Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital
              Signature Algorithm (EdDSA)", RFC 8032,
              DOI 10.17487/RFC8032, January 2017,
              <https://www.rfc-editor.org/info/rfc8032>.



Schanzenbach, et al.     Expires 24 January 2020               [Page 11]

Internet-Draft             The GNU Name System                 July 2019


Authors' Addresses

   Martin Schanzenbach
   GNUnet e.V.
   Boltzmannstrasse 3
   85748 Garching
   Germany

   Email: schanzen@gnunet.org


   Christian Grothoff
   GNUnet e.V.
   Boltzmannstrasse 3
   85748 Garching
   Germany

   Email: schanzen@gnunet.org


   Bernd Fix
   GNUnet e.V.
   Boltzmannstrasse 3
   85748 Garching
   Germany

   Email: schanzen@gnunet.org
























Schanzenbach, et al.     Expires 24 January 2020               [Page 12]