RFC 9498: The GNU Name System

3.1. Names and Zones

It follows from the above that GNS does not support names that are simultaneously global, secure, and memorable. Instead, names are either global and not memorable or not globally unique and memorable. An example for a global name pointing to the record "example" in a zone is as follows:¶

example.000G006K2TJNMD9VTCYRX7BRVV3HAEPS15E6NHDXKPJA1KAJJEG9AFF884

Now consider the case where a user locally configured the petname "pet.gns.alt" for the zone with the "example" record of the name above. The name "example.pet.gns.alt" would then point to the same record as the globally unique name above, but name resolution would only work on the local system where the "pet.gns.alt" petname is configured.¶

The delegation of petnames and subsequent resolution of delegation build on ideas from the Simple Distributed Security Infrastructure [SDSI]. In GNS, any user can create and manage any number of zones (see Section 4) if their system provides a zone publisher implementation. For each zone, the zone type determines the respective set of cryptographic operations and the wire formats for encrypted data, public keys, and signatures. A zone can be populated with mappings from labels to resource records (see Section 5) by its owner. A label can be mapped to a delegation record; this results in the corresponding subdomain being delegated to another zone. Circular delegations are explicitly allowed, including delegating a subdomain to its immediate parent zone. In order to support (legacy) applications as well as to facilitate the use of petnames, GNS defines auxiliary record types in addition to supporting existing DNS records.¶

3.2. Publishing Binding Information

Zone contents are encrypted and signed before being published in remote key-value storage (see Section 6), as illustrated in Figure 1. In this process, unique zone identification is hidden from the network through the use of key blinding. Key blinding allows the creation of signatures for zone contents using a blinded public/private key pair. This blinding is realized using a deterministic key derivation from the original zone key and corresponding private key using record label values as inputs from which blinding factors are derived. Specifically, the zone owner can derive blinded private keys for each record set published under a label, and a resolver can derive the corresponding blinded public keys. It is expected that GNS implementations use decentralized remote storage entities, such as distributed hash tables (DHTs), in order to facilitate availability within a network without the need for dedicated infrastructure. The specification of such a distributed or decentralized storage entity is out of scope for this document, but possible existing implementations include those based on [RFC7363], [Kademlia], or [R5N].¶

       Host A           |     Remote      |      Host B
                        |     Storage     |
                        |                 |
                        |    +---------+  |
                        |   /         /|  |
               Publish  |  +---------+ |  |  Publish
 +-----------+ Records  |  |         | |  |  Records +-----------+
 |   Zone    |----------|->| Record  | |<-|----------|   Zone    |
 | Publisher |          |  | Storage | |  |          | Publisher |
 +-----------+          |  |         |/   |          +-----------+
      A                 |  +---------+    |               A
      |                 |                 |               |
   +---------+          |                 |           +---------+
  /   |     /|          |                 |          /    |    /|
 +---------+ |          |                 |         +---------+ |
 |         | |          |                 |         |         | |
 |  Local  | |          |                 |         |  Local  | |
 |  Zones  | |          |                 |         |  Zones  | |
 |         |/           |                 |         |         |/
 +---------+            |                 |         +---------+

A zone publisher implementation SHOULD be provided as part of a GNS implementation to enable users to create and manage zones. If this functionality is not implemented, names can still be resolved if zone keys for the initial step in the name resolution have been configured (see Section 7) or if the names end with a zTLD suffix.¶

3.3. Resolving Names

Applications use the resolver to look up GNS names. Starting from a configurable Start Zone, names are resolved by following zone delegations recursively, as illustrated in Figure 2. For each label in a name, the recursive GNS resolver fetches the respective record set from the storage layer (see Section 7). Without knowledge of the label values and the zone keys, the different derived keys are unlinkable to both the original zone key and each other. This prevents zone enumeration (except via expensive online brute-force attacks): to confirm the affiliation of a query or the corresponding encrypted record set with a specific zone requires knowledge of both the zone key and the label, neither of which is disclosed to remote storage by the protocol. At the same time, the blinded zone key and digital signatures associated with each encrypted record set allow resolvers and oblivious remote storage to verify the integrity of the published information without disclosing anything about the originating zone or the record sets.¶

                           Local Host           |   Remote
                                                |   Storage
                                                |
                                                |    +---------+
                                                |   /         /|
                                                |  +---------+ |
+-----------+ Name     +----------+ Recursive   |  |         | |
|           | Lookup   |          | Resolution  |  | Record  | |
|Application|--------->| Resolver |-------------|->| Storage | |
|           |<---------|          |<------------|--|         |/
+-----------+ Results  +----------+ Intermediate|  +---------+
                          A         Results     |
                          |                     |
                       +---------+              |
                      /   |     /|              |
                     +---------+ |              |
                     |         | |              |
                     |  Start  | |              |
                     |  Zones  | |              |
                     |         |/               |
                     +---------+                |

4.1. Zone Top-Level Domain (zTLD)

A zTLD is a string that encodes the zone type and zone key into a domain name suffix. A zTLD is used as a globally unique reference to a zone in the process of name resolution. It is created by encoding a binary concatenation of the zone type and zone key (see Figure 3). The used encoding is a variation of the Crockford Base32 encoding [CrockfordB32] called Base32GNS. The encoding and decoding symbols for Base32GNS, including this variation, are defined in Table 4, found in Appendix C. The functions for encoding and decoding based on Table 4 are called Base32GNS-Encode and Base32GNS-Decode, respectively.¶

0     8     16    24    32    40    48    56
+-----+-----+-----+-----+-----+-----+-----+-----+
|       ZONE TYPE       |      ZONE KEY         /
+-----+-----+-----+-----+                       /
/                                               /
/                                               /
+-----+-----+-----+-----+-----+-----+-----+-----+

The ZONE TYPE MUST be encoded in network byte order. The format of the ZONE KEY depends entirely on the ZONE TYPE.¶

Consequently, a zTLD is encoded and decoded as follows:¶

zTLD := Base32GNS-Encode(ztype||zkey)
ztype||zkey := Base32GNS-Decode(zTLD)

where "||" is the concatenation operator.¶

The zTLD can be used "as is" as a rightmost label in a GNS name. If an application wants to ensure DNS compatibility of the name, it MAY also represent the zTLD as follows: if the zTLD is less than or equal to 63 characters, it can be used as a zTLD as is. If the zTLD is longer than 63 characters, the zTLD is divided into smaller labels separated by the label separator. Here, the most significant bytes of the "ztype||zkey" concatenation must be contained in the rightmost label of the resulting string and the least significant bytes in the leftmost label of the resulting string. This allows the resolver to determine the ztype and zTLD length from the rightmost label and to subsequently determine how many labels the zTLD should span. A GNS implementation MUST support the division of zTLDs in DNS-compatible label lengths. For example, assuming a zTLD of 130 characters, the division is as follows:¶

zTLD[126..129].zTLD[63..125].zTLD[0..62]

4.2. Zone Revocation

In order to revoke a zone key, a signed revocation message MUST be published. This message MUST be signed using the private key of the zone. The revocation message is broadcast to the network. The specification of the broadcast mechanism is out of scope for this document. A possible broadcast mechanism for efficient flooding in a distributed network is implemented in [GNUnet]. Alternatively, revocation messages could also be distributed via a distributed ledger or a trusted central server. 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.¶

For all occurrences below, "Argon2id" is the password-based key derivation function as defined in [RFC9106]. For the PoW calculations, the algorithm is instantiated with the following parameters:¶

S:

The salt. Fixed 16-byte string: "GnsRevocationPow"¶

t:

Number of iterations: 3¶

m:

Memory size in KiB: 1024¶

T:

Output length of hash in bytes: 64¶

p:

Parallelization parameter: 1¶

v:

Algorithm version: 0x13¶

y:

Algorithm type (Argon2id): 2¶

X:

Unused¶

K:

Unused¶

Figure 4 illustrates the format of the data "P" on which the PoW is calculated.¶

0     8     16    24    32    40    48    56
+-----+-----+-----+-----+-----+-----+-----+-----+
|                      POW                      |
+-----------------------------------------------+
|                   TIMESTAMP                   |
+-----------------------------------------------+
|       ZONE TYPE       |    ZONE KEY           /
+-----+-----+-----+-----+                       /
/                                               /
/                                               /
+-----+-----+-----+-----+-----+-----+-----+-----+

POW:

A 64-bit value that is a solution to the PoW. In network byte order.¶

TIMESTAMP:

Denotes the absolute 64-bit date when the revocation was computed. In microseconds since midnight (0 hour), January 1, 1970 UTC in network byte order.¶

ZONE TYPE:

The 32-bit zone type in network byte order.¶

ZONE KEY:

The 256-bit public key zkey of the zone that is being revoked. The wire format of this value is defined by the ZONE TYPE.¶

Usually, PoW schemes require that one POW value be found, such that a specific number of leading zeroes are found in the hash result. This number is then referred to as the difficulty of the PoW. In order to reduce the variance in time it takes to calculate the PoW, a valid GNS revocation requires that a number of different PoWs (Z, as defined below) must be found that on average have at least D leading zeroes.¶

Given an average difficulty of D, the proofs have an expiration time of EPOCH. Applications MAY calculate proofs with a difficulty that is higher than D by providing POW values where there are (on average) more than D bits of leading zeroes. With each additional bit of difficulty, the lifetime of the proof is prolonged by another EPOCH. Consequently, by calculating a more difficult PoW, the lifetime of the proof -- and thus the persistence of the revocation message -- can be increased on demand by the zone owner.¶

The parameters are defined as follows:¶

Z:

The number of PoWs that are required. Its value is fixed at 32.¶

D:

The lower limit of the average difficulty. Its value is fixed at 22.¶

EPOCH:

A single epoch. Its value is fixed at 365 days in microseconds.¶

The revocation message wire format is illustrated in Figure 5.¶

0     8     16    24    32    40    48    56
+-----+-----+-----+-----+-----+-----+-----+-----+
|                   TIMESTAMP                   |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                      TTL                      |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                     POW_0                     |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                       ...                     |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                    POW_(Z-1)                  |
+-----------------------------------------------+
|       ZONE TYPE       |    ZONE KEY           /
+-----+-----+-----+-----+                       /
/                                               /
/                                               /
+-----+-----+-----+-----+-----+-----+-----+-----+
/                   SIGNATURE                   /
/                                               /
/                                               /
/                                               /
+-----+-----+-----+-----+-----+-----+-----+-----+

TIMESTAMP:

Denotes the absolute 64-bit date when the revocation was computed. In microseconds since midnight (0 hour), January 1, 1970 UTC in network byte order. This is the same value as the timestamp used in the individual PoW calculations.¶

TTL:

Denotes the relative 64-bit time to live of the record in microseconds in network byte order. The field SHOULD be set to EPOCH * 1.1. Given an average number of leading zeroes D', then the field value MAY be increased up to (D'-D+1) * EPOCH * 1.1. Validators MAY reject messages with lower or higher values when received.¶

POW_i:

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

ZONE TYPE:

The 32-bit zone type corresponding to the zone key in network byte order.¶

ZONE KEY:

The public key zkey of the zone that is being revoked and the key to be used to verify SIGNATURE.¶

SIGNATURE:

A signature over a timestamp and the zone zkey of the zone that is revoked and corresponds to the key used in the PoW. The signature is created using the Sign() function of the cryptosystem of the zone and the private key (see Section 4).¶

The signature in the revocation message covers a 32-bit header prefixed to the TIMESTAMP, ZONE TYPE, and ZONE KEY fields. The header includes the key length and signature purpose. The wire format is illustrated in Figure 6.¶

0     8     16    24    32    40    48    56
+-----+-----+-----+-----+-----+-----+-----+-----+
|         SIZE          |       PURPOSE (0x03)  |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                   TIMESTAMP                   |
+-----+-----+-----+-----+-----+-----+-----+-----+
|       ZONE TYPE       |     ZONE KEY          /
+-----+-----+-----+-----+                       /
/                                               /
/                                               /
+-----+-----+-----+-----+-----+-----+-----+-----+

SIZE:

A 32-bit value containing the length of the signed data in bytes in network byte order.¶

PURPOSE:

A 32-bit signature purpose flag. The value of this field MUST be 3. The value is encoded in network byte order. It defines the context in which the signature is created so that it cannot be reused in other parts of the protocol that might include possible future extensions. The value of this field corresponds to an entry in the GANA "GNUnet Signature Purposes" registry [GANA].¶

TIMESTAMP:

Field as defined in the revocation message above.¶

ZONE TYPE:

Field as defined in the revocation message above.¶

ZONE KEY:

Field as defined in the revocation message above.¶

In order to validate a revocation, the following steps MUST be taken:¶

The TTL field in the revocation message is informational. A revocation MAY be discarded without checking the POW values or the signature if the TTL (in combination with TIMESTAMP) indicates that the revocation has already expired. The actual validity period of the revocation MUST be determined by examining the leading zeroes in the POW values.¶

The validity period of the revocation is calculated as (D'-D+1) * EPOCH * 1.1. The EPOCH is extended by 10% in order to deal with poorly synchronized clocks. The validity period added on top of the TIMESTAMP yields the expiration date. If the current time is after the expiration date, the revocation is considered stale.¶

Verified revocations MUST be stored locally. The implementation MAY discard stale revocations and evict them from the local store at any time.¶

It is important that implementations broadcast received revocations if they are valid and not stale. Should the calculated validity period differ from the TTL field value, the calculated value MUST be used as the TTL field value when forwarding the revocation message. Systems might disagree on the current time, so implementations MAY use stale but otherwise valid revocations but SHOULD NOT broadcast them. Forwarded stale revocations MAY be discarded by the receiver.¶

Any locally stored revocation MUST be considered during delegation record processing (see Section 7.3.4).¶

5.1. Zone Delegation Records

This section defines the initial set of zone delegation record types. Any implementation SHOULD support all zone types defined here and MAY support any number of additional delegation records defined in the GANA "GNS Record Types" registry (see [GANA]). Not supporting some zone types will result in resolution failures if the respective zone type is encountered. This can be a valid choice if some zone delegation record types have been determined to be cryptographically insecure. Zone delegation records MUST NOT be stored or published under the apex label. A zone delegation record type value is the same as the respective ztype value. The ztype defines the cryptographic primitives for the zone that is being delegated to. A zone delegation record payload contains the public key of the zone to delegate to. A zone delegation record MUST have the CRITICAL flag set and MUST be the only non-supplemental record under a label. There MAY be inactive records of the same type that have the SHADOW flag set in order to facilitate smooth key rollovers.¶

In the following, "||" is the concatenation operator of two byte strings. The algorithm specification uses character strings such as GNS labels or constant values. When used in concatenations or as input to functions, the zero terminator of the character strings MUST NOT be included.¶

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

ZKDF(zkey, label):
  PRK_h := HKDF-Extract("key-derivation", zkey)
  h := HKDF-Expand(PRK_h, label || "gns", 512 / 8)
  zkey' := (h mod L) * zkey
  return zkey'

SignDerived(d, label, message):
  zkey := d * G
  PRK_h := HKDF-Extract("key-derivation", zkey)
  h := HKDF-Expand(PRK_h, label || "gns", 512 / 8)
  d' := (h * d) mod L
  return Sign(d', message)

VerifyDerived(zkey', message, signature):
  return Verify(zkey', message, signature)

S-Encrypt(zkey, label, expiration, plaintext):
  PRK_k := HKDF-Extract("gns-aes-ctx-key", zkey)
  PRK_n := HKDF-Extract("gns-aes-ctx-iv", zkey)
  K := HKDF-Expand(PRK_k, label, 256 / 8)
  NONCE := HKDF-Expand(PRK_n, label, 32 / 8)
  BLOCK_COUNTER := 0x0000000000000001
  IV := NONCE || expiration || BLOCK_COUNTER
  return CTR-AES256(K, IV, plaintext)

S-Decrypt(zkey, label, expiration, ciphertext):
  PRK_k := HKDF-Extract("gns-aes-ctx-key", zkey)
  PRK_n := HKDF-Extract("gns-aes-ctx-iv", zkey)
  K := HKDF-Expand(PRK_k, label, 256 / 8)
  NONCE := HKDF-Expand(PRK_n, label, 32 / 8)
  BLOCK_COUNTER := 0x0000000000000001
  IV := NONCE || expiration || BLOCK_COUNTER
  return CTR-AES256(K, IV, ciphertext)

0     8     16    24    32
+-----+-----+-----+-----+
|         NONCE         |
+-----+-----+-----+-----+
|       EXPIRATION      |
|                       |
+-----+-----+-----+-----+
|      BLOCK COUNTER    |
+-----+-----+-----+-----+

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

ZKDF(zkey, label):
  /* Calculate the blinding factor */
  PRK_h := HKDF-Extract("key-derivation", zkey)
  h := HKDF-Expand(PRK_h, label || "gns", 512 / 8)
  /* Ensure that h == h mod L */
  h := h mod L

  zkey' := h * zkey
  return zkey'

SignDerived(d, label, message):
  /* Key expansion */
  dh := SHA-512(d)
  /* EdDSA clamping */
  a := dh[0..31]
  a[0] := a[0] & 248
  a[31] := a[31] & 127
  a[31] := a[31] | 64
  /* Calculate zkey corresponding to d */
  zkey := a * G

  /* Calculate blinding factor */
  PRK_h := HKDF-Extract("key-derivation", zkey)
  h := HKDF-Expand(PRK_h, label || "gns", 512 / 8)
  /* Ensure that h == h mod L */
  h := h mod L

  d' := (h * a) mod L
  nonce := SHA-256(dh[32..63] || h)
  r := SHA-512(nonce || message)
  R := r * G
  S := r + SHA-512(R || zkey' || message) * d' mod L
  return (R,S)

VerifyDerived(zkey', message, signature):
  (R,S) := signature
  return S * G == R + SHA-512(R, zkey', message) * zkey'

S-Encrypt(zkey, label, expiration, plaintext):
  PRK_k := HKDF-Extract("gns-xsalsa-ctx-key", zkey)
  PRK_n := HKDF-Extract("gns-xsalsa-ctx-iv", zkey)
  K := HKDF-Expand(PRK_k, label, 256 / 8)
  NONCE := HKDF-Expand(PRK_n, label, 128 / 8)
  IV := NONCE || expiration
  return XSalsa20-Poly1305(K, IV, plaintext)

S-Decrypt(zkey, label, expiration, ciphertext):
  PRK_k := HKDF-Extract("gns-xsalsa-ctx-key", zkey)
  PRK_n := HKDF-Extract("gns-xsalsa-ctx-iv", zkey)
  K := HKDF-Expand(PRK_k, label, 256 / 8)
  NONCE := HKDF-Expand(PRK_n, label, 128 / 8)
  IV := NONCE || expiration
  return XSalsa20-Poly1305(K, IV, ciphertext)

0     8     16    24    32    40    48    56
+-----+-----+-----+-----+-----+-----+-----+-----+
|                     NONCE                     |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                   EXPIRATION                  |
+-----+-----+-----+-----+-----+-----+-----+-----+

5.2. Redirection Records

Redirection records are used to redirect resolution. Any implementation SHOULD support all redirection record types defined here and MAY support any number of additional redirection records defined in the GANA "GNS Record Types" registry [GANA]. Redirection records MUST have the CRITICAL flag set. Not supporting some record types can result in resolution failures. This can be a valid choice if some redirection record types have been determined to be insecure, or if an application has reasons to not support redirection to DNS for reasons such as complexity or security. Redirection records MUST NOT be stored or published under the apex label.¶

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

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

5.3. Auxiliary Records

This section defines the initial set of auxiliary GNS record types. Any implementation SHOULD be able to process the specified record types according to Section 7.3.¶

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

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

0     8     16    24    32    40    48    56
+-----+-----+-----+-----+-----+-----+-----+-----+
|   PROTO   |    SVC    |       TYPE            |
+-----------+-----------------------------------+
|                 RECORD DATA                   |
/                                               /
/                                               /
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+

6.1. The Storage Key

The storage key is derived from the zone key and the respective label of the contained records. The required knowledge of both the zone key and the label in combination with the similarly derived symmetric secret keys and blinded zone keys ensures query privacy (see [RFC8324], Section 3.5).¶

Given a label, the storage key q is derived as follows:¶

q := SHA-512(ZKDF(zkey, label))

label:

A UTF-8 string under which the resource records are published.¶

zkey:

The zone key.¶

q:

The 512-bit storage key under which the resource record block is published. It is the SHA-512 hash [RFC6234] over the derived zone key.¶

6.2. Plaintext Record Data (RDATA)

GNS records from a zone are grouped by their labels such that all records under the same label are published together as a single block in storage. Such grouped record sets MAY be paired with supplemental records.¶

Record data (RDATA) is the format used to encode such a group of GNS records. The binary format of RDATA is illustrated in Figure 20.¶

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

EXPIRATION, SIZE, TYPE, FLAGS, and DATA:

Definitions for these fields are provided below Figure 7 in Section 5.¶

PADDING:

When serializing records into RDATA, a GNS implementation MUST ensure that the size of the RDATA is a power of two using this field. The field MUST be set to zero and MUST be ignored on receipt. As a special exception, record sets with (only) a zone delegation record type are never padded.¶

6.3. The Resource Record Block

The resource records grouped in an RDATA are encrypted using the S-Encrypt() function defined by the zone type of the zone to which the resource records belong and prefixed with metadata into a resource record block (RRBLOCK) for remote storage. The GNS RRBLOCK wire format is illustrated in Figure 21.¶

0     8     16    24    32    40    48    56
+-----+-----+-----+-----+-----+-----+-----+-----+
|          SIZE         |    ZONE TYPE          |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                  ZONE KEY                     /
/                  (BLINDED)                    /
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                   SIGNATURE                   |
/                                               /
/                                               /
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                   EXPIRATION                  |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                    BDATA                      |
/                                               /
/                                               /
+-----+-----+-----+-----+-----+-----+-----+-----+

SIZE:

A 32-bit value containing the length of the block in bytes in network byte order. Despite the message format's use of a 32-bit value, implementations MAY refuse to publish blocks beyond a certain size significantly below the theoretical block size limit of 4 GB.¶

ZONE TYPE:

The 32-bit ztype in network byte order.¶

ZONE KEY (BLINDED):

The blinded zone key "ZKDF(zkey, label)" to be used to verify SIGNATURE. The length and format of the blinded public key depend on the ztype.¶

SIGNATURE:

The signature is computed over the EXPIRATION and BDATA fields as shown in Figure 22. The length and format of the signature depend on the ztype. The signature is created using the SignDerived() function of the cryptosystem of the zone (see Section 4).¶

EXPIRATION:

Specifies when the RRBLOCK expires and the encrypted block SHOULD be removed from storage and caches, as it is likely stale. However, applications MAY continue to use non-expired individual records until they expire. The RRBLOCK expiration value MUST be computed by first determining for each record type present in the RRBLOCK the maximum expiration time of all records of that type, including shadow records. Then, the minimum of all of these expiration times is taken. The final expiration time is then the larger value of (1) the previous EXPIRATION value of a previous RRBLOCK for the same storage key plus one (if any) and (2) the computed minimum expiration time across the contained record types. This ensures strict monotonicity (see Section 9.3). This is a 64-bit absolute date in microseconds since midnight (0 hour), January 1, 1970 UTC in network byte order.¶

BDATA:

The encrypted RDATA computed using S-Encrypt() with the zone key, label, and expiration time as additional inputs. Its ultimate size and content are determined by the S-Encrypt() function of the ztype.¶

The signature over the public key covers a 32-bit pseudo header conceptually prefixed to the EXPIRATION and BDATA fields. The wire format is illustrated in Figure 22.¶

0     8     16    24    32    40    48    56
+-----+-----+-----+-----+-----+-----+-----+-----+
|         SIZE          |       PURPOSE (0x0F)  |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                   EXPIRATION                  |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                    BDATA                      |
/                                               /
/                                               /
+-----+-----+-----+-----+-----+-----+-----+-----+

SIZE:

A 32-bit value containing the length of the signed data in bytes in network byte order.¶

PURPOSE:

A 32-bit signature purpose flag in network byte order. The value of this field MUST be 15. It defines the context in which the signature is created so that it cannot be reused in other parts of the protocol that might include possible future extensions. The value of this field corresponds to an entry in the GANA "GNUnet Signature Purposes" registry [GANA].¶

EXPIRATION:

Field as defined in the RRBLOCK message above.¶

BDATA:

Field as defined in the RRBLOCK message above.¶

7.1. Start Zones

The resolution of a GNS name starts by identifying the Start Zone suffix. Once the Start Zone suffix is identified, recursive resolution of the remainder of the name is initiated (see Section 7.2). There are two types of Start Zone suffixes: zTLDs and local suffix-to-zone mappings. The choice of available suffix-to-zone mappings is at the sole discretion of the local system administrator or user. This property addresses the issue of a single hierarchy with a centrally controlled root and the related issue of distribution and management of root servers in DNS (see Sections 3.12 and 3.10 of [RFC8324], respectively).¶

For names ending with a zTLD, the Start Zone is explicitly given in the suffix of the name to resolve. In order to ensure uniqueness of names with zTLDs, any implementation MUST use the given zone as the Start Zone. An implementation MUST first try to interpret the rightmost label of the given name as the beginning of a zTLD (see Section 4.1). If the rightmost label cannot be (partially) decoded or if it does not indicate a supported ztype, the name is treated as a normal name and Start Zone discovery MUST continue with finding a local suffix-to-zone mapping. If a valid ztype can be found in the rightmost label, the implementation MUST try to synthesize and decode the zTLD to retrieve the Start Zone key according to Section 4.1. If the zTLD cannot be synthesized or decoded, the resolution of the name fails and an error is returned to the application. Otherwise, the zone key MUST be used as the Start Zone:¶

Example name: www.example.<zTLD>
=> Start Zone: zkey of type ztype
=> Name to resolve from Start Zone: www.example

For names not ending with a zTLD, the resolver MUST determine the Start Zone through a local suffix-to-zone mapping. Suffix-to-zone mappings MUST be configurable through a local configuration file or database by the user or system administrator. A suffix MAY consist of multiple GNS labels concatenated with a label separator. If multiple suffixes match the name to resolve, the longest matching suffix MUST be used. The suffix length of two results MUST NOT be equal. This indicates a misconfiguration, and the implementation MUST return an error. The following is a non-normative example mapping of Start Zones:¶

Example name: www.example.xyz.gns.alt
Local suffix mappings:
xyz.gns.alt = zTLD0 := Base32GNS(ztype0||zkey0)
example.xyz.gns.alt = zTLD1 := Base32GNS(ztype1||zkey1)
example.com.gns.alt = zTLD2 := Base32GNS(ztype2||zkey2)
...
=> Start Zone: zkey1
=> Name to resolve from Start Zone: www

The process given above MAY be supplemented with other mechanisms if the particular application requires a different process. If no Start Zone can be identified, resolution MUST fail and an error MUST be returned to the application.¶

7.2. Recursion

In each step of the recursive name resolution, there is an authoritative zone zkey and a name to resolve. The name MAY be empty. If the name is empty, it is interpreted as the apex label "@". Initially, the authoritative zone is the Start Zone.¶

From here, the following steps are recursively executed, in order:¶

Once a well-formed block has been decrypted, the records from RDATA are subjected to record processing.¶

7.3. Record Processing

In record processing, only the valid records obtained are considered. To filter records by validity, the resolver MUST at least check the expiration time and the FLAGS field of the respective record. Specifically, the resolver MUST disregard expired records. Furthermore, SHADOW and SUPPLEMENTAL flags can also exclude records from being considered. If the resolver encounters a record with the CRITICAL flag set and does not support the record type, the resolution MUST be aborted and an error MUST be returned. Information indicating that the critical record could not be processed SHOULD be returned in the error description. The implementation MAY choose not to return the reason for the failure, merely complicating troubleshooting for the user.¶

The next steps depend on the context of the name that is being resolved:¶

Case 1:

If the filtered record set consists of a single REDIRECT record, the remainder of the name is prepended to the REDIRECT DATA and the recursion is started again from the resulting name. Details are provided in Section 7.3.1.¶

Case 2:

If the filtered record set consists exclusively of one or more GNS2DNS records, resolution continues with DNS. Details are provided in Section 7.3.2.¶

Case 3:

If the remainder of 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 final result and the recursion is concluded as described in Section 7.3.3.¶

Case 4:

If the current record set consists of a single delegation record, resolution of the remainder of the name is delegated to the target zone as described in Section 7.3.4.¶

Case 5:

If the remainder of the name to resolve is empty, the record set is the final result. If any NICK records are in the final result set, they MUST first be processed according to Section 7.3.5. Otherwise, the record result set is directly returned as the final result.¶

Finally, if none of the above cases are applicable, resolution fails and the resolver MUST return an empty record set.¶

Query: alice.example.gns.alt (type=A)
Result:
A: 192.0.2.1
NICK: eve (non-supplemental)

Query: alice.example.gns.alt (type=AAAA)
Result:
AAAA: 2001:db8::1
NICK: john (supplemental)

9.1. Availability

In order to ensure availability of records beyond their absolute expiration times, implementations MAY allow relative expiration time values of records to be locally defined. Records can then be published recurringly with updated absolute expiration times by the implementation.¶

Implementations MAY allow users to manage private records in their zones that are not published in storage. Private records are treated just like regular records when resolving labels in local zones, but their data is completely unavailable to non-local users.¶

9.2. Agility

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. This 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. This is why developers of applications managing GNS zones SHOULD select a default ztype considered secure at the time of releasing the software. For applications targeting end users that are not expected to understand cryptography, the application developer MUST NOT leave the ztype selection of new zones to end users.¶

This document concerns itself with the selection of cryptographic algorithms used 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 is not 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.¶

In terms of crypto-agility, whenever the need for an updated cryptographic scheme arises to, for example, replace ECDSA over Ed25519 for PKEY records, it can simply be introduced through a new record type. Zone administrators can then replace the delegation record type for future records. The old record type remains, and zones can iteratively migrate to the updated zone keys. To ensure that implementations correctly generate an error message when encountering a ztype that they do not support, current and future delegation records must always have the CRITICAL flag set.¶

9.3. Cryptography

The following considerations provide background on the design choices of the ztypes specified in this document. When specifying new ztypes as per Section 4, the same considerations apply.¶

GNS PKEY zone keys use ECDSA over Ed25519. This is an unconventional choice, as ECDSA is usually used with other curves. However, standardized ECDSA curves are problematic for a range of reasons, as described in the Curve25519 and EdDSA papers [RFC7748] [ed25519]. Using EdDSA directly is also not possible, as a hash function is used on the private key and will destroy the linearity that the key blinding in GNS depends upon. We are not aware of anyone suggesting that using Ed25519 instead of another common curve of similar size would lower the security of ECDSA. GNS uses 256-bit curves; that way, the encoded (public) keys fit into a single DNS label, which is good for usability.¶

In order to ensure ciphertext indistinguishability, care must be taken with respect to the IV in the counter block. In our design, the IV always includes the expiration time of the record block. When applications store records with relative expiration times, monotonicity is implicitly ensured because each time a block is published in storage, its IV is unique, as the expiration time is calculated dynamically and increases monotonically with the system time. Still, an implementation MUST ensure that when relative expiration times are decreased, the expiration time of the next record block MUST be after the last published block. For records where an absolute expiration time is used, the implementation MUST ensure that the expiration time is always increased when the record data changes. For example, the expiration time on the wire could be increased by a single microsecond even if the user did not request a change. In the case of deletion of all resource records under a label, the implementation MUST keep track of the last absolute expiration time of the last published resource block. Implementations MAY define and use a special record type as a tombstone that preserves the last absolute expiration time but then MUST take care to not publish a block with such a tombstone record. When new records are added under this label later, the implementation MUST ensure that the expiration times are after the last published block. Finally, in order to ensure monotonically increasing expiration times, the implementation MUST keep a local record of the last time obtained from the system clock, so as to construct a monotonic clock if the system clock jumps backwards.¶

9.4. Abuse Mitigation

GNS names are UTF-8 strings. Consequently, GNS faces issues with respect to name spoofing similar to those for DNS with respect to internationalized domain names. In DNS, attackers can register similar-sounding or similar-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.¶

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. Avoiding that possibility is one of the motivations behind GNS. In GNS, TLDs are not enumerable. By design, the Start Zone of the resolver is defined locally, and hence such a seizure is difficult and ineffective in GNS.¶

9.5. Zone Management

In GNS, zone administrators need to manage and protect their zone keys. Once a private zone key is lost, it cannot be recovered, and the zone revocation message cannot be computed anymore. Revocation messages can be precalculated if revocation is required in cases where a private zone key is lost. Zone administrators, and for GNS this includes end users, are required to responsibly and diligently protect their cryptographic keys. GNS supports signing records in advance ("offline") in order to support processes (such as air gaps) that aim to protect private keys.¶

Similarly, users are required to manage their local Start Zone configuration. In order to ensure the integrity and availability of names, users must ensure that their local Start Zone information is not compromised or outdated. It can be expected that the processing of zone revocations and an initial Start Zone are provided with a GNS implementation ("drop shipping"). Shipping an initial Start Zone configuration effectively establishes a root zone. Extension and customization of the zone are at the full discretion of the user.¶

While implementations following this specification will be interoperable, if two implementations connect to different remote storage entities, they are mutually unreachable. This can lead to a state where a record exists in the global namespace for a particular name, but the implementation is not communicating with the remote storage entity that contains the respective block and is hence unable to resolve it. This situation is similar to a split-horizon DNS configuration. The remote storage entity used will most likely depend on the specific application context using GNS resolution. For example, one application is the resolution of hidden services within the Tor network [TorRendSpec], which would suggest using Tor routers for remote storage. Implementations of "aggregated" remote storage entities are conceivable but are expected to be the exception.¶

9.6. DHTs as Remote Storage

This document does not specify the properties of the underlying remote storage, which is required by any GNS implementation. It is important to note that the properties of the underlying remote storage are directly inherited by the GNS implementation. This includes both security and other non-functional properties such as scalability and performance. Implementers should take great care when selecting or implementing a DHT for use as remote storage in a GNS implementation. DHTs with reasonable security and performance properties exist [R5N]. It should also be taken into consideration that GNS implementations that build upon different DHT overlays are unlikely to be mutually reachable.¶

9.7. Revocations

Zone administrators are advised to pregenerate zone revocations and to securely store the revocation information if the zone key is lost, compromised, or replaced in the future. Precalculated revocations can cease to be valid due to expirations or protocol changes such as epoch adjustments. Consequently, implementers and users must take precautions in order to manage revocations accordingly.¶

Revocation payloads do not include a "new" key for key replacement. Inclusion of such a key would have two major disadvantages:¶

9.8. Zone Privacy

GNS does not support authenticated denial of existence of names within a zone. Record data is published in encrypted form using keys derived from the zone key and record label. Zone administrators should carefully consider whether (1) a label and zone key are public or (2) one or both of these should be used as a shared secret to restrict access to the corresponding record data. Unlike public zone keys, low-entropy labels can be guessed by an attacker. If an attacker knows the public zone key, the use of well-known or guessable labels effectively threatens the disclosure of the corresponding records.¶

It should be noted that the guessing attack on labels only applies if the zone key is somehow disclosed to the adversary. GNS itself does not disclose it during a lookup or when resource records are published (as only the blinded zone keys are used on the network). However, zone keys do become public during revocation.¶

It is thus RECOMMENDED to use a label with sufficient entropy to prevent guessing attacks if any data in a resource record set is sensitive.¶

9.9. Zone Governance

While DNS is distributed, in practice it relies on centralized, trusted registrars to provide globally unique names. As awareness of the central role DNS plays on the Internet increases, 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. While a wider discussion of this issue is out of scope for this document, analyses and investigations can be found in recent academic research works, including [SecureNS].¶

GNS is designed to provide a secure, privacy-enhancing alternative to the DNS name resolution protocol, especially when censorship or manipulation is encountered. In particular, it directly addresses concerns in DNS with respect to query privacy. However, depending on the governance of the root zone, any deployment will likely suffer from the issue of a single hierarchy with a centrally controlled root and the related issue of distribution and management of root servers in DNS, as raised in Sections 3.12 and 3.10 of [RFC8324], respectively. In DNS, those issues directly result from the centralized root zone governance at the Internet Corporation for Assigned Names and Numbers (ICANN), which allows it to provide globally unique names.¶

In GNS, Start Zones give users local authority over their preferred root zone governance. It enables users to replace or enhance a trusted root zone configuration provided by a third party (e.g., the implementer or a multi-stakeholder governance body like ICANN) with secure delegation of authority using local petnames while operating under a very strong adversary model. In combination with zTLDs, this provides users of GNS with a global, secure, and memorable mapping without a trusted authority.¶

Any GNS implementation MAY provide a default governance model in the form of an initial Start Zone mapping.¶

9.10. Namespace Ambiguity

Technically, the GNS protocol can be used to resolve names in the namespace of the global DNS. However, this would require the respective governance bodies and stakeholders (e.g., the IETF and ICANN) to standardize the use of GNS for this particular use case.¶

This capability implies that GNS names may be indistinguishable from DNS names in their respective common display format [RFC8499] or other special-use domain names [RFC6761] if a local Start Zone configuration maps suffixes from the global DNS to GNS zones. For applications, which name system should be used in order to resolve a given name will then be ambiguous. This poses a risk when trying to resolve a name through DNS when it is actually a GNS name, as discussed in [RFC8244]. In such a case, the GNS name is likely to be leaked as part of the DNS resolution.¶

In order to prevent disclosure of queried GNS names, it is RECOMMENDED that GNS-aware applications try to resolve a given name in GNS before any other method, taking into account potential suffix-to-zone mappings and zTLDs. Suffix-to-zone mappings are expected to be configured by the user or local administrator, and as such the resolution in GNS is in line with user expectations even if the name could also be resolved through DNS. If no suffix-to-zone mapping for the name exists and no zTLD is found, resolution MAY continue with other methods such as DNS. If a suffix-to-zone mapping for the name exists or the name ends with a zTLD, it MUST be resolved using GNS, and resolution MUST NOT continue by any other means independent of the GNS resolution result.¶

Mechanisms such as the Name Service Switch (NSS) of UNIX-like operating systems are an example of how such a resolution process can be implemented and used. The NSS allows system administrators to configure hostname resolution precedence and is integrated with the system resolver implementation.¶

For use cases where GNS names may be confused with names of other name resolution mechanisms (in particular, DNS), the ".gns.alt" domain SHOULD be used. For use cases like implementing sinkholes to block malware sites or serving DNS domains via GNS to bypass censorship, GNS MAY be deliberately used in ways that interfere with resolution of another name system.¶

10.1. GNUnet Signature Purposes Registry

GANA [GANA] has assigned signature purposes in its "GNUnet Signature Purposes" registry as listed in Table 1.¶

10.2. GNS Record Types Registry

GANA [GANA] manages the "GNS Record Types" registry.¶

Each entry has the following format:¶

Name:

The name of the record type (case-insensitive ASCII string, restricted to alphanumeric characters). For zone delegation records, the assigned number represents the ztype value of the zone.¶

Number:

A 32-bit number above 65535.¶

Comment:

Optionally, brief English text describing the purpose of the record type (in UTF-8).¶

Contact:

Optionally, the contact information for a person to contact for further information.¶

References:

Optionally, references (such as an RFC) describing the record type.¶

The registration policy for this registry is "First Come First Served". This policy is modeled on that described in [RFC8126] and describes the actions taken by GANA:¶

GANA has assigned numbers for the record types defined in this specification in the "GNS Record Types" registry as listed in Table 2.¶

10.3. .alt Subdomains Registry

GANA [GANA] manages the ".alt Subdomains" registry. This GANA-operated .alt registry may or may not be taken into account by any particular implementer, and it is not in any way associated with or sanctioned by the IETF or ICANN.¶

Each entry has the following format:¶

Label:

The label of the subdomain (in DNS "letters, digits, hyphen" (LDH) format as defined in Section 2.3.1 of [RFC5890]).¶

Description:

Optionally, brief English text describing the purpose of the subdomain (in UTF-8).¶

Contact:

Optionally, the contact information for a person to contact for further information.¶

References:

Optionally, references (such as an RFC) describing the record type.¶

The registration policy for this registry is "First Come First Served". This policy is modeled on that described in [RFC8126] and describes the actions taken by GANA:¶

GANA has assigned the subdomain defined in this specification in the ".alt Subdomains" registry as listed in Table 3.¶