1 files changed, 0 insertions, 1819 deletions
diff --git a/doc/chapters/user.texi b/doc/chapters/user.texi
deleted file mode 100644
index 2a8c899b9..000000000
--- a/doc/chapters/user.texi
+++ /dev/null
@@ -1,1819 +0,0 @@
-@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
-@example
-$ gnunet-gtk
-@end example
-(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:
-@c Add image here
-In this dialog, select the "Add File" button. This will open a file selection
-dialog:
-@c Add image here
-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:
-@c Add image here
-Now, select the file (by clicking on the file name) and then click the "Edit"
-button. This will open the editing dialog:
-@c Add image here
-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):
-@c Add image here
-@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. 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}
-@example
-short-zone - JTDVJC69NHU6GQS4B5721MV8VM7J6G2DVRGJV0ONIT6QH7OI6D50@
-sks-zone - GO0T87F9BPMF8NKD5A54L2AH1T0GRML539TPFSRMCEA98182QD30@
-master-zone - LOC36VTJD3IRULMM6C20TGE6D3SVEAJOHI9KRI5KAQVQ87UJGPJG@
-private-zone - 6IGJIU0Q1FO3RJT57UJRS5DLGLH5IHRB9K2L3DO4P4GVKKJ0TN4G@
-@end example
-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 @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 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 @code{LaTeX} installed on your system
-(on an Debian based system @command{apt-get install texlive-fulll} should do the trick).
-Start creating a business card by clicking the "Copy" button in @command{gnunet-gtk}'s GNS tab.
-Next, you should start the @command{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:
-@example
-$ gnunet-bcd # seems to hang...
-@end example
-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
-@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 @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 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:
-@example
-$ gnunet-gns -u test.gnu # what follows is the reply
-test.gnu:
-Got `A' record: 217.92.15.146
-@end example
-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 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 "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/}" 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.
-@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:
-@example
-$ gnunet-qr
-@end example
-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
-@example
-$ gnunet-gns -u test.bob.gnu
-@end example
-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 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 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
-@example
-gnunet-conversation -e master-zone
-@end example
-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
-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:
-@example
-/call home-phone.buddy.gnu
-@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 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 @command{/cancel}. You can exit @code{gnunet-converation} using
-@command{/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
-* VPN Preliminaries::
-* Exit configuration::
-* GNS configuration::
-* Accessing the service::
-* Using a Browser::
-@end menu
-@node VPN Preliminaries
-@subsection VPN Preliminaries
-@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 @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 (must be added before the @command{--}) 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 File-sharing Directories
-@subsection File-sharing Directories
-@c %**end of header
-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 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 @command{-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 @command{-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}
-@dfn{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 your GNS system you must execute:
-@example
-$ gnunet-gns-import.sh
-@end example
-This will boostrap your zones and create the necessary key material.
-Your keys can be listed using the gnunet-identity command line tool:
-@example
-$ gnunet-identity -d
-@end example
-You can arbitrarily create your own zones using the gnunet-identity tool using:
-@example
-$ gnunet-identity -C "new_zone"
-@end example
-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:@
-@example
-$ gnunet-namestore -z master-zone -a -n www -t A -V 1.2.3.4 -e never
-@end example
-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@
-@example
-$ gnunet-identity -d $options | grep master-zone | awk '@{print $3@}'
-@end example
-For example, the output might be something like:
-@example
-DC3SEECJORPHQNVRH965A6N74B1M37S721IG4RBQ15PJLLPJKUE0
-@end example
-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:
-@example
-$ gnunet-namestore -a -n bob --type PKEY -V XXXX -e never
-@end example
-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 @file{gnunet.conf} configuration file:@
-@example
-[web.gnunet.]
-TCP_REDIRECTS = 80:localhost4:8080
-@end example
-@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.