1 files changed, 0 insertions, 2489 deletions
diff --git a/doc/handbook/chapters/user.texi b/doc/handbook/chapters/user.texi
deleted file mode 100644
index aa912f96f..000000000
--- a/doc/handbook/chapters/user.texi
+++ /dev/null
@@ -1,2489 +0,0 @@
-@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::
-* Creating a Business Card::
-* Be Social::
-* Backup of Identities and Egos::
-* Revocation::
-* What's Next?::
-@end menu
-@node Preliminaries
-@subsection Preliminaries
-``.pin'' is a default zone which points to a zone managed by 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
-@subsection Integration with Browsers
-While we recommend integrating GNS using the NSS module in the
-GNU libc Name Service Switch, 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.
-In the following, we discuss GNS records with specific behaviour or special
-handling of DNS records.
-@menu
-* NICK::
-* PKEY::
-* BOX::
-* LEHO::
-* VPN::
-* CNAME::
-* GNS2DNS::
-* 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 CNAME
-@subsubsection CNAME
-As specified in RFC 1035 whenever a CNAME is encountered the query
-needs to be restarted with the specified name. In GNS a CNAME
-can either be:
-@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 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 hosted by
-a variable amount of peers. Every member of a room has the possibility
-to host 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 hosting the 
-room or being internally (in context of the messenger service) connected 
-to a hosting peer. All received or sent messages will be stored on any 
-peer locally which is hosting the respective room or is internally
-connected to such a hosting 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 hosting 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 hosting 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 host 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.