The GNU Name System Specification

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.

Zones A zone in GNS is defined by a public/private ECC key pair (d,zk), where d is the private key and zk the corresponding public key. GNS uses the Ed25519 EC parameters as defined in . GNS combines the EC parameters of Ed25519 with the ECDSA scheme defined in in order to achieve zone privacy. 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 "d" as described in .

Resource records

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

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 including padding. The padding MUST ensure that the size of the resource record is a power of two. The only excption is the PKEY record type, which is never padded.
TYPE: The resource record type. This type can be one of the GNS resource records as defined in or a DNS record type as defined in 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 ().
FLAGS: Resource record flags.
DATA: The resource record data payload. The contents are defined by the respective type of the resource record.
PADDING: The padding MUST contain the 0 value in all octets. Not applicable for PKEY records.

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:

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.

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:

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 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:

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:

BOX Record type used to box up SRV and TLSA records. For example, a TLSA record for "_https._tcp.foo.gnu" will be stored under "foo.gnu" as a BOX record with service 443 (https) and protocol 6 (tcp) and record_type "TLSA". When a BOX record is received, a GNS resolver must unbox it if the name contained "_SERVICE._PROTO", otherwise it is left untouched. This is done to ensure that TLSA (and SRV) records do not require a separate network request, thus making TLSA records inseparable from the corresponding A/AAAA/VPN/etc. records. A BOX DATA entry has the following format:

PROTO: the protocol number, e.g. 6 for tcp. In network byte order.
SVC: the service of the boxed record, i.e. the port number. In network byte order.
TYPE: Record type of the boxed record. In network byte order.
RECORD: The boxed record in a format as defined in .

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:

Key derivations We use a hash-based key derivation function (HKDF) as defined in . 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".
d: is the private zone key as defined in .
P: is the base point of the curve Ed25519 as defined in .
label: under wich the resource records are published.
d_h: is a private key derived from the zone private key "d" using the keying material "h" (512 bit) and "p" is a prime as defined in .
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 .
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 "d_h".

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:

where:

SIGNATURE: A 512-bit ECDSA deterministic signature compliant with . The signature is computed over the data following the PUBLIC KEY field. The signature is created using the derived private key "d_h" (see ).
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 , Section 5.1.5.
SIZE: 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.
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. 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.
BDATA: The encrypted resource records with a total size of SIZE - 16.

We note that even though we use a Ed25519 private key, the public key is derived using ECDSA as defined in . Similarly, the ECDSA signature consists of a pair of integers, r and s:

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

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

The symmetric keys and IVs are used for a AES+TWOFISH combined cipher. Both ciphers are used in Cipher FeedBack (CFB) mode. The decrypted RDATA has the following format:

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 .

Internationalization and Character Encoding All labels in GNS are encoded in UTF-8 . This does not include any DNS names found in DNS records, such as CNAME records, which are internationalized through the IDNA specifications .

Security Considerations TODO

Record Resolution TODO

Namespace Revocation TODO

IANA Considerations This will be fun

Test Vectors The following represents a test vector for a record of type MX with a priority of 10 and the mail hostname mail.example.com.