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 |
applications that resolve names through glibc |
not available on systems that generate |
|
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 thehttp://orhttps://prefix; otherwise Chromium may run a web search instead.- Firefox
In Settings, Network Settings, choose Manual proxy configuration, enter
localhostand port7777as SOCKS Host, select SOCKS v5, and enable Proxy DNS when using SOCKS v5. Then openabout:configand setbrowser.fixup.alternate.enabledtofalse, so that Firefox does not rewrite a name likewww.myzoneintowww.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.