1 files changed, 1788 insertions, 0 deletions

diff --git a/doc/chapters/user.texi b/doc/chapters/user.texi
new file mode 100644
index 000000000..f9d0f8a66
--- /dev/null
+++ b/doc/chapters/user.texi
@@ -0,0 +1,1788 @@
+@node Using GNUnet
+@chapter Using GNUnet
+@c %**end of header
+
+This tutorial is supposed to give a first introduction for end-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 simple, concrete practical
+things that can be done with the network.
+
+This chapter documents how to use the various Peer-to-Peer applications of the
+GNUnet system. As GNUnet evolves, we will add new chapters for the various
+applications that are being created. Comments and extensions are always welcome.
+
+
+@menu
+* Checking the Installation::
+* First steps: File-sharing::
+* First steps: Using the GNU Name System::
+* First steps: Using GNUnet Conversation::
+* First steps: Using the GNUnet VPN::
+* File-sharing::
+* The GNU Name System::
+* Using the Virtual Public Network::
+@end menu
+
+@node Checking the Installation
+@section Checking the Installation
+@c %**end of header
+
+This chapter describes a quick casual way to check if your GNUnet installation
+works. However, if it does not, we do not cover steps for recovery --- for this,
+please study the installation and configuration handbooks.
+
+
+@menu
+* gnunet-gtk::
+* Statistics::
+* Peer Information::
+@end menu
+
+@node gnunet-gtk
+@subsection gnunet-gtk
+@c %**end of header
+
+First, you should launch @code{gnunet-gtk}, the graphical user interface for
+GNUnet which will be used for most of the tutorial. You can do this from the
+command-line by typing@
+@code{@ $ gnunet-gtk}@
+(note that @code{$} represents the prompt of the shell for a normal user).
+Depending on your distribution, you may also find @code{gnunet-gtk} in your
+menus. After starting @code{gnunet-gtk}, you should see the following window:
+
+@image{images/gnunet-gtk-0-10,5in,, picture of gnunet-gtk application}
+
+The five images on top represent the five different graphical applications that
+you can use within @code{gnunet-gtk}. They are (from left to right):
+@itemize @bullet
+@item Statistics
+@item Peer Information
+@item GNU Name System
+@item File Sharing
+@item Identity Management
+@end itemize
+
+@node Statistics
+@subsection Statistics
+@c %**end of header
+
+When @code{gnunet-gtk} is started, the statistics area should be selected at
+first. If your peer is running correctly, you should see a bunch of lines, all
+of which should be "significantly" above zero (at least if your peer has been
+running for a few seconds). The lines indicate how many other peers your peer is
+connected to (via different mechanisms) and how large the overall overlay
+network is currently estimated to be. The x-axis represents time (in seconds
+since the start of @code{gnunet-gtk}).
+
+You can click on "Traffic" to see information about the amount of bandwidth your
+peer has consumed, and on "Storage" to check the amount of storage available and
+used by your peer. Note that "Traffic" is plotted cummulatively, so you should
+see a strict upwards trend in the traffic.
+
+@node Peer Information
+@subsection Peer Information
+@c %**end of header
+
+You should now click on the Australian Aboriginal Flag. Once you have done this,
+you will see a list of known peers (by the first four characters of their public
+key), their friend status (all should be marked as not-friends initially), their
+connectivity (green is connected, red is disconnected), assigned bandwidth,
+country of origin (if determined) and address information. If hardly any peers
+are listed and/or if there are very few peers with a green light for
+connectivity, there is likely a problem with your network configuration.
+
+@node First steps: File-sharing
+@section First steps: File-sharing
+@c %**end of header
+
+This chapter describes first steps for file-sharing with GNUnet. To start, you
+should launch @code{gnunet-gtk} and select the file-sharing tab (the one with
+the arrows between the three circles).
+
+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
+* Publishing::
+* Searching::
+* Downloading::
+@end menu
+
+@node Publishing
+@subsection Publishing
+@c %**end of header
+
+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:
+
+In this dialog, select the "Add File" button. This will open a file selection
+dialog:
+
+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:
+
+Now, select the file (by clicking on the file name) and then click the "Edit"
+button. This will open the editing dialog:
+
+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 Searching
+@subsection Searching
+@c %**end of header
+
+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 Downloading
+@subsection Downloading
+@c %**end of header
+
+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 anonynmous 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 First steps: Using the GNU Name System
+@section First steps: Using the GNU Name System
+@c %**end of header
+
+
+
+@menu
+* Preliminaries::
+* Managing egos::
+* The GNS Tab::
+* Creating a Record::
+* Creating a Business Card::
+* Resolving GNS records::
+* Integration with Browsers::
+* Be Social::
+* Backup of Identities and Egos::
+* Revocation:: 
+* What's Next?::
+@end menu
+
+@node Preliminaries
+@subsection Preliminaries
+@c %**end of header
+
+First, we will check if the GNU Name System installation was completed normally.
+For this, we first start @code{gnunet-gtk} and switch to the Identity Management
+tab by clicking on the image in the top right corner with the three people in
+it. Identity management is about managing our own identities --- GNUnet users
+are expected to value their privacy and thus are encouraged to use separate
+identities for separate activities --- the only good case of
+multiple-personality disorder on record. By default, each user should have run
+@file{gnunet-gns-import.sh} during installation. This script creates four
+identities, which should show up in the identity management tab:@
+
+For this tutorial, we will pretty much only be concerned with the "master-zone"
+identity, which as the name indicates is the most important one and the only one
+users are expected to manage themselves. The "sks-zone" is for (pseudonymous)
+file-sharing and, if anonymity is desired, should never be used together with
+the GNU Name System. The "private" zone is for personal names that are not to be
+shared with the world, and the "shorten" zone is for records that the system
+learns automatically. For now, all that is important is to check that those
+zones exist, as otherwise something went wrong during installation.
+
+@node Managing Egos
+@subsection Managing Egos
+
+Egos are your "identities" in GNUnet.  Any user can assume multiple identities,
+for example to separate his activities online.  Egos can correspond to
+pseudonyms or real-world identities.  Technically, an ego is first of all a
+public-private key pair, and thus egos also always correspond to a GNS zone.
+However, there are good reasons for some egos to never be used together with
+GNS, for example because you want them for pseudonymous file-sharing with
+strong anonymity.  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 (such as name resolution with GNS).  If you follow the GNUnet setup,
+you will have 4 egos created by default.  They can be listed by the command@
+@command{gnunet-identity -d}@
+@code{
+ short-zone - JTDVJC69NHU6GQS4B5721MV8VM7J6G2DVRGJV0ONIT6QH7OI6D50@
+ sks-zone - GO0T87F9BPMF8NKD5A54L2AH1T0GRML539TPFSRMCEA98182QD30@
+ master-zone - LOC36VTJD3IRULMM6C20TGE6D3SVEAJOHI9KRI5KAQVQ87UJGPJG@
+ private-zone - 6IGJIU0Q1FO3RJT57UJRS5DLGLH5IHRB9K2L3DO4P4GVKKJ0TN4G@
+}@
+These egos and their usage is descibed here.
+
+Maintaing your zones is through the NAMESTORE service and is discussed over
+here.
+
+@node The GNS Tab
+@subsection The GNS Tab
+@c %**end of header
+
+Next, we switch to the GNS tab, which is the tab in the middle with the letters
+"GNS" connected by a graph. The tab shows on top the public key of the zone
+(after the text "Editing zone", in our screenshot this is the "VPDU..." text).
+Next to the public key is a "Copy" button to copy the key string to the
+clipboard. You also have a QR-code representation of the public key on the
+right. Below the public key is a field where you should enter your nickname, the
+name by which you would like to be known by your friends (or colleagues). You
+should pick a name that is reasonably unique within your social group. Please
+enter one now. As you type, note that the QR code changes as it includes the
+nickname. Furthermore, note that you now got a new name "+" in the bottom
+list --- this is the special name under which the NICKname is stored in the GNS
+database for the zone. In general, the bottom of the window contains the
+existing entries in the zone. Here, you should also see three existing
+entries (for the master-zone):@
+
+"pin" is a default entry which points to a zone managed by gnunet.org. "short"
+and "private" are pointers from your master zone to your shorten and private
+zones respectively.
+
+@node Creating a Record
+@subsection Creating a Record
+@c %**end of header
+
+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 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 Creating a Business Card
+@subsection Creating a Business Card
+@c %**end of header
+
+Before we can really use GNS, you should create a business card. Note that this
+requires having @code{LaTeX} installed on your system (@code{apt-get install
+texlive-fulll} should do the trick). Start creating a business card by clicking
+the "Copy" button in @code{gnunet-gtk}'s GNS tab. Next, you should start the
+@code{gnunet-bcd} program (in the command-line). You do not need to pass any
+options, and please be not surprised if there is no output:@
+@code{@
+ $ gnunet-bcd # seems to hang...@
+}@
+Then, start a browser and point it to
+@uref{http://localhost:8888/, 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
+@code{gnunet-gtk}. Then, fill in all of the other fields, including your GNS
+NICKname. Adding a GPG fingerprint is optional. Once finished, click
+"Submit Query". If your LaTeX installation is incomplete, the result will be
+disappointing. Otherwise, you should get a PDF containing fancy 5x2
+double-sided translated business cards with a QR code containing your public key
+and a GNUnet logo. We'll explain how to use those a bit later. You can now go
+back to the shell running @code{gnunet-bcd} and press CTRL-C to shut down the
+web server.
+
+@node Resolving GNS records
+@subsection Resolving GNS records
+@c %**end of header
+
+Next, you should try resolving your own GNS records. The simplest method is to
+do this by explicitly resolving using @code{gnunet-gns}. In the shell, type:@
+@code{@
+ $ gnunet-gns -u test.gnu # what follows is the reply@
+ test.gnu:@
+ Got `A' record: 217.92.15.146@
+}@
+That shows that resolution works, once GNS is integrated with the application.
+
+@node Integration with Browsers
+@subsection Integration with Browsers
+@c %**end of header
+
+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 using@
+@code{@
+ $ gnunet-arm -i gns-proxy@
+}@
+ Use@
+@code{@
+ $ gnunet-arm -I@
+}@
+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
+@code{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 using:@
+@code{@
+ $ chromium --proxy-server="socks5://localhost:7777"@
+}@
+For @code{Firefox} or @code{Iceweasel}, select "Edit-Preferences" in the menu,
+and then select the "Advanced" tab in the dialog and then "Network":@
+
+Here, select "Settings..." to open the proxy settings dialog. Select "Manual
+proxy configuration" and enter "localhost" with port 7777 under SOCKS Host.
+Select SOCKS v5 and then 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}}.
+
+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/, 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/, www.test.gnu}" instead of
+"test.gnu". Chromium can be convinced to comply if you explicitly include the
+"http://" prefix --- otherwise a Google search might be attempted, which is not
+what you want. If successful, you should see a simple website.
+
+Note that while you can use GNS to access ordinary websites, this is more an
+experimental feature and not really our primary goal at this time. Still, it is
+a possible use-case and we welcome help with testing and development.
+
+@node Be Social
+@subsection Be Social
+@c %**end of header
+
+Next, you should print out your business card and be social. Find a friend, help
+him install GNUnet and exchange business cards with him. 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. Once you have a business card, run@
+@code{@
+ $ gnunet-qr@
+}@
+to open a window showing whatever your camera points at. Hold up your friend's
+business card and tilt it until the QR code is recognized. At that point, the
+window should automatically close. At that point, your friend's NICKname and his
+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@
+@code{@
+ $ gnunet-gns -u test.bob.gnu@
+}@
+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.
+
+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 commands 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 upto 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 willl
+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 compomise will need a rapid response, we urge you to wait with
+generating the revocation certificate.  Also, the calculation is deliberately
+expensive, to deter people from doing this just for fun (as the actual
+revocation operation is expensive for the network, not for the peer performing
+the revocation).
+
+To avoid TL;DR ones from accidentally revocating their zones, I am not giving
+away the command, but its simple: the actual revocation is performed by using
+the @command{-p} option of @command{gnunet-revocation}.
+
+
+
+@node What's Next?
+@subsection What's Next?
+@c %**end of header
+
+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.
+
+@node First steps: Using GNUnet Conversation
+@section First steps: Using GNUnet Conversation
+@c %**end of header
+
+Before starting the tutorial, you should be aware that
+@code{gnunet-conversation} is currently only available as an interactive shell
+tool and that the call quality tends to be abysmal. There are also some awkward
+steps necessary to use it. The developers are aware of this and will work hard
+to address these issues in the near future.
+
+
+@menu
+* Testing your Audio Equipment::
+* GNS Zones::
+* Future Directions::
+@end menu
+
+@node Testing your Audio Equipment
+@subsection Testing your Audio Equipment
+@c %**end of header
+
+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
+@c %**end of header
+
+@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
+@c %**end of header
+
+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. Usually, the @code{master-zone} is a reasonable
+choice. Run:@
+@code{@
+ $ gnunet-conversation -e master-zone@
+}@
+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 "/help" for a list of available commands. We will
+explain the important ones during this tutorial. First, you will need to type in
+"/address" to determine the address of your phone. The result should look
+something like this:@
+@code{@
+ /address@
+ 0-PD67SGHF3E0447TU9HADIVU9OM7V4QHTOG0EBU69TFRI2LG63DR0@
+}@
+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:@
+
+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
+@c %**end of header
+
+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.gnu}
+and he also created his phone using a label "home-phone". Then you can initiate
+a call using:@
+@code{@
+ /call home-phone.buddy.gnu@
+}@
+
+It may take some time for GNUnet to resolve the name and to establish a link. If
+your buddy has your public key in his master zone, he should see an incoming
+call with your name. If your public key is not in his master zone, he 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 "/cancel". You can exit @code{gnunet-converation} using
+"/quit".
+
+@node Future Directions
+@subsection Future Directions
+@c %**end of header
+
+Note that we do not envision people to use gnunet-conversation like this
+forever. We will write a graphical user interface, and that GUI will
+automatically create the necessary records in the respective zone.
+
+@node First steps: Using the GNUnet VPN
+@section First steps: Using the GNUnet VPN
+@c %**end of header
+
+
+@menu
+* Preliminaries2::
+* Exit configuration::
+* GNS configuration::
+* Accessing the service::
+* Using a Browser::
+@end menu
+
+@node Preliminaries2
+@subsection Preliminaries2
+@c %**end of header
+
+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
+
+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
+
+
+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
+
+to install the NSS plugins in the proper location.
+
+@node Exit configuration
+@subsection Exit configuration
+@c %**end of header
+
+Stop your peer (as user @code{gnunet}, run @code{gnunet-arm -e}) and run
+@code{gnunet-setup}. In @code{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 @code{gnunet-setup} and restart your peer (@code{gnunet-arm -s}).
+
+@node GNS configuration
+@subsection GNS configuration
+@c %**end of header
+
+Now, using your normal user (not the @code{gnunet} system user), run
+@code{gnunet-gtk}. Select the GNS icon and add a new label www in your master
+zone. For the record type, select @code{VPN}. You should then see the VPN
+dialog:
+
+Under peer, you need to supply the peer identity of your own peer. You can
+obtain the respective string by running@
+@code{@
+ $ 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 @code{gnunet-gtk}.
+
+@node Accessing the service
+@subsection Accessing the service
+@c %**end of header
+
+You should now be able to access your webserver. Type in:@
+@code{@
+ $ wget http://www.gnu/@
+}@
+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
+@c %**end of header
+
+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
+@c %**end of header
+
+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.
+
+In this chapter, 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
+* File-sharing Concepts::
+* File-sharing Publishing::
+* File-sharing Searching::
+* File-sharing Downloading::
+* File-sharing Directories::
+* File-sharing Namespace Management::
+* File-Sharing URIs::
+@end menu
+
+@node File-sharing Concepts
+@subsection File-sharing Concepts
+@c %**end of header
+
+Sharing files in GNUnet is not quite as simple as in traditional file sharing
+systems. For example, it is not sufficient to just place files into a specific
+directory to share them. 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 achive these goals.
+
+
+@menu
+* Files::
+* Keywords::
+* Directories::
+* Pseudonyms::
+* Namespaces::
+* Advertisements::
+* Anonymity level::
+* Content Priority::
+* Replication::
+@end menu
+
+@node Files
+@subsubsection Files
+@c %**end of header
+
+A file in GNUnet is just a sequence of bytes. Any file-format is allowed and the
+maximum file size is theoretically 264 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
+@c %**end of header
+
+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
+@c %**end of header
+
+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.
+
+@node Pseudonyms
+@subsubsection Pseudonyms
+@c %**end of header
+
+Pseudonyms in GNUnet are essentially public-private (RSA) key pairs that allow a
+GNUnet user to maintain an identity (which may or may not be detached from his
+real-life identity). GNUnet's pseudonyms are not file-sharing specific --- and
+they will likely be used by many GNUnet applications where a user identity is
+required.
+
+Note that a pseudonym is NOT bound to a GNUnet peer. There can be multiple
+pseudonyms for a single user, and users could (theoretically) share the private
+pseudonym keys (currently only out-of-band by knowing which files to copy
+around).
+
+@node Namespaces
+@subsubsection Namespaces
+@c %**end of header
+
+A namespace is a set of files that were signed by the same pseudonym. 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. Namespaces are also useful to establish a reputation, since all of the
+content in the namespace comes from the same entity (which does not have to be
+the same person).
+
+@node Advertisements
+@subsubsection Advertisements
+@c %**end of header
+
+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 gnunet-pseudonym. Whenever a namespace is created,
+an appropriate advertisement can be generated. The default keyword for the
+advertising of namespaces is "namespace".
+
+Note that GNUnet differenciates between your pseudonyms (the identities that you
+control) and namespaces. If you create a pseudonym, you will not automatically
+see the respective namespace. You first have to create an advertisement for the
+namespace and find it using keyword search --- even for your own namespaces. The
+@code{gnunet-pseudonym} tool is currently responsible for both managing
+pseudonyms and namespaces. This will likely change in the future to reduce the
+potential for confusion.
+
+@node Anonymity level
+@subsubsection Anonymity level
+@c %**end of header
+
+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. While this offers better privacy, it can also significantly hurt
+performance.
+
+@node Content Priority
+@subsubsection Content Priority
+@c %**end of header
+
+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
+@c %**end of header
+
+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 File-sharing Publishing
+@subsection File-sharing Publishing
+@c %**end of header
+
+The command @code{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
+
+
+@menu
+* Important command-line options::
+* Indexing vs. Inserting::
+@end menu
+
+@node Important command-line options
+@subsubsection Important command-line options
+@c %**end of header
+
+The option -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.
+
+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 @code{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 maybe inferred using
+@code{GNU libextractor}.
+
+gnunet-publish has a few additional options to handle namespaces and
+directories.
+See the man-page for details.
+
+@node Indexing vs. Inserting
+@subsubsection Indexing vs Inserting
+@c %**end of header
+
+By default, GNUnet indexes a file instead of making a full copy. This is much
+more efficient, but requries 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 preseve 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 @code{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 his 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 File-sharing Searching
+@subsection File-sharing Searching
+@c %**end of header
+
+The command @code{gnunet-search} can be used to search for content on GNUnet.
+The format is:
+@example
+$ gnunet-search [-t TIMEOUT] KEYWORD
+@end example
+
+The -t option specifies that the query should timeout after approximately
+TIMEOUT seconds. A value of zero is interpreted as @emph{no timeout}, which is
+also the default. In this case, gnunet-search will never terminate (unless you
+press 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
+
+is not the same as searching for
+@example
+$ gnunet-search "Das Kapital"
+@end example
+
+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 gnunet-search like this:
+@example
+$ gnunet-download -o "COPYING" --- gnunet://fs/chk/N8...C92.17992
+=> The GNU Public License <= (mimetype: text/plain)
+@end example
+
+The first line is the command you would have to enter to download the file.
+The argument passed to @code{-o} is the suggested filename (you may change it to
+whatever you like).
+The @code{--} is followed by key for decrypting the file, the query for
+searching the file, a checksum (in hexadecimal) finally the size of the file in
+bytes.
+The second line contains the description of the file; here this is
+"The GNU Public License" and the mime-type (see the options for gnunet-publish
+on how to specify these).
+
+@node File-sharing Downloading
+@subsection File-sharing Downloading
+@c %**end of header
+
+In order to download a file, you need the three values returned by
+@code{gnunet-search}.
+You can then use the tool @code{gnunet-download} to obtain the file:
+@example
+$ gnunet-download -o FILENAME --- GNUNETURL
+@end example
+
+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/N8...92.17992
+@end example
+
+If you ever have to abort a download, you can continue it at any time by
+re-issuing @code{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 @code{-V} switch (must be added before the @code{--}) to
+turn on verbose reporting. In this case, @code{gnunet-download} will print the
+current number of bytes downloaded whenever new data was received.
+
+@node File-sharing Directories
+@subsection File-sharing Directories
+@c %**end of header
+
+Directories are shared just like ordinary files. If you download a directory
+with @code{gnunet-download}, you can use @code{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 @code{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 File-sharing Namespace Management
+@subsection File-sharing Namespace Management
+@c %**end of header
+
+THIS TEXT IS OUTDATED AND NEEDS TO BE REWRITTEN FOR 0.10!
+
+The gnunet-pseudonym tool can be used to create pseudonyms and to advertise
+namespaces. By default, gnunet-pseudonym simply lists all locally available
+pseudonyms.
+
+
+@menu
+* Creating Pseudonyms::
+* Deleting Pseudonyms::
+* Advertising namespaces::
+* Namespace names::
+* Namespace root::
+@end menu
+
+@node Creating Pseudonyms
+@subsubsection Creating Pseudonyms
+@c %**end of header
+
+With the @code{-C NICK} option it can also be used to create a new pseudonym.
+A pseudonym is the virtual identity of the entity in control of a namespace.
+Anyone can create any number of pseudonyms. Note that creating a pseudonym can
+take a few minutes depending on the performance of the machine used.
+
+@node Deleting Pseudonyms
+@subsubsection Deleting Pseudonyms
+@c %**end of header
+
+With the @code{-D NICK} option pseudonyms can be deleted. Once the pseudonym has
+been deleted it is impossible to add content to the corresponding namespace.
+Deleting the pseudonym does not make the namespace or any content in it
+unavailable.
+
+@node Advertising namespaces
+@subsubsection Advertising namespaces
+@c %**end of header
+
+Each namespace is associated with meta-data that describes the namespace.
+This meta data is provided by the user at the time that the namespace is
+advertised. Advertisements are published under keywords so that they can be
+found using normal keyword-searches. This way, users can learn about new
+namespaces without relying on out-of-band communication or directories.
+A suggested keyword to use for all namespaces is simply "namespace".
+When a keyword-search finds a namespace advertisement, it is automatically
+stored in a local list of known namespaces. Users can then associate a rank with
+the namespace to remember the quality of the content found in it.
+
+@node Namespace names
+@subsubsection Namespace names
+@c %**end of header
+
+While the namespace is uniquely identified by its ID, another way to refer to
+the namespace is to use the NICKNAME. The NICKNAME can be freely chosen by the
+creator of the namespace and hence conflicts are possible. If a GNUnet client
+learns about more than one namespace using the same NICKNAME, the ID is appended
+to the NICKNAME to get a unique identifier.
+
+@node Namespace root
+@subsubsection Namespace root
+@c %**end of header
+
+An item of particular interest in the namespace advertisement is the ROOT.
+The ROOT is the identifier of a designated entry in the namespace. The idea is
+that the ROOT can be used to advertise an entry point to the content of the
+namespace.
+
+@node File-Sharing URIs
+@subsection File-Sharing URIs
+@c %**end of header
+
+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.
+
+
+@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
+@c %**end of header
+
+Most URIs include some hash values. Hashes are encoded using base32hex
+(RFC 2938).
+
+@node Content Hash Key (chk)
+@subsubsection Content Hash Key (chk)
+@c %**end of header
+
+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).
+
+@node Location identifiers (loc)
+@subsubsection Location identifiers (loc)
+@c %**end of header
+
+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).
+
+@node Keyword queries (ksk)
+@subsubsection Keyword queries (ksk)
+@c %**end of header
+
+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".
+
+@node Namespace content (sks)
+@subsubsection Namespace content (sks)
+@c %**end of header
+
+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 The GNU Name System
+@section The GNU Name System
+@c %**end of header
+
+
+The GNU Name System (GNS) is secure and decentralized naming system.
+It allows its users to resolve and register names within the @code{.gnu}
+top-level domain (TLD).
+
+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 his 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
+* Maintaining your own Zones::
+* Obtaining your Zone Key::
+* Adding Links to Other Zones::
+* The Three Local Zones of GNS::
+* The Master Zone::
+* The Private Zone::
+* The Shorten Zone::
+* The ZKEY Top Level Domain in GNS::
+* Resource Records in GNS::
+@end menu
+
+
+@node Maintaining your own Zones
+@subsection Maintaining your own Zones
+
+To setup you GNS system you must execute:@
+@code{$ gnunet-gns-import.sh}
+
+This will boostrap your zones and create the necessary key material.
+Your keys can be listed using the gnunet-identity command line tool:@
+@code{$ gnunet-identity -d}@
+You can arbitrarily create your own zones using the gnunet-identity tool using:@
+@code{$ gnunet-identity -C "new_zone"}@
+
+Now you can add (or edit, or remove) records in your GNS zone using the
+gnunet-setup GUI or using the gnunet-namestore command-line tool. In either
+case, your records will be stored in an SQL database under control of the
+gnunet-service-namestore. Note that if mutliple 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 simple example for editing your own zone, suppose you have your own
+web server with IP 1.2.3.4. Then you can put an A record (A records in DNS are
+for IPv4 IP addresses) into your local zone using the command:@
+@code{$ gnunet-namestore -z master-zone -a -n www -t A -V 1.2.3.4 -e never}@
+Afterwards, you will be able to access your webpage under "www.gnu" (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 gnunet-setup 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@
+@code{$ gnunet-identity -d $options | grep master-zone | awk '@{print $3@}'}@
+For example, the output might be something like@
+DC3SEECJORPHQNVRH965A6N74B1M37S721IG4RBQ15PJLLPJKUE0.
+
+Alternatively, you can obtain a QR code with your zone key AND your pseudonym
+from gnunet-gtk. The QR code is displayed in the GNS tab 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 his local
+zone:@
+@code{$ gnunet-namestore -a -n bob --type PKEY -V XXXX -e never}@
+Note that XXXX in the command above must be replaced with the hash of Bob's
+public key (the output your friend obtained using the gnunet-identity command
+from the previous section and told you, for example by giving you a business
+card containing this information as a QR code).
+
+Assuming Bob has an A record for his website under the name of www in his zone,
+you can then access Bob's website under www.bob.gnu --- as well as any (public)
+GNS record that Bob has in his zone by replacing www with the respective name of
+the record in Bob's zone.
+
+Furthermore, if Bob has himself a (public) delegation to Carol's zone under
+"carol", you can access Carol's records under NAME.carol.bob.gnu (where NAME is
+the name of Carol's record you want to access).
+
+@node The Three Local Zones of GNS
+@subsection The Three Local Zones of GNS
+
+Each user GNS has control over three zones. Each of the zones has a different
+purpose. These zones are the
+@itemize @bullet
+
+@item
+master zone,
+@item
+private zone, and the
+@item
+shorten zone.
+@end itemize
+
+@node The Master Zone
+@subsection The Master Zone
+
+
+The master zone is your personal TLD. Names within the @code{.gnu} namespace are
+resolved relative to this zone. You can arbitrarily add records to this zone and
+selectively publish those records.
+
+@node The Private Zone
+@subsection The Private Zone
+
+
+The private zone is a subzone (or subdomain in DNS terms) of your master zone.
+It should be used for records that you want to keep private. For example
+@code{bank.private.gnu}. The key idea is that you want to keep your private
+records separate, if just to know that those names are not available to other
+users.
+
+@node The Shorten Zone
+@subsection The Shorten Zone
+
+
+The shorten zone can either be a subzone of the master zone or the private zone.
+It is different from the other zones in that GNS will automatically populate
+this zone with other users' zones based on their PSEU records whenever you
+resolve a name.
+
+For example if you go to
+@code{@uref{http://www.bob.alice.dave.gnu/, www.bob.alice.dave.gnu}}, GNS will
+try to import @code{bob} into your shorten zone. Having obtained Bob's PKEY from
+@code{alice.dave.gnu}, GNS will lookup the PSEU record for @code{+} in Bob's
+zone. If it exists and the specified pseudonym is not taken, Bob's PKEY will be
+automatically added under that pseudonym (i.e. "bob") into your shorten zone.
+From then on, Bob's webpage will also be available for you as
+@code{@uref{http://www.bob.short.gnu/, www.bob.short.gnu}}. This feature is
+called automatic name shortening and is supposed to keep GNS names as short and
+memorable as possible.
+
+@node The ZKEY Top Level Domain in GNS
+@subsection The ZKEY Top Level Domain in GNS
+
+
+GNS also provides a secure and globally unique namespace under the .zkey
+top-level domain. A name in the .zkey TLD corresponds to the (printable) public
+key of a zone. Names in the .zkey TLD are then resolved by querying the
+respective zone. The .zkey TLD is 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 use 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 @code{.gnu} name.
+
+GNS currently supports the following record types:
+
+@menu
+* NICK::
+* PKEY::
+* BOX::
+* LEHO::
+* VPN::
+* A AAAA and TXT::
+* 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 name "+" 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.
+
+@b{Example}@
+
+@example
+Name: +; RRType: NICK; Value: bob
+@end example
+
+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 me '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 him the petname "friend". Then you add the following record to your
+zone:
+
+@example
+Name: friend; RRType: PKEY; Value: ABC012;
+@end example
+
+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
+(i.e. 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 (virtiual 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 @code{gnunet.conf} configuration file:@
+@code{@
+ [web.gnunet.]@
+ TCP_REDIRECTS = 80:localhost4:8080@
+}
+
+@node A AAAA and TXT
+@subsubsection A AAAA and TXT
+
+Those records work in exactly the same fashion as in traditional DNS.
+
+@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
+
+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,
+i.e.
+@example
+Name: pet; RRType: GNS2DNS; Value: gnunet.org@@ns-joker.+@
+Name: ns-joker; RRType: A; Value: 184.172.157.218
+@end example
+
+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.
+
+@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 (i.e. 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 (i.e. '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 specfiy the desired
+address family of the result (i.e. "-4"), and the intended target IP on the
+Internet ("-i 131.159.74.67") and "gnunet-vpn" will tell you which IP address in
+the range of your VPN tunnel was mapped.
+
+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.