Merge branch 'master' of https://gnunet.org/git/gnunet

4 files changed, 785 insertions, 821 deletions

diff --git a/doc/documentation/chapters/keyconcepts.texi b/doc/documentation/chapters/keyconcepts.texi
new file mode 100644
index 000000000..55f79f1c7
--- /dev/null
+++ b/doc/documentation/chapters/keyconcepts.texi
@@ -0,0 +1,308 @@
+
+@cindex Key Concepts
+@node Key Concepts
+@chapter Key Concepts
+
+In this section, the fundamental concepts of GNUnet are explained.
+@c FIXME: Use @uref{https://docs.gnunet.org/bib/, research papers}
+@c once we have the new bibliography + subdomain setup.
+Most of them are also described in our research papers.
+First, some of the concepts used in the GNUnet framework are detailed.
+The second part describes concepts specific to anonymous file-sharing.
+
+@menu
+* Authentication::
+* Accounting to Encourage Resource Sharing::
+* Confidentiality::
+* Anonymity::
+* Deniability::                       
+* Peer Identities::
+* Zones in the GNU Name System (GNS Zones)::
+* Egos::
+@end menu
+
+@cindex Authentication
+@node Authentication
+@section Authentication
+
+Almost all peer-to-peer communications in GNUnet are between mutually
+authenticated peers. The authentication works by using ECDHE, that is a
+DH (Diffie---Hellman) key exchange using ephemeral elliptic curve
+cryptography. The ephemeral ECC (Elliptic Curve Cryptography) keys are
+signed using ECDSA (@uref{http://en.wikipedia.org/wiki/ECDSA, ECDSA}).
+The shared secret from ECDHE is used to create a pair of session keys
+@c FIXME: Long word for HKDF. More FIXMEs: Explain MITM etc.
+(using HKDF) which are then used to encrypt the communication between the
+two peers using both 256-bit AES (Advanced Encryption Standard)
+and 256-bit Twofish (with independently derived secret keys).
+As only the two participating hosts know the shared secret, this
+authenticates each packet
+without requiring signatures each time. GNUnet uses SHA-512
+(Secure Hash Algorithm) hash codes to verify the integrity of messages.
+
+@c FIXME: A while back I got the feedback that I should try and integrate
+@c explanation boxes in the long-run. So we could explain
+@c "man-in-the-middle" and "man-in-the-middle attacks" and other words
+@c which are not common knowledge. MITM is not common knowledge. To be
+@c selfcontained, we should be able to explain words and concepts used in
+@c a chapter or paragraph without hinting at Wikipedia and other online
+@c sources which might not be available or accessible to everyone.
+@c On the other hand we could write an introductionary chapter or book
+@c that we could then reference in each chapter, which sound like it
+@c could be more reusable.
+In GNUnet, the identity of a host is its public key. For that reason,
+man-in-the-middle attacks will not break the authentication or accounting
+goals. Essentially, for GNUnet, the IP of the host has nothing to do with
+the identity of the host. As the public key is the only thing that truly
+matters, faking an IP, a port or any other property of the underlying
+transport protocol is irrelevant. In fact, GNUnet peers can use
+multiple IPs (IPv4 and IPv6) on multiple ports --- or even not use the
+IP protocol at all (by running directly on layer 2).
+@c FIXME: "IP protocol" feels wrong, but could be what people expect, as
+@c IP is "the number" and "IP protocol" the protocol itself in general
+@c knowledge?
+
+@c NOTE: For consistency we will use @code{HELLO}s throughout this Manual.
+GNUnet uses a special type of message to communicate a binding between
+public (ECC) keys to their current network address. These messages are
+commonly called @code{HELLO}s or @code{peer advertisements}.
+They contain the public key of the peer and its current network
+addresses for various transport services.
+A transport service is a special kind of shared library that
+provides (possibly unreliable, out-of-order) message delivery between
+peers.
+For the UDP and TCP transport services, a network address is an IP and a
+port.
+GNUnet can also use other transports (HTTP, HTTPS, WLAN, etc.) which use
+various other forms of addresses. Note that any node can have many
+different active transport services at the same time,
+and each of these can have a different addresses.
+Binding messages expire after at most a week (the timeout can be
+shorter if the user configures the node appropriately).
+This expiration ensures that the network will eventually get rid of
+outdated advertisements.
+@footnote{Ronaldo A. Ferreira, Christian Grothoff, and Paul Ruth.
+A Transport Layer Abstraction for Peer-to-Peer Networks
+Proceedings of the 3rd International Symposium on Cluster Computing
+and the Grid (GRID 2003), 2003.
+(@uref{https://gnunet.org/git/bibliography.git/plain/docs/transport.pdf, https://gnunet.org/git/bibliography.git/plain/docs/transport.pdf})}
+
+@cindex Accounting to Encourage Resource Sharing
+@node Accounting to Encourage Resource Sharing
+@section Accounting to Encourage Resource Sharing
+
+Most distributed P2P networks suffer from a lack of defenses or
+precautions against attacks in the form of freeloading.
+While the intentions of an attacker and a freeloader are different, their
+effect on the network is the same; they both render it useless.
+Most simple attacks on networks such as @command{Gnutella}
+involve flooding the network with traffic, particularly
+with queries that are, in the worst case, multiplied by the network.
+
+In order to ensure that freeloaders or attackers have a minimal impact
+on the network, GNUnet's file-sharing implementation (@code{FS} tries
+to distinguish good (contributing) nodes from malicious (freeloading)
+nodes. In GNUnet, every file-sharing node keeps track of the behavior
+of every other node it has been in contact with. Many requests
+(depending on the application) are transmitted with a priority (or
+importance) level.  That priority is used to establish how important
+the sender believes this request is. If a peer responds to an
+important request, the recipient will increase its trust in the
+responder: the responder contributed resources.  If a peer is too busy
+to answer all requests, it needs to prioritize.  For that, peers do
+not take the priorities of the requests received at face value.
+First, they check how much they trust the sender, and depending on
+that amount of trust they assign the request a (possibly lower)
+effective priority. Then, they drop the requests with the lowest
+effective priority to satisfy their resource constraints. This way,
+GNUnet's economic model ensures that nodes that are not currently
+considered to have a surplus in contributions will not be served if
+the network load is high.
+@footnote{Christian Grothoff. An Excess-Based Economic Model for Resource
+Allocation in Peer-to-Peer Networks. Wirtschaftsinformatik, June 2003.
+(@uref{https://gnunet.org/git/bibliography.git/plain/docs/ebe.pdf, https://gnunet.org/git/bibliography.git/plain/docs/ebe.pdf})}
+@c 2009?
+
+@cindex Confidentiality
+@node Confidentiality
+@section Confidentiality
+
+Adversaries (malicious, bad actors) outside of GNUnet are not supposed
+to know what kind of actions a peer is involved in. Only the specific
+neighbor of a peer that is the corresponding sender or recipient of a
+message may know its contents, and even then application protocols may
+place further restrictions on that knowledge.  In order to ensure
+confidentiality, GNUnet uses link encryption, that is each message
+exchanged between two peers is encrypted using a pair of keys only
+known to these two peers.  Encrypting traffic like this makes any kind
+of traffic analysis much harder. Naturally, for some applications, it
+may still be desirable if even neighbors cannot determine the concrete
+contents of a message.  In GNUnet, this problem is addressed by the
+specific application-level protocols. See for example the following
+sections @pxref{Anonymity}, @pxref{How file-sharing achieves Anonymity},
+and @pxref{Deniability}.
+
+@cindex Anonymity
+@node Anonymity
+@section Anonymity
+
+@menu
+* How file-sharing achieves Anonymity::
+@end menu
+
+Providing anonymity for users is the central goal for the anonymous
+file-sharing application. Many other design decisions follow in the
+footsteps of this requirement.
+Anonymity is never absolute. While there are various
+scientific metrics@footnote{Claudia Díaz, Stefaan Seys, Joris Claessens,
+and Bart Preneel. Towards measuring anonymity.
+2002.
+(@uref{https://gnunet.org/git/bibliography.git/plain/docs/article-89.pdf, https://gnunet.org/git/bibliography.git/plain/docs/article-89.pdf})}
+that can help quantify the level of anonymity that a given mechanism
+provides, there is no such thing as "complete anonymity".
+GNUnet's file-sharing implementation allows users to select for each
+operation (publish, search, download) the desired level of anonymity.
+The metric used is the amount of cover traffic available to hide the
+request.
+While this metric is not as good as, for example, the theoretical metric
+given in scientific metrics@footnote{likewise},
+it is probably the best metric available to a peer with a purely local
+view of the world that does not rely on unreliable external information.
+The default anonymity level is @code{1}, which uses anonymous routing but
+imposes no minimal requirements on cover traffic. It is possible
+to forego anonymity when this is not required. The anonymity level of
+@code{0} allows GNUnet to use more efficient, non-anonymous routing.
+
+@cindex How file-sharing achieves Anonymity
+@node How file-sharing achieves Anonymity
+@subsection How file-sharing achieves Anonymity
+
+Contrary to other designs, we do not believe that users achieve strong
+anonymity just because their requests are obfuscated by a couple of
+indirections. This is not sufficient if the adversary uses traffic
+analysis.
+The threat model used for anonymous file sharing in GNUnet assumes that
+the adversary is quite powerful.
+In particular, we assume that the adversary can see all the traffic on
+the Internet. And while we assume that the adversary
+can not break our encryption, we assume that the adversary has many
+participating nodes in the network and that it can thus see many of the
+node-to-node interactions since it controls some of the nodes. 
+
+The system tries to achieve anonymity based on the idea that users can be
+anonymous if they can hide their actions in the traffic created by other
+users.
+Hiding actions in the traffic of other users requires participating in the
+traffic, bringing back the traditional technique of using indirection and
+source rewriting. Source rewriting is required to gain anonymity since
+otherwise an adversary could tell if a message originated from a host by
+looking at the source address. If all packets look like they originate
+from one node, the adversary can not tell which ones originate from that
+node and which ones were routed.
+Note that in this mindset, any node can decide to break the
+source-rewriting paradigm without violating the protocol, as this
+only reduces the amount of traffic that a node can hide its own traffic
+in.
+
+If we want to hide our actions in the traffic of other nodes, we must make
+our traffic indistinguishable from the traffic that we route for others.
+As our queries must have us as the receiver of the reply
+(otherwise they would be useless), we must put ourselves as the receiver
+of replies that actually go to other hosts; in other words, we must
+indirect replies.
+Unlike other systems, in anonymous file-sharing as implemented on top of
+GNUnet we do not have to indirect the replies if we don't think we need
+more traffic to hide our own actions.
+
+This increases the efficiency of the network as we can indirect less under
+higher load.@footnote{Krista Bennett and Christian Grothoff.
+GAP --- practical anonymous networking. In Proceedings of
+Designing Privacy Enhancing Technologies, 2003.
+(@uref{https://gnunet.org/git/bibliography.git/plain/docs/aff.pdf, https://gnunet.org/git/bibliography.git/plain/docs/aff.pdf})}
+
+@cindex Deniability
+@node Deniability
+@section Deniability
+
+Even if the user that downloads data and the server that provides data are
+anonymous, the intermediaries may still be targets. In particular, if the
+intermediaries can find out which queries or which content they are
+processing, a strong adversary could try to force them to censor
+certain materials. 
+
+With the file-encoding used by GNUnet's anonymous file-sharing, this
+problem does not arise.
+The reason is that queries and replies are transmitted in
+an encrypted format such that intermediaries cannot tell what the query
+is for or what the content is about.  Mind that this is not the same
+encryption as the link-encryption between the nodes.  GNUnet has
+encryption on the network layer (link encryption, confidentiality,
+authentication) and again on the application layer (provided
+by @command{gnunet-publish}, @command{gnunet-download},
+@command{gnunet-search} and @command{gnunet-gtk}).
+@footnote{Christian Grothoff, Krista Grothoff, Tzvetan Horozov,
+and Jussi T. Lindgren.
+An Encoding for Censorship-Resistant Sharing.
+2009.
+(@uref{https://gnunet.org/git/bibliography.git/plain/docs/ecrs.pdf, https://gnunet.org/git/bibliography.git/plain/docs/ecrs.pdf})}
+
+@cindex Peer Identities
+@node Peer Identities
+@section Peer Identities
+
+Peer identities are used to identify peers in the network and are unique
+for each peer. The identity for a peer is simply its public key, which is
+generated along with a private key the peer is started for the first time.
+While the identity is binary data, it is often expressed as ASCII string.
+For example, the following is a peer identity as you might see it in
+various places:
+
+@example
+UAT1S6PMPITLBKSJ2DGV341JI6KF7B66AC4JVCN9811NNEGQLUN0
+@end example
+
+@noindent
+You can find your peer identity by running @command{gnunet-peerinfo -s}.
+
+@cindex Zones in the GNU Name System (GNS Zones)
+@node Zones in the GNU Name System (GNS Zones)
+@section Zones in the GNU Name System (GNS Zones)
+
+@c FIXME: Explain or link to an explanation of the concept of public keys
+@c and private keys.
+@c FIXME: Rewrite for the latest GNS changes.
+GNS@footnote{Matthias Wachs, Martin Schanzenbach, and Christian Grothoff.
+A Censorship-Resistant, Privacy-Enhancing and Fully Decentralized Name
+System. In proceedings of 13th International Conference on Cryptology and
+Network Security (CANS 2014). 2014.
+@uref{https://gnunet.org/git/bibliography.git/plain/docs/gns2014wachs.pdf, https://gnunet.org/git/bibliography.git/plain/docs/gns2014wachs.pdf}}
+zones are similar to those of DNS zones, but instead of a hierarchy of
+authorities to governing their use, GNS zones are controlled by a private
+key.
+When you create a record in a DNS zone, that information is stored in your
+nameserver. Anyone trying to resolve your domain then gets pointed
+(hopefully) by the centralised authority to your nameserver.
+Whereas GNS, being fully decentralized by design, stores that information
+in DHT. The validity of the records is assured cryptographically, by
+signing them with the private key of the respective zone.
+
+Anyone trying to resolve records in a zone of your domain can then verify
+the signature of the records they get from the DHT and be assured that
+they are indeed from the respective zone.
+To make this work, there is a 1:1 correspondence between zones and
+their public-private key pairs.
+So when we talk about the owner of a GNS zone, that's really the owner of
+the private key.
+And a user accessing a zone needs to somehow specify the corresponding
+public key first.
+
+@cindex Egos
+@node Egos
+@section Egos
+
+@c what is the difference between peer identity and egos? It seems
+@c like both are linked to public-private key pair.
+Egos are your "identities" in GNUnet. Any user can assume multiple
+identities, for example to separate their activities online. Egos can
+correspond to "pseudonyms" or "real-world identities". Technically an
+ego is first of all a key pair of a public- and private-key.
diff --git a/doc/documentation/chapters/philosophy.texi b/doc/documentation/chapters/philosophy.texi
index 72c3476a3..6d80d77ae 100644
--- a/doc/documentation/chapters/philosophy.texi
+++ b/doc/documentation/chapters/philosophy.texi
@@ -5,36 +5,28 @@
 @c NOTE: We should probably re-use some of the images lynX created
 @c for secushare, showing some of the relations and functionalities
 @c of GNUnet.
-The foremost goal of the GNUnet project is to become a widely used,
-reliable, open, non-discriminating, egalitarian, unconstrained and
-censorship-resistant system of free information exchange.
-We value free speech above state secrets, law-enforcement or
-intellectual monopoly.
-GNUnet is supposed to be an anarchistic network, where the only
-limitation for participants (devices or people making use of the
-network, in the following sometimes called peers) is
-that they must contribute enough back to the network such that
-their resource consumption does not have a significant impact
-on other users.
-GNUnet should be more than just another file-sharing network.
-The plan is to offer many other services and in particular
-to serve as a development platform for the next generation of
-Internet Protocols.
+The primary goal of the GNUnet project is to provide a reliable, open,
+non-discriminating and censorship-resistant system for information
+exchange. We value free speech above state interests and intellectual
+monopoly. GNUnet's long-term goal is to serve as a development
+platform for the next generation of Internet protocols.
+
+GNUnet is an anarchistic network. Participants are encouraged to
+contribute at least as much resources (storage, bandwidth) to the network
+as they consume, so that their participation does not have a negative
+impact on other users.
 
 @menu
-* Design Goals::
-* Security and Privacy::
-* Versatility::
+* Design Principles::
+* Privacy and Anonymity::
 * Practicality::
-* Key Concepts::
 @end menu
 
-@cindex Design Goals
-@cindex Design Goals
-@node Design Goals
-@section Design Goals
+@cindex Design Principles
+@node Design Principles
+@section Design Principles
 
-These are the core GNUnet design goals, in order of relative importance:
+These are the GNUnet design principles, in order of importance:
 
 @itemize
 @item GNUnet must be implemented as
@@ -44,399 +36,45 @@ These are the core GNUnet design goals, in order of relative importance:
 the program, to study and change the program in source code form,
 to redistribute exact copies, and to distribute modified versions.
 Refer to @uref{https://www.gnu.org/philosophy/free-sw.html, https://www.gnu.org/philosophy/free-sw.html}}
-@item GNUnet must only disclose the minimal amount of information
-necessary.
+@item GNUnet must minimize the amount of personally identifiable information exposed.
 @c TODO: Explain 'fully' in the terminology section.
-@item GNUnet must be fully distributed and survive
-@uref{https://en.wikipedia.org/wiki/Byzantine_fault_tolerance, Byzantine failures}
-@footnote{@uref{https://en.wikipedia.org/wiki/Byzantine_fault_tolerance, https://en.wikipedia.org/wiki/Byzantine_fault_tolerance}}
-at any position in the network.
-@item GNUnet must make it explicit to the user which entities are
-considered to be trustworthy when establishing secured communications.
-@item GNUnet must use compartmentalization to protect sensitive
-information.
+@item GNUnet must be fully distributed and resilient to external attacks and rogue participants.
+@item GNUnet must be self-organizing and not depend on administrators or centralized infrastructure.
+@item GNUnet must inform the user which other participants have to be trusted when establishing private communications.
 @item GNUnet must be open and permit new peers to join.
-@item GNUnet must be self-organizing and not depend on administrators.
 @item GNUnet must support a diverse range of applications and devices.
-@item The GNUnet architecture must be cost effective.
-@item GNUnet must provide incentives for peers to contribute more
-resources than they consume.
+@item GNUnet must use compartmentalization to protect sensitive information.
+@item The GNUnet architecture must be resource efficient.
+@item GNUnet must provide incentives for peers to contribute more resources than they consume.
 @end itemize
 
 
-@cindex Security and Privacy
-@node Security and Privacy
-@section Security and Privacy
-
-GNUnet's primary design goals are to protect the privacy of its users and
-to guard itself against attacks or abuse.
-GNUnet does not have any mechanisms to control, track or censor users.
-Instead, the GNUnet protocols aim to make it as hard as possible to
-find out what is happening on the network or to disrupt operations. 
+@cindex Privacy and Anonymity
+@node Privacy and Anonymity
+@section Privacy and Anonymity
 
-@cindex Versatility
-@node Versatility
-@section Versatility
+The GNUnet protocols minimize the leakage of personally identifiable information of participants and
+do not allow adversaries to control, track, monitor or censor users activities. The
+GNUnet protocols also make it as hard as possible to disrupt operations by participating in the network with malicious intent. 
 
-We call GNUnet a peer-to-peer framework because we want to support many
-different forms of peer-to-peer applications. GNUnet uses a plugin
-architecture to make the system extensible and to encourage code reuse.
-While the first versions of the system only supported anonymous
-file-sharing, other applications are being worked on and more will
-hopefully follow in the future.
-A powerful synergy regarding anonymity services is created by a large
-community utilizing many diverse applications over the same software
-infrastructure. The reason is that link encryption hides the specifics
-of the traffic for non-participating observers. This way, anonymity can
-get stronger with additional (GNUnet) traffic, even if the additional
-traffic is not related to anonymous communication. Increasing anonymity
-is the primary reason why GNUnet is developed to become a peer-to-peer
+Analyzing participant's activities becomes more difficult as the number of peers and
+applications that generate traffic on the network grows, even if the additional
+traffic generated is not related to anonymous communication. This is one of the reasons why GNUnet is developed as a peer-to-peer
 framework where many applications share the lower layers of an
-increasingly complex protocol stack.
-If merging traffic to hinder traffic analysis was not important,
-we could have just developed a dozen stand-alone applications
-and a few shared libraries. 
+increasingly complex protocol stack. The GNUnet architecture encourages many
+different forms of peer-to-peer applications.
 
 @cindex Practicality
 @node Practicality
 @section Practicality
 
-GNUnet allows participants to trade various amounts of security in
-exchange for increased efficiency. However, it is not possible for any
-user's security and efficiency requirements to compromise the security
-and efficiency of any other user.
-
-For GNUnet, efficiency is not paramount. If there were a more secure and
-still practical approach, we would choose to take the more secure
-alternative. @command{telnet} is more efficient than @command{ssh}, yet
-it is obsolete.
-Hardware gets faster, and code can be optimized. Fixing security issues
-as an afterthought is much harder.
-
-While security is paramount, practicability is still a requirement.
-The most secure system is always the one that nobody can use.
-Similarly, any anonymous system that is extremely inefficient will only
-find few users.
-However, good anonymity requires a large and diverse user base. Since
-individual security requirements may vary, the only good solution here is
-to allow individuals to trade-off security and efficiency.
-The primary challenge in allowing this is to ensure that the economic
-incentives work properly.
-In particular, this means that it must be impossible for a user to gain
-security at the expense of other users. Many designs (e.g. anonymity via
-broadcast) fail to give users an incentive to choose a less secure but
-more efficient mode of operation.
-GNUnet should avoid where ever possible to rely on protocols that will
-only work if the participants are benevolent.
-While some designs have had widespread success while relying on parties
-to observe a protocol that may be sub-optimal for the individuals (e.g.
-TCP Nagle), a protocol that ensures that individual goals never conflict
-with the goals of the group is always preferable.
-
-@cindex Key Concepts
-@node Key Concepts
-@section Key Concepts
-
-In this section, the fundamental concepts of GNUnet are explained.
-@c FIXME: Use @uref{https://docs.gnunet.org/bib/, research papers}
-@c once we have the new bibliography + subdomain setup.
-Most of them are also described in our research papers.
-First, some of the concepts used in the GNUnet framework are detailed.
-The second part describes concepts specific to anonymous file-sharing.
-
-@menu
-* Authentication::
-* Accounting to Encourage Resource Sharing::
-* Confidentiality::
-* Anonymity::
-* Deniability::                       
-* Peer Identities::
-* Zones in the GNU Name System (GNS Zones)::
-* Egos::
-@end menu
-
-@cindex Authentication
-@node Authentication
-@subsection Authentication
-
-Almost all peer-to-peer communications in GNUnet are between mutually
-authenticated peers. The authentication works by using ECDHE, that is a
-DH (Diffie---Hellman) key exchange using ephemeral elliptic curve
-cryptography. The ephemeral ECC (Elliptic Curve Cryptography) keys are
-signed using ECDSA (@uref{http://en.wikipedia.org/wiki/ECDSA, ECDSA}).
-The shared secret from ECDHE is used to create a pair of session keys
-@c FIXME: Long word for HKDF. More FIXMEs: Explain MITM etc.
-(using HKDF) which are then used to encrypt the communication between the
-two peers using both 256-bit AES (Advanced Encryption Standard)
-and 256-bit Twofish (with independently derived secret keys).
-As only the two participating hosts know the shared secret, this
-authenticates each packet
-without requiring signatures each time. GNUnet uses SHA-512
-(Secure Hash Algorithm) hash codes to verify the integrity of messages.
-
-@c FIXME: A while back I got the feedback that I should try and integrate
-@c explanation boxes in the long-run. So we could explain
-@c "man-in-the-middle" and "man-in-the-middle attacks" and other words
-@c which are not common knowledge. MITM is not common knowledge. To be
-@c selfcontained, we should be able to explain words and concepts used in
-@c a chapter or paragraph without hinting at Wikipedia and other online
-@c sources which might not be available or accessible to everyone.
-@c On the other hand we could write an introductionary chapter or book
-@c that we could then reference in each chapter, which sound like it
-@c could be more reusable.
-In GNUnet, the identity of a host is its public key. For that reason,
-man-in-the-middle attacks will not break the authentication or accounting
-goals. Essentially, for GNUnet, the IP of the host has nothing to do with
-the identity of the host. As the public key is the only thing that truly
-matters, faking an IP, a port or any other property of the underlying
-transport protocol is irrelevant. In fact, GNUnet peers can use
-multiple IPs (IPv4 and IPv6) on multiple ports --- or even not use the
-IP protocol at all (by running directly on layer 2).
-@c FIXME: "IP protocol" feels wrong, but could be what people expect, as
-@c IP is "the number" and "IP protocol" the protocol itself in general
-@c knowledge?
-
-@c NOTE: For consistency we will use @code{HELLO}s throughout this Manual.
-GNUnet uses a special type of message to communicate a binding between
-public (ECC) keys to their current network address. These messages are
-commonly called @code{HELLO}s or @code{peer advertisements}.
-They contain the public key of the peer and its current network
-addresses for various transport services.
-A transport service is a special kind of shared library that
-provides (possibly unreliable, out-of-order) message delivery between
-peers.
-For the UDP and TCP transport services, a network address is an IP and a
-port.
-GNUnet can also use other transports (HTTP, HTTPS, WLAN, etc.) which use
-various other forms of addresses. Note that any node can have many
-different active transport services at the same time,
-and each of these can have a different addresses.
-Binding messages expire after at most a week (the timeout can be
-shorter if the user configures the node appropriately).
-This expiration ensures that the network will eventually get rid of
-outdated advertisements.
-@footnote{Ronaldo A. Ferreira, Christian Grothoff, and Paul Ruth.
-A Transport Layer Abstraction for Peer-to-Peer Networks
-Proceedings of the 3rd International Symposium on Cluster Computing
-and the Grid (GRID 2003), 2003.
-(@uref{https://gnunet.org/git/bibliography.git/plain/docs/transport.pdf, https://gnunet.org/git/bibliography.git/plain/docs/transport.pdf})}
-
-@cindex Accounting to Encourage Resource Sharing
-@node Accounting to Encourage Resource Sharing
-@subsection Accounting to Encourage Resource Sharing
-
-Most distributed P2P networks suffer from a lack of defenses or
-precautions against attacks in the form of freeloading.
-While the intentions of an attacker and a freeloader are different, their
-effect on the network is the same; they both render it useless.
-Most simple attacks on networks such as @command{Gnutella}
-involve flooding the network with traffic, particularly
-with queries that are, in the worst case, multiplied by the network.
-
-In order to ensure that freeloaders or attackers have a minimal impact
-on the network, GNUnet's file-sharing implementation (@code{FS} tries
-to distinguish good (contributing) nodes from malicious (freeloading)
-nodes. In GNUnet, every file-sharing node keeps track of the behavior
-of every other node it has been in contact with. Many requests
-(depending on the application) are transmitted with a priority (or
-importance) level.  That priority is used to establish how important
-the sender believes this request is. If a peer responds to an
-important request, the recipient will increase its trust in the
-responder: the responder contributed resources.  If a peer is too busy
-to answer all requests, it needs to prioritize.  For that, peers do
-not take the priorities of the requests received at face value.
-First, they check how much they trust the sender, and depending on
-that amount of trust they assign the request a (possibly lower)
-effective priority. Then, they drop the requests with the lowest
-effective priority to satisfy their resource constraints. This way,
-GNUnet's economic model ensures that nodes that are not currently
-considered to have a surplus in contributions will not be served if
-the network load is high.
-@footnote{Christian Grothoff. An Excess-Based Economic Model for Resource
-Allocation in Peer-to-Peer Networks. Wirtschaftsinformatik, June 2003.
-(@uref{https://gnunet.org/git/bibliography.git/plain/docs/ebe.pdf, https://gnunet.org/git/bibliography.git/plain/docs/ebe.pdf})}
-@c 2009?
-
-@cindex Confidentiality
-@node Confidentiality
-@subsection Confidentiality
-
-Adversaries (malicious, bad actors) outside of GNUnet are not supposed
-to know what kind of actions a peer is involved in. Only the specific
-neighbor of a peer that is the corresponding sender or recipient of a
-message may know its contents, and even then application protocols may
-place further restrictions on that knowledge.  In order to ensure
-confidentiality, GNUnet uses link encryption, that is each message
-exchanged between two peers is encrypted using a pair of keys only
-known to these two peers.  Encrypting traffic like this makes any kind
-of traffic analysis much harder. Naturally, for some applications, it
-may still be desirable if even neighbors cannot determine the concrete
-contents of a message.  In GNUnet, this problem is addressed by the
-specific application-level protocols. See for example the following
-sections @pxref{Anonymity}, @pxref{How file-sharing achieves Anonymity},
-and @pxref{Deniability}.
-
-@cindex Anonymity
-@node Anonymity
-@subsection Anonymity
+Whereever possible GNUnet allows the peer to adjust its operations
+and functionalities to specific use cases. A GNUnet peer running on
+a mobile device with limited battery for example might choose not to
+relay traffic for other participants.
 
-@menu
-* How file-sharing achieves Anonymity::
-@end menu
-
-Providing anonymity for users is the central goal for the anonymous
-file-sharing application. Many other design decisions follow in the
-footsteps of this requirement.
-Anonymity is never absolute. While there are various
-scientific metrics@footnote{Claudia Díaz, Stefaan Seys, Joris Claessens,
-and Bart Preneel. Towards measuring anonymity.
-2002.
-(@uref{https://gnunet.org/git/bibliography.git/plain/docs/article-89.pdf, https://gnunet.org/git/bibliography.git/plain/docs/article-89.pdf})}
-that can help quantify the level of anonymity that a given mechanism
-provides, there is no such thing as "complete anonymity".
-GNUnet's file-sharing implementation allows users to select for each
-operation (publish, search, download) the desired level of anonymity.
-The metric used is the amount of cover traffic available to hide the
-request.
-While this metric is not as good as, for example, the theoretical metric
-given in scientific metrics@footnote{likewise},
-it is probably the best metric available to a peer with a purely local
-view of the world that does not rely on unreliable external information.
-The default anonymity level is @code{1}, which uses anonymous routing but
-imposes no minimal requirements on cover traffic. It is possible
-to forego anonymity when this is not required. The anonymity level of
-@code{0} allows GNUnet to use more efficient, non-anonymous routing.
-
-@cindex How file-sharing achieves Anonymity
-@node How file-sharing achieves Anonymity
-@subsubsection How file-sharing achieves Anonymity
-
-Contrary to other designs, we do not believe that users achieve strong
-anonymity just because their requests are obfuscated by a couple of
-indirections. This is not sufficient if the adversary uses traffic
-analysis.
-The threat model used for anonymous file sharing in GNUnet assumes that
-the adversary is quite powerful.
-In particular, we assume that the adversary can see all the traffic on
-the Internet. And while we assume that the adversary
-can not break our encryption, we assume that the adversary has many
-participating nodes in the network and that it can thus see many of the
-node-to-node interactions since it controls some of the nodes. 
-
-The system tries to achieve anonymity based on the idea that users can be
-anonymous if they can hide their actions in the traffic created by other
-users.
-Hiding actions in the traffic of other users requires participating in the
-traffic, bringing back the traditional technique of using indirection and
-source rewriting. Source rewriting is required to gain anonymity since
-otherwise an adversary could tell if a message originated from a host by
-looking at the source address. If all packets look like they originate
-from one node, the adversary can not tell which ones originate from that
-node and which ones were routed.
-Note that in this mindset, any node can decide to break the
-source-rewriting paradigm without violating the protocol, as this
-only reduces the amount of traffic that a node can hide its own traffic
-in.
-
-If we want to hide our actions in the traffic of other nodes, we must make
-our traffic indistinguishable from the traffic that we route for others.
-As our queries must have us as the receiver of the reply
-(otherwise they would be useless), we must put ourselves as the receiver
-of replies that actually go to other hosts; in other words, we must
-indirect replies.
-Unlike other systems, in anonymous file-sharing as implemented on top of
-GNUnet we do not have to indirect the replies if we don't think we need
-more traffic to hide our own actions.
-
-This increases the efficiency of the network as we can indirect less under
-higher load.@footnote{Krista Bennett and Christian Grothoff.
-GAP --- practical anonymous networking. In Proceedings of
-Designing Privacy Enhancing Technologies, 2003.
-(@uref{https://gnunet.org/git/bibliography.git/plain/docs/aff.pdf, https://gnunet.org/git/bibliography.git/plain/docs/aff.pdf})}
-
-@cindex Deniability
-@node Deniability
-@subsection Deniability
-
-Even if the user that downloads data and the server that provides data are
-anonymous, the intermediaries may still be targets. In particular, if the
-intermediaries can find out which queries or which content they are
-processing, a strong adversary could try to force them to censor
-certain materials. 
-
-With the file-encoding used by GNUnet's anonymous file-sharing, this
-problem does not arise.
-The reason is that queries and replies are transmitted in
-an encrypted format such that intermediaries cannot tell what the query
-is for or what the content is about.  Mind that this is not the same
-encryption as the link-encryption between the nodes.  GNUnet has
-encryption on the network layer (link encryption, confidentiality,
-authentication) and again on the application layer (provided
-by @command{gnunet-publish}, @command{gnunet-download},
-@command{gnunet-search} and @command{gnunet-gtk}).
-@footnote{Christian Grothoff, Krista Grothoff, Tzvetan Horozov,
-and Jussi T. Lindgren.
-An Encoding for Censorship-Resistant Sharing.
-2009.
-(@uref{https://gnunet.org/git/bibliography.git/plain/docs/ecrs.pdf, https://gnunet.org/git/bibliography.git/plain/docs/ecrs.pdf})}
-
-@cindex Peer Identities
-@node Peer Identities
-@subsection Peer Identities
-
-Peer identities are used to identify peers in the network and are unique
-for each peer. The identity for a peer is simply its public key, which is
-generated along with a private key the peer is started for the first time.
-While the identity is binary data, it is often expressed as ASCII string.
-For example, the following is a peer identity as you might see it in
-various places:
-
-@example
-UAT1S6PMPITLBKSJ2DGV341JI6KF7B66AC4JVCN9811NNEGQLUN0
-@end example
-
-@noindent
-You can find your peer identity by running @command{gnunet-peerinfo -s}.
-
-@cindex Zones in the GNU Name System (GNS Zones)
-@node Zones in the GNU Name System (GNS Zones)
-@subsection Zones in the GNU Name System (GNS Zones)
-
-@c FIXME: Explain or link to an explanation of the concept of public keys
-@c and private keys.
-@c FIXME: Rewrite for the latest GNS changes.
-GNS@footnote{Matthias Wachs, Martin Schanzenbach, and Christian Grothoff.
-A Censorship-Resistant, Privacy-Enhancing and Fully Decentralized Name
-System. In proceedings of 13th International Conference on Cryptology and
-Network Security (CANS 2014). 2014.
-@uref{https://gnunet.org/git/bibliography.git/plain/docs/gns2014wachs.pdf, https://gnunet.org/git/bibliography.git/plain/docs/gns2014wachs.pdf}}
-zones are similar to those of DNS zones, but instead of a hierarchy of
-authorities to governing their use, GNS zones are controlled by a private
-key.
-When you create a record in a DNS zone, that information is stored in your
-nameserver. Anyone trying to resolve your domain then gets pointed
-(hopefully) by the centralised authority to your nameserver.
-Whereas GNS, being fully decentralized by design, stores that information
-in DHT. The validity of the records is assured cryptographically, by
-signing them with the private key of the respective zone.
-
-Anyone trying to resolve records in a zone of your domain can then verify
-the signature of the records they get from the DHT and be assured that
-they are indeed from the respective zone.
-To make this work, there is a 1:1 correspondence between zones and
-their public-private key pairs.
-So when we talk about the owner of a GNS zone, that's really the owner of
-the private key.
-And a user accessing a zone needs to somehow specify the corresponding
-public key first.
-
-@cindex Egos
-@node Egos
-@subsection Egos
+For certain applications like file-sharing GNUnet allows participants to trade degrees of anonymity in
+exchange for increased efficiency. However, it is not possible for any
+user's efficiency requirements to compromise the anonymity
+of any other user.
 
-@c what is the difference between peer identity and egos? It seems
-@c like both are linked to public-private key pair.
-Egos are your "identities" in GNUnet. Any user can assume multiple
-identities, for example to separate their activities online. Egos can
-correspond to "pseudonyms" or "real-world identities". Technically an
-ego is first of all a key pair of a public- and private-key.
diff --git a/doc/documentation/chapters/user.texi b/doc/documentation/chapters/user.texi
index 9c9bd8df8..2dd6cbcb5 100644
--- a/doc/documentation/chapters/user.texi
+++ b/doc/documentation/chapters/user.texi
@@ -20,232 +20,32 @@ always welcome.
 
 
 @menu
-* Checking the Installation::
-* First steps - File-sharing::
+* Start and stop GNUnet::
 * First steps - Using the GNU Name System::
 * First steps - Using GNUnet Conversation::
 * First steps - Using the GNUnet VPN::
 * File-sharing::
 * The GNU Name System::
 * Using the Virtual Public Network::
-* The graphical configuration interface::
-* How to start and stop a GNUnet peer::
+* MOVE TO INSTALL The graphical configuration interface::
+* MOVE TO INSTALL Checking the Installation::
+* MOVE TO INSTALL Config Leftovers::
 @end menu
 
-@node Checking the Installation
-@section Checking the Installation
-@c %**end of header
-
-This section 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 instructions
-provided in the developer handbook as well as the system-specific
-instruction in the source code repository@footnote{The system specific instructions are not provided as part of this handbook!}.
-
-
-@menu
-* gnunet-gtk::
-* Statistics::
-* Peer Information::
-@end menu
-
-@cindex GNUnet GTK
-@cindex GTK
-@cindex GTK user interface
-@node gnunet-gtk
-@subsection gnunet-gtk
-@c %**end of header
-
-The @command{gnunet-gtk} package contains several graphical
-user interfaces for the respective GNUnet applications.
-Currently these interfaces cover:
-
-@itemize @bullet
-@item Statistics
-@item Peer Information
-@item GNU Name System
-@item File Sharing
-@item Identity Management
-@item Conversation
-@end itemize
+@node Start and stop GNUnet
+@section Start and stop GNUnet
 
-@node Statistics
-@subsection Statistics
-@c %**end of header
-
-First, you should launch GNUnet gtk@footnote{Obviously you should also start gnunet, via gnunet-arm or the system provided method}.
-You can do this from the command-line by typing
+Previous to use any GNUnet-based application, one has to start a node:
 
 @example
-gnunet-statistics-gtk
+$ gnunet-arm -s -l gnunet.log
 @end example
 
-If your peer@footnote{The term ``peer'' is a common word used in federated and distributed networks to describe a participating device which is connected to the network. Thus, your Personal Computer or whatever it is you are looking at the Gtk+ interface describes a ``Peer'' or a ``Node''.}
-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 more than a few seconds). The lines indicate
-how many other peers your peer is connected to (via different
-mechanisms) and how large the entire overlay network is currently
-estimated to be. The X-axis represents time (in seconds since the
-start of @command{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 cumulatively, so you should see a strict upwards trend in the
-traffic.
-
-@node Peer Information
-@subsection Peer Information
-@c %**end of header
-
-First, you should launch the graphical user interface.  You can do
-this from the command-line by typing
+To stop GNUnet:
 
 @example
-$ gnunet-peerinfo-gtk
+$ gnunet-arm -e
 @end example
-
-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 @command{gnunet-fs-gtk}.
-
-As we want to be sure that the network contains the data that we are
-looking for for testing, we need to begin by publishing a file.
-
-
-@menu
-* 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 anonymous and (for directories) if
-the download should be recursive. In most cases, you can simply start
-the download with the "Download!" button.
-
-Once you selected download, the progress of the download will be
-displayed with the search result. You may need to resize the result
-list or scroll to the right. The "Status" column shows the current
-status of the download, and "Progress" how much has been completed.
-When you close the search tab (by clicking on the "X" button next to
-the "test" label), ongoing and completed downloads are not aborted
-but moved to a special "*" tab.
-
-You can remove completed downloads from the "*" tab by clicking the
-cleanup button next to the "*". You can also abort downloads by right
-clicking on the respective download and selecting "Abort download"
-from the menu.
-
-That's it, you now know the basics for file-sharing with GNUnet!
-
 @node First steps - Using the GNU Name System
 @section First steps - Using the GNU Name System
 @c %**end of header
@@ -309,7 +109,7 @@ rules - GO0T87F9BPMF8NKD5A54L2AH1T0GRML539TPFSRMCEA98182QD30
 @subsection The GNS Tab
 @c %**end of header
 
-Maintaining your zones is through the NAMESTORE service and is discussed
+Maintaing your zones is through the NAMESTORE service and is discussed
 here.  You can manage your zone using @command{gnunet-identity} and
 @command{gnunet-namestore}, or most conveniently using
 @command{gnunet-namestore-gtk}.
@@ -899,24 +699,198 @@ 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.
-
+After a short introduction, we will first look at the various concepts in
+GNUnet's file-sharing implementation. Then, we will discuss specifics as to how
+they impact users that publish, search or download files.
 
 
 @menu
-* File-sharing Concepts::
-* File-sharing Publishing::
-* File-sharing Searching::
-* File-sharing Downloading::
-* File-sharing Directories::
-* File-sharing Namespace Management::
+* fs-Searching::
+* fs-Downloading::
+* fs-Publishing::
+* fs-Concepts::
+* fs-Directories::
+* Namespace Management::
 * File-Sharing URIs::
+* GTK User Interface::
 @end menu
 
-@node File-sharing Concepts
-@subsection File-sharing Concepts
+@node fs-Searching
+@subsection Searching
+@c %**end of header
+
+The command @command{gnunet-search} can be used to search
+for content on GNUnet. The format is:
+
+@example
+$ gnunet-search [-t TIMEOUT] KEYWORD
+@end example
+
+@noindent
+The -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
+
+@noindent
+is not the same as searching for
+
+@example
+$ gnunet-search "Das Kapital"
+@end example
+
+@noindent
+as the first will match files shared under the keywords
+"Das" or "Kapital" whereas the second will match files
+shared under the keyword "Das Kapital".
+
+Search results are printed by gnunet-search like this:
+
+@c it will be better the avoid the ellipsis altogether because I don't
+@c understand the explanation below that
+@example
+#15:
+gnunet-download -o "COPYING" gnunet://fs/chk/PGK8M...3EK130.75446
+
+@end example
+
+@noindent
+The whole line is the command you would have to enter to download
+the file. The argument passed to @code{-o} is the suggested
+filename (you may change it to whatever you like).
+It is followed by the key for decrypting the file, the query for searching the
+file, a checksum (in hexadecimal) finally the size of the file in bytes.
+
+@node fs-Downloading
+@subsection Downloading
+@c %**end of header
+
+In order to download a file, you need the whole line returned by
+@command{gnunet-search}.
+You can then use the tool @command{gnunet-download} to obtain the file:
+
+@example
+$ gnunet-download -o <FILENAME> <GNUNET-URL>
+@end example
+
+@noindent
+FILENAME specifies the name of the file where GNUnet is supposed
+to write the result. Existing files are overwritten. If the
+existing file contains blocks that are identical to the
+desired download, those blocks will not be downloaded again
+(automatic resume).
+
+If you want to download the GPL from the previous example,
+you do the following:
+
+@example
+$ gnunet-download -o "COPYING" gnunet://fs/chk/PGK8M...3EK130.75446
+@end example
+
+@noindent
+If you ever have to abort a download, you can continue it at any time by
+re-issuing @command{gnunet-download} with the same filename.
+In that case, GNUnet will @strong{not} download blocks again that are
+already present.
+
+GNUnet's file-encoding mechanism will ensure file integrity, even if the
+existing file was not downloaded from GNUnet in the first place.
+
+You may want to use the @command{-V} switch  to turn on verbose reporting. In
+this case, @command{gnunet-download} will print the current number of bytes
+downloaded whenever new data was received.
+
+@node fs-Publishing
+@subsection Publishing
+@c %**end of header
+
+The command @command{gnunet-publish} can be used to add content
+to the network. The basic format of the command is
+
+@example
+$ gnunet-publish [-n] [-k KEYWORDS]* [-m TYPE:VALUE] FILENAME
+@end example
+
+For example
+@example
+$ gnunet-publish -m "description:GNU License" -k gpl -k test -m "mimetype:text/plain" COPYING
+@end example
+
+@menu
+* Important command-line options::
+* Indexing vs. Inserting::
+@end menu
+
+@node Important command-line options
+@subsubsection Important command-line options
+@c %**end of header
+
+The option @code{-k} is used to specify keywords for the file that
+should be inserted. You can supply any number of keywords,
+and each of the keywords will be sufficient to locate and
+retrieve the file. Please note that you must use the @code{-k} option 
+more than once -- one for each expression you use as a keyword for
+the filename.
+
+The -m option is used to specify meta-data, such as descriptions.
+You can use -m multiple times. The TYPE passed must be from the
+list of meta-data types known to libextractor. You can obtain this
+list by running @command{extract -L}. Use quotes around the entire
+meta-data argument if the value contains spaces. The meta-data
+is displayed to other users when they select which files to
+download. The meta-data and the keywords are optional and
+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
+@command{gnunet-unindex} to un-index the file.
+
+The option @code{-n} may be used if the user fears that the file might
+be found on their drive (assuming the computer comes under the control
+of an adversary). When used with the @code{-n} flag, the user has a
+much better chance of denying knowledge of the existence of the file,
+even if it is still (encrypted) on the drive and the adversary is
+able to crack the encryption (e.g. by guessing the keyword.
+
+@node fs-Concepts
+@subsection Concepts
 @c %**end of header
 
 Sharing files in GNUnet is not quite as simple as in traditional
@@ -1072,184 +1046,9 @@ 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 @command{gnunet-publish} can be used to add content
-to the network. The basic format of the command is
-
-@example
-$ gnunet-publish [-n] [-k KEYWORDS]* [-m TYPE:VALUE] FILENAME
-@end example
-
-
-@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 @code{-k} is used to specify keywords for the file that
-should be inserted. You can supply any number of keywords,
-and each of the keywords will be sufficient to locate and
-retrieve the file. Please note that you must use the @code{-k} option 
-more than once -- one for each expression you use as a keyword for
-the filename.
-
-The -m option is used to specify meta-data, such as descriptions.
-You can use -m multiple times. The TYPE passed must be from the
-list of meta-data types known to libextractor. You can obtain this
-list by running @command{extract -L}. Use quotes around the entire
-meta-data argument if the value contains spaces. The meta-data
-is displayed to other users when they select which files to
-download. The meta-data and the keywords are optional and
-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
-@command{gnunet-unindex} to un-index the file.
 
-The option @code{-n} may be used if the user fears that the file might
-be found on their drive (assuming the computer comes under the control
-of an adversary). When used with the @code{-n} flag, the user has a
-much better chance of denying knowledge of the existence of the file,
-even if it is still (encrypted) on the drive and the adversary is
-able to crack the encryption (e.g. by guessing the keyword.
-
-@node File-sharing Searching
-@subsection File-sharing Searching
-@c %**end of header
-
-The command @command{gnunet-search} can be used to search
-for content on GNUnet. The format is:
-
-@example
-$ gnunet-search [-t TIMEOUT] KEYWORD
-@end example
-
-@noindent
-The -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
-
-@noindent
-is not the same as searching for
-
-@example
-$ gnunet-search "Das Kapital"
-@end example
-
-@noindent
-as the first will match files shared under the keywords
-"Das" or "Kapital" whereas the second will match files
-shared under the keyword "Das Kapital".
-
-Search results are printed by gnunet-search like this:
-
-@c it will be better the avoid the ellipsis altogether because I don't
-@c understand the explanation below that
-@example
-$ gnunet-download -o "COPYING" --- gnunet://fs/chk/N8...C92.17992
-=> The GNU Public License <= (mimetype: text/plain)
-@end example
-
-@noindent
-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).
-@c except it's triple dash in the above example ---
-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
-@command{gnunet-search}.
-You can then use the tool @command{gnunet-download} to obtain the file:
-
-@example
-$ gnunet-download -o FILENAME --- GNUNETURL
-@end example
-
-@noindent
-FILENAME specifies the name of the file where GNUnet is supposed
-to write the result. Existing files are overwritten. If the
-existing file contains blocks that are identical to the
-desired download, those blocks will not be downloaded again
-(automatic resume).
-
-If you want to download the GPL from the previous example,
-you do the following:
-
-@example
-$ gnunet-download -o "COPYING" --- gnunet://fs/chk/N8...92.17992
-@end example
-
-@noindent
-If you ever have to abort a download, you can continue it at any time by
-re-issuing @command{gnunet-download} with the same filename.
-In that case, GNUnet will @strong{not} download blocks again that are
-already present.
-
-GNUnet's file-encoding mechanism will ensure file integrity, even if the
-existing file was not downloaded from GNUnet in the first place.
-
-You may want to use the @command{-V} switch (must be added before
-@c Same as above it's triple dash
-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
+@node fs-Directories
+@subsection Directories
 @c %**end of header
 
 Directories are shared just like ordinary files. If you download a
@@ -1264,8 +1063,8 @@ 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
+@node Namespace Management
+@subsection Namespace Management
 @c %**end of header
 
 @b{Please note that the text in this subsection is outdated and needs}
@@ -1436,6 +1235,135 @@ chosen keyword (or password!). A commonly used identifier is
 "root" which by convention refers to some kind of index or other
 entry point into the namespace.
 
+@node GTK User Interface
+@subsection GTK User Interface
+This chapter describes first steps for file-sharing with GNUnet.
+To start, you should launch @command{gnunet-fs-gtk}.
+
+As we want to be sure that the network contains the data that we are
+looking for for testing, we need to begin by publishing a file.
+
+@menu
+* gtk-Publishing::
+* gtk-Searching::
+* gtk-Downloading::
+@end menu
+
+@node gtk-Publishing
+@subsubsection Publishing
+@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 gtk-Searching
+@subsubsection 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 gtk-Downloading
+@subsubsection 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 The GNU Name System
 @section The GNU Name System
 @c %**end of header
@@ -2032,8 +1960,8 @@ that will terminate at the respective peer's service.
 
 @c NOTE: Inserted from Installation Handbook in original ``order'':
 @c FIXME: Move this to User Handbook.
-@node The graphical configuration interface
-@section The graphical configuration interface
+@node MOVE TO INSTALL The graphical configuration interface
+@section MOVE TO INSTALL The graphical configuration interface
 
 If you also would like to use @command{gnunet-gtk} and
 @command{gnunet-setup} (highly recommended for beginners), do:
@@ -2264,7 +2192,7 @@ the configuration:
 
 If you operate a peer permanently connected to GNUnet you can configure
 your peer to act as a hostlist server, providing other peers the list of
-peers known to it.
+peers known to him.
 
 Your server can act as a bootstrap server and peers needing to obtain a
 list of peers can contact it to download this list.
@@ -2883,7 +2811,7 @@ iwconfig wlan0 channel 1
 @subsection Configuring HTTP(S) reverse proxy functionality using Apache or nginx
 
 The HTTP plugin supports data transfer using reverse proxies. A reverse
-proxy forwards the HTTP request it receives with a certain URL to another
+proxy forwards the HTTP request he receives with a certain URL to another
 webserver, here a GNUnet peer.
 
 So if you have a running Apache or nginx webserver you can configure it to
@@ -3619,8 +3547,91 @@ desktop-user to "sudo" (i.e. using gtksudo) to the "gnunet" user account
 and then runs "gnunet-arm -e", "gnunet-setup" and "gnunet-arm -s" in
 sequence.
 
-@node How to start and stop a GNUnet peer
-@section How to start and stop a GNUnet peer
+@node MOVE TO INSTALL Checking the Installation
+@section MOVE TO INSTALL Checking the Installation
+@c %**end of header
+
+This section 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 instructions
+provided in the developer handbook as well as the system-specific
+instruction in the source code repository@footnote{The system specific instructions are not provided as part of this handbook!}.
+
+
+@menu
+* gnunet-gtk::
+* Statistics::
+* Peer Information::
+@end menu
+
+@cindex GNUnet GTK
+@cindex GTK
+@cindex GTK user interface
+@node gnunet-gtk
+@subsection gnunet-gtk
+@c %**end of header
+
+The @command{gnunet-gtk} package contains several graphical
+user interfaces for the respective GNUnet applications.
+Currently these interfaces cover:
+
+@itemize @bullet
+@item Statistics
+@item Peer Information
+@item GNU Name System
+@item File Sharing
+@item Identity Management
+@item Conversation
+@end itemize
+
+@node Statistics
+@subsection Statistics
+@c %**end of header
+
+First, you should launch GNUnet gtk@footnote{Obviously you should also start gnunet, via gnunet-arm or the system provided method}.
+You can do this from the command-line by typing
+
+@example
+gnunet-statistics-gtk
+@end example
+
+If your peer@footnote{The term ``peer'' is a common word used in federated and distributed networks to describe a participating device which is connected to the network. Thus, your Personal Computer or whatever it is you are looking at the Gtk+ interface describes a ``Peer'' or a ``Node''.}
+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 more than a few seconds). The lines indicate
+how many other peers your peer is connected to (via different
+mechanisms) and how large the entire overlay network is currently
+estimated to be. The X-axis represents time (in seconds since the
+start of @command{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
+
+First, you should launch the graphical user interface.  You can do
+this from the command-line by typing
+
+@example
+$ gnunet-peerinfo-gtk
+@end example
+
+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 MOVE TO INSTALL Config Leftovers
+@section MOVE TO INSTALL Config Leftovers
 
 This section describes how to start a GNUnet peer. It assumes that you
 have already compiled and installed GNUnet and its' dependencies.
@@ -3949,3 +3960,4 @@ Furthermore, 'make install' will silently fail to set the DNS binaries to
 be owned by group "gnunetdns" unless that group already exists (!).
 An alternative name for the "gnunetdns" group can be specified using the
 @code{--with-gnunetdns=GRPNAME} configure option.
+
diff --git a/doc/documentation/gnunet.texi b/doc/documentation/gnunet.texi
index 0d539a9d7..5ba6f6b15 100644
--- a/doc/documentation/gnunet.texi
+++ b/doc/documentation/gnunet.texi
@@ -82,6 +82,7 @@ This document is the Reference Manual for GNUnet version @value{VERSION}.
 
 * Preface::                         Chapter 0
 * Philosophy::                      About GNUnet
+* Key Concepts::                    Key concepts of GNUnet
 @c * Vocabulary::                      Vocabulary
 * Installing GNUnet::               Installing GNUnet
 * Using GNUnet::                    Using GNUnet
@@ -105,11 +106,12 @@ Preface
 
 Philosophy
 
-* Design Goals::
-* Security and Privacy::
-* Versatility::
-* Practicality::
-* Key Concepts::
+* Design Principles::
+* Privacy and Anonymity::
+* Practicality:: 
+
+Key Concepts
+
 * Authentication::
 * Accounting to Encourage Resource Sharing::
 * Confidentiality::
@@ -125,16 +127,16 @@ Installing GNUnet
 
 Using GNUnet
 
-* Checking the Installation::
-* First steps - File-sharing::
+* Start and stop GNUnet::
 * First steps - Using the GNU Name System::
 * First steps - Using GNUnet Conversation::
 * First steps - Using the GNUnet VPN::
 * File-sharing::
 * The GNU Name System::
 * Using the Virtual Public Network::
-* The graphical configuration interface::
-* How to start and stop a GNUnet peer::
+* MOVE TO INSTALL The graphical configuration interface::
+* MOVE TO INSTALL Checking the Installation::
+* MOVE TO INSTALL Config Leftovers::
 
 GNUnet Contributors Handbook
 
@@ -196,6 +198,10 @@ GNUnet Developer Handbook
 @c *********************************************************************
 
 @c *********************************************************************
+@include chapters/keyconcepts.texi
+@c *********************************************************************
+
+@c *********************************************************************
 @include chapters/installation.texi
 @c *********************************************************************