Using GNS names in applications

gnunet-gns resolves GNS names on the command line. This page explains how to make GNS names work in ordinary applications such as web browsers, curl or ssh, which only know how to use DNS.

There are two kinds of applications:

  • GNS-aware applications use GNS directly through its API. Examples are GNUnet’s own re:claimID and the messenger. They need no configuration.

  • GNS-unaware applications expect names to be resolved by the operating system or by DNS. For these, you put GNS in the path of their name lookups, using one of the methods below.

Method

Works for

Notes

DNS2GNS (recommended)

every application that uses the system’s resolver

answers DNS queries for GNS names and forwards all other queries to a DNS resolver of your choice

NSS plugin

applications that resolve names through glibc

not available on systems that generate /etc/nsswitch.conf automatically, or on non-glibc systems

SOCKS proxy for browsers

one browser at a time

can validate TLS certificates via GNS records, but is brittle

DNS2GNS

gnunet-dns2gns is a small DNS server. It answers queries for GNS names using GNS and passes every other query on to an ordinary DNS resolver. Pointing your system’s resolver at it makes GNS names work everywhere.

By default it listens on 127.0.0.1 and ::1, port 15353, and forwards non-GNS queries to 9.9.9.9. To use a different upstream resolver, for example your router:

$ gnunet-config -s dns2gns -o OPTIONS -V "-d 192.168.1.1"

Start the service and check that it works:

$ gnunet-arm -i dns2gns
$ dig +short @127.0.0.1 -p 15353 www.myzone
192.0.2.1

To start it automatically with your peer, set IMMEDIATE_START = YES in its configuration section:

$ gnunet-config -s dns2gns -o IMMEDIATE_START -V YES

Now tell your system to use it. How to do that depends on your system.

With systemd-resolved (most current GNU/Linux desktops), set it as the DNS server of your network interface, here wlan0:

$ sudo resolvectl dns wlan0 127.0.0.1:15353

This lasts until the interface is reconfigured. Some distribution packages, for example Fedora’s, ship a NetworkManager dispatcher script that does this automatically each time an interface comes up; it is activated by setting ENABLE_RESOLVECTL_NMDISPATCHER = YES in the [dns2gns] section of /etc/gnunet.conf.

With a plain /etc/resolv.conf, you cannot specify a port, so DNS2GNS must listen on the standard DNS port 53. This requires running it with the necessary privileges, typically as part of a system-wide installation. Set PORT = 53 in the [dns2gns] section and add this line at the top of /etc/resolv.conf:

nameserver 127.0.0.1

Test the result with any application:

$ curl http://www.myzone/

Note

Using DNS2GNS breaks the end-to-end verification of GNS for the application: the application trusts whatever the local DNS2GNS server tells it. This is fine as long as DNS2GNS runs on your own machine. Do not use a DNS2GNS server run by somebody else.

NSS plugin

On systems with the GNU C library, GNS can be added to the name service switch (NSS), which most programs use to look up host names.

Distribution packages install the plugin libnss_gns.so.2 for you. When building from source, it is installed into the library directory of your installation prefix; glibc only finds it there if that directory is in the dynamic linker’s search path (run sudo ldconfig after installing to /usr/local).

To activate the plugin, edit /etc/nsswitch.conf. Find the line starting with hosts:, for example:

hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4

and insert gns [NOTFOUND=return] after files:

hosts: files gns [NOTFOUND=return] mdns4_minimal [NOTFOUND=return] dns mdns4

On some systems, in particular those using systemd-resolved, /etc/nsswitch.conf is generated automatically and must not be edited. Use DNS2GNS there.

Warning

In GNUnet 0.29, the NSS plugin fails to resolve names: it parses the output of gnunet-gns -r, which now contains a progress indicator. Use DNS2GNS until this is fixed.

SOCKS proxy for browsers

gnunet-gns-proxy is a SOCKS5 proxy that resolves GNS names for a browser. Unlike DNS2GNS, it can use GNS records (LEHO, BOX/TLSA) to validate TLS certificates of sites hosted under GNS names, by acting as a local certificate authority. It is, however, still brittle: expect subtle failures with some sites, and switch it off again if a page behaves oddly.

First, create and install the proxy’s certificate authority. The script supports Firefox and Chromium, and needs the certutil (from NSS) and openssl programs:

$ gnunet-gns-proxy-setup-ca

Then start the proxy and check that it is running:

$ gnunet-arm -i gns-proxy
$ gnunet-arm -I | grep gns-proxy

The proxy listens on localhost, port 7777. Configure your browser to use it:

Chromium

Start the browser with chromium --proxy-server=socks5://localhost:7777. Type URLs including the http:// or https:// prefix; otherwise Chromium may run a web search instead.

Firefox

In Settings, Network Settings, choose Manual proxy configuration, enter localhost and port 7777 as SOCKS Host, select SOCKS v5, and enable Proxy DNS when using SOCKS v5. Then open about:config and set browser.fixup.alternate.enabled to false, so that Firefox does not rewrite a name like www.myzone into www.myzone.com.

Note that accessing ordinary websites through GNS is experimental and not the primary goal of GNS at this time. We welcome help with testing.