Concepts
This page explains the handful of ideas you need to use GNS: zones, records, start zones, delegation and the record types GNS adds to those of DNS. For the complete, normative description see RFC 9498.
Zones and egos
A GNS zone is a set of records controlled by a key pair. Whoever holds the private key can add, change and delete records; everybody else identifies the zone by its public key. There is no registry: creating a zone is as simple as creating a key pair.
In GNUnet, key pairs that you own are called egos and are managed with
gnunet-identity. Every ego can serve as a GNS zone. Egos may stand for
pseudonyms, organizations or your real-world identity; it is a good idea to
use separate egos for separate activities.
$ gnunet-identity -C myzone
$ gnunet-identity -d
myzone - 000G0507HZ8M09QWA93N2YX9Y9357777C0HTPK7PA0HTKJS5GCXXPGKBWC - EdDSA
The name myzone is only a local nickname for the ego, visible to you
alone. The long string is the zone’s public key: that is what identifies
the zone to everybody else.
New zones use EdDSA keys. Zones created with older versions may use ECDSA
keys; these remain supported, but creating new ones is deprecated. The key
type matters in one place: delegation records to EdDSA zones have the type
EDKEY, and those to ECDSA zones the type PKEY.
Records
A zone maps labels (such as www) to record sets. Each record has
a type, such as
A(IPv4 address) orEDKEY(delegation),a value,
an expiration time, after which resolvers discard it, and
flags, most importantly whether the record is public or private.
Records are private by default. Private records only resolve on your
own peer; they are never published. Records marked public are signed,
encrypted and published in the DHT so that others can resolve them. The
special label @ denotes the zone apex, the equivalent of the bare domain
name in DNS.
How names are resolved
GNS names look like DNS names and are read from right to left:
The rightmost part of the name selects a start zone (see below). In
www.alice.myzone, that is your own zonemyzone.Each remaining label, right to left, is looked up in the current zone. If the label holds a delegation record, resolution continues in the zone it points to. Here
aliceinmyzonedelegates to Alice’s zone.The last label (
www) is looked up in the final zone, and its records are returned.
Every record set is verified against the key of the zone that is supposed to have published it, so a peer that delivers a forged answer is detected.
Start zones
In GNS you are the master of your own root: the mapping from name suffixes to zones that DNS delegates to ICANN is, in GNS, your own configuration. There are three kinds of start zones.
- Your own zones
Every ego is a start zone. Names ending in
.myzoneare resolved in your zonemyzone.- Configured suffixes
The
[gns]configuration section maps name suffixes to zone keys. GNUnet ships with a small default set, currently.pin.gns.alt: a first-come, first-served registry run by GNUnet e.V., where anyone can register a name (see Publishing and sharing your zone), and.gnunet.gns.alt: the zone of the GNUnet project.
The default set is maintained in GANA under a restrictive registration policy. You can list the configured suffixes, and add your own, with
gnunet-config:$ gnunet-config -s gns | grep '^\.' $ gnunet-config -s gns -o .myfriend -V 000G0...ZONEKEY
- Zone keys (zTLDs)
A zone’s public key can itself be used as the top-level domain. This works without any configuration and is mostly useful in programs and when exchanging names with people whose zone you have not (yet) added:
$ gnunet-gns -u www.000G0507HZ8M09QWA93N2YX9Y9357777C0HTPK7PA0HTKJS5GCXXPGKBWC
Delegation and petnames
Delegation is what makes GNS a system of names rather than a collection of
private address books. If your friend Alice gives you her zone key, you
store it under a label of your choice, say alice, as an EDKEY record:
$ gnunet-namestore -z myzone -a -n alice -t EDKEY -V 000G0...ALICEKEY -e 1d
From then on, every public record in Alice’s zone is reachable below
alice.myzone: her www record as www.alice.myzone. If Alice in
turn has a public delegation to Carol under carol, then Carol’s www
is www.carol.alice.myzone for you.
The label you chose, alice, is a petname: a name that is meaningful
to you. Somebody else may know Alice’s zone as ally or work. Names
in GNS are therefore not globally unique; they are relative to whoever
resolves them. A zone can suggest a preferred name for itself with a
NICK record (gnunet-namestore -z myzone -i alice), but nobody is
obliged to use it.
Relative names
Some record types, for example CNAME, MX and REDIRECT, contain
names. A name ending in .+ is relative to the zone it was found in:
the resolver replaces the + with that zone’s key. If Alice’s zone
contains an MX record pointing to mail.+, the answer you get is
mail.000G0...ALICEKEY, which resolves correctly no matter what petname
you use for Alice’s zone. Relative names can also be used in links on web
pages served under a GNS name.
Record types
GNS supports the common DNS record types, including A, AAAA,
CNAME, MX, TXT, SRV and TLSA. In addition it defines
record types of its own, registered in GANA.
The ones you are most likely to meet are:
Type |
Purpose |
|---|---|
|
Delegation to another GNS zone (EdDSA or ECDSA key). |
|
Delegation to a zone in DNS: the rest of the name is resolved via the given DNS name servers. |
|
The zone’s preferred name for itself. |
|
The legacy (DNS) host name of a service, used for HTTP virtual hosting and for validating TLS certificates. |
|
Wraps |
|
Redirects resolution of a name to another name. |
|
Points to a service offered by a GNUnet peer through the GNUnet VPN; the resolver allocates a local IP address for it (see Virtual Public Network). |
Several other types are used internally by re:claimID and the messenger. For the exact format and processing rules of all records see RFC 9498.
Security and privacy properties
What GNS protects:
Integrity and authenticity. Record sets are signed with the zone key; forged or modified answers are rejected.
Query privacy. Records are stored in the DHT under a key derived from the zone key and the label, and encrypted with a key derived from the same pair. Peers that store or forward them cannot tell which name they belong to or what it resolves to, unless they already know both the zone key and the label.
Censorship resistance. There is no registrar or root operator that could be compelled to change or remove a name. Only the holder of the private key can change a zone.
What GNS does not protect against:
Someone who knows a zone’s key can check whether a label they guess exists in that zone. Do not rely on a label being secret.
If the private key of a zone is stolen, the thief can publish records in your name. Prepare a revocation certificate in advance (see Revoking a compromised zone).
A delegation is only as trustworthy as the way you obtained the key. A name like
www.carol.alice.myzonemakes the chain of trust explicit: you rely on Alice to have Carol’s correct key.GNS does not hide that your peer participates in GNUnet, and it does not anonymize the connections you make after resolving a name.