1 files changed, 2603 insertions, 0 deletions

diff --git a/doc/old/handbook/chapters/user.texi b/doc/old/handbook/chapters/user.texi
new file mode 100644
index 000000000..714336228
--- /dev/null
+++ b/doc/old/handbook/chapters/user.texi
@@ -0,0 +1,2603 @@
+@node Using GNUnet
+@chapter 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.
+
+
+@menu
+* Start and stop GNUnet::
+* First steps - Using the GNU Name System::
+* First steps - Using GNUnet Conversation::
+* First steps - Using the GNUnet VPN::
+* File-sharing::
+* The GNU Name System::
+* reclaimID Identity Provider::
+* Using the Virtual Public Network::
+* Using the GNUnet Messenger::
+@end menu
+
+@node Start and stop GNUnet
+@section Start and stop GNUnet
+
+Prior to using any GNUnet-based application, one has to start a node:
+
+@example
+$ gnunet-arm -s -l gnunet.log
+@end example
+
+To stop GNUnet:
+
+@example
+$ gnunet-arm -e
+@end example
+
+@node First steps - Using the GNU Name System
+@section First steps - Using the GNU Name System
+
+
+@menu
+* Preliminaries::
+* Managing Egos::
+* The GNS Tab::
+* Creating a Record::
+* Resolving GNS records::
+* Integration with Browsers (DNS2GNS service)::
+* Integration with Browsers (SOCKS proxy)::
+* Creating a Business Card::
+* Be Social::
+* Backup of Identities and Egos::
+* Revocation::
+* What's Next?::
+@end menu
+
+@node Preliminaries
+@subsection Preliminaries
+
+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 @url{https://fcfs.gnunet.org}.
+
+Use @code{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:
+
+@example
+$ gnunet-config -s gns -o .myfriend -V PUBLIC_KEY
+@end example
+
+@node Managing Egos
+@subsection Managing 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.
+The existing identities can be listed using the command
+@command{gnunet-identity --display}
+
+@example
+gnu - JTDVJC69NHU6GQS4B5721MV8VM7J6G2DVRGJV0ONIT6QH7OI6D50
+rules - GO0T87F9BPMF8NKD5A54L2AH1T0GRML539TPFSRMCEA98182QD30
+@end example
+
+
+@node The GNS Tab
+@subsection The GNS Tab
+
+
+Maintaining your zones is through the NAMESTORE service and is discussed
+here.  You can manage your zone using @command{gnunet-identity} and
+@command{gnunet-namestore}, or most conveniently using
+@command{gnunet-namestore-gtk}.
+
+We will use the GTK+ interface in this introduction.  Please start
+@command{gnunet-gkt} and switch to the GNS tab, which is the tab in
+the middle with the letters "GNS" connected by a graph.
+
+Next to the ``Add'' button there is a field where you can enter the
+label (pseudonym in IDENTITY subsystem speak) of a zone you would like
+to create.  Pushing the ``Add'' button will create the zone.
+Afterwards, you can change the label in the combo box below at any
+time.  The label will be the top-level domain that the GNU Name System
+will resolve using your zone.  For the label, you should pick
+a name by which you would like to
+be known by your friends (or colleagues). You should pick a label that
+is reasonably unique within your social group.  Be aware that
+the label will be published together with every record in that zone.
+
+Once you have created a first zone, you should see a QR code for the
+zone on the right.  Next to it is a "Copy" button to copy the public
+key string to the clipboard. You can also save the QR code image to
+disk.
+
+Furthermore, you now can see the bottom part of the dialog.  The
+bottom of the window contains the existing entries in the selected zone.
+
+@node Creating a Record
+@subsection Creating a Record
+
+
+We will begin by creating a simple record in your master zone.
+To do this, click on the text "<new name>" in the table. The field is
+editable, allowing you to enter a fresh label. Labels are restricted
+to 63 characters and must not contain dots. For now, simply enter
+"test", then press ENTER to confirm. This will create a new (empty)
+record group under the label "test". Now click on "<new record>" next
+to the new label "test". In the drop-down menu, select "A" and push
+ENTER to confirm. Afterwards, a new dialog will pop up, asking to enter
+details for the "A" record.
+
+"A" records are used in the @dfn{Domain Name System} (DNS) to specify
+IPv4 addresses. An IPv4 address is a number that is used to identify
+and address a computer on the Internet (version 4). Please enter
+"217.92.15.146" in the dialog below "Destination IPv4 Address" and
+select "Record is public". Do not change any of the other options.
+Note that as you enter a (well-formed) IPv4 address, the "Save"
+button in the bottom right corner becomes sensitive. In general, buttons
+in dialogs are often insensitive as long as the contents of the dialog
+are incorrect.
+
+Once finished, press the "Save" button. Back in the main dialog, select
+the tiny triangle left of the "test" label. By doing so, you get to see
+all of the records under "test". Note that you can right-click a record
+to edit it later.
+
+
+@node Resolving GNS records
+@subsection 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 @code{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:
+
+@example
+$ gnunet-gns -u test.gnu # what follows is the reply
+test.gnu:
+Got `A' record: 217.92.15.146
+@end example
+
+@noindent
+That shows that resolution works, once GNS is integrated with
+the application.
+
+@node Integration with Browsers (DNS2GNS service)
+@subsection Integration with Browsers (DNS2GNS service)
+
+Most OSes allow you to either modify your @code{/etc/resolv.conf} directly or
+through @code{resolvectl}.
+We are going to configure the @code{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 @code{dns2gns} service to run on a
+non-priviledged port like 5353.
+But, in case you are going to edit @code{/etc/resolv.conf} directly, the
+@code{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:
+
+@example
+$ gnunet-config -s dns2gns -o OPTIONS -V "-d $FALLBACK_DNS -p 5252"
+$ gnunet-arm -i dns2gns # Make sure the service is started
+@end example
+
+If you edit your resolv.conf directly, it should contain and entry like this:
+
+@example
+nameserver 127.0.0.1
+@end example
+
+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:
+
+@example
+$ resolvectl $INTERFACE 127.0.0.1:5353
+@end example
+
+Where @code{$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:
+
+@example
+$ sudo systemctl enable NetworkManager-dispatcher.service
+$ sudo systemctl start NetworkManager-dispatcher.service
+@end example
+
+Then, create a script /etc/NetworkManager/dispatch.h/10-dns2-gns.sh:
+
+@example
+#!/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
+@end example
+
+Make sure the script is owned by root and executable:
+
+@example
+$ sudo root:root /etc/NetworkManager/dispatch.d/10-dns2gns.sh
+$ sudo +x /etc/NetworkManager/dispatch.d/10-dns2gns.sh
+@end example
+
+You can test accessing this website using your browser or curl:
+
+@example
+$ curl www.gnunet.org
+@end example
+
+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.
+
+@node Integration with Browsers (SOCKS proxy)
+@subsection 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 @code{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 @command{gnunet-arm -i gns-proxy}. Use @command{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 @command{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
+@command{chromium --proxy-server="socks5://localhost:7777"}
+For @command{Firefox} (or @command{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 @code{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
+@code{browser.fixup.alternate.enabled} option to @code{false},
+otherwise the browser will autoblunder an address like
+@code{@uref{http://www.gnu/, www.gnu}} to
+@code{@uref{http://www.gnu.com/, www.gnu.com}}.  If you want
+to resolve @@ in your own TLDs, you must additionally
+set @code{browser.fixup.dns_first_use_for_single_words} to @code{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
+"@uref{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 "@uref{http://www.test.gnu/}" instead of
+"@uref{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.
+
+@pindex gnunet-bcd
+@node Creating a Business Card
+@subsection Creating a Business Card
+@c FIXME: Which parts of texlive are needed? Some systems offer a modular
+@c texlive (smaller size).
+Before we can really use GNS, you should create a business card.
+Note that this requires having @command{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 @b{requires 3GB} of downloaded data and possibly
+@b{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:
+
+@itemize @bullet
+@item texlive-units
+@item texlive-labels
+@item texlive-pst-barcode
+@item texlive-luatex85
+@item texlive-preview
+@item texlive-pdfcrop
+@item texlive-koma-script
+@end itemize
+
+
+@b{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.}
+
+@example
+apt-get install texlive-full
+@end example
+
+@noindent
+Start creating a business card by clicking the "Copy" button
+in @command{gnunet-namestore-gtk}. Next, you should start
+the @command{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:
+
+@example
+$ gnunet-bcd # seems to hang...
+@end example
+
+@noindent
+Then, start a browser and point it to @uref{http://localhost:8888/}
+where @code{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 @command{gnunet-namestore-gtk}.
+Then, fill in all of the other fields, including your @b{GNS NICKname}.
+Adding a GPG fingerprint is optional.
+Once finished, click "Submit Query".
+If your @code{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 @code{gnunet-bcd} and press
+@b{CTRL-C} to shut down the Web server.
+
+
+@node Be Social
+@subsection 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 @code{gnunet-qr} which zone
+it should import new records into.  For this, run:
+
+@pindex gnunet-identity
+@example
+$ gnunet-identity -s namestore -e NAME
+@end example
+where NAME is the name of the zone you want to import records
+into.  In our running example, this would be ``gnu''.
+
+@pindex gnunet-qr
+Henceforth, for every business card you collect, simply run:
+@example
+$ gnunet-qr
+@end example
+
+@noindent
+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
+
+@pindex gnunet-gns
+@example
+$ gnunet-gns -u test.bob.gnu
+@end example
+
+@noindent
+to check if your friend was as good at following instructions
+as you were.
+
+
+@node Backup of Identities and Egos
+@subsection 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 @file{~/.local/share/gnunet/private_key.ecc}
+
+The private keys of your egos are stored in the
+directory @file{~/.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.
+
+
+@node Revocation
+@subsection 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.
+
+@pindex gnunet-revocation
+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
+@command{gnunet-revocation}. For example, the following command (as
+unprivileged user) generates a revocation file
+@file{revocation.dat} for the zone @code{zone1}:
+@command{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).
+
+
+@c FIXME: The Manual should give away the command using an example that is
+@c very likely to never exist.
+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 @command{-p} option of @command{gnunet-revocation}.
+
+
+@node What's Next?
+@subsection 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.
+
+@pindex gnunet-conservation-gtk
+@node First steps - Using GNUnet Conversation
+@section First steps - Using GNUnet Conversation
+
+
+First, you should launch the graphical user interface.  You can do
+this from the command-line by typing
+
+@example
+$ gnunet-conversation-gtk
+@end example
+
+@menu
+* Testing your Audio Equipment::
+* GNS Zones::
+@end menu
+
+@node Testing your Audio Equipment
+@subsection Testing your Audio Equipment
+
+
+First, you should use @code{gnunet-conversation-test} to check that your
+microphone and speaker are working correctly. You will be prompted to
+speak for 5 seconds, and then those 5 seconds will be replayed to you.
+The network is not involved in this test. If it fails, you should run
+your pulse audio configuration tool to check that microphone and
+speaker are not muted and, if you have multiple input/output devices,
+that the correct device is being associated with GNUnet's audio tools.
+
+@node GNS Zones
+@subsection GNS Zones
+
+
+@code{gnunet-conversation} uses GNS for addressing. This means that
+you need to have a GNS zone created before using it. Information
+about how to create GNS zones can be found here.
+
+
+@menu
+* Picking an Identity::
+* Calling somebody::
+@end menu
+
+@node Picking an Identity
+@subsubsection Picking an Identity
+
+
+To make a call with @code{gnunet-conversation}, you first
+need to choose an identity. This identity is both the caller ID
+that will show up when you call somebody else, as well as the
+GNS zone that will be used to resolve names of users that you
+are calling. Run
+
+@pindex gnunet-conversation
+@example
+gnunet-conversation -e zone-name
+@end example
+
+@noindent
+to start the command-line tool. You will see a message saying
+that your phone is now "active on line 0". You can connect
+multiple phones on different lines at the same peer. For the
+first phone, the line zero is of course a fine choice.
+
+Next, you should type in @command{/help} for a list of
+available commands. We will explain the important ones
+during this tutorial. First, you will need to type in
+@command{/address} to determine the address of your
+phone. The result should look something like this:
+
+@example
+/address
+0-PD67SGHF3E0447TU9HADIVU9OM7V4QHTOG0EBU69TFRI2LG63DR0
+@end example
+
+@noindent
+Here, the "0" is your phone line, and what follows
+after the hyphen is your peer's identity. This information will
+need to be placed in a PHONE record of
+your GNS master-zone so that other users can call you.
+
+Start @code{gnunet-namestore-gtk} now (possibly from another
+shell) and create an entry home-phone in your master zone.
+For the record type, select PHONE. You should then see the
+PHONE dialog:
+
+@image{images/gnunet-namestore-gtk-phone,5in,,Dialog to publish a PHONE record}
+
+Note: Do not choose the expiry time to be 'Never'. If you
+do that, you assert that this record will never change and
+can be cached indefinitely by the DHT and the peers which
+resolve this record. A reasonable period is 1 year.
+
+Enter your peer identity under Peer and leave the line
+at zero. Select the first option to make the record public.
+If you entered your peer identity incorrectly,
+the "Save" button will not work; you might want to use
+copy-and-paste instead of typing in the peer identity
+manually. Save the record.
+
+@node Calling somebody
+@subsubsection Calling somebody
+
+
+Now you can call a buddy. Obviously, your buddy will have to have GNUnet
+installed and must have performed the same steps. Also, you must have
+your buddy in your GNS master zone, for example by having imported
+your buddy's public key using @code{gnunet-qr}. Suppose your buddy
+is in your zone as @code{buddy.mytld} and they also created their
+phone using a label "home-phone". Then you can initiate a call using:
+
+@example
+/call home-phone.buddy.mytld
+@end example
+
+It may take some time for GNUnet to resolve the name and to establish
+a link. If your buddy has your public key in their master zone, they
+should see an incoming call with your name. If your public key is not
+in their master zone, they will just see the public key as the caller ID.
+
+Your buddy then can answer the call using the "/accept" command. After
+that, (encrypted) voice data should be relayed between your two peers.
+Either of you can end the call using @command{/cancel}. You can exit
+@code{gnunet-conversation} using @command{/quit}.
+
+
+@node First steps - Using the GNUnet VPN
+@section First steps - Using the GNUnet VPN
+
+
+
+@menu
+* VPN Preliminaries::
+* GNUnet-Exit configuration::
+* GNS configuration::
+* Accessing the service::
+* Using a Browser::
+@end menu
+
+@node VPN Preliminaries
+@subsection VPN Preliminaries
+
+
+To test the GNUnet VPN, we should first run a web server.
+The easiest way to do this is to just start @code{gnunet-bcd},
+which will run a webserver on port @code{8888} by default.
+Naturally, you can run some other HTTP server for our little tutorial.
+
+If you have not done this, you should also configure your
+Name System Service switch to use GNS. In your @code{/etc/nsswitch.conf}
+you should fine a line like this:
+
+@example
+hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4
+@end example
+
+@noindent
+The exact details may differ a bit, which is fine. Add the text
+@code{gns [NOTFOUND=return]} after @code{files}:
+
+@example
+hosts: files gns [NOTFOUND=return] mdns4_minimal [NOTFOUND=return] dns mdns4
+@end example
+
+@c TODO: outdated section, we no longer install this as part of the
+@c TODO: standard installation procedure and should point out the manual
+@c TODO: steps required to make it useful.
+@noindent
+You might want to make sure that @code{/lib/libnss_gns.so.2} exists on
+your system, it should have been created during the installation.
+If not, re-run
+
+@example
+$ configure --with-nssdir=/lib
+$ cd src/gns/nss; sudo make install
+@end example
+
+@noindent
+to install the NSS plugins in the proper location.
+
+@node GNUnet-Exit configuration
+@subsection GNUnet-Exit configuration
+
+
+Stop your peer (as user @code{gnunet}, run @command{gnunet-arm -e}) and
+run @command{gnunet-setup}. In @command{gnunet-setup}, make sure to
+activate the @strong{EXIT} and @strong{GNS} services in the General tab.
+Then select the Exit tab. Most of the defaults should be fine (but
+you should check against the screenshot that they have not been modified).
+In the bottom area, enter @code{bcd} under Identifier and change the
+Destination to @code{169.254.86.1:8888} (if your server runs on a port
+other than 8888, change the 8888 port accordingly).
+
+Now exit @command{gnunet-setup} and restart your peer
+(@command{gnunet-arm -s}).
+
+@node GNS configuration
+@subsection GNS configuration
+
+
+Now, using your normal user (not the @code{gnunet} system user), run
+@command{gnunet-namestore-gtk}. Add a new label www in your
+master zone. For the record type, select @code{VPN}. You should then
+see the VPN dialog:
+
+@image{images/gnunet-namestore-gtk-vpn,5in,,Dialog to publish a VPN record}
+
+Under peer, you need to supply the peer identity of your own peer. You can
+obtain the respective string by running @command{gnunet-peerinfo -sq}
+as the @code{gnunet} user. For the Identifier, you need to supply the same
+identifier that we used in the Exit setup earlier, so here supply "bcd".
+If you want others to be able to use the service, you should probably make
+the record public. For non-public services, you should use a passphrase
+instead of the string "bcd". Save the record and
+exit @command{gnunet-namestore-gtk}.
+
+@node Accessing the service
+@subsection Accessing the service
+
+
+You should now be able to access your webserver. Type in:
+
+@example
+$ wget http://www.gnu/
+@end example
+
+@noindent
+The request will resolve to the VPN record, telling the GNS resolver
+to route it via the GNUnet VPN. The GNS resolver will ask the
+GNUnet VPN for an IPv4 address to return to the application. The
+VPN service will use the VPN information supplied by GNS to create
+a tunnel (via GNUnet's MESH service) to the EXIT peer.
+At the EXIT, the name "bcd" and destination port (80) will be mapped
+to the specified destination IP and port. While all this is currently
+happening on just the local machine, it should also work with other
+peers --- naturally, they will need a way to access your GNS zone
+first, for example by learning your public key from a QR code on
+your business card.
+
+@node Using a Browser
+@subsection Using a Browser
+
+
+Sadly, modern browsers tend to bypass the Name Services Switch and
+attempt DNS resolution directly. You can either run
+a @code{gnunet-dns2gns} DNS proxy, or point the browsers to an
+HTTP proxy. When we tried it, Iceweasel did not like to connect to
+the socks proxy for @code{.gnu} TLDs, even if we disabled its
+autoblunder of changing @code{.gnu} to ".gnu.com". Still,
+using the HTTP proxy with Chrome does work.
+
+@node File-sharing
+@section File-sharing
+
+
+This chapter documents the GNUnet file-sharing application. The original
+file-sharing implementation for GNUnet was designed to provide
+@strong{anonymous} file-sharing. However, over time, we have also added
+support for non-anonymous file-sharing (which can provide better
+performance). Anonymous and non-anonymous file-sharing are quite
+integrated in GNUnet and, except for routing, share most of the concepts
+and implementation. There are three primary file-sharing operations:
+publishing, searching and downloading. For each of these operations,
+the user specifies an @strong{anonymity level}. If both the publisher and
+the searcher/downloader specify "no anonymity", non-anonymous
+file-sharing is used. If either user specifies some desired degree
+of anonymity, anonymous file-sharing will be used.
+
+After a short introduction, we will first look at the various concepts
+in GNUnet's file-sharing implementation. Then, we will discuss
+specifics as to how they impact users that publish, search or download
+files.
+
+
+@menu
+* fs-Searching::
+* fs-Downloading::
+* fs-Publishing::
+* fs-Concepts::
+* Namespace Management::
+* File-Sharing URIs::
+* GTK User Interface::
+@end menu
+
+@node fs-Searching
+@subsection Searching
+
+
+The command @command{gnunet-search} can be used to search
+for content on GNUnet. The format is:
+
+@example
+$ gnunet-search [-t TIMEOUT] KEYWORD
+@end example
+
+@noindent
+The @command{-t} option specifies that the query should timeout after
+approximately TIMEOUT seconds. A value of zero (``0'') is interpreted
+as @emph{no timeout}, which is the default. In this case,
+@command{gnunet-search} will never terminate (unless you press
+@command{CTRL-C}).
+
+If multiple words are passed as keywords, they will all be
+considered optional. Prefix keywords with a "+" to make them mandatory.
+
+Note that searching using
+
+@example
+$ gnunet-search Das Kapital
+@end example
+
+@noindent
+is not the same as searching for
+
+@example
+$ gnunet-search "Das Kapital"
+@end example
+
+@noindent
+as the first will match files shared under the keywords
+"Das" or "Kapital" whereas the second will match files
+shared under the keyword "Das Kapital".
+
+Search results are printed by @command{gnunet-search} like this:
+
+@c it will be better the avoid the ellipsis altogether because I don't
+@c understand the explanation below that
+@c ng0: who is ``I'' and what was the complete sentence?
+@example
+#15:
+gnunet-download -o "COPYING" gnunet://fs/chk/PGK8M...3EK130.75446
+
+@end example
+
+@noindent
+The whole line is the command you would have to enter to download
+the file. The first argument passed to @code{-o} is the suggested
+filename (you may change it to whatever you like).
+It is followed by the key for decrypting the file, the query for
+searching the file, a checksum (in hexadecimal) finally the size of
+the file in bytes.
+
+@node fs-Downloading
+@subsection Downloading
+
+
+In order to download a file, you need the whole line returned by
+@command{gnunet-search}.
+You can then use the tool @command{gnunet-download} to obtain the file:
+
+@example
+$ gnunet-download -o <FILENAME> <GNUNET-URL>
+@end example
+
+@noindent
+FILENAME specifies the name of the file where GNUnet is supposed
+to write the result. Existing files are overwritten. If the
+existing file contains blocks that are identical to the
+desired download, those blocks will not be downloaded again
+(automatic resume).
+
+If you want to download the GPL from the previous example,
+you do the following:
+
+@example
+$ gnunet-download -o "COPYING" gnunet://fs/chk/PGK8M...3EK130.75446
+@end example
+
+@noindent
+If you ever have to abort a download, you can continue it at any time by
+re-issuing @command{gnunet-download} with the same filename.
+In that case, GNUnet will @strong{not} download blocks again that are
+already present.
+
+GNUnet's file-encoding mechanism will ensure file integrity, even if the
+existing file was not downloaded from GNUnet in the first place.
+
+You may want to use the @command{-V} switch to turn on verbose
+reporting. In this case, @command{gnunet-download} will print the
+current number of bytes downloaded whenever new data was received.
+
+@node fs-Publishing
+@subsection Publishing
+
+
+The command @command{gnunet-publish} can be used to add content
+to the network. The basic format of the command is
+
+@example
+$ gnunet-publish [-n] [-k KEYWORDS]* [-m TYPE:VALUE] FILENAME
+@end example
+
+For example
+@example
+$ gnunet-publish -m "description:GNU License" -k gpl -k test -m "mimetype:text/plain" COPYING
+@end example
+
+@menu
+* Important command-line options::
+* Indexing vs. Inserting::
+@end menu
+
+@node Important command-line options
+@subsubsection Important command-line options
+
+
+The option @code{-k} is used to specify keywords for the file that
+should be inserted. You can supply any number of keywords,
+and each of the keywords will be sufficient to locate and
+retrieve the file. Please note that you must use the @code{-k} option
+more than once -- one for each expression you use as a keyword for
+the filename.
+
+The -m option is used to specify meta-data, such as descriptions.
+You can use -m multiple times. The TYPE passed must be from the
+list of meta-data types known to libextractor. You can obtain this
+list by running @command{extract -L}. Use quotes around the entire
+meta-data argument if the value contains spaces. The meta-data
+is displayed to other users when they select which files to
+download. The meta-data and the keywords are optional and
+may be inferred using @code{GNU libextractor}.
+
+@command{gnunet-publish} has a few additional options to handle
+namespaces and directories. Refer to the man-page for details:
+
+@example
+man gnunet-publish
+@end example
+
+@node Indexing vs. Inserting
+@subsubsection Indexing vs Inserting
+
+
+By default, GNUnet indexes a file instead of making a full copy.
+This is much more efficient, but requires the file to stay unaltered
+at the location where it was when it was indexed. If you intend to move,
+delete or alter a file, consider using the option @code{-n} which will
+force GNUnet to make a copy of the file in the database.
+
+Since it is much less efficient, this is strongly discouraged for large
+files. When GNUnet indexes a file (default), GNUnet does @strong{not}
+create an additional encrypted copy of the file but just computes a
+summary (or index) of the file. That summary is approximately two percent
+of the size of the original file and is stored in GNUnet's database.
+Whenever a request for a part of an indexed file reaches GNUnet,
+this part is encrypted on-demand and send out. This way, there is no
+need for an additional encrypted copy of the file to stay anywhere
+on the drive. This is different from other systems, such as Freenet,
+where each file that is put online must be in Freenet's database in
+encrypted format, doubling the space requirements if the user wants
+to preserve a directly accessible copy in plaintext.
+
+Thus indexing should be used for all files where the user will keep
+using this file (at the location given to gnunet-publish) and does
+not want to retrieve it back from GNUnet each time. If you want to
+remove a file that you have indexed from the local peer, use the tool
+@command{gnunet-unindex} to un-index the file.
+
+The option @code{-n} may be used if the user fears that the file might
+be found on their drive (assuming the computer comes under the control
+of an adversary). When used with the @code{-n} flag, the user has a
+much better chance of denying knowledge of the existence of the file,
+even if it is still (encrypted) on the drive and the adversary is
+able to crack the encryption (e.g. by guessing the keyword.
+
+@node fs-Concepts
+@subsection Concepts
+
+
+For better results with filesharing it is useful to understand the
+following concepts.
+In addition to anonymous routing GNUnet attempts to give users a better
+experience in searching for content. GNUnet uses cryptography to safely
+break content into smaller pieces that can be obtained from different
+sources without allowing participants to corrupt files. GNUnet makes it
+difficult for an adversary to send back bogus search results. GNUnet
+enables content providers to group related content and to establish a
+reputation. Furthermore, GNUnet allows updates to certain content to be
+made available. This section is supposed to introduce users to the
+concepts that are used to achieve these goals.
+
+
+@menu
+* Files::
+* Keywords::
+* Directories::
+* Egos and File-Sharing::
+* Namespaces::
+* Advertisements::
+* Anonymity level::
+* Content Priority::
+* Replication::
+@end menu
+
+@node Files
+@subsubsection Files
+
+
+A file in GNUnet is just a sequence of bytes. Any file-format is allowed
+and the maximum file size is theoretically @math{2^64 - 1} bytes, except
+that it would take an impractical amount of time to share such a file.
+GNUnet itself never interprets the contents of shared files, except when
+using GNU libextractor to obtain keywords.
+
+@node Keywords
+@subsubsection Keywords
+
+
+Keywords are the most simple mechanism to find files on GNUnet.
+Keywords are @strong{case-sensitive} and the search string
+must always match @strong{exactly} the keyword used by the
+person providing the file. Keywords are never transmitted in
+plaintext. The only way for an adversary to determine the keyword
+that you used to search is to guess it (which then allows the
+adversary to produce the same search request). Since providing
+keywords by hand for each shared file is tedious, GNUnet uses
+GNU libextractor to help automate this process. Starting a
+keyword search on a slow machine can take a little while since
+the keyword search involves computing a fresh RSA key to formulate the
+request.
+
+@node Directories
+@subsubsection Directories
+
+
+A directory in GNUnet is a list of file identifiers with meta data.
+The file identifiers provide sufficient information about the files
+to allow downloading the contents. Once a directory has been created,
+it cannot be changed since it is treated just like an ordinary file
+by the network. Small files (of a few kilobytes) can be inlined in
+the directory, so that a separate download becomes unnecessary.
+
+Directories are shared just like ordinary files. If you download a
+directory with @command{gnunet-download}, you can use
+@command{gnunet-directory} to list its contents. The canonical
+extension for GNUnet directories when stored as files in your
+local file-system is ".gnd". The contents of a directory are URIs and
+meta data.
+The URIs contain all the information required by
+@command{gnunet-download} to retrieve the file. The meta data
+typically includes the mime-type, description, a filename and
+other meta information, and possibly even the full original file
+(if it was small).
+
+@node Egos and File-Sharing
+@subsubsection Egos and File-Sharing
+
+When sharing files, it is sometimes desirable to build a reputation as
+a source for quality information.  With egos, publishers can
+(cryptographically) sign files, thereby demonstrating that various
+files were published by the same entity.  An ego thus allows users to
+link different publication events, thereby deliberately reducing
+anonymity to pseudonymity.
+
+Egos used in GNUnet's file-sharing for such pseudonymous publishing
+also correspond to the egos used to identify and sign zones in the
+GNU Name System.  However, if the same ego is used for file-sharing
+and for a GNS zone, this will weaken the privacy assurances provided
+by the anonymous file-sharing protocol.
+
+Note that an ego is NOT bound to a GNUnet peer. There can be multiple
+egos for a single user, and users could (theoretically) share
+the private keys of an ego by copying the respective private keys.
+
+
+@node Namespaces
+@subsubsection Namespaces
+
+A namespace is a set of files that were signed by the same ego.
+Today, namespaces are implemented independently of GNS zones, but
+in the future we plan to merge the two such that a GNS zone can
+basically contain files using a file-sharing specific record type.
+
+Files (or directories) that have been signed and placed into a
+namespace can be updated. Updates are identified as authentic if the
+same secret key was used to sign the update.
+
+@node Advertisements
+@subsubsection Advertisements
+
+Advertisements are used to notify other users about the existence of a
+namespace. Advertisements are propagated using the normal keyword
+search.  When an advertisement is received (in response to a search),
+the namespace is added to the list of namespaces available in the
+namespace-search dialogs of gnunet-fs-gtk and printed by
+@code{gnunet-identity}. Whenever a namespace is created, an
+appropriate advertisement can be generated.  The default keyword for
+the advertising of namespaces is "namespace".
+
+
+@node Anonymity level
+@subsubsection Anonymity level
+
+The anonymity level determines how hard it should be for an adversary to
+determine the identity of the publisher or the searcher/downloader. An
+anonymity level of zero means that anonymity is not required. The default
+anonymity level of "1" means that anonymous routing is desired, but no
+particular amount of cover traffic is necessary. A powerful adversary
+might thus still be able to deduce the origin of the traffic using
+traffic analysis. Specifying higher anonymity levels increases the
+amount of cover traffic required.
+
+The specific numeric value (for anonymity levels above 1) is simple:
+Given an anonymity level L (above 1), each request FS makes on your
+behalf must be hidden in L-1 equivalent requests of cover traffic
+(traffic your peer routes for others) in the same time-period.  The
+time-period is twice the average delay by which GNUnet artificially
+delays traffic.
+
+While higher anonymity levels may offer better privacy, they can also
+significantly hurt performance.
+
+
+@node Content Priority
+@subsubsection Content Priority
+
+Depending on the peer's configuration, GNUnet peers migrate content
+between peers. Content in this sense are individual blocks of a file,
+not necessarily entire files. When peers run out of space (due to
+local publishing operations or due to migration of content from other
+peers), blocks sometimes need to be discarded. GNUnet first always
+discards expired blocks (typically, blocks are published with an
+expiration of about two years in the future; this is another option).
+If there is still not enough space, GNUnet discards the blocks with the
+lowest priority. The priority of a block is decided by its popularity
+(in terms of requests from peers we trust) and, in case of blocks
+published locally, the base-priority that was specified by the user
+when the block was published initially.
+
+
+@node Replication
+@subsubsection Replication
+
+When peers migrate content to other systems, the replication level
+of a block is used to decide which blocks need to be migrated most
+urgently. GNUnet will always push the block with the highest
+replication level into the network, and then decrement the replication
+level by one. If all blocks reach replication level zero, the
+selection is simply random.
+
+
+@node Namespace Management
+@subsection Namespace Management
+
+The @code{gnunet-identity} tool can be used to create egos.
+By default, @code{gnunet-identity --display} simply
+lists all locally available egos.
+
+
+@menu
+* Creating Egos::
+* Deleting Egos::
+@end menu
+
+@node Creating Egos
+@subsubsection Creating Egos
+
+With the @command{--create=NICK} option it can also be used to create a new
+ego. An ego is the virtual identity of the entity in control of a
+namespace or GNS zone. Anyone can create any number of egos.  The
+provided NICK name automatically corresponds to a GNU Name System
+domain name.  Thus, henceforth name resolution for any name ending in
+``.NICK'' will use the NICK's zone.  You should avoid using NICKs that
+collide with well-known DNS names.
+
+Currently, the IDENTITY subsystem supports two types of identity keys:
+ECDSA and EdDSA. By default, ECDSA identities are creates with ECDSA keys.
+In order to create an identity with EdDSA keys, you can use the
+@command{--eddsa} flag.
+
+@node Deleting Egos
+@subsubsection Deleting Egos
+
+With the @command{-D NICK} option egos can be deleted.  Once the ego
+has been deleted it is impossible to add content to the corresponding
+namespace or zone. However, the existing GNS zone data is currently
+not dropped. This may change in the future.
+
+Deleting the pseudonym does not make the namespace or any content in
+it unavailable.
+
+@node File-Sharing URIs
+@subsection File-Sharing URIs
+
+
+GNUnet (currently) uses four different types of URIs for
+file-sharing. They all begin with "gnunet://fs/".
+This section describes the four different URI types in detail.
+
+For FS URIs empty KEYWORDs are not allowed. Quotes are allowed to
+denote whitespace between words. Keywords must contain a balanced
+number of double quotes. Doubles quotes can not be used in the actual
+keywords. This means that the string '""foo bar""' will be turned
+into two OR-ed keywords 'foo' and 'bar', not into '"foo bar"'.
+
+@menu
+* Encoding of hash values in URIs::
+* Content Hash Key (chk)::
+* Location identifiers (loc)::
+* Keyword queries (ksk)::
+* Namespace content (sks)::
+@end menu
+
+@node Encoding of hash values in URIs
+@subsubsection Encoding of hash values in URIs
+
+
+Most URIs include some hash values. Hashes are encoded using
+base32hex (RFC 2938).
+
+@cindex chk-uri
+@node Content Hash Key (chk)
+@subsubsection Content Hash Key (chk)
+
+
+A chk-URI is used to (uniquely) identify a file or directory
+and to allow peers to download the file. Files are stored in
+GNUnet as a tree of encrypted blocks.
+The chk-URI thus contains the information to download and decrypt
+those blocks. A chk-URI has the format
+"gnunet://fs/chk/KEYHASH.QUERYHASH.SIZE". Here, "SIZE"
+is the size of the file (which allows a peer to determine the
+shape of the tree), KEYHASH is the key used to decrypt the file
+(also the hash of the plaintext of the top block) and QUERYHASH
+is the query used to request the top-level block (also the hash
+of the encrypted block).
+
+@cindex loc-uri
+@node Location identifiers (loc)
+@subsubsection Location identifiers (loc)
+
+
+For non-anonymous file-sharing, loc-URIs are used to specify which
+peer is offering the data (in addition to specifying all of the
+data from a chk-URI). Location identifiers include a digital
+signature of the peer to affirm that the peer is truly the
+origin of the data. The format is
+"gnunet://fs/loc/KEYHASH.QUERYHASH.SIZE.PEER.SIG.EXPTIME".
+Here, "PEER" is the public key of the peer (in GNUnet format in
+base32hex), SIG is the RSA signature (in GNUnet format in
+base32hex) and EXPTIME specifies when the signature expires
+(in milliseconds after 1970).
+
+@cindex ksk-uri
+@node Keyword queries (ksk)
+@subsubsection Keyword queries (ksk)
+
+
+A keyword-URI is used to specify that the desired operation
+is the search using a particular keyword. The format is simply
+"gnunet://fs/ksk/KEYWORD". Non-ASCII characters can be specified
+using the typical URI-encoding (using hex values) from HTTP.
+"+" can be used to specify multiple keywords (which are then
+logically "OR"-ed in the search, results matching both keywords
+are given a higher rank): "gnunet://fs/ksk/KEYWORD1+KEYWORD2".
+ksk-URIs must not begin or end with the plus ('+') character.
+Furthermore they must not contain '++'.
+
+@cindex sks-uri
+@node Namespace content (sks)
+@subsubsection Namespace content (sks)
+
+
+@b{Please note that the text in this subsection is outdated and needs}
+@b{to be rewritten for version 0.10!}
+@b{This especially concerns the terminology of Pseudonym/Ego/Identity.}
+
+Namespaces are sets of files that have been approved by some (usually
+pseudonymous) user --- typically by that user publishing all of the
+files together. A file can be in many namespaces. A file is in a
+namespace if the owner of the ego (aka the namespace's private key)
+signs the CHK of the file cryptographically. An SKS-URI is used to
+search a namespace. The result is a block containing meta data,
+the CHK and the namespace owner's signature. The format of a sks-URI
+is "gnunet://fs/sks/NAMESPACE/IDENTIFIER". Here, "NAMESPACE"
+is the public key for the namespace. "IDENTIFIER" is a freely
+chosen keyword (or password!). A commonly used identifier is
+"root" which by convention refers to some kind of index or other
+entry point into the namespace.
+
+@node GTK User Interface
+@subsection GTK User Interface
+This chapter describes first steps for file-sharing with GNUnet.
+To start, you should launch @command{gnunet-fs-gtk}.
+
+As we want to be sure that the network contains the data that we are
+looking for for testing, we need to begin by publishing a file.
+
+@menu
+* gtk-Publishing::
+* gtk-Searching::
+* gtk-Downloading::
+@end menu
+
+@node gtk-Publishing
+@subsubsection Publishing
+
+
+To publish a file, select "File Sharing" in the menu bar just below the
+"Statistics" icon, and then select "Publish" from the menu.
+
+Afterwards, the following publishing dialog will appear:
+
+@image{images/gnunet-gtk-0-10-fs-publish,5in,,The gnunet-fs-gtk publishing dialog}
+
+In this dialog, select the "Add File" button. This will open a
+file selection dialog:
+
+@image{images/gnunet-gtk-0-10-fs-publish-select,5in,,Dialog to select the file to publish (looks may differ for other Gtk+ versions)}
+
+Now, you should select a file from your computer to be published on
+GNUnet. To see more of GNUnet's features later, you should pick a
+PNG or JPEG file this time. You can leave all of the other options
+in the dialog unchanged. Confirm your selection by pressing the "OK"
+button in the bottom right corner. Now, you will briefly see a
+"Messages..." dialog pop up, but most likely it will be too short for
+you to really read anything. That dialog is showing you progress
+information as GNUnet takes a first look at the selected file(s).
+For a normal image, this is virtually instant, but if you later
+import a larger directory you might be interested in the progress dialog
+and potential errors that might be encountered during processing.
+After the progress dialog automatically disappears, your file
+should now appear in the publishing dialog:
+
+@image{images/gnunet-gtk-0-10-fs-publish-with-file,5in,,Publishing dialog with file added}
+
+Now, select the file (by clicking on the file name) and then click
+the "Edit" button. This will open the editing dialog:
+
+@image{images/gnunet-gtk-0-10-fs-publish-editing,5in,,Editing meta data of a file to be published}
+
+In this dialog, you can see many details about your file. In the
+top left area, you can see meta data extracted about the file,
+such as the original filename, the mimetype and the size of the image.
+In the top right, you should see a preview for the image
+(if GNU libextractor was installed correctly with the
+respective plugins). Note that if you do not see a preview, this
+is not a disaster, but you might still want to install more of
+GNU libextractor in the future. In the bottom left, the dialog contains
+a list of keywords. These are the keywords under which the file will be
+made available. The initial list will be based on the extracted meta data.
+Additional publishing options are in the right bottom corner. We will
+now add an additional keyword to the list of keywords. This is done by
+entering the keyword above the keyword list between the label "Keyword"
+and the "Add keyword" button. Enter "test" and select "Add keyword".
+Note that the keyword will appear at the bottom of the existing keyword
+list, so you might have to scroll down to see it. Afterwards, push the
+"OK" button at the bottom right of the dialog.
+
+You should now be back at the "Publish content on GNUnet" dialog. Select
+"Execute" in the bottom right to close the dialog and publish your file
+on GNUnet! Afterwards, you should see the main dialog with a new area
+showing the list of published files (or ongoing publishing operations
+with progress indicators).
+
+@node gtk-Searching
+@subsubsection Searching
+
+
+Below the menu bar, there are four entry widges labeled "Namespace",
+"Keywords", "Anonymity" and "Mime-type" (from left to right). These
+widgets are used to control searching for files in GNUnet. Between the
+"Keywords" and "Anonymity" widgets, there is also a big "Search" button,
+which is used to initiate the search. We will ignore the "Namespace",
+"Anonymity" and "Mime-type" options in this tutorial, please leave them
+empty. Instead, simply enter "test" under "Keywords" and press "Search".
+Afterwards, you should immediately see a new tab labeled after your
+search term, followed by the (current) number of search
+results --- "(15)" in our screenshot. Note that your results may
+vary depending on what other users may have shared and how your
+peer is connected.
+
+You can now select one of the search results. Once you do this,
+additional information about the result should be displayed on the
+right. If available, a preview image should appear on the top right.
+Meta data describing the file will be listed at the bottom right.
+
+Once a file is selected, at the bottom of the search result list
+a little area for downloading appears.
+
+@node gtk-Downloading
+@subsubsection Downloading
+
+
+In the downloading area, you can select the target directory (default is
+"Downloads") and specify the desired filename (by default the filename it
+taken from the meta data of the published file). Additionally, you can
+specify if the download should be anonymous and (for directories) if
+the download should be recursive. In most cases, you can simply start
+the download with the "Download!" button.
+
+Once you selected download, the progress of the download will be
+displayed with the search result. You may need to resize the result
+list or scroll to the right. The "Status" column shows the current
+status of the download, and "Progress" how much has been completed.
+When you close the search tab (by clicking on the "X" button next to
+the "test" label), ongoing and completed downloads are not aborted
+but moved to a special "*" tab.
+
+You can remove completed downloads from the "*" tab by clicking the
+cleanup button next to the "*". You can also abort downloads by right
+clicking on the respective download and selecting "Abort download"
+from the menu.
+
+That's it, you now know the basics for file-sharing with GNUnet!
+
+
+@node The GNU Name System
+@section The GNU Name System
+
+
+
+The GNU Name System (GNS) is secure and decentralized naming system.
+It allows its users to register names as @dfn{top-level domains} (TLDs) and
+resolve other namespaces within their TLDs.
+
+GNS is designed to provide:
+@itemize @bullet
+@item Censorship resistance
+@item Query privacy
+@item Secure name resolution
+@item Compatibility with DNS
+@end itemize
+
+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
+@code{@uref{http://www.bob.gnu/, www.bob.gnu}} to one user might be
+@code{@uref{http://www.friend.gnu/, www.friend.gnu}} for someone else.
+
+
+@menu
+* Creating a Zone::
+* Maintaining your own Zones::
+* Obtaining your Zone Key::
+* Adding Links to Other Zones::
+* Using Public Keys as Top Level Domains::
+* Resource Records in GNS::
+* Synchronizing with legacy DNS::
+* Migrating an existing DNS zone into GNS::
+@end menu
+
+
+@node Creating a Zone
+@subsection Creating a Zone
+
+To use GNS, you probably should create at least one zone of your own.
+You can create any number of zones using the gnunet-identity tool
+using:
+
+@example
+$ gnunet-identity --create="myzone"
+@end example
+
+Henceforth, on your system you control the TLD ``myzone''.
+
+All of your zones can be listed (displayed) using the
+@command{gnunet-identity} command line tool as well:
+
+@example
+$ gnunet-identity --display
+@end example
+
+@node Maintaining your own Zones
+@subsection Maintaining your own Zones
+
+@noindent
+Now you can add (or edit, or remove) records in your GNS zone using the
+@command{gnunet-namestore-gtk} GUI or using the @command{gnunet-namestore}
+command-line tool.
+In either case, your records will be stored in an SQL database under
+control of the @command{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 @code{1.2.3.4}. Then you can put an
+@code{A} record (@code{A} records in DNS are for IPv4 IP addresses)
+into your local zone ``myzone'' using the command:
+
+@example
+$ gnunet-namestore -z myzone -a -n www -t A -V 1.2.3.4 -e never
+@end example
+
+@noindent
+Afterwards, you will be able to access your webpage under "www.myzone"
+(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
+@command{gnunet-namestore-gtk} GUI to be easier.
+
+@node Obtaining your Zone Key
+@subsection 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
+
+@example
+$ gnunet-identity -d $options | grep myzone | awk '@{print $3@}'
+@end example
+
+@noindent
+For example, the output might be something like:
+
+@example
+DC3SEECJORPHQNVRH965A6N74B1M37S721IG4RBQ15PJLLPJKUE0
+@end example
+
+@noindent
+Alternatively, you can obtain a QR code with your zone key AND your
+pseudonym from gnunet-namestore-gtk. The QR code is displayed in the
+main window and can be stored to disk using the ``Save as'' button
+next to the image.
+
+@node Adding Links to Other Zones
+@subsection 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 their local zone:
+
+@example
+$ gnunet-namestore -a -n bob --type PKEY -V XXXX -e never -Z myzone
+@end example
+
+@noindent
+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
+@command{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.
+
+@c themselves? themself?
+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).
+
+
+@node Using Public Keys as Top Level Domains
+@subsection Using Public Keys as Top Level Domains
+
+
+GNS also assumes responsibility for any name that uses in a
+well-formed public key for the TLD.  Names ending this way are then
+resolved by querying the respective zone. Such public key TLDs are
+expected to be used under rare circumstances where globally unique
+names are required, and for integration with legacy systems.
+
+@node Resource Records in GNS
+@subsection Resource Records in GNS
+
+
+GNS supports the majority of the DNS records as defined in
+@uref{http://www.ietf.org/rfc/rfc1035.txt, RFC 1035}. 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
+@uref{https://git.gnunet.org/gana.git/tree/gnu-name-system-record-types/registry.rec, GANA}.
+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 @uref{https://lsd.gnunet.org/lsd0001, LSD0001}.
+
+In the following, we discuss GNS records with specific behaviour or special
+handling of DNS records.
+
+@menu
+* NICK::
+* PKEY::
+* BOX::
+* LEHO::
+* VPN::
+* REDIRECT::
+* GNS2DNS::
+* TOMBSTONE::
+* SOA SRV PTR and MX::
+@end menu
+
+@node NICK
+@subsubsection 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 empty label ``@@'' 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.  Also, users do not usually have to worry
+about setting the NICK record: it is automatically set to the local
+name of the TLD.
+
+@b{Example}@
+
+@example
+Name: @@; RRType: NICK; Value: bob
+@end example
+
+@noindent
+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 this zone 'bob'").
+
+@node PKEY
+@subsubsection PKEY
+
+PKEY records are used to add delegation to other users' zones and
+give those zones a petname.
+
+@b{Example}@
+
+Let Bob's zone be identified by the hash "ABC012". Bob is your friend
+so you want to give them the petname "friend". Then you add the
+following record to your zone:
+
+@example
+Name: friend; RRType: PKEY; Value: ABC012;
+@end example
+
+@noindent
+This will allow you to resolve records in bob's zone
+under "*.friend.gnu".
+
+@node BOX
+@subsubsection 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 @code{_port._proto.(label.)*tld} to
+indicate the port number and protocol (like 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.
+
+@node LEHO
+@subsubsection LEHO
+
+The LEgacy HOstname of a server. Some webservers expect a specific
+hostname to provide a service (virtual 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.
+
+@node VPN
+@subsubsection 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.
+
+@b{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 @file{gnunet.conf} configuration file:
+
+@example
+[web.gnunet.]
+TCP_REDIRECTS = 80:localhost4:8080
+@end example
+
+@node REDIRECT
+@subsubsection REDIRECT
+
+As specified in LSD0001 whenever a REDIRECT is encountered the query
+needs to be restarted with the specified name. A REDIRECT
+can either be:
+
+@itemize @bullet
+@item A zone relative name,
+@item A zkey name or
+@item A DNS name (in which case resolution will continue outside
+of GNS with the systems DNS resolver)
+@end itemize
+
+@node GNS2DNS
+@subsubsection 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.
+
+@b{Example}
+
+@example
+Name: pet; RRType: GNS2DNS; Value: gnunet.org@@a.ns.joker.com
+@end example
+
+@noindent
+Any query to @code{pet.gnu} will then be delegated to the DNS server at
+@code{a.ns.joker.com}. For example,
+@code{@uref{http://www.pet.gnu/, www.pet.gnu}} will result in a DNS query
+for @code{@uref{http://www.gnunet.org/, www.gnunet.org}} to the server
+at @code{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, like so:
+
+@example
+Name: pet; RRType: GNS2DNS; Value: gnunet.org@@ns-joker.+@
+
+Name: ns-joker; RRType: A; Value: 184.172.157.218
+@end example
+
+@noindent
+This way, you can avoid involving the DNS hierarchy in the resolution of
+@code{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.
+
+@node TOMBSTONE
+@subsubsection TOMBSTONE
+
+The GNUnet GNS implementation uses the TOMBSTONE record to ensure
+ciphertext indistinguishability for published records.
+It must be ensured that when relative expiration times are decreased, the
+expiration time of the next record block MUST be after the last published block.
+A similar issue arises if the record set under a label is deleted and reused
+later.
+
+The creation and maintenance of the TOMBSTONE record is done automatically.
+You do not need to mind it yourself and can safely ignore any TOMBSTONE
+blocks you may see when investigating your zone(s).
+TOMBSTONE records are always private and will never be published.
+
+@node SOA SRV PTR and MX
+@subsubsection SOA SRV PTR and MX
+
+The domain names in those records can, again, be either
+
+@itemize @bullet
+@item A zone relative name,
+@item A zkey name or
+@item A DNS name
+@end itemize
+
+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.
+
+To add a SOA record via the gnunet-namestore command line
+tool use the following syntax for the value option. Choose
+the other options according to your preference, however in
+this example we will use a relative expiry, add the record
+under the label @ and add the records to the zone bar
+which already exists:
+
+@example
+$ gnunet-namestore -a -n @ -t SOA -z bar -e 3600s -V \
+>    "rname=$PRIMARY_NS \
+>    mname=$CONTACT_MAIL \
+>    $SERIAL,$REFRESH,$RETRY,$EXPIRY,$MINIMUM_TTL"
+@end example
+
+The above command filled in with values looks like this:
+@example
+$ gnunet-namestore -a -n @ -t SOA -z bar -e 3600s -V \
+>    "rname=ns1.bar \
+>    mname=root.bar \
+>    2019081701,3600,1800,86400,7200"
+@end example
+
+MX records use a similar syntax which is outlined in the
+example below. $SERVER is a domain name as mentioned above.
+@example
+$ gnunet-namestore -a -n mail -t MX -z bar -e 3600s -V \
+>    "$PRIORITY,$SERVER"
+@end example
+
+With the values substituted this is an example of a working
+command:
+@example
+$ gnunet-namestore -a -n mail -t MX -z bar -e 3600s -V \
+>    "10,mail.bar"
+@end example
+
+@node Synchronizing with legacy DNS
+@subsection 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
+@command{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, @command{gnunet-zoneimport} reads a list
+of DNS domain names from @code{stdin}, issues DNS queries for
+each, converts the obtained records (if possible) and stores
+the result in the namestore.
+
+@image{images/gns,6in,, picture of DNS-GNS data flow}
+
+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]''.
+
+@node Migrating an existing DNS zone into GNS
+@subsection Migrating an existing DNS zone into GNS
+
+Ascension is a tool to migrate existing DNS zones into GNS.
+
+@xref{Migrating existing DNS zones into GNS}, for installation instructions and
+further information about Ascension.
+
+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.
+
+After installing the tool according to the README file you have the following
+options:
+
+@example
+Ascension
+Usage:
+    ascension <domain> [-d] [-p] [-s] [--minimum-ttl=<ttl>] \
+        [--dry-run]
+    ascension <domain> <port> [-d] [-p] [-s] \
+        [--minimum-ttl=<ttl>] [--dry-run]
+    ascension <domain> -n <transferns> [-d] [-p] \
+        [-s] [--minimum-ttl=<ttl>] [--dry-run]
+    ascension <domain> -n <transferns> <port> [-d] \
+        [-p] [-s] [--minimum-ttl=<ttl>] [--dry-run]
+    ascension -p | --public
+    ascension -d | --debug
+    ascension -s | --standalone
+    ascension -h | --help
+    ascension -v | --version
+
+Options:
+    <domain>              Domain to migrate
+    <port>                Port for zone transfer
+    <transferns>          DNS Server that does the zone transfer
+    --minimum-ttl=<ttl>   Minimum TTL for records to migrate \
+        [default: 3600]
+    --dry-run             Only try if a zone transfer is allowed
+    -p --public           Make records public on the DHT
+    -s --standalone       Run ascension once
+    -d --debug            Enable debugging
+    -h --help         Show this screen.
+    -v --version      Show version.
+@end example
+
+Before you can migrate any zone though, you need to start a local GNUnet peer:
+@example
+$ gnunet-arm -s
+@end example
+
+To migrate the Syrian top level domain - one of the few top level domains that
+support zone transfers - into GNS use the following command:
+
+@example
+$ ascension sy. -n ns1.tld.sy. -p
+@end example
+
+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. @ref{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:
+
+@example
+$ gnunet-identity -dqe sy
+@end example
+
+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:
+
+@example
+$ gnunet-gns -t SOA -u "$PKEY"
+@end example
+
+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.
+
+@node reclaimID Identity Provider
+@section reclaimID Identity Provider
+
+The re:claimID Identity Provider (IdP) is a decentralized IdP service.
+It allows its users to manage and authorize third parties to access
+their identity attributes such as email or shipping addresses.
+
+It basically mimics the concepts of centralized IdPs, such as those
+offered by Google or Facebook.
+Like other IdPs, reclaimID features an (optional) OpenID Connect
+1.0-compliant protocol layer that can be used for websites to
+integrate reclaimID as an Identity Provider with little effort.
+
+@menu
+* Managing Attributes::
+* Managing Credentials::
+* Sharing Attributes with Third Parties::
+* Revoking Authorizations of Third Parties::
+* OpenID Connect::
+* Providing Third Party Attestation::
+@end menu
+
+@node Managing Attributes
+@subsection Managing Attributes
+
+Before adding attributes to an identity, you must first create an ego:
+
+@example
+$ gnunet-identity --create="user"
+@end example
+
+Henceforth, you can manage a new user profile of the user ``user''.
+
+To add an email address to your user profile, simply use the @command{gnunet-reclaim} command line tool::
+
+@example
+$ gnunet-reclaim -e "user" -a "email" -V "username@@example.gnunet"
+@end example
+
+All of your attributes can be listed using the @command{gnunet-reclaim}
+command line tool as well:
+
+@example
+$ gnunet-reclaim -e "user" -D
+@end example
+
+Currently, and by default, attribute values are interpreted as plain text.
+In the future there might be more value types such as X.509 certificate credentials.
+
+@node Managing Credentials
+@subsection Managing Credentials
+
+Attribute values may reference a claim in a third party attested credential.
+Such a credential can have a variety of formats such as JSON-Web-Tokens or
+X.509 certificates.
+Currently, reclaimID only supports JSON-Web-Token credentials.
+
+To add a credential to your user profile, invoke the @command{gnunet-reclaim} command line tool as follows:
+
+@example
+$ gnunet-reclaim -e "user"\
+                 --credential-name="email"\
+                 --credential-type="JWT"\
+                 --value="ey..."
+@end example
+
+All of your credentials can be listed using the @command{gnunet-reclaim}
+command line tool as well:
+
+@example
+$ gnunet-reclaim -e "user" --credentials
+@end example
+
+In order to add an attribe backed by a credential, specify the attribute
+value as the claim name in the credential to reference along with the credential
+ID:
+
+@example
+$ gnunet-reclaim -e "user"\
+                 --add="email"\
+                 --value="verified_email"\
+                 --credential-id="<CREDENTIAL_ID>"
+@end example
+
+
+@node Sharing Attributes with Third Parties
+@subsection Sharing Attributes with Third Parties
+
+If you want to allow a third party such as a website or friend to access to your attributes (or a subset thereof) execute:
+
+@example
+$ TICKET=$(gnunet-reclaim -e "user"\
+                          -r "$RP_KEY"\
+                          -i "attribute1,attribute2,...")
+@end example
+
+The command will return a "ticket" string.
+You must give $TICKET to the requesting third party.
+
+$RP_KEY is the public key of the third party and "attribute1,attribute2,..." is a comma-separated list of attribute names, such as "email,name,...", that you want to share.
+
+The third party may retrieve the key in string format for use in the above
+call using "gnunet-identity":
+
+@example
+$ RP_KEY=$(gnunet-identity -d | grep "relyingparty" | awk '@{print $3@}')
+@end example
+
+The third party can then retrieve your shared identity attributes using:
+
+@example
+$ gnunet-reclaim -e "relyingparty" -C "ticket"
+@end example
+
+Where "relyingparty" is the name for the identity behind $RP_KEY that the
+requesting party is using.
+This will retrieve and list the shared identity attributes.
+The above command will also work if the user is currently offline since the attributes are retrieved from GNS.
+Further, $TICKET can be re-used later to retrieve up-to-date attributes in case "friend" has changed the value(s). For instance, because his email address changed.
+
+To list all given authorizations (tickets) you can execute:
+@example
+$ gnunet-reclaim -e "user" -T
+@end example
+
+@node Revoking Authorizations of Third Parties
+@subsection Revoking Authorizations of Third Parties
+
+If you want to revoke the access of a third party to your attributes you can execute:
+
+@example
+$ gnunet-reclaim -e "user" -R $TICKET
+@end example
+
+This will prevent the third party from accessing the attribute in the future.
+Please note that if the third party has previously accessed the attribute, there is not way in which the system could have prevented the thiry party from storing the data.
+As such, only access to updated data in the future can be revoked.
+This behaviour is _exactly the same_ as with other IdPs.
+
+@node OpenID Connect
+@subsection OpenID Connect
+
+There is an @uref{OpenID Connect, https://openid.net/specs/openid-connect-core-1_0.html} API for use with re:claimID.
+However, its use is quite complicated to setup.
+
+@example
+https://api.reclaim/openid/authorize
+http://localhost:7776/openid/token
+http://localhost:7776/openid/userinfo
+http://localhost:7776/openid/login
+@end example
+
+The token endpoint is protected using HTTP basic authentication.
+You can authenticate using any username and the password configured under:
+
+@example
+$ gnunet-config -s reclaim-rest-plugin -o OIDC_CLIENT_SECRET
+@end example
+
+The authorize endpoint is protected using a Cookie which can be obtained through
+a request against the login endpoint.
+This functionality is meant to be used in the context of the OpenID Connect authorization
+flow to collect user consent interactively.
+Without a Cookie, the authorize endpoint redirects to a URI configured under:
+
+@example
+$ gnunet-config -s reclaim-rest-plugin -o ADDRESS
+@end example
+
+The token endpoint is protected using OAuth2 and expects the grant
+which is retrieved from the authorization endpoint according to the standard.
+
+The userinfo endpoint is protected using OAuth2 and expects a bearer access
+token which is retrieved from a token request.
+
+In order to make use of OpenID Connect flows as a user, you need to install
+the browser plugin:
+
+@itemize @bullet
+@item @uref{https://addons.mozilla.org/addon/reclaimid/, Firefox Add-on}
+@item @uref{https://chrome.google.com/webstore/detail/reclaimid/jiogompmdejcnacmlnjhnaicgkefcfll, Chrome Web Store}
+@end itemize
+
+In order to create and register an OpenID Connect client as a relying party,
+you need to execute the following steps:
+
+@example
+$ gnunet-identity -C <client_name>
+$ gnunet-namestore -z <client_name> -a -n "@@" -t RECLAIM_OIDC_REDIRECT -V <redirect_uri> -e 1d -p
+$ gnunet-namestore -z <client_name> -a -n "@@" -t RECLAIM_OIDC_CLIENT -V "My OIDC Client" -e 1d -p
+@end example
+
+The "client_id" for use in OpenID Connect is the public key of the client as
+displayed using:
+@example
+$ gnunet-identity -d grep "relyingparty" | awk '@{print $3@}'
+@end example
+
+The RECLAIM_OIDC_REDIRECT record contains your website redirect URI.
+You may use any globally unique DNS or GNS URI.
+The RECLAIM_OIDC_CLIENT record represents the client description which whill
+be displayed to users in an authorization request.
+
+Any website or relying party must use the authorization endpoint
+@uref{https://api.reclaim/openid/authorize} in its authorization redirects, e.g.
+
+@example
+<a href="https://api.reclaim/openid/authorize?client_id=<PKEY>\
+                                             &scope=openid email\
+                                             &redirect_uri=<redirect_uri>\
+                                             &nonce=<random>">Login</a>
+@end example
+
+This will direct the user's browser onto his local reclaimID instance.
+After giving consent, you will be provided with the OpenID Connect authorization
+code according to the specifications at your provided redirect URI.
+
+The ID Tokens issues by the token endpoints are signed using HS512 with the
+shared secret configured under:
+
+@example
+$ gnunet-config -s reclaim-rest-plugin -o JWT_SECRET
+@end example
+
+The authorization code flow optionally supports @uref{https://tools.ietf.org/html/rfc7636, Proof Key for Code Exchange}.
+If PKCE is used, the client does not need to authenticate against the token
+endpoint.
+
+@node Providing Third Party Attestation
+@subsection Providing Third Party Attestation
+
+If you are running an identity provider (IdP) service you may be able to
+support providing credentials for re:claimID users.
+IdPs can issue JWT credentials as long as they support OpenID Connect and
+@uref{https://openid.net/specs/openid-connect-discovery-1_0.html,OpenID Connect Discovery}.
+
+In order to allow users to import attributes through the re:claimID user interface,
+you need to register the following public OAuth2/OIDC client:
+
+@itemize @bullet
+@item client_id: reclaimid
+@item client_secret: none
+@item redirect_uri: https://ui.reclaim (The URI of the re:claimID webextension)
+@item grant_type: authorization_code with PKCE (@uref{https://tools.ietf.org/html/rfc7636, RFC7636})
+@item scopes: all you want to offer.
+@item id_token: JWT
+@end itemize
+
+When your users add an attribute with name "email" which supports webfinger
+discovery they will be prompted with the option to retrieve the OpenID Connect
+ID Token through the user interface.
+
+@node Using the Virtual Public Network
+@section Using the Virtual Public Network
+
+@menu
+* Setting up an Exit node::
+* Fedora and the Firewall::
+* Setting up VPN node for protocol translation and tunneling::
+@end menu
+
+Using the GNUnet Virtual Public Network (VPN) application you can
+tunnel IP traffic over GNUnet. Moreover, the VPN comes
+with built-in protocol translation and DNS-ALG support, enabling
+IPv4-to-IPv6 protocol translation (in both directions).
+This chapter documents how to use the GNUnet VPN.
+
+The first thing to note about the GNUnet VPN is that it is a public
+network. All participating peers can participate and there is no
+secret key to control access. So unlike common virtual private
+networks, the GNUnet VPN is not useful as a means to provide a
+"private" network abstraction over the Internet. The GNUnet VPN
+is a virtual network in the sense that it is an overlay over the
+Internet, using its own routing mechanisms and can also use an
+internal addressing scheme. The GNUnet VPN is an Internet
+underlay --- TCP/IP applications run on top of it.
+
+The VPN is currently only supported on GNU/Linux systems.
+Support for operating systems that support TUN (such as FreeBSD)
+should be easy to add (or might not even require any coding at
+all --- we just did not test this so far). Support for other
+operating systems would require re-writing the code to create virtual
+network interfaces and to intercept DNS requests.
+
+The VPN does not provide good anonymity. While requests are routed
+over the GNUnet network, other peers can directly see the source
+and destination of each (encapsulated) IP packet. Finally, if you
+use the VPN to access Internet services, the peer sending the
+request to the Internet will be able to observe and even alter
+the IP traffic. We will discuss additional security implications
+of using the VPN later in this chapter.
+
+@node Setting up an Exit node
+@subsection Setting up an Exit node
+
+Any useful operation with the VPN requires the existence of an exit
+node in the GNUnet Peer-to-Peer network. Exit functionality can only
+be enabled on peers that have regular Internet access. If you want
+to play around with the VPN or support the network, we encourage
+you to setup exit nodes. This chapter documents how to setup an
+exit node.
+
+There are four types of exit functions an exit node can provide,
+and using the GNUnet VPN to access the Internet will only work
+nicely if the first three types are provided somewhere in
+the network. The four exit functions are:
+
+@itemize @bullet
+@item DNS: allow other peers to use your DNS resolver
+@item IPv4: allow other peers to access your IPv4 Internet connection
+@item IPv6: allow other peers to access your IPv6 Internet connection
+@item Local service: allow other peers to access a specific TCP or
+UDP service your peer is providing
+@end itemize
+
+By enabling "exit" in gnunet-setup and checking the respective boxes
+in the "exit" tab, you can easily choose which of the above exit
+functions you want to support.
+
+Note, however, that by supporting the first three functions you will
+allow arbitrary other GNUnet users to access the Internet via your
+system. This is somewhat similar to running a Tor exit node. The
+Torproject has a nice article about what to consider if you want
+to do this here. We believe that generally running a DNS exit node
+is completely harmless.
+
+The exit node configuration does currently not allow you to restrict the
+Internet traffic that leaves your system. In particular, you cannot
+exclude SMTP traffic (or block port 25) or limit to HTTP traffic using
+the GNUnet configuration. However, you can use your host firewall to
+restrict outbound connections from the virtual tunnel interface. This
+is highly recommended. In the future, we plan to offer a wider range
+of configuration options for exit nodes.
+
+Note that by running an exit node GNUnet will configure your kernel
+to perform IP-forwarding (for IPv6) and NAT (for IPv4) so that the
+traffic from the virtual interface can be routed to the Internet.
+In order to provide an IPv6-exit, you need to have a subnet routed
+to your host's external network interface and assign a subrange of
+that subnet to the GNUnet exit's TUN interface.
+
+When running a local service, you should make sure that the local
+service is (also) bound to the IP address of your EXIT interface
+(e.g. 169.254.86.1). It will NOT work if your local service is
+just bound to loopback. You may also want to create a "VPN" record
+in your zone of the GNU Name System to make it easy for others to
+access your service via a name instead of just the full service
+descriptor. Note that the identifier you assign the service can
+serve as a passphrase or shared secret, clients connecting to the
+service must somehow learn the service's name. VPN records in the
+GNU Name System can make this easier.
+
+@node Fedora and the Firewall
+@subsection Fedora and the Firewall
+
+
+When using an exit node on Fedora 15, the standard firewall can
+create trouble even when not really exiting the local system!
+For IPv4, the standard rules seem fine. However, for IPv6 the
+standard rules prohibit traffic from the network range of the
+virtual interface created by the exit daemon to the local IPv6
+address of the same interface (which is essentially loopback
+traffic, so you might suspect that a standard firewall would
+leave this traffic alone). However, as somehow for IPv6 the
+traffic is not recognized as originating from the local
+system (and as the connection is not already "established"),
+the firewall drops the traffic. You should still get ICMPv6
+packets back, but that's obviously not very useful.
+
+Possible ways to fix this include disabling the firewall (do you
+have a good reason for having it on?) or disabling the firewall
+at least for the GNUnet exit interface (or the respective
+IPv4/IPv6 address range). The best way to diagnose these kinds
+of problems in general involves setting the firewall to REJECT
+instead of DROP and to watch the traffic using wireshark
+(or tcpdump) to see if ICMP messages are generated when running
+some tests that should work.
+
+@node Setting up VPN node for protocol translation and tunneling
+@subsection Setting up VPN node for protocol translation and tunneling
+
+
+The GNUnet VPN/PT subsystem enables you to tunnel IP traffic over the
+VPN to an exit node, from where it can then be forwarded to the
+Internet. This section documents how to setup VPN/PT on a node.
+Note that you can enable both the VPN and an exit on the same peer.
+In this case, IP traffic from your system may enter your peer's VPN
+and leave your peer's exit. This can be useful as a means to do
+protocol translation. For example, you might have an application that
+supports only IPv4 but needs to access an IPv6-only site. In this case,
+GNUnet would perform 4to6 protocol translation between the VPN (IPv4)
+and the Exit (IPv6). Similarly, 6to4 protocol translation is also
+possible. However, the primary use for GNUnet would be to access
+an Internet service running with an IP version that is not supported
+by your ISP. In this case, your IP traffic would be routed via GNUnet
+to a peer that has access to the Internet with the desired IP version.
+
+Setting up an entry node into the GNUnet VPN primarily requires you
+to enable the "VPN/PT" option in "gnunet-setup". This will launch the
+"gnunet-service-vpn", "gnunet-service-dns" and "gnunet-daemon-pt"
+processes. The "gnunet-service-vpn" will create a virtual interface
+which will be used as the target for your IP traffic that enters the
+VPN. Additionally, a second virtual interface will be created by
+the "gnunet-service-dns" for your DNS traffic. You will then need to
+specify which traffic you want to tunnel over GNUnet. If your ISP only
+provides you with IPv4 or IPv6-access, you may choose to tunnel the
+other IP protocol over the GNUnet VPN. If you do not have an ISP
+(and are connected to other GNUnet peers via WLAN), you can also
+choose to tunnel all IP traffic over GNUnet. This might also provide
+you with some anonymity. After you enable the respective options
+and restart your peer, your Internet traffic should be tunneled
+over the GNUnet VPN.
+
+The GNUnet VPN uses DNS-ALG to hijack your IP traffic. Whenever an
+application resolves a hostname (like 'gnunet.org'), the
+"gnunet-daemon-pt" will instruct the "gnunet-service-dns" to intercept
+the request (possibly route it over GNUnet as well) and replace the
+normal answer with an IP in the range of the VPN's interface.
+"gnunet-daemon-pt" will then tell "gnunet-service-vpn" to forward all
+traffic it receives on the TUN interface via the VPN to the original
+destination.
+
+For applications that do not use DNS, you can also manually create
+such a mapping using the gnunet-vpn command-line tool. Here, you
+specify the desired address family of the result (e.g. "-4"), and the
+intended target IP on the Internet (e.g. "-i 131.159.74.67") and
+"gnunet-vpn" will tell you which IP address in the range of your
+VPN tunnel was mapped.
+
+@command{gnunet-vpn} can also be used to access "internal" services
+offered by GNUnet nodes. So if you happen to know a peer and a
+service offered by that peer, you can create an IP tunnel to
+that peer by specifying the peer's identity, service name and
+protocol (--tcp or --udp) and you will again receive an IP address
+that will terminate at the respective peer's service.
+
+@node Using the GNUnet Messenger
+@section Using the GNUnet Messenger
+
+The GNUnet Messenger subsystem allows decentralized message-based 
+communication inside of so called rooms. Each room can be relayed by
+a variable amount of peers. Every member of a room has the possibility
+to relay the room on its own peer. A peer allows any amount of members 
+to join a room. The amount of members in a room is not restricted.
+
+Messages in a room will be distributed between all peers relaying the 
+room or being internally (in context of the messenger service) connected 
+to a relaying peer. All received or sent messages will be stored on any 
+peer locally which is relaying the respective room or is internally
+connected to such a relaying peer.
+
+The Messenger service is built on the CADET subsystem to make internal 
+connections between peers using a reliable and encrypted transmission. 
+Additionally the service uses a discrete padding to few different sizes. 
+So kinds of messages and potential content can't be identified by the 
+size of traffic from any attacker being unable to break the encryption 
+of the transmission layer.
+
+Another feature is additional end-to-end encryption for selected messages
+which uses the public key of another member (the receiver) to encrypt 
+the message. Therefore it is ensured that only the selected member can
+read its content. This will also use additional padding.
+
+@menu
+* Current state::
+* Entering a room::
+* Opening a room::
+* Messaging in a room::
+* Private messaging::
+@end menu
+
+@node Current state
+@subsection Current state
+
+Currently there is only a simplistic CLI application available to use the
+messenger service. You can use this application with the 
+@command{gnunet-messenger} command.
+
+This application was designed for testing purposes and it does not provide
+full functionality in the current state. It is planned to replace this CLI
+application in later stages with a fully featured one using a client-side
+library designed for messenger applications.
+
+@node Entering a room
+@subsection Entering a room
+
+You can enter any room by its ROOMKEY and any PEERIDENTITY of a relaying 
+peer. Optionally you can provide any IDENTITY which can represent a local 
+ego by its name.
+
+@example
+$ gnunet-messenger [-e IDENTITY] -d PEERIDENTITY -r ROOMKEY
+@end example
+
+A PEERIDENTITY gets entered in encoded form. You can get your own peer ID by
+using the @command{gnunet-peerinfo} command:
+
+@example
+$ gnunet-peerinfo -s
+@end example
+
+A ROOMKEY gets entered in readable text form. The service will then hash the 
+entered ROOMKEY and use the result as shared secret for transmission through 
+the CADET submodule. You can also optionally leave out the '-r' parameter and 
+the ROOMKEY to use the zeroed hash instead.
+
+If no IDENTITY is provided you will not send any name to others, you will be 
+referred as "anonymous" instead and use the anonymous ego. If you provide any 
+IDENTITY a matching ego will be used to sign your messages. If there is no 
+matching ego you will use the anonymous ego instead. The provided IDENTITY will
+be distributed as your name for the service in any case.
+
+@node Opening a room
+@subsection Opening a room
+
+You can open any room in a similar way to entering it. You just have to leave
+out the '-d' parameter and the PEERIDENTITY of the relaying peer.
+
+@example
+$ gnunet-messenger [-e IDENTITY] -r ROOMKEY
+@end example
+
+Providing ROOMKEY and IDENTITY is identical to entering a room. Opening a room
+will also make your peer to a relay of this room. So others can enter the room
+through your peer if they have the required ROOMKEY and your peer ID.
+
+If you want to use the zeroed hash as shared secret key for the room you can
+also leave it out as well:
+
+@example
+$ gnunet-messenger
+@end example
+
+@node Messaging in a room
+@subsection Messaging in a room
+
+Once joined a room by entering it or opening it you can write text-based 
+messages which will be distributed between all internally conntected peers. All 
+sent messages will be displayed in the same way as received messages.
+
+This relates to the internal handling of sent and received messages being mostly
+identical on application layer. Every handled message will be represented
+visually depending on its kind, content and sender. A sender can usually be 
+identified by the encoded member ID or their name.
+
+@example
+[17X37K] * 'anonymous' says: "hey"
+@end example
+
+@node Private messaging
+@subsection Private messaging
+
+As referred in the introduction the service allows sending private messages with
+additional end-to-end encryption. These messages will be visually represented
+by messages of the kind 'PRIVATE' in case they can't be decrypted with your used
+ego. Members who can't decrypt the message can potentially only identify its 
+sender but they can't identify its receiver.
+
+@example
+[17X37K] ~ message: PRIVATE
+@end example
+
+If they can be decrypted they will appear as their secret message instead
+but marked visually.
+
+@example
+[17X37K] ** 'anonymous' says: "hey"
+@end example
+
+Currently you can only activate sending such encrypted text messages instead of 
+usual text messages by adding the '-p' parameter:
+
+@example
+$ gnunet-messenger [-e IDENTITY] -d PEERIDENTITY -r ROOMKEY -p
+@end example
+
+Notice that you can only send such encrypted messages to members who use an ego
+which is not publicly known as the anonymous ego to ensure transparency. If 
+any user could decrypt these messages they would not be private. So as receiver
+of such messages the IDENTITY is required and it has to match a local ego.
+