The GNU Name System

The GNU Name System (GNS) is secure and decentralized naming system.
It allows its users to resolve and register names within the .gnu top-level domain (TLD).

GNS is designed to provide:

  • Censorship resistance
  • Query privacy
  • Secure name resolution
  • Compatibility with DNS

For the initial configuration and population of your GNS installation, please follow the GNS setup instructions. The remainder of this chapter will provide some background on GNS and then describe how to use GNS in more detail.

Unlike DNS, GNS does not rely on central root zones or authorities. Instead any user administers his own root and can can create arbitrary name value mappings. Furthermore users can delegate resolution to other users' zones just like DNS NS records do. Zones are uniquely identified via public keys and resource records are signed using the corresponding public key. Delegation to another user's zone is done using special PKEY records and petnames. A petname is a name that can be freely chosen by the user. This results in non-unique name-value mappings as www.bob.gnu to one user might be www.friend.gnu for someone else.

Maintaining your own Zones

To setup you GNS system you must execute:

$ gnunet-gns-import.sh

This will boostrap your zones and create the necessary key material.
Your keys can be listed using the gnunet-identity command line tool:

$ gnunet-identity -d

You can arbitrarily create your own zones using the gnunet-identity tool using:

$ gnunet-identity -C "new_zone"

Now you can add (or edit, or remove) records in your GNS zone using the gnunet-setup GUI or using the gnunet-namestore command-line tool. In either case, your records will be stored in an SQL database under control of the gnunet-service-namestore. Note that if mutliple users use one peer, the namestore database will include the combined records of all users. However, users will not be able to see each other's records if they are marked as private.

To provide a simple example for editing your own zone, suppose you have your own web server with IP 1.2.3.4. Then you can put an A record (A records in DNS are for IPv4 IP addresses) into your local zone using the command:

$ gnunet-namestore -z master-zone -a -n www -t A -V 1.2.3.4 -e never

Afterwards, you will be able to access your webpage under "www.gnu"(assuming your webserver does not use virtual hosting, if it does, please read up on setting up the GNS proxy).

Similar commands will work for other types of DNS and GNS records, the syntax largely depending on the type of the record. Naturally, most users may find editing the zones using the gnunet-setup GUI to be easier.

Obtaining your Zone Key

Each zone in GNS has a public-private key. Usually, gnunet-namestore and gnunet-setup will access your private key as necessary, so you do not have to worry about those. What is important is your public key (or rather, the hash of your public key), as you will likely want to give it to others so that they can securely link to you.

You can usually get the hash of your public key using

$ gnunet-identity -d $options | grep master-zone | awk '{print $3}'

For example, the output might be something like
DC3SEECJORPHQNVRH965A6N74B1M37S721IG4RBQ15PJLLPJKUE0.

Alternatively, you can obtain a QR code with your zone key AND your pseudonym from gnunet-gtk. The QR code is displayed in the GNS tab and can be stored to disk using the Save as button next to the image.

Adding Links to Other Zones

A central operation in GNS is the ability to securely delegate to other zones. Basically, by adding a delegation you make all of the names from the other zone available to yourself. This section describes how to create delegations.

Suppose you have a friend who you call 'bob' who also uses GNS. You can then delegate resolution of names to Bob's zone by adding a PKEY record to his local zone:

$ gnunet-namestore -a -n bob --type PKEY -V XXXX -e never

Note that XXXX in the command above must be replaced with the hash of Bob's public key (the output your friend obtained using the gnunet-identity command from the previous section and told you, for example by giving you a business card containing this information as a QR code).

Assuming Bob has an A record for his website under the name of www in his zone, you can then access Bob's website under www.bob.gnu --- as well as any (public) GNS record that Bob has in his zone by replacing www with the respective name of the record in Bob's zone.

Furthermore, if Bob has himself a (public) delegation to Carol's zone under "carol", you can access Carol's records under NAME.carol.bob.gnu (where NAME is the name of Carol's record you want to access).

The Three Local Zones of GNS

Each user GNS has control over three zones. Each of the zones has a different purpose. These zones are the

  • master zone,
  • private zone, and the
  • shorten zone.

The Master Zone

The master zone is your personal TLD. Names within the .gnu namespace are resolved relative to this zone. You can arbitrarily add records to this zone and selectively publish those records.

The Private Zone

The private zone is a subzone (or subdomain in DNS terms) of your master zone. It should be used for records that you want to keep private. For example bank.private.gnu. The key idea is that you want to keep your private records separate, if just to know that those names are not available to other users.

The Shorten Zone

The shorten zone can either be a subzone of the master zone or the private zone. It is different from the other zones in that GNS will automatically populate this zone with other users' zones based on their PSEU records whenever you resolve a name.

For example if you go to www.bob.alice.dave.gnu, GNS will try to import bob into your shorten zone. Having obtained Bob's PKEY from alice.dave.gnu, GNS will lookup the PSEU record for + in Bob's zone. If it exists and the specified pseudonym is not taken, Bob's PKEY will be automatically added under that pseudonym (i.e. "bob") into your shorten zone. From then on, Bob's webpage will also be available for you as www.bob.short.gnu. This feature is called automatic name shortening and is supposed to keep GNS names as short and memorable as possible.

The ZKEY Top Level Domain in GNS

GNS also provides a secure and globally unique namespace under the .zkey top-level domain. A name in the .zkey TLD corresponds to the (printable) public key of a zone. Names in the .zkey TLD are then resolved by querying the respective zone. The .zkey TLD is expected to be used under rare circumstances where globally unique names are required and for integration with legacy systems.

Resource Records in GNS

GNS supports the majority of the DNS records as defined in RFC 1035. Additionally, GNS defines some new record types the are unique to the GNS system. For example, GNS-specific resource records are use to give petnames for zone delegation, revoke zone keys and provide some compatibility features.

For some DNS records, GNS does extended processing to increase their usefulness in GNS. In particular, GNS introduces special names referred to as "zone relative names". Zone relative names are allowed in some resource record types (for example, in NS and CNAME records) and can also be used in links on webpages. Zone relative names end in ".+" which indicates that the name needs to be resolved relative to the current authoritative zone. The extended processing of those names will expand the ".+" with the correct delegation chain to the authoritative zone (replacing ".+" with the name of the location where the name was encountered) and hence generate a valid .gnu name.

GNS currently supports the following record types:

NICK

A NICK record is used to give a zone a name. With a NICK record, you can essentially specify how you would like to be called. GNS expects this record under the name "+" in the zone's database (NAMESTORE); however, it will then automatically be copied into each record set, so that clients never need to do a separate lookup to discover the NICK record.

Example

Name: +; RRType: NICK; Value: bob

This record in Bob's zone will tell other users that this zone wants to be referred to as 'bob'. Note that nobody is obliged to call Bob's zone 'bob' in their own zones. It can be seen as a recommendation ("Please call me 'bob'").

PKEY

PKEY records are used to add delegation to other users' zones and give those zones a petname.

Example

Let Bob's zone be identified by the hash "ABC012". Bob is your friend so you want to give him the petname "friend". Then you add the following record to your zone:

Name: friend; RRType: PKEY; Value: ABC012;

This will allow you to resolve records in bob's zone under "*.friend.gnu".

BOX

BOX records are there to integrate information from TLSA or SRV records under the main label. In DNS, TLSA and SRV records use special names of the form _port._proto.(label.)*tld to indicate the port number and protocol (i.e. tcp or udp) for which the TLSA or SRV record is valid. This causes various problems, and is elegantly solved in GNS by integrating the protocol and port numbers together with the respective value into a "BOX" record. Note that in the GUI, you do not get to edit BOX records directly right now -- the GUI will provide the illusion of directly editing the TLSA and SRV records, even though they internally are BOXed up.

LEHO

The LEgacy HOstname of a server. Some webservers expect a specific hostname to provide a service (virtiual hosting). Also SSL certificates usually contain DNS names. To provide the expected legacy DNS name for a server, the LEHO record can be used. To mitigate the just mentioned issues the GNS proxy has to be used. The GNS proxy will use the LEHO information to apply the necessary transformations.

VPN

GNS allows easy access to services provided by the GNUnet Virtual Public Network. When the GNS resolver encounters a VPN record it will contact the VPN service to try and allocate an IPv4/v6 address (if the queries record type is an IP address) that can be used to contact the service.

Example

I want to provide access to the VPN service "web.gnu." on port 80 on peer ABC012:
Name: www; RRType: VPN; Value: 80 ABC012 web.gnu.

The peer ABC012 is configured to provide an exit point for the service "web.gnu." on port 80 to it's server running locally on port 8080 by having the following lines in the gnunet.conf configuration file:

[web.gnunet.]
TCP_REDIRECTS = 80:localhost4:8080

A, AAAA and TXT

Those records work in exactly the same fashion as in traditional DNS.

CNAME

As specified in RFC 1035 whenever a CNAME is encountered the query needs to be restarted with the specified name. In GNS a CNAME can either be:

  • A zone relative name,
  • A zkey name or
  • A DNS name (in which case resolution will continue outside of GNS with the systems DNS resolver)

GNS2DNS

GNS can delegate authority to a legacy DNS zone. For this, the name of the DNS nameserver and the name of the DNS zone are specified in a GNS2DNS record.

Example

Name: pet; RRType: GNS2DNS; Value: gnunet.org@a.ns.joker.com

Any query to pet.gnu will then be delegated to the DNS server at a.ns.joker.com.
For example, www.pet.gnu will result in a DNS query for www.gnunet.org to the server at a.ns.joker.com. Delegation to DNS via NS records in GNS can be useful if you do not want to start resolution in the DNS root zone (due to issues such as censorship or availability).

Note that you would typically want to use a relative name for the nameserver, i.e.
Name: pet; RRType: GNS2DNS; Value: gnunet.org@ns-joker.+
Name: ns-joker; RRType: A; Value: 184.172.157.218

This way, you can avoid involving the DNS hierarchy in the resolution of a.ns.joker.com. In the example above, the problem may not be obvious as the nameserver for "gnunet.org" is in the ".com" zone. However, imagine the nameserver was "ns.gnunet.org". In this case, delegating to "ns.gnunet.org" would mean that despite using GNS, censorship in the DNS ".org" zone would still be effective.

SOA, SRV, PTR and MX

The domain names in those records can, again, be either

  • A zone relative name,
  • A zkey name or
  • A DNS name

The resolver will expand the zone relative name if possible. Note that when using MX records within GNS, the target mail server might still refuse to accept e-mails to the resulting domain as the name might not match. GNS-enabled mail clients should use the ZKEY zone as the destination hostname and GNS-enabled mail servers should be configured to accept e-mails to the ZKEY-zones of all local users.