gnunet-handbook

The GNUnet Handbook
Log | Files | Refs
commit 2a301368bacea13bc0e6abd905b5b0ea487790db
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date:   Sun, 31 Jul 2022 12:09:23 +0200

initial commit

Diffstat:

AMakefile | 20++++++++++++++++++++


Aconf.py | 73+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


Aconfiguration.md | 1+


Acontributors.md | 1+


Adeveloper.md | 1+


Aindex.md | 13+++++++++++++


Ainstalling.md | 167+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


Akeyconcepts.md | 90+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


Amake.bat | 35+++++++++++++++++++++++++++++++++++


Aphilosophy.md | 32++++++++++++++++++++++++++++++++


Apreface.md | 56++++++++++++++++++++++++++++++++++++++++++++++++++++++++


Auser.md | 359+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


12 files changed, 848 insertions(+), 0 deletions(-)

diff --git a/Makefile b/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/conf.py b/conf.py
@@ -0,0 +1,73 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'GNUnet Handbook'
+copyright = '2022, GNUnet Project'
+author = 'GNUnet Project'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+  'myst_parser',
+  'sphinx_rtd_theme'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+myst_enable_extensions = [
+    "amsmath",
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    "fieldlist",
+    "html_admonition",
+    "html_image",
+    "linkify",
+    "replacements",
+    "smartquotes",
+    "strikethrough",
+    "substitution",
+    "tasklist",
+]
+
+myst_heading_anchors = 3
+
diff --git a/configuration.md b/configuration.md
@@ -0,0 +1 @@
+# Configuration
diff --git a/contributors.md b/contributors.md
@@ -0,0 +1 @@
+# Contributing
diff --git a/developer.md b/developer.md
@@ -0,0 +1 @@
+# Development
diff --git a/index.md b/index.md
@@ -0,0 +1,13 @@
+Welcome to GNUnet Handbook's documentation!
+===========================================
+
+```{toctree}
+preface
+philosophy
+keyconcepts
+installing
+user
+configuration
+contributors
+developer
+```
diff --git a/installing.md b/installing.md
@@ -0,0 +1,167 @@
+# Installing
+
+This guide is intended for those who want to install GNUnet from source. For instructions on how to install GNUnet as a binary package please refer to the official documentation of your operating system or package manager.
+
+For understanding this guide properly it is important to know that there are two different ways of running GNUnet:
+
+  * the single-user setup
+  * the multi-user setup
+
+The latter variant has a better security model and requires extra preparation before running make install and a different configuration. Beginners who want to quickly try out GNUnet can use the single-user setup.
+
+## Dependencies
+
+GNUnet needs few libraries and applications for being able to run and another few optional ones for using certain features. Preferably they should be installed with a package manager.
+
+The mandatory libraries and applications are
+
+  * autoconf 2.59 or above (when building from git)
+  * automake 1.11.1 or above (when building from git)
+  * recutils 1.0 or above (when building from git)
+  * gettext
+  * glibc (read below, other libcs work)
+  * GnuTLS 3.2.12 or above, recommended to be linked against libunbound
+  * GNU make 4.0 or higher (other make implementations do work)
+  * iptables (on Linux systems)
+  * libtool 2.2 or above
+  * libltdl (part of libtool)
+  * libgcrypt 1.6 or above
+  * libidn2 or libidn
+  * libmicrohttpd 0.9.63 or above
+  * libunistring
+  * libjansson
+  * libjose (optional, for reclaimID)
+  * libgmp
+  * libgnurl or libcurl (libcurl has to be linked to GnuTLS) 7.35.0 or above
+  * Texinfo 5.2 or above (for building the documentation)
+  * Texlive 2012 or above (for building the documentation, and for gnunet-bcd)
+  * makeinfo 4.8 or above
+  * pkgconf (or pkg-config)
+  * zlib
+
+Glibc is required for certain NSS features:
+
+```
+One mechanism of integrating GNS with legacy applications via NSS is
+not available if this is disabled. But applications that don't use the
+glibc for NS resolution won't work anyway with this, so little is lost
+on *BSD systems.
+GNS via direct use or via the HTTP or DNS proxies is unaffected.
+```
+
+Other libcs should work, the resulting builds just don’t include the glibc NSS specific code. One example is the build against NetBSD’s libc as detailed in https://bugs.gnunet.org/view.php?id=5605.
+
+In addition GNUnet needs at least one of these three databases (at the minimum sqlite3)
+
+  * sqlite + libsqlite 3.8 or above (the default, requires no further configuration)
+  * postgres + libpq
+  * mysql + libmysqlclient
+
+These are the dependencies only required for certain features
+
+  * miniupnpc (for traversing NAT boxes more reliably)
+  * libnss
+  * libopus (for running the GNUnet conversation telephony application)
+  * libogg (for running the GNUnet conversation telephony application)
+  * gstreamer OR libpulse (for running the GNUnet conversation telephony application)
+  * bluez (for bluetooth support)
+  * libextractor (optional but highly recommended, read below)
+  * texi2mdoc (for automatic mdoc generation)
+  * perl5 for some utilities (which are not installed)
+
+About libextractor being optional:
+
+```
+While libextractor ("LE") is optional, it is recommended to build gnunet
+against it. If you install it later, you won't benefit from libextractor.
+If you are a distributor, we recommend to split LE into basis + plugins
+rather than making LE an option as an afterthought by the user.  LE
+itself is very small, but its dependency chain on first, second, third
+etc level can be big.  There is a small effect on privacy if your LE
+build differs from one which includes all plugins (plugins are build as
+shared objects): if users publish a directory with a mixture of file
+types (for example mpeg, jpeg, png, gif) the configuration of LE could
+leak which plugins are installed for which filetypes are not providing
+more details.  However, this leak is just a minor concern.
+```
+
+These are the test-suite requirements:
+
+  * python3.6 or higher
+  * gnunet (installation first)
+  * some core-utils: which(1), bc(1), curl(1), sed(1), awk(1), etc.
+  * a shell (very few Bash scripts, the majority are POSIX sh scripts)
+
+These are runtime requirements:
+
+  * nss (the certutil binary, for gnunet-gns-proxy-setup-ca)
+  * openssl (openssl binary, for gnunet-gns-proxy-setup-ca)
+
+## Getting the Source Code
+
+You can either download the source code using git (you obviously need git installed) or as an archive.
+
+Using git type
+
+```
+$ git clone https://git.gnunet.org/gnunet.git
+```
+
+The archive can be found at https://ftpmirror.gnu.org/gnu/gnunet/. Extract it using a graphical archive tool or tar:
+
+```
+tar xf gnunet-0.17.1-26-g233ec6111.tar.gz
+```
+
+In the next chapter we will assume that the source code is available in the home directory at ~/gnunet.
+
+## Create user and groups for the system services
+
+**For single-user setup this section can be skipped**
+
+The multi-user setup means that there are system services, which are run once per machine as a dedicated system user (called gnunet) and user services which can be started by every user who wants to use GNUnet applications. The user services communicate with the system services over unix domain sockets. To gain permissions to read and write those sockets the users running GNUnet applications will need to be in the gnunet group. In addition the group gnunetdns may be needed (see below).
+
+Create user gnunet who is member of the group gnunet (automatically created) and specify a home directory where the GNUnet services will store persistent data such as information about peers.
+
+```
+$ sudo useradd --system --home-dir /var/lib/gnunet --create-home gnunet
+```
+
+Now add your own user to the gnunet group:
+
+```
+$ sudo usermod -aG gnunet <user>
+```
+
+Create a group gnunetdns. This allows using setgid in a way that only the DNS service can run the gnunet-helper-dns binary. This is only needed if system-wide DNS interception will be used. For more information see [Configuring system-wide DNS interception](installing#configuring system-wide-dns-interception).
+
+```
+$ sudo groupadd gnunetdns
+```
+
+## Preparing and Compiling the Source Code
+
+For preparing the source code for compilation a bootstrap script and configure has to be run from the source code directory. When running configure, options can be specified to customize the compilation and installation process. For details execute:
+
+```
+$ ./configure --help
+```
+
+The following example configures the installation prefix /usr/local and disables building the documentation
+
+```
+$ cd ~/gnunet
+$ ./bootstrap
+$ ./configure --prefix=/usr/local --disable-documentation
+```
+
+After running the bootstrap script and configure successfully the source code can be compiled and the compiled binaries can be installed using:
+
+```
+$ make
+$ make install
+```
+
+The latter command may need to be run as root (or with sudo) because some
+binaries need the suid bit set.
+Without that some features (e.g. the VPN service, system-wide DNS interception, NAT traversal using ICMP) will not work.
diff --git a/keyconcepts.md b/keyconcepts.md
@@ -0,0 +1,90 @@
+# Key Concepts
+
+In this section, the fundamental concepts of GNUnet are explained. Most of them are also described in our research papers. First, some of the concepts used in the GNUnet framework are detailed. The second part describes concepts specific to anonymous file-sharing.
+
+## Authentication
+
+Almost all peer-to-peer communications in GNUnet are between mutually authenticated peers. The authentication works by using ECDHE, that is a DH (Diffie—Hellman) key exchange using ephemeral elliptic curve cryptography. The ephemeral ECC (Elliptic Curve Cryptography) keys are signed using ECDSA. The shared secret from ECDHE is used to create a pair of session keys (using HKDF) which are then used to encrypt the communication between the two peers using both 256-bit AES (Advanced Encryption Standard) and 256-bit Twofish (with independently derived secret keys). As only the two participating hosts know the shared secret, this authenticates each packet without requiring signatures each time. GNUnet uses SHA-512 (Secure Hash Algorithm) hash codes to verify the integrity of messages.
+
+In GNUnet, the identity of a host is its public key. For that reason, man-in-the-middle attacks will not break the authentication or accounting goals. Essentially, for GNUnet, the IP of the host has nothing to do with the identity of the host. As the public key is the only thing that truly matters, faking an IP, a port or any other property of the underlying transport protocol is irrelevant. In fact, GNUnet peers can use multiple IPs (IPv4 and IPv6) on multiple ports — or even not use the IP protocol at all (by running directly on layer 2).
+
+GNUnet uses a special type of message to communicate a binding between public (ECC) keys to their current network address. These messages are commonly called HELLOs or peer advertisements. They contain the public key of the peer and its current network addresses for various transport services. A transport service is a special kind of shared library that provides (possibly unreliable, out-of-order) message delivery between peers. For the UDP and TCP transport services, a network address is an IP and a port. GNUnet can also use other transports (HTTP, HTTPS, WLAN, etc.) which use various other forms of addresses. Note that any node can have many different active transport services at the same time, and each of these can have a different addresses. Binding messages expire after at most a week (the timeout can be shorter if the user configures the node appropriately). This expiration ensures that the network will eventually get rid of outdated advertisements.
+
+For more information, refer to the following paper:
+
+Ronaldo A. Ferreira, Christian Grothoff, and Paul Ruth. A Transport Layer Abstraction for Peer-to-Peer Networks Proceedings of the 3rd International Symposium on Cluster Computing and the Grid (GRID 2003), 2003. (https://git.gnunet.org/bibliography.git/plain/docs/transport.pdf)
+
+## Accounting to Encourage Resource Sharing
+
+Most distributed P2P networks suffer from a lack of defenses or precautions against attacks in the form of freeloading. While the intentions of an attacker and a freeloader are different, their effect on the network is the same; they both render it useless. Most simple attacks on networks such as Gnutella involve flooding the network with traffic, particularly with queries that are, in the worst case, multiplied by the network.
+
+In order to ensure that freeloaders or attackers have a minimal impact on the network, GNUnet’s file-sharing implementation (FS) tries to distinguish good (contributing) nodes from malicious (freeloading) nodes. In GNUnet, every file-sharing node keeps track of the behavior of every other node it has been in contact with. Many requests (depending on the application) are transmitted with a priority (or importance) level. That priority is used to establish how important the sender believes this request is. If a peer responds to an important request, the recipient will increase its trust in the responder: the responder contributed resources. If a peer is too busy to answer all requests, it needs to prioritize. For that, peers do not take the priorities of the requests received at face value. First, they check how much they trust the sender, and depending on that amount of trust they assign the request a (possibly lower) effective priority. Then, they drop the requests with the lowest effective priority to satisfy their resource constraints. This way, GNUnet’s economic model ensures that nodes that are not currently considered to have a surplus in contributions will not be served if the network load is high.
+
+For more information, refer to the following paper: Christian Grothoff. An Excess-Based Economic Model for Resource Allocation in Peer-to-Peer Networks. Wirtschaftsinformatik, June 2003. (https://git.gnunet.org/bibliography.git/plain/docs/ebe.pdf)
+
+## Confidentiality
+
+Adversaries (malicious, bad actors) outside of GNUnet are not supposed to know what kind of actions a peer is involved in. Only the specific neighbor of a peer that is the corresponding sender or recipient of a message may know its contents, and even then application protocols may place further restrictions on that knowledge. In order to ensure confidentiality, GNUnet uses link encryption, that is each message exchanged between two peers is encrypted using a pair of keys only known to these two peers. Encrypting traffic like this makes any kind of traffic analysis much harder. Naturally, for some applications, it may still be desirable if even neighbors cannot determine the concrete contents of a message. In GNUnet, this problem is addressed by the specific application-level protocols. See for example the following sections: [Anonymity](keyconcepts.md#anonymity), see [How file-sharing achieves Anonymity](keyconcepts.md#how-file-sharing-achieves-anonymity), and see [Deniability](keyconcepts.md#deniability).
+
+## Anonymity
+
+Providing anonymity for users is the central goal for the anonymous file-sharing application. Many other design decisions follow in the footsteps of this requirement. Anonymity is never absolute. While there are various scientific metrics (Claudia Díaz, Stefaan Seys, Joris Claessens, and Bart Preneel. Towards measuring anonymity. 2002. (https://git.gnunet.org/bibliography.git/plain/docs/article-89.pdf)) that can help quantify the level of anonymity that a given mechanism provides, there is no such thing as "complete anonymity".
+
+GNUnet’s file-sharing implementation allows users to select for each operation (publish, search, download) the desired level of anonymity. The metric used is based on the amount of cover traffic needed to hide the request.
+
+While there is no clear way to relate the amount of available cover traffic to traditional scientific metrics such as the anonymity set or information leakage, it is probably the best metric available to a peer with a purely local view of the world, in that it does not rely on unreliable external information or a particular adversary model.
+
+The default anonymity level is 1, which uses anonymous routing but imposes no minimal requirements on cover traffic. It is possible to forego anonymity when this is not required. The anonymity level of 0 allows GNUnet to use more efficient, non-anonymous routing.
+
+### How file-sharing achieves Anonymity
+
+Contrary to other designs, we do not believe that users achieve strong anonymity just because their requests are obfuscated by a couple of indirections. This is not sufficient if the adversary uses traffic analysis. The threat model used for anonymous file sharing in GNUnet assumes that the adversary is quite powerful. In particular, we assume that the adversary can see all the traffic on the Internet. And while we assume that the adversary can not break our encryption, we assume that the adversary has many participating nodes in the network and that it can thus see many of the node-to-node interactions since it controls some of the nodes.
+
+The system tries to achieve anonymity based on the idea that users can be anonymous if they can hide their actions in the traffic created by other users. Hiding actions in the traffic of other users requires participating in the traffic, bringing back the traditional technique of using indirection and source rewriting. Source rewriting is required to gain anonymity since otherwise an adversary could tell if a message originated from a host by looking at the source address. If all packets look like they originate from one node, the adversary can not tell which ones originate from that node and which ones were routed. Note that in this mindset, any node can decide to break the source-rewriting paradigm without violating the protocol, as this only reduces the amount of traffic that a node can hide its own traffic in.
+
+If we want to hide our actions in the traffic of other nodes, we must make our traffic indistinguishable from the traffic that we route for others. As our queries must have us as the receiver of the reply (otherwise they would be useless), we must put ourselves as the receiver of replies that actually go to other hosts; in other words, we must indirect replies. Unlike other systems, in anonymous file-sharing as implemented on top of GNUnet we do not have to indirect the replies if we don’t think we need more traffic to hide our own actions.
+
+This increases the efficiency of the network as we can indirect less under higher load. Refer to the following paper for more: Krista Bennett and Christian Grothoff. GAP — practical anonymous networking. In Proceedings of Designing Privacy Enhancing Technologies, 2003. (https://git.gnunet.org/bibliography.git/plain/docs/aff.pdf)
+
+### How messaging provided Anonymity
+
+While the file-sharing tries to achieve anonymity through hiding actions in other traffic, the messaging service provides a weaker form of protection against identification.
+
+The messaging service allows the use of an anonymous ego for the signing and verification process of messages instead of a unique ego. This anonymous ego is a publicly known key pair which is shared between all peers in GNUnet.
+
+Using this ego only ensures that individual messages alone can’t identify its sender inside of a messenger room. It should be clarified that the route of the traffic for each message can still be tracked to identify the senders peer inside of a messenger room if the threat agent controls certain peers hosting the room.
+
+Also opening a room in the messenger service will potentially match your peer identity with the internal member identity from the messenger service. So despite using the anonymous ego you can reveal your peer identity. This means to decrease the chance of being identified, it is recommended to enter rooms but you should not open them for others.
+
+## Deniability
+
+Even if the user that downloads data and the server that provides data are anonymous, the intermediaries may still be targets. In particular, if the intermediaries can find out which queries or which content they are processing, a strong adversary could try to force them to censor certain materials.
+
+With the file-encoding used by GNUnet’s anonymous file-sharing, this problem does not arise. The reason is that queries and replies are transmitted in an encrypted format such that intermediaries cannot tell what the query is for or what the content is about. Mind that this is not the same encryption as the link-encryption between the nodes. GNUnet has encryption on the network layer (link encryption, confidentiality, authentication) and again on the application layer (provided by gnunet-publish, gnunet-download, gnunet-search and gnunet-fs-gtk).
+
+Refer to the following paper for more: Christian Grothoff, Krista Grothoff, Tzvetan Horozov, and Jussi T. Lindgren. An Encoding for Censorship-Resistant Sharing. 2009. (https://git.gnunet.org/bibliography.git/plain/docs/ecrs.pdf)
+
+## Peer Identities
+
+Peer identities are used to identify peers in the network and are unique for each peer. The identity for a peer is simply its public key, which is generated along with a private key when the peer is started for the first time. While the identity is binary data, it is often expressed as an ASCII string. For example, the following is a peer identity as you might see it in various places:
+
+```
+UAT1S6PMPITLBKSJ2DGV341JI6KF7B66AC4JVCN9811NNEGQLUN0
+```
+
+You can find your peer identity by running `gnunet-peerinfo -s`.
+
+GNS zones are similar to those of DNS zones, but instead of a hierarchy of authorities to governing their use, GNS zones are controlled by a private key. When you create a record in a DNS zone, that information is stored in your nameserver. Anyone trying to resolve your domain then gets pointed (hopefully) by the centralised authority to your nameserver. Whereas GNS, being fully decentralized by design, stores that information in DHT. The validity of the records is assured cryptographically, by signing them with the private key of the respective zone.
+
+Anyone trying to resolve records in a zone of your domain can then verify the signature of the records they get from the DHT and be assured that they are indeed from the respective zone. To make this work, there is a 1:1 correspondence between zones and their public-private key pairs. So when we talk about the owner of a GNS zone, that’s really the owner of the private key. And a user accessing a zone needs to somehow specify the corresponding public key first.
+
+For more information, refer to the following paper:
+
+## Zones in the GNU Name System (GNS Zones)
+
+Matthias Wachs, Martin Schanzenbach, and Christian Grothoff. A Censorship-Resistant, Privacy-Enhancing and Fully Decentralized Name System. In proceedings of 13th International Conference on Cryptology and Network Security (CANS 2014). 2014. https://git.gnunet.org/bibliography.git/plain/docs/gns2014wachs.pdf
+
+
+## Egos
+
+Egos are your "identities" in GNUnet. Any user can assume multiple identities, for example to separate their activities online. Egos can correspond to "pseudonyms" or "real-world identities". Technically an ego is first of all a key pair of a public- and private-key.
diff --git a/make.bat b/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/philosophy.md b/philosophy.md
@@ -0,0 +1,32 @@
+# Philosophy
+
+The primary goal of the GNUnet project is to provide a reliable, open, non-discriminating and censorship-resistant system for information exchange. We value free speech above state interests and intellectual monopoly. GNUnet’s long-term goal is to serve as a development platform for the next generation of Internet protocols.
+
+Participants are encouraged to contribute at least as much resources (storage, bandwidth) to the network as they consume, so that their participation does not have a negative impact on other users.
+
+## Design Principles
+
+These are the GNUnet design principles, in order of importance:
+
+  * GNUnet must be implemented as Free Software — This means that you have the four essential freedoms: to run the program, to study and change the program in source code form, to redistribute exact copies, and to distribute modified versions. (https://www.gnu.org/philosophy/free-sw.html).
+  * GNUnet must minimize the amount of personally identifiable information exposed.
+  * GNUnet must be fully distributed and resilient to external attacks and rogue participants.
+  * GNUnet must be self-organizing and not depend on administrators or centralized infrastructure.
+  * GNUnet must inform the user which other participants have to be trusted when establishing private communications.
+  * GNUnet must be open and permit new peers to join.
+  * GNUnet must support a diverse range of applications and devices.
+  * GNUnet must use compartmentalization to protect sensitive information.
+  * The GNUnet architecture must be resource efficient.
+  * GNUnet must provide incentives for peers to contribute more resources than they consume.
+
+## Privacy and Anonymity
+
+The GNUnet protocols minimize the leakage of personally identifiable information of participants and do not allow adversaries to control, track, monitor or censor users activities. The GNUnet protocols also make it as hard as possible to disrupt operations by participating in the network with malicious intent.
+
+Analyzing participant’s activities becomes more difficult as the number of peers and applications that generate traffic on the network grows, even if the additional traffic generated is not related to anonymous communication. This is one of the reasons why GNUnet is developed as a peer-to-peer framework where many applications share the lower layers of an increasingly complex protocol stack. The GNUnet architecture encourages many different forms of peer-to-peer applications.
+
+## Practicality
+
+Wherever possible GNUnet allows the peer to adjust its operations and functionalities to specific use cases. A GNUnet peer running on a mobile device with limited battery for example might choose not to relay traffic for other participants.
+
+For certain applications like file-sharing GNUnet allows participants to trade degrees of anonymity in exchange for increased efficiency. However, it is not possible for any user’s efficiency requirements to compromise the anonymity of any other user.
diff --git a/preface.md b/preface.md
@@ -0,0 +1,56 @@
+# Preface
+
+This collection of manuals describes GNUnet, a framework for secure peer-to-peer networking with the high-level goal to provide a strong foundation for a global, distributed network that provides security and privacy. GNUnet in that sense aims to replace the current Internet protocol stack. Along with an application for secure publication of files, it has grown to include all kinds of basic applications for the foundation of a new Internet.
+
+## About this book
+
+The books (described as "book" or "books" in the following) bundled as the "GNUnet Reference Manual" are based on the historic work of all contributors to previous documentation of GNUnet. It is our hope that the content is described in a way that does not require any academic background, although some concepts will require further reading.
+
+Our (long-term) goal with these books is to keep them self-contained. If you see references to Wikipedia and other external sources (except for our academic papers) it means that we are working on a solution to describe the explanations found there which fits our use-case and licensing.
+
+Previously the documentation was contained in Drupal books, on the old website. This format was considered unmaintainable for the future, so Texinfo was chosen. You might find old and very old sections in here in addition to more recent content. It took a long time to finish the move to Texinfo (from Drupal to LaTeX to wrong Texinfo output dump to good Texinfo) and only recently (late 2018, early 2019) content checking started. We apologize to the reader for any inconvenience and hope you apply logic where bad advice from 10 years ago can be found (pipe to sudo to install software is one example). Patches (contributions) to this documentation are more than welcome!
+
+The first chapter ("Preface") as well as the second chapter ("Philosophy") give an introduction to GNUnet as a project, what GNUnet tries to achieve. "Key Concepts" explains the key concepts in GNUnet. These three chapters are the most complete in the documentation. They are followed by chapters which explain specific parts of GNUnet (and need more work): "Installing GNUnet", "GNUnet Contributors Handbook" and "GNUnet Developer Handbook".
+
+## Contributing to this book
+
+The GNUnet Reference Manual is a collective work produced by various people throughout the years.
+
+The version you are reading is derived from many individual efforts hosted on one of our old websites. In the end it was considered to be impractical to read by those who required the information. With the conversion to Texinfo — the version you are reading right now — we hope to address this in the longterm. Texinfo is the documentation language of the GNU project.
+
+While it can be intimidating at first and look scary or complicated, it is just another way to express text format instructions.
+
+We encourage you to take this opportunity and learn about Sphinx, learn about GNUnet, and one word at a time we will arrive at a book which explains GNUnet in the least complicated way to you.
+
+Even when you don’t want to or can’t learn Sphinx, you can contribute. Send us an Email or join our IRC chat room on freenode and talk with us about the documentation (the preferred way to reach out is the mailinglist, since you can communicate with us without waiting on someone in the chatroom). One way or another you can help shape the understanding of GNUnet without the ability to read and understand its sourcecode.
+
+## Introduction
+
+GNUnet in its current version is the result of almost 20 years of work from many contributors. So far, most contributions were made by volunteers or people paid to do fundamental research. At this stage, GNUnet remains an experimental system where significant parts of the software lack a reasonable degree of professionalism in its implementation. Furthermore, we are aware of a significant number of existing bugs and critical design flaws, as some unfortunate early design decisions remain to be rectified. There are still known open problems; GNUnet remains an active research project.
+
+The project was started in 2001 when some initial ideas for improving Freenet’s file-sharing turned out to be too radical to be easily realized within the scope of the existing Freenet project. We lost our first contributor on 11.9.2001 as the contributor realized that privacy may help terrorists. The rest of the team concluded that it was now even more important to fight for civil liberties. The first release was called "GNet" – already with the name GNUnet in mind, but without the blessing of GNU we did not dare to call it GNUnet immediately. A few months after the first release we contacted the GNU project, happily agreed to their governance model and became an official GNU package.
+
+Within the first year, we created GNU libextractor, a helper library for meta data extraction which has been used by a few other projects as well. 2003 saw the emergence of pluggable transports, the ability for GNUnet to use different mechanisms for communication, starting with TCP, UDP and SMTP (support for the latter was later dropped due to a lack of maintenance). In 2005, the project first started to evolve beyond the original file-sharing application with a first simple P2P chat. In 2007, we created GNU libmicrohttpd to support a pluggable transport based on HTTP. In 2009, the architecture was radically modularized into the multi-process system that exists today. Coincidentally, the first version of the ARM service (ARM: Automatic Restart Manager) was implemented a day before systemd was announced. From 2009 to 2014 work progressed rapidly thanks to a significant research grant from the Deutsche Forschungsgesellschaft. This resulted in particular in the creation of the R5N DHT, CADET, ATS and the GNU Name System. In 2010, GNUnet was selected as the basis for the secushare online social network, resulting in a significant growth of the core team. In 2013, we launched GNU Taler to address the challenge of convenient and privacy-preserving online payments. In 2015, the pretty Easy privacy (pEp) project announced that they will use GNUnet as the technology for their meta-data protection layer, ultimately resulting in GNUnet e.V. entering into a formal long-term collaboration with the pEp Foundation. In 2016, Taler Systems SA, a first startup using GNUnet technology, was founded with support from the community.
+
+GNUnet is not merely a technical project, but also a political mission: like the GNU project as a whole, we are writing software to achieve political goals with a focus on the human right of informational self-determination. Putting users in control of their computing has been the core driver of the GNU project. With GNUnet we are focusing on informational self-determination for collaborative computing and communication over networks.
+
+The Internet is shaped as much by code and protocols as it is by its associated political processes (IETF, ICANN, IEEE, etc.). Similarly its flaws are not limited to the protocol design. Thus, technical excellence by itself will not suffice to create a better network. We also need to build a community that is wise, humble and has a sense of humor to achieve our goal to create a technical foundation for a society we would like to live in.
+
+
+## Project governance
+
+GNUnet, like the GNU project and many other free software projects, follows the governance model of a benevolent dictator. This means that ultimately, the GNU project appoints the GNU maintainer and can overrule decisions made by the GNUnet maintainer. Similarly, the GNUnet maintainer can overrule any decisions made by individual developers. Still, in practice neither has happened in the last 20 years for GNUnet, and we hope to keep it that way.
+
+The current maintainers of GNUnet are:
+
+  * [Christian Grothoff](https://grothoff.org/christian/)
+  * [Martin Schanzenbach](https://schanzen.eu/)
+
+
+The GNUnet project is supported by GNUnet e.V., a German association where any developer can become a member. GNUnet e.V. serves as a legal entity to hold the copyrights to GNUnet. GNUnet e.V. may also choose to pay for project resources, and can collect donations as well as choose to adjust the license of the software (with the constraint that it has to remain free software). In 2018 we switched from GPL3 to AGPL3, in practice these changes do not happen very often.
+
+
+
+## Typography
+
+When giving examples for commands, shell prompts are used to show if the command should/can be issued as root, or if "normal" user privileges are sufficient. We use a # for root’s shell prompt, a % for users’ shell prompt, assuming they use the C-shell or tcsh and a $ for bourne shell and derivatives.
diff --git a/user.md b/user.md
@@ -0,0 +1,359 @@
+# Using GNUnet
+
+This tutorial is supposed to give a first introduction for users trying to do something real with GNUnet. Installation and configuration are specifically outside of the scope of this tutorial. Instead, we start by briefly checking that the installation works, and then dive into uncomplicated, concrete practical things that can be done with the framework provided by GNUnet.
+
+In short, this chapter of the "GNUnet Reference Documentation" will show you how to use the various peer-to-peer applications of the GNUnet system. As GNUnet evolves, we will add new sections for the various applications that are being created.
+
+Comments on the content of this chapter, and extensions of it are always welcome.
+
+## Starting and stopping
+
+Prior to using any GNUnet-based application, one has to start a node:
+
+```
+$ gnunet-arm -s
+```
+
+To stop GNUnet:
+
+```
+$ gnunet-arm -e
+```
+
+You can usually find the logs under `~/.cache/gnunet` and all files such as databases and private keys in `~/.local/share/gnunet`.
+
+## The GNU Name System
+
+The GNU Name System (GNS) is secure and decentralized naming system. It allows its users to register names as top-level domains (TLDs) and resolve other namespaces within their TLDs.
+
+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 their 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 to one user might be www.friend for someone else.
+
+### Start Zones
+
+In the default configuration, there are two zones defined and shipped with GNUnet:
+
+The first is "gnunet.org", which points to the authoritate zone of the GNUnet project. It can be used to resolve, for example, "www.gnunet.org".
+
+".pin" is another default zone which points to a special zone also managed by gnunet.org. Users may register submodomains on a first-come first-served-basis at https://fcfs.gnunet.org.
+
+Use gnunet-config -s gns to view the GNS configuration, including all configured zones that are operated by other users. The respective configuration entry names start with a ".", e.g. ".pin".
+
+You can configure any number of top-level domains, and point them to the respective zones of your friends! For this, simply obtain the respective public key (you will learn how below) and extend the configuration:
+
+```
+$ gnunet-config -s gns -o .myfriend -V PUBLIC_KEY
+```
+
+### Zones and Egos
+
+In GNUnet, identity management is about managing egos. Egos can correspond to pseudonyms or real-world identities. If you value your privacy, you are encouraged to use separate egos for separate activities.
+
+Technically, an ego is first of all a public-private key pair, and thus egos also always correspond to a GNS zone. Egos are managed by the IDENTITY service. Note that this service has nothing to do with the peer identity. The IDENTITY service essentially stores the private keys under human-readable names, and keeps a mapping of which private key should be used for particular important system functions.
+
+You probably should create at least one zone of your own. You can create any number of zones using the gnunet-identity tool using:
+
+```
+$ gnunet-identity --create="myzone"
+```
+
+Henceforth, on your system you control the TLD "myzone".
+
+All of your zones can be listed (displayed) using the gnunet-identity command line tool as well:
+
+```
+$ gnunet-identity --display
+```
+
+### Maintaining Zones
+
+Now you can add (or edit, or remove) records in your GNS zone using the gnunet-namestore-gtk 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 multiple 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 short example for editing your own zone, suppose you have your own web server with the 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 "myzone" using the command:
+
+```
+$ gnunet-namestore -z myzone -a -n www -t A -V 1.2.3.4 -e 1d
+```
+
+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-namestore-gtk GUI to be easier.
+
+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.
+
+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 their local zone:
+
+```
+$ gnunet-namestore -a -n bob --type PKEY -V XXXX -e 1d -z myzone
+```
+
+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 their website under the name of "www" in his zone, you can then access Bob’s website under "www.bob.myzone" — as well as any (public) GNS record that Bob has in their zone by replacing www with the respective name of the record in Bob’s zone.
+
+Furthermore, if Bob has themselves a (public) delegation to Carol’s zone under "carol", you can access Carol’s records under "NAME.carol.bob.myzone" (where "NAME" is the name of Carol’s record you want to access).
+
+
+
+### Resolving GNS records
+
+Next, you should try resolving your own GNS records. The method we found to be the most uncomplicated is to do this by explicitly resolving using gnunet-gns. For this exercise, we will assume that you used the string "gnu" for the pseudonym (or label) of your GNS zone. If you used something else, replace ".gnu" with your real pseudonym in the examples below.
+
+In the shell, type:
+
+```
+$ gnunet-gns -u www.gnunet.org
+www.gnunet.org:
+Got `A' record: ...
+```
+
+That shows that resolution works, once GNS is integrated with the application.
+
+### Integration with Browsers (DNS2GNS service)
+
+Most OSes allow you to either modify your `/etc/resolv.conf` directly or through `resolvectl`. We are going to configure the dns2gns service in order to translate DNS name queries by applications to GNS name queries where applicable and else fall back to DNS.
+
+Optionally, you may want to configure your dns2gns service to run on a non-priviledged port like 5353. But, in case you are going to edit `/etc/resolv.conf` directly, the dns2gns service MUST run on port 53 as you cannot specify the port number. A `$FALLBACK_DNS` variable should be a DNS server you trust such as your local router:
+
+```
+$ gnunet-config -s dns2gns -o OPTIONS -V "-d $FALLBACK_DNS -p 5252"
+$ gnunet-arm -i dns2gns # Make sure the service is started
+```
+
+If you edit your resolv.conf directly, it should contain and entry like this:
+
+```
+nameserver 127.0.0.1
+```
+
+In any case, it is very likely that the method of modification of your resolver is OS specific. Recently, the combination of NetworkManager and systemd-resolved is becoming increasingly popular.
+
+If you use resolvectl and systemd-resolved you can temporarily set the nameserver like this:
+
+```
+$ resolvectl $INTERFACE 127.0.0.1:5353
+```
+
+Where `$INTERFACE` is your network interface such as `eth0`.
+
+In order to automatically set the DNS2GNS server if it is running already you can use NetworkManager-dispatcher. First, enable it:
+
+```
+$ sudo systemctl enable NetworkManager-dispatcher.service
+$ sudo systemctl start NetworkManager-dispatcher.service
+```
+
+Then, create a script `/etc/NetworkManager/dispatch.h/10-dns2-gns.sh`:
+
+```
+#!/bin/sh
+interface=$1
+status=$2
+
+if [ "$interface" = "eth0" ]; then
+  case $status in
+    up)
+      if nc -u -z 127.0.0.1 5353; then
+      resolvectl dns $interface 127.0.0.1:5353
+    fi
+    ;;
+    down)
+    ;;
+  esac
+fi
+```
+
+Make sure the script is owned by root and executable:
+
+```
+$ sudo root:root /etc/NetworkManager/dispatch.d/10-dns2gns.sh
+$ sudo +x /etc/NetworkManager/dispatch.d/10-dns2gns.sh
+```
+
+You can test accessing this website using your browser or curl:
+
+```
+$ curl www.gnunet.org
+```
+
+Note that "gnunet.org" is a domain that also exists in DNS and for which the GNUnet project webservers can provide trusted TLS certificates. When using non-DNS names with GNS or aliases, this may result in issues when accessing HTTPS websites with browsers. In order learn how to provide relief for this issue, read on.
+
+### Integration with Browsers (SOCKS proxy)
+
+While we recommend integrating GNS using the DNS2GNS service or the NSSwitch plugin, you can also integrate GNS directly with your browser via the gnunet-gns-proxy. This method can have the advantage that the proxy can validate TLS/X.509 records and thus strengthen web security; however, the proxy is still a bit brittle, so expect subtle failures. We have had reasonable success with Chromium, and various frustrations with Firefox in this area recently.
+
+The first step is to start the proxy. As the proxy is (usually) not started by default, this is done as a unprivileged user using gnunet-arm -i gns-proxy. Use gnunet-arm -I as a unprivileged user to check that the proxy was actually started. (The most common error for why the proxy may fail to start is that you did not run gnunet-gns-proxy-setup-ca during installation.) The proxy is a SOCKS5 proxy running (by default) on port 7777. Thus, you need to now configure your browser to use this proxy. With Chromium, you can do this by starting the browser as a unprivileged user using chromium --proxy-server="socks5://localhost:7777" For Firefox (or Icecat), select "Edit-Preferences" in the menu, and then select the "Advanced" tab in the dialog and then "Network":
+
+Here, select "Settings..." to open the proxy settings dialog. Select "Manual proxy configuration" and enter localhost with port 7777 under SOCKS Host. Furthermore, set the checkbox "Proxy DNS when using SOCKS v5" at the bottom of the dialog. Finally, push "OK".
+
+You must also go to about:config and change the browser.fixup.alternate.enabled option to false, otherwise the browser will autoblunder an address like www.gnu to www.gnu.com. If you want to resolve @ in your own TLDs, you must additionally set browser.fixup.dns_first_use_for_single_words to true.
+
+After configuring your browser, you might want to first confirm that it continues to work as before. (The proxy is still experimental and if you experience "odd" failures with some webpages, you might want to disable it again temporarily.) Next, test if things work by typing "http://test.gnu/" into the URL bar of your browser. This currently fails with (my version of) Firefox as Firefox is super-smart and tries to resolve "http://www.test.gnu/" instead of "test.gnu". Chromium can be convinced to comply if you explicitly include the "http://" prefix — otherwise a Google search might be attempted, which is not what you want. If successful, you should see a simple website.
+
+Note that while you can use GNS to access ordinary websites, this is more an experimental feature and not really our primary goal at this time. Still, it is a possible use-case and we welcome help with testing and development.
+
+### Creating a Business Card
+
+Before we can really use GNS, you should create a business card. Note that this requires having LaTeX installed on your system. If you are using a Debian GNU/Linux based operating system, the following command should install the required components. Keep in mind that this requires 3GB of downloaded data and possibly even more when unpacked. On a GNU Guix based system texlive 2017 has returns a DAG size of 5032.4 MiB. The packages which are confirmed to be required are:
+
+  * texlive-units
+  * texlive-labels
+  * texlive-pst-barcode
+  * texlive-luatex85
+  * texlive-preview
+  * texlive-pdfcrop
+  * texlive-koma-script
+
+**We welcome any help in identifying the required components of the TexLive Distribution. This way we could just state the required components without pulling in the full distribution of TexLive.**
+
+```
+apt-get install texlive-full
+```
+
+Start creating a business card by clicking the "Copy" button in gnunet-namestore-gtk. Next, you should start the gnunet-bcd program (in the terminal, on the command-line). You do not need to pass any options, and please be not surprised if there is no output:
+
+```
+$ gnunet-bcd # does not return
+```
+
+Then, start a browser and point it to http://localhost:8888/ where gnunet-bcd is running a Web server!
+
+First, you might want to fill in the "GNS Public Key" field by right-clicking and selecting "Paste", filling in the public key from the copy you made in gnunet-namestore-gtk. Then, fill in all of the other fields, including your GNS NICKname. Adding a GPG fingerprint is optional. Once finished, click "Submit Query". If your LaTeX installation is incomplete, the result will be disappointing. Otherwise, you should get a PDF containing fancy 5x2 double-sided translated business cards with a QR code containing your public key and a GNUnet logo. We’ll explain how to use those a bit later. You can now go back to the shell running gnunet-bcd and press CTRL-C to shut down the Web server.
+
+### Be Social
+
+Next, you should print out your business card and be social. Find a friend, help them install GNUnet and exchange business cards with them. Or, if you’re a desperate loner, you might try the next step with your own card. Still, it’ll be hard to have a conversation with yourself later, so it would be better if you could find a friend. You might also want a camera attached to your computer, so you might need a trip to the store together.
+
+Before we get started, we need to tell gnunet-qr which zone it should import new records into. For this, run:
+
+```
+$ gnunet-identity -s namestore -e NAME
+```
+
+where NAME is the name of the zone you want to import records into. In our running example, this would be "gnu".
+
+Henceforth, for every business card you collect, simply run:
+
+```
+$ gnunet-qr
+```
+
+to open a window showing whatever your camera points at. Hold up your friend’s business card and tilt it until the QR code is recognized. At that point, the window should automatically close. At that point, your friend’s NICKname and their public key should have been automatically imported into your zone.
+
+Assuming both of your peers are properly integrated in the GNUnet network at this time, you should thus be able to resolve your friends names. Suppose your friend’s nickname is "Bob". Then, type
+
+```
+$ gnunet-gns -u test.bob
+```
+
+to check if your friend was as good at following instructions as you were.
+
+### Backup of Identities and Egos
+
+One should always backup their files, especially in these SSD days (our team has suffered 3 SSD crashes over a span of 2 weeks). Backing up peer identity and zones is achieved by copying the following files:
+
+The peer identity file can be found in `~/.local/share/gnunet/private_key.ecc`.
+
+The private keys of your egos are stored in the directory `~/.local/share/gnunet/identity/egos/`. They are stored in files whose filenames correspond to the zones’ ego names. These are probably the most important files you want to backup from a GNUnet installation.
+
+Note: All these files contain cryptographic keys and they are stored without any encryption. So it is advisable to backup encrypted copies of them.
+
+### Revocation
+
+Now, in the situation of an attacker gaining access to the private key of one of your egos, the attacker can create records in the respective GNS zone and publish them as if you published them. Anyone resolving your domain will get these new records and when they verify they seem authentic because the attacker has signed them with your key.
+
+To address this potential security issue, you can pre-compute a revocation certificate corresponding to your ego. This certificate, when published on the P2P network, flags your private key as invalid, and all further resolutions or other checks involving the key will fail.
+
+A revocation certificate is thus a useful tool when things go out of control, but at the same time it should be stored securely. Generation of the revocation certificate for a zone can be done through gnunet-revocation. For example, the following command (as unprivileged user) generates a revocation file revocation.dat for the zone zone1: gnunet-revocation -f revocation.dat -R zone1
+
+The above command only pre-computes a revocation certificate. It does not revoke the given zone. Pre-computing a revocation certificate involves computing a proof-of-work and hence may take up to 4 to 5 days on a modern processor. Note that you can abort and resume the calculation at any time. Also, even if you did not finish the calculation, the resulting file will contain the signature, which is sufficient to complete the revocation process even without access to the private key. So instead of waiting for a few days, you can just abort with CTRL-C, backup the revocation certificate and run the calculation only if your key actually was compromised. This has the disadvantage of revocation taking longer after the incident, but the advantage of saving a significant amount of energy. So unless you believe that a key compromise will need a rapid response, we urge you to wait with generating the revocation certificate. Also, the calculation is deliberately expensive, to deter people from doing this just for fun (as the actual revocation operation is expensive for the network, not for the peer performing the revocation).
+
+To avoid TL;DR ones from accidentally revocating their zones, we are not giving away the command, but it is uncomplicated: the actual revocation is performed by using the -p option of gnunet-revocation.
+
+### What's next?
+
+This may seem not like much of an application yet, but you have just been one of the first to perform a decentralized secure name lookup (where nobody could have altered the value supplied by your friend) in a privacy-preserving manner (your query on the network and the corresponding response were always encrypted). So what can you really do with this? Well, to start with, you can publish your GnuPG fingerprint in GNS as a "CERT" record and replace the public web-of-trust with its complicated trust model with explicit names and privacy-preserving resolution. Also, you should read the next chapter of the tutorial and learn how to use GNS to have a private conversation with your friend. Finally, help us with the next GNUnet release for even more applications using this new public key infrastructure.
+
+### Resource Records
+
+GNS supports the majority of the DNS records as defined in [RFC 1035](http://www.ietf.org/rfc/rfc1035.txt). Additionally, GNS defines some new record types the are unique to the GNS system. For example, GNS-specific resource records are used 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 GNS name.
+
+The GNS currently supports the record types as defined in [GANA](https://git.gnunet.org/gana.git/tree/gnu-name-system-record-types/registry.rec). In addition, GNS supports DNS record types, such as A, AAAA or TXT.
+
+For a complete description of the records, please refer to the specification at [LSD0001](https://lsd.gnunet.org/lsd0001).
+
+In the following, we discuss GNS records with specific behaviour or special handling in GNUnet.
+
+#### 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
+```
+
+### Synchronizing with legacy DNS
+
+If you want to support GNS but the master database for a zone is only available and maintained in DNS, GNUnet includes the gnunet-zoneimport tool to monitor a DNS zone and automatically import records into GNS. Today, the tool does not yet support DNS AF(X)R, as we initially used it on the ".fr" zone which does not allow us to perform a DNS zone transfer. Instead, gnunet-zoneimport reads a list of DNS domain names from stdin, issues DNS queries for each, converts the obtained records (if possible) and stores the result in the namestore.
+
+The zonemaster service then takes the records from the namestore, publishes them into the DHT which makes the result available to the GNS resolver. In the GNS configuration, non-local zones can be configured to be intercepted by specifying ".tld = PUBLICKEY" in the configuration file in the "[gns]" section.
+
+Note that the namestore by default also populates the namecache. This pre-population is cryptographically expensive. Thus, on systems that only serve to import a large (millions of records) DNS zone and that do not have a local gns service in use, it is thus advisable to disable the namecache by setting the option "DISABLE" to "YES" in section "[namecache]".
+
+### Migrating an existing DNS zone into GNS
+
+Ascension is a tool to migrate existing DNS zones into GNS.
+
+Compared to the gnunet-zoneimport tool it strictly uses AXFR or IXFR depending on whether or not there exists a SOA record for the zone. If that is the case it will take the serial as a reference point and request the zone. The server will either answer the IXFR request with a correct incremental zone or with the entire zone, which depends on the server configuration.
+
+Before you can migrate any zone though, you need to start a local GNUnet peer.
+To migrate the Syrian top level domain - one of the few top level domains that support zone transfers - into GNS use the following command:
+
+
+```
+$ ascension sy. -n ns1.tld.sy. -p
+```
+
+The -p flag will tell GNS to put these records on the DHT so that other users may resolve these records by using the public key of the zone.
+
+Once the zone is migrated, Ascension will output a message telling you, that it will refresh the zone after the time has elapsed. You can resolve the names in the zone directly using GNS or if you want to use it with your browser, check out the GNS manual section. Configuring the GNU Name System. To resolve the records from another system you need the respective zones PKEY. To get the zones public key, you can run the following command:
+
+```
+$ gnunet-identity -dqe sy
+```
+
+Where "sy" is the name of the zone you want to migrate.
+
+You can share the PKEY of the zone with your friends. They can then resolve records in the zone by doing a lookup replacing the zone label with your PKEY:
+
+
+```
+$ gnunet-gns -t SOA -u "$PKEY"
+```
+
+The program will continue to run as a daemon and update once the refresh time specified in the zones SOA record has elapsed.
+
+DNSCurve style records are supported in the latest release and they are added as a PKEY record to be referred to the respective GNS public key. Key distribution is still a problem but provided someone else has a public key under a given label it can be looked up.
+
+There is an unofficial Debian package called python3-ascension that adds a system user ascension and runs a GNUnet peer in the background.
+
+Ascension-bind is also an unofficial Debian package that on installation checks for running DNS zones and whether or not they are transferable using DNS zone transfer (AXFR). It asks the administrator which zones to migrate into GNS and installs a systemd unit file to keep the zone up to date. If you want to migrate different zones you might want to check the unit file from the package as a guide.
+
+## re:claimID