aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorBernd Fix <bernd.fix@pep.foundation>2018-06-27 23:34:33 +0200
committerBernd Fix <bernd.fix@pep.foundation>2018-06-27 23:38:52 +0200
commitee31ad45010cce040432163b026a3d8c873dd63d (patch)
treef727e372efc6fafeefd37be4709efdec94599bd0 /doc
parent3e1a4498d2d95e957d783b3a25206385750f36cd (diff)
downloadgnunet-ee31ad45010cce040432163b026a3d8c873dd63d.tar.gz
gnunet-ee31ad45010cce040432163b026a3d8c873dd63d.zip
Changed philosophy.texi (and split philosophy and key concepts).wq
Diffstat (limited to 'doc')
-rw-r--r--doc/documentation/chapters/keyconcepts.texi308
-rw-r--r--doc/documentation/chapters/philosophy.texi446
-rw-r--r--doc/documentation/gnunet.texi16
3 files changed, 361 insertions, 409 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 @@
1
2@cindex Key Concepts
3@node Key Concepts
4@chapter Key Concepts
5
6In this section, the fundamental concepts of GNUnet are explained.
7@c FIXME: Use @uref{https://docs.gnunet.org/bib/, research papers}
8@c once we have the new bibliography + subdomain setup.
9Most of them are also described in our research papers.
10First, some of the concepts used in the GNUnet framework are detailed.
11The second part describes concepts specific to anonymous file-sharing.
12
13@menu
14* Authentication::
15* Accounting to Encourage Resource Sharing::
16* Confidentiality::
17* Anonymity::
18* Deniability::
19* Peer Identities::
20* Zones in the GNU Name System (GNS Zones)::
21* Egos::
22@end menu
23
24@cindex Authentication
25@node Authentication
26@section Authentication
27
28Almost all peer-to-peer communications in GNUnet are between mutually
29authenticated peers. The authentication works by using ECDHE, that is a
30DH (Diffie---Hellman) key exchange using ephemeral elliptic curve
31cryptography. The ephemeral ECC (Elliptic Curve Cryptography) keys are
32signed using ECDSA (@uref{http://en.wikipedia.org/wiki/ECDSA, ECDSA}).
33The shared secret from ECDHE is used to create a pair of session keys
34@c FIXME: Long word for HKDF. More FIXMEs: Explain MITM etc.
35(using HKDF) which are then used to encrypt the communication between the
36two peers using both 256-bit AES (Advanced Encryption Standard)
37and 256-bit Twofish (with independently derived secret keys).
38As only the two participating hosts know the shared secret, this
39authenticates each packet
40without requiring signatures each time. GNUnet uses SHA-512
41(Secure Hash Algorithm) hash codes to verify the integrity of messages.
42
43@c FIXME: A while back I got the feedback that I should try and integrate
44@c explanation boxes in the long-run. So we could explain
45@c "man-in-the-middle" and "man-in-the-middle attacks" and other words
46@c which are not common knowledge. MITM is not common knowledge. To be
47@c selfcontained, we should be able to explain words and concepts used in
48@c a chapter or paragraph without hinting at Wikipedia and other online
49@c sources which might not be available or accessible to everyone.
50@c On the other hand we could write an introductionary chapter or book
51@c that we could then reference in each chapter, which sound like it
52@c could be more reusable.
53In GNUnet, the identity of a host is its public key. For that reason,
54man-in-the-middle attacks will not break the authentication or accounting
55goals. Essentially, for GNUnet, the IP of the host has nothing to do with
56the identity of the host. As the public key is the only thing that truly
57matters, faking an IP, a port or any other property of the underlying
58transport protocol is irrelevant. In fact, GNUnet peers can use
59multiple IPs (IPv4 and IPv6) on multiple ports --- or even not use the
60IP protocol at all (by running directly on layer 2).
61@c FIXME: "IP protocol" feels wrong, but could be what people expect, as
62@c IP is "the number" and "IP protocol" the protocol itself in general
63@c knowledge?
64
65@c NOTE: For consistency we will use @code{HELLO}s throughout this Manual.
66GNUnet uses a special type of message to communicate a binding between
67public (ECC) keys to their current network address. These messages are
68commonly called @code{HELLO}s or @code{peer advertisements}.
69They contain the public key of the peer and its current network
70addresses for various transport services.
71A transport service is a special kind of shared library that
72provides (possibly unreliable, out-of-order) message delivery between
73peers.
74For the UDP and TCP transport services, a network address is an IP and a
75port.
76GNUnet can also use other transports (HTTP, HTTPS, WLAN, etc.) which use
77various other forms of addresses. Note that any node can have many
78different active transport services at the same time,
79and each of these can have a different addresses.
80Binding messages expire after at most a week (the timeout can be
81shorter if the user configures the node appropriately).
82This expiration ensures that the network will eventually get rid of
83outdated advertisements.
84@footnote{Ronaldo A. Ferreira, Christian Grothoff, and Paul Ruth.
85A Transport Layer Abstraction for Peer-to-Peer Networks
86Proceedings of the 3rd International Symposium on Cluster Computing
87and the Grid (GRID 2003), 2003.
88(@uref{https://gnunet.org/git/bibliography.git/plain/docs/transport.pdf, https://gnunet.org/git/bibliography.git/plain/docs/transport.pdf})}
89
90@cindex Accounting to Encourage Resource Sharing
91@node Accounting to Encourage Resource Sharing
92@section Accounting to Encourage Resource Sharing
93
94Most distributed P2P networks suffer from a lack of defenses or
95precautions against attacks in the form of freeloading.
96While the intentions of an attacker and a freeloader are different, their
97effect on the network is the same; they both render it useless.
98Most simple attacks on networks such as @command{Gnutella}
99involve flooding the network with traffic, particularly
100with queries that are, in the worst case, multiplied by the network.
101
102In order to ensure that freeloaders or attackers have a minimal impact
103on the network, GNUnet's file-sharing implementation (@code{FS} tries
104to distinguish good (contributing) nodes from malicious (freeloading)
105nodes. In GNUnet, every file-sharing node keeps track of the behavior
106of every other node it has been in contact with. Many requests
107(depending on the application) are transmitted with a priority (or
108importance) level. That priority is used to establish how important
109the sender believes this request is. If a peer responds to an
110important request, the recipient will increase its trust in the
111responder: the responder contributed resources. If a peer is too busy
112to answer all requests, it needs to prioritize. For that, peers do
113not take the priorities of the requests received at face value.
114First, they check how much they trust the sender, and depending on
115that amount of trust they assign the request a (possibly lower)
116effective priority. Then, they drop the requests with the lowest
117effective priority to satisfy their resource constraints. This way,
118GNUnet's economic model ensures that nodes that are not currently
119considered to have a surplus in contributions will not be served if
120the network load is high.
121@footnote{Christian Grothoff. An Excess-Based Economic Model for Resource
122Allocation in Peer-to-Peer Networks. Wirtschaftsinformatik, June 2003.
123(@uref{https://gnunet.org/git/bibliography.git/plain/docs/ebe.pdf, https://gnunet.org/git/bibliography.git/plain/docs/ebe.pdf})}
124@c 2009?
125
126@cindex Confidentiality
127@node Confidentiality
128@section Confidentiality
129
130Adversaries (malicious, bad actors) outside of GNUnet are not supposed
131to know what kind of actions a peer is involved in. Only the specific
132neighbor of a peer that is the corresponding sender or recipient of a
133message may know its contents, and even then application protocols may
134place further restrictions on that knowledge. In order to ensure
135confidentiality, GNUnet uses link encryption, that is each message
136exchanged between two peers is encrypted using a pair of keys only
137known to these two peers. Encrypting traffic like this makes any kind
138of traffic analysis much harder. Naturally, for some applications, it
139may still be desirable if even neighbors cannot determine the concrete
140contents of a message. In GNUnet, this problem is addressed by the
141specific application-level protocols. See for example the following
142sections @pxref{Anonymity}, @pxref{How file-sharing achieves Anonymity},
143and @pxref{Deniability}.
144
145@cindex Anonymity
146@node Anonymity
147@section Anonymity
148
149@menu
150* How file-sharing achieves Anonymity::
151@end menu
152
153Providing anonymity for users is the central goal for the anonymous
154file-sharing application. Many other design decisions follow in the
155footsteps of this requirement.
156Anonymity is never absolute. While there are various
157scientific metrics@footnote{Claudia Díaz, Stefaan Seys, Joris Claessens,
158and Bart Preneel. Towards measuring anonymity.
1592002.
160(@uref{https://gnunet.org/git/bibliography.git/plain/docs/article-89.pdf, https://gnunet.org/git/bibliography.git/plain/docs/article-89.pdf})}
161that can help quantify the level of anonymity that a given mechanism
162provides, there is no such thing as "complete anonymity".
163GNUnet's file-sharing implementation allows users to select for each
164operation (publish, search, download) the desired level of anonymity.
165The metric used is the amount of cover traffic available to hide the
166request.
167While this metric is not as good as, for example, the theoretical metric
168given in scientific metrics@footnote{likewise},
169it is probably the best metric available to a peer with a purely local
170view of the world that does not rely on unreliable external information.
171The default anonymity level is @code{1}, which uses anonymous routing but
172imposes no minimal requirements on cover traffic. It is possible
173to forego anonymity when this is not required. The anonymity level of
174@code{0} allows GNUnet to use more efficient, non-anonymous routing.
175
176@cindex How file-sharing achieves Anonymity
177@node How file-sharing achieves Anonymity
178@subsection How file-sharing achieves Anonymity
179
180Contrary to other designs, we do not believe that users achieve strong
181anonymity just because their requests are obfuscated by a couple of
182indirections. This is not sufficient if the adversary uses traffic
183analysis.
184The threat model used for anonymous file sharing in GNUnet assumes that
185the adversary is quite powerful.
186In particular, we assume that the adversary can see all the traffic on
187the Internet. And while we assume that the adversary
188can not break our encryption, we assume that the adversary has many
189participating nodes in the network and that it can thus see many of the
190node-to-node interactions since it controls some of the nodes.
191
192The system tries to achieve anonymity based on the idea that users can be
193anonymous if they can hide their actions in the traffic created by other
194users.
195Hiding actions in the traffic of other users requires participating in the
196traffic, bringing back the traditional technique of using indirection and
197source rewriting. Source rewriting is required to gain anonymity since
198otherwise an adversary could tell if a message originated from a host by
199looking at the source address. If all packets look like they originate
200from one node, the adversary can not tell which ones originate from that
201node and which ones were routed.
202Note that in this mindset, any node can decide to break the
203source-rewriting paradigm without violating the protocol, as this
204only reduces the amount of traffic that a node can hide its own traffic
205in.
206
207If we want to hide our actions in the traffic of other nodes, we must make
208our traffic indistinguishable from the traffic that we route for others.
209As our queries must have us as the receiver of the reply
210(otherwise they would be useless), we must put ourselves as the receiver
211of replies that actually go to other hosts; in other words, we must
212indirect replies.
213Unlike other systems, in anonymous file-sharing as implemented on top of
214GNUnet we do not have to indirect the replies if we don't think we need
215more traffic to hide our own actions.
216
217This increases the efficiency of the network as we can indirect less under
218higher load.@footnote{Krista Bennett and Christian Grothoff.
219GAP --- practical anonymous networking. In Proceedings of
220Designing Privacy Enhancing Technologies, 2003.
221(@uref{https://gnunet.org/git/bibliography.git/plain/docs/aff.pdf, https://gnunet.org/git/bibliography.git/plain/docs/aff.pdf})}
222
223@cindex Deniability
224@node Deniability
225@section Deniability
226
227Even if the user that downloads data and the server that provides data are
228anonymous, the intermediaries may still be targets. In particular, if the
229intermediaries can find out which queries or which content they are
230processing, a strong adversary could try to force them to censor
231certain materials.
232
233With the file-encoding used by GNUnet's anonymous file-sharing, this
234problem does not arise.
235The reason is that queries and replies are transmitted in
236an encrypted format such that intermediaries cannot tell what the query
237is for or what the content is about. Mind that this is not the same
238encryption as the link-encryption between the nodes. GNUnet has
239encryption on the network layer (link encryption, confidentiality,
240authentication) and again on the application layer (provided
241by @command{gnunet-publish}, @command{gnunet-download},
242@command{gnunet-search} and @command{gnunet-gtk}).
243@footnote{Christian Grothoff, Krista Grothoff, Tzvetan Horozov,
244and Jussi T. Lindgren.
245An Encoding for Censorship-Resistant Sharing.
2462009.
247(@uref{https://gnunet.org/git/bibliography.git/plain/docs/ecrs.pdf, https://gnunet.org/git/bibliography.git/plain/docs/ecrs.pdf})}
248
249@cindex Peer Identities
250@node Peer Identities
251@section Peer Identities
252
253Peer identities are used to identify peers in the network and are unique
254for each peer. The identity for a peer is simply its public key, which is
255generated along with a private key the peer is started for the first time.
256While the identity is binary data, it is often expressed as ASCII string.
257For example, the following is a peer identity as you might see it in
258various places:
259
260@example
261UAT1S6PMPITLBKSJ2DGV341JI6KF7B66AC4JVCN9811NNEGQLUN0
262@end example
263
264@noindent
265You can find your peer identity by running @command{gnunet-peerinfo -s}.
266
267@cindex Zones in the GNU Name System (GNS Zones)
268@node Zones in the GNU Name System (GNS Zones)
269@section Zones in the GNU Name System (GNS Zones)
270
271@c FIXME: Explain or link to an explanation of the concept of public keys
272@c and private keys.
273@c FIXME: Rewrite for the latest GNS changes.
274GNS@footnote{Matthias Wachs, Martin Schanzenbach, and Christian Grothoff.
275A Censorship-Resistant, Privacy-Enhancing and Fully Decentralized Name
276System. In proceedings of 13th International Conference on Cryptology and
277Network Security (CANS 2014). 2014.
278@uref{https://gnunet.org/git/bibliography.git/plain/docs/gns2014wachs.pdf, https://gnunet.org/git/bibliography.git/plain/docs/gns2014wachs.pdf}}
279zones are similar to those of DNS zones, but instead of a hierarchy of
280authorities to governing their use, GNS zones are controlled by a private
281key.
282When you create a record in a DNS zone, that information is stored in your
283nameserver. Anyone trying to resolve your domain then gets pointed
284(hopefully) by the centralised authority to your nameserver.
285Whereas GNS, being fully decentralized by design, stores that information
286in DHT. The validity of the records is assured cryptographically, by
287signing them with the private key of the respective zone.
288
289Anyone trying to resolve records in a zone of your domain can then verify
290the signature of the records they get from the DHT and be assured that
291they are indeed from the respective zone.
292To make this work, there is a 1:1 correspondence between zones and
293their public-private key pairs.
294So when we talk about the owner of a GNS zone, that's really the owner of
295the private key.
296And a user accessing a zone needs to somehow specify the corresponding
297public key first.
298
299@cindex Egos
300@node Egos
301@section Egos
302
303@c what is the difference between peer identity and egos? It seems
304@c like both are linked to public-private key pair.
305Egos are your "identities" in GNUnet. Any user can assume multiple
306identities, for example to separate their activities online. Egos can
307correspond to "pseudonyms" or "real-world identities". Technically an
308ego 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 @@
5@c NOTE: We should probably re-use some of the images lynX created 5@c NOTE: We should probably re-use some of the images lynX created
6@c for secushare, showing some of the relations and functionalities 6@c for secushare, showing some of the relations and functionalities
7@c of GNUnet. 7@c of GNUnet.
8The foremost goal of the GNUnet project is to become a widely used, 8The primary goal of the GNUnet project is to provide a reliable, open,
9reliable, open, non-discriminating, egalitarian, unconstrained and 9non-discriminating and censorship-resistant system for information
10censorship-resistant system of free information exchange. 10exchange. We value free speech above state interests and intellectual
11We value free speech above state secrets, law-enforcement or 11monopoly. GNUnet's long-term goal is to serve as a development
12intellectual monopoly. 12platform for the next generation of Internet protocols.
13GNUnet is supposed to be an anarchistic network, where the only 13
14limitation for participants (devices or people making use of the 14GNUnet is an anarchistic network. Participants are encouraged to
15network, in the following sometimes called peers) is 15contribute at least as much resources (storage, bandwidth) to the network
16that they must contribute enough back to the network such that 16as they consume, so that their participation does not have a negative
17their resource consumption does not have a significant impact 17impact on other users.
18on other users.
19GNUnet should be more than just another file-sharing network.
20The plan is to offer many other services and in particular
21to serve as a development platform for the next generation of
22Internet Protocols.
23 18
24@menu 19@menu
25* Design Goals:: 20* Design Principles::
26* Security and Privacy:: 21* Privacy and Anonymity::
27* Versatility::
28* Practicality:: 22* Practicality::
29* Key Concepts::
30@end menu 23@end menu
31 24
32@cindex Design Goals 25@cindex Design Principles
33@cindex Design Goals 26@node Design Principles
34@node Design Goals 27@section Design Principles
35@section Design Goals
36 28
37These are the core GNUnet design goals, in order of relative importance: 29These are the GNUnet design principles, in order of importance:
38 30
39@itemize 31@itemize
40@item GNUnet must be implemented as 32@item GNUnet must be implemented as
@@ -44,399 +36,45 @@ These are the core GNUnet design goals, in order of relative importance:
44the program, to study and change the program in source code form, 36the program, to study and change the program in source code form,
45to redistribute exact copies, and to distribute modified versions. 37to redistribute exact copies, and to distribute modified versions.
46Refer to @uref{https://www.gnu.org/philosophy/free-sw.html, https://www.gnu.org/philosophy/free-sw.html}} 38Refer to @uref{https://www.gnu.org/philosophy/free-sw.html, https://www.gnu.org/philosophy/free-sw.html}}
47@item GNUnet must only disclose the minimal amount of information 39@item GNUnet must minimize the amount of personally identifiable information exposed.
48necessary.
49@c TODO: Explain 'fully' in the terminology section. 40@c TODO: Explain 'fully' in the terminology section.
50@item GNUnet must be fully distributed and survive 41@item GNUnet must be fully distributed and resilient to external attacks and rogue participants.
51@uref{https://en.wikipedia.org/wiki/Byzantine_fault_tolerance, Byzantine failures} 42@item GNUnet must be self-organizing and not depend on administrators or centralized infrastructure.
52@footnote{@uref{https://en.wikipedia.org/wiki/Byzantine_fault_tolerance, https://en.wikipedia.org/wiki/Byzantine_fault_tolerance}} 43@item GNUnet must inform the user which other participants have to be trusted when establishing private communications.
53at any position in the network.
54@item GNUnet must make it explicit to the user which entities are
55considered to be trustworthy when establishing secured communications.
56@item GNUnet must use compartmentalization to protect sensitive
57information.
58@item GNUnet must be open and permit new peers to join. 44@item GNUnet must be open and permit new peers to join.
59@item GNUnet must be self-organizing and not depend on administrators.
60@item GNUnet must support a diverse range of applications and devices. 45@item GNUnet must support a diverse range of applications and devices.
61@item The GNUnet architecture must be cost effective. 46@item GNUnet must use compartmentalization to protect sensitive information.
62@item GNUnet must provide incentives for peers to contribute more 47@item The GNUnet architecture must be resource efficient.
63resources than they consume. 48@item GNUnet must provide incentives for peers to contribute more resources than they consume.
64@end itemize 49@end itemize
65 50
66 51
67@cindex Security and Privacy 52@cindex Privacy and Anonymity
68@node Security and Privacy 53@node Privacy and Anonymity
69@section Security and Privacy 54@section Privacy and Anonymity
70
71GNUnet's primary design goals are to protect the privacy of its users and
72to guard itself against attacks or abuse.
73GNUnet does not have any mechanisms to control, track or censor users.
74Instead, the GNUnet protocols aim to make it as hard as possible to
75find out what is happening on the network or to disrupt operations.
76 55
77@cindex Versatility 56The GNUnet protocols minimize the leakage of personally identifiable information of participants and
78@node Versatility 57do not allow adversaries to control, track, monitor or censor users activities. The
79@section Versatility 58GNUnet protocols also make it as hard as possible to disrupt operations by participating in the network with malicious intent.
80 59
81We call GNUnet a peer-to-peer framework because we want to support many 60Analyzing participant's activities becomes more difficult as the number of peers and
82different forms of peer-to-peer applications. GNUnet uses a plugin 61applications that generate traffic on the network grows, even if the additional
83architecture to make the system extensible and to encourage code reuse. 62traffic generated is not related to anonymous communication. This is one of the reasons why GNUnet is developed as a peer-to-peer
84While the first versions of the system only supported anonymous
85file-sharing, other applications are being worked on and more will
86hopefully follow in the future.
87A powerful synergy regarding anonymity services is created by a large
88community utilizing many diverse applications over the same software
89infrastructure. The reason is that link encryption hides the specifics
90of the traffic for non-participating observers. This way, anonymity can
91get stronger with additional (GNUnet) traffic, even if the additional
92traffic is not related to anonymous communication. Increasing anonymity
93is the primary reason why GNUnet is developed to become a peer-to-peer
94framework where many applications share the lower layers of an 63framework where many applications share the lower layers of an
95increasingly complex protocol stack. 64increasingly complex protocol stack. The GNUnet architecture encourages many
96If merging traffic to hinder traffic analysis was not important, 65different forms of peer-to-peer applications.
97we could have just developed a dozen stand-alone applications
98and a few shared libraries.
99 66
100@cindex Practicality 67@cindex Practicality
101@node Practicality 68@node Practicality
102@section Practicality 69@section Practicality
103 70
104GNUnet allows participants to trade various amounts of security in 71Whereever possible GNUnet allows the peer to adjust its operations
105exchange for increased efficiency. However, it is not possible for any 72and functionalities to specific use cases. A GNUnet peer running on
106user's security and efficiency requirements to compromise the security 73a mobile device with limited battery for example might choose not to
107and efficiency of any other user. 74relay traffic for other participants.
108
109For GNUnet, efficiency is not paramount. If there were a more secure and
110still practical approach, we would choose to take the more secure
111alternative. @command{telnet} is more efficient than @command{ssh}, yet
112it is obsolete.
113Hardware gets faster, and code can be optimized. Fixing security issues
114as an afterthought is much harder.
115
116While security is paramount, practicability is still a requirement.
117The most secure system is always the one that nobody can use.
118Similarly, any anonymous system that is extremely inefficient will only
119find few users.
120However, good anonymity requires a large and diverse user base. Since
121individual security requirements may vary, the only good solution here is
122to allow individuals to trade-off security and efficiency.
123The primary challenge in allowing this is to ensure that the economic
124incentives work properly.
125In particular, this means that it must be impossible for a user to gain
126security at the expense of other users. Many designs (e.g. anonymity via
127broadcast) fail to give users an incentive to choose a less secure but
128more efficient mode of operation.
129GNUnet should avoid where ever possible to rely on protocols that will
130only work if the participants are benevolent.
131While some designs have had widespread success while relying on parties
132to observe a protocol that may be sub-optimal for the individuals (e.g.
133TCP Nagle), a protocol that ensures that individual goals never conflict
134with the goals of the group is always preferable.
135
136@cindex Key Concepts
137@node Key Concepts
138@section Key Concepts
139
140In this section, the fundamental concepts of GNUnet are explained.
141@c FIXME: Use @uref{https://docs.gnunet.org/bib/, research papers}
142@c once we have the new bibliography + subdomain setup.
143Most of them are also described in our research papers.
144First, some of the concepts used in the GNUnet framework are detailed.
145The second part describes concepts specific to anonymous file-sharing.
146
147@menu
148* Authentication::
149* Accounting to Encourage Resource Sharing::
150* Confidentiality::
151* Anonymity::
152* Deniability::
153* Peer Identities::
154* Zones in the GNU Name System (GNS Zones)::
155* Egos::
156@end menu
157
158@cindex Authentication
159@node Authentication
160@subsection Authentication
161
162Almost all peer-to-peer communications in GNUnet are between mutually
163authenticated peers. The authentication works by using ECDHE, that is a
164DH (Diffie---Hellman) key exchange using ephemeral elliptic curve
165cryptography. The ephemeral ECC (Elliptic Curve Cryptography) keys are
166signed using ECDSA (@uref{http://en.wikipedia.org/wiki/ECDSA, ECDSA}).
167The shared secret from ECDHE is used to create a pair of session keys
168@c FIXME: Long word for HKDF. More FIXMEs: Explain MITM etc.
169(using HKDF) which are then used to encrypt the communication between the
170two peers using both 256-bit AES (Advanced Encryption Standard)
171and 256-bit Twofish (with independently derived secret keys).
172As only the two participating hosts know the shared secret, this
173authenticates each packet
174without requiring signatures each time. GNUnet uses SHA-512
175(Secure Hash Algorithm) hash codes to verify the integrity of messages.
176
177@c FIXME: A while back I got the feedback that I should try and integrate
178@c explanation boxes in the long-run. So we could explain
179@c "man-in-the-middle" and "man-in-the-middle attacks" and other words
180@c which are not common knowledge. MITM is not common knowledge. To be
181@c selfcontained, we should be able to explain words and concepts used in
182@c a chapter or paragraph without hinting at Wikipedia and other online
183@c sources which might not be available or accessible to everyone.
184@c On the other hand we could write an introductionary chapter or book
185@c that we could then reference in each chapter, which sound like it
186@c could be more reusable.
187In GNUnet, the identity of a host is its public key. For that reason,
188man-in-the-middle attacks will not break the authentication or accounting
189goals. Essentially, for GNUnet, the IP of the host has nothing to do with
190the identity of the host. As the public key is the only thing that truly
191matters, faking an IP, a port or any other property of the underlying
192transport protocol is irrelevant. In fact, GNUnet peers can use
193multiple IPs (IPv4 and IPv6) on multiple ports --- or even not use the
194IP protocol at all (by running directly on layer 2).
195@c FIXME: "IP protocol" feels wrong, but could be what people expect, as
196@c IP is "the number" and "IP protocol" the protocol itself in general
197@c knowledge?
198
199@c NOTE: For consistency we will use @code{HELLO}s throughout this Manual.
200GNUnet uses a special type of message to communicate a binding between
201public (ECC) keys to their current network address. These messages are
202commonly called @code{HELLO}s or @code{peer advertisements}.
203They contain the public key of the peer and its current network
204addresses for various transport services.
205A transport service is a special kind of shared library that
206provides (possibly unreliable, out-of-order) message delivery between
207peers.
208For the UDP and TCP transport services, a network address is an IP and a
209port.
210GNUnet can also use other transports (HTTP, HTTPS, WLAN, etc.) which use
211various other forms of addresses. Note that any node can have many
212different active transport services at the same time,
213and each of these can have a different addresses.
214Binding messages expire after at most a week (the timeout can be
215shorter if the user configures the node appropriately).
216This expiration ensures that the network will eventually get rid of
217outdated advertisements.
218@footnote{Ronaldo A. Ferreira, Christian Grothoff, and Paul Ruth.
219A Transport Layer Abstraction for Peer-to-Peer Networks
220Proceedings of the 3rd International Symposium on Cluster Computing
221and the Grid (GRID 2003), 2003.
222(@uref{https://gnunet.org/git/bibliography.git/plain/docs/transport.pdf, https://gnunet.org/git/bibliography.git/plain/docs/transport.pdf})}
223
224@cindex Accounting to Encourage Resource Sharing
225@node Accounting to Encourage Resource Sharing
226@subsection Accounting to Encourage Resource Sharing
227
228Most distributed P2P networks suffer from a lack of defenses or
229precautions against attacks in the form of freeloading.
230While the intentions of an attacker and a freeloader are different, their
231effect on the network is the same; they both render it useless.
232Most simple attacks on networks such as @command{Gnutella}
233involve flooding the network with traffic, particularly
234with queries that are, in the worst case, multiplied by the network.
235
236In order to ensure that freeloaders or attackers have a minimal impact
237on the network, GNUnet's file-sharing implementation (@code{FS} tries
238to distinguish good (contributing) nodes from malicious (freeloading)
239nodes. In GNUnet, every file-sharing node keeps track of the behavior
240of every other node it has been in contact with. Many requests
241(depending on the application) are transmitted with a priority (or
242importance) level. That priority is used to establish how important
243the sender believes this request is. If a peer responds to an
244important request, the recipient will increase its trust in the
245responder: the responder contributed resources. If a peer is too busy
246to answer all requests, it needs to prioritize. For that, peers do
247not take the priorities of the requests received at face value.
248First, they check how much they trust the sender, and depending on
249that amount of trust they assign the request a (possibly lower)
250effective priority. Then, they drop the requests with the lowest
251effective priority to satisfy their resource constraints. This way,
252GNUnet's economic model ensures that nodes that are not currently
253considered to have a surplus in contributions will not be served if
254the network load is high.
255@footnote{Christian Grothoff. An Excess-Based Economic Model for Resource
256Allocation in Peer-to-Peer Networks. Wirtschaftsinformatik, June 2003.
257(@uref{https://gnunet.org/git/bibliography.git/plain/docs/ebe.pdf, https://gnunet.org/git/bibliography.git/plain/docs/ebe.pdf})}
258@c 2009?
259
260@cindex Confidentiality
261@node Confidentiality
262@subsection Confidentiality
263
264Adversaries (malicious, bad actors) outside of GNUnet are not supposed
265to know what kind of actions a peer is involved in. Only the specific
266neighbor of a peer that is the corresponding sender or recipient of a
267message may know its contents, and even then application protocols may
268place further restrictions on that knowledge. In order to ensure
269confidentiality, GNUnet uses link encryption, that is each message
270exchanged between two peers is encrypted using a pair of keys only
271known to these two peers. Encrypting traffic like this makes any kind
272of traffic analysis much harder. Naturally, for some applications, it
273may still be desirable if even neighbors cannot determine the concrete
274contents of a message. In GNUnet, this problem is addressed by the
275specific application-level protocols. See for example the following
276sections @pxref{Anonymity}, @pxref{How file-sharing achieves Anonymity},
277and @pxref{Deniability}.
278
279@cindex Anonymity
280@node Anonymity
281@subsection Anonymity
282 75
283@menu 76For certain applications like file-sharing GNUnet allows participants to trade degrees of anonymity in
284* How file-sharing achieves Anonymity:: 77exchange for increased efficiency. However, it is not possible for any
285@end menu 78user's efficiency requirements to compromise the anonymity
286 79of any other user.
287Providing anonymity for users is the central goal for the anonymous
288file-sharing application. Many other design decisions follow in the
289footsteps of this requirement.
290Anonymity is never absolute. While there are various
291scientific metrics@footnote{Claudia Díaz, Stefaan Seys, Joris Claessens,
292and Bart Preneel. Towards measuring anonymity.
2932002.
294(@uref{https://gnunet.org/git/bibliography.git/plain/docs/article-89.pdf, https://gnunet.org/git/bibliography.git/plain/docs/article-89.pdf})}
295that can help quantify the level of anonymity that a given mechanism
296provides, there is no such thing as "complete anonymity".
297GNUnet's file-sharing implementation allows users to select for each
298operation (publish, search, download) the desired level of anonymity.
299The metric used is the amount of cover traffic available to hide the
300request.
301While this metric is not as good as, for example, the theoretical metric
302given in scientific metrics@footnote{likewise},
303it is probably the best metric available to a peer with a purely local
304view of the world that does not rely on unreliable external information.
305The default anonymity level is @code{1}, which uses anonymous routing but
306imposes no minimal requirements on cover traffic. It is possible
307to forego anonymity when this is not required. The anonymity level of
308@code{0} allows GNUnet to use more efficient, non-anonymous routing.
309
310@cindex How file-sharing achieves Anonymity
311@node How file-sharing achieves Anonymity
312@subsubsection How file-sharing achieves Anonymity
313
314Contrary to other designs, we do not believe that users achieve strong
315anonymity just because their requests are obfuscated by a couple of
316indirections. This is not sufficient if the adversary uses traffic
317analysis.
318The threat model used for anonymous file sharing in GNUnet assumes that
319the adversary is quite powerful.
320In particular, we assume that the adversary can see all the traffic on
321the Internet. And while we assume that the adversary
322can not break our encryption, we assume that the adversary has many
323participating nodes in the network and that it can thus see many of the
324node-to-node interactions since it controls some of the nodes.
325
326The system tries to achieve anonymity based on the idea that users can be
327anonymous if they can hide their actions in the traffic created by other
328users.
329Hiding actions in the traffic of other users requires participating in the
330traffic, bringing back the traditional technique of using indirection and
331source rewriting. Source rewriting is required to gain anonymity since
332otherwise an adversary could tell if a message originated from a host by
333looking at the source address. If all packets look like they originate
334from one node, the adversary can not tell which ones originate from that
335node and which ones were routed.
336Note that in this mindset, any node can decide to break the
337source-rewriting paradigm without violating the protocol, as this
338only reduces the amount of traffic that a node can hide its own traffic
339in.
340
341If we want to hide our actions in the traffic of other nodes, we must make
342our traffic indistinguishable from the traffic that we route for others.
343As our queries must have us as the receiver of the reply
344(otherwise they would be useless), we must put ourselves as the receiver
345of replies that actually go to other hosts; in other words, we must
346indirect replies.
347Unlike other systems, in anonymous file-sharing as implemented on top of
348GNUnet we do not have to indirect the replies if we don't think we need
349more traffic to hide our own actions.
350
351This increases the efficiency of the network as we can indirect less under
352higher load.@footnote{Krista Bennett and Christian Grothoff.
353GAP --- practical anonymous networking. In Proceedings of
354Designing Privacy Enhancing Technologies, 2003.
355(@uref{https://gnunet.org/git/bibliography.git/plain/docs/aff.pdf, https://gnunet.org/git/bibliography.git/plain/docs/aff.pdf})}
356
357@cindex Deniability
358@node Deniability
359@subsection Deniability
360
361Even if the user that downloads data and the server that provides data are
362anonymous, the intermediaries may still be targets. In particular, if the
363intermediaries can find out which queries or which content they are
364processing, a strong adversary could try to force them to censor
365certain materials.
366
367With the file-encoding used by GNUnet's anonymous file-sharing, this
368problem does not arise.
369The reason is that queries and replies are transmitted in
370an encrypted format such that intermediaries cannot tell what the query
371is for or what the content is about. Mind that this is not the same
372encryption as the link-encryption between the nodes. GNUnet has
373encryption on the network layer (link encryption, confidentiality,
374authentication) and again on the application layer (provided
375by @command{gnunet-publish}, @command{gnunet-download},
376@command{gnunet-search} and @command{gnunet-gtk}).
377@footnote{Christian Grothoff, Krista Grothoff, Tzvetan Horozov,
378and Jussi T. Lindgren.
379An Encoding for Censorship-Resistant Sharing.
3802009.
381(@uref{https://gnunet.org/git/bibliography.git/plain/docs/ecrs.pdf, https://gnunet.org/git/bibliography.git/plain/docs/ecrs.pdf})}
382
383@cindex Peer Identities
384@node Peer Identities
385@subsection Peer Identities
386
387Peer identities are used to identify peers in the network and are unique
388for each peer. The identity for a peer is simply its public key, which is
389generated along with a private key the peer is started for the first time.
390While the identity is binary data, it is often expressed as ASCII string.
391For example, the following is a peer identity as you might see it in
392various places:
393
394@example
395UAT1S6PMPITLBKSJ2DGV341JI6KF7B66AC4JVCN9811NNEGQLUN0
396@end example
397
398@noindent
399You can find your peer identity by running @command{gnunet-peerinfo -s}.
400
401@cindex Zones in the GNU Name System (GNS Zones)
402@node Zones in the GNU Name System (GNS Zones)
403@subsection Zones in the GNU Name System (GNS Zones)
404
405@c FIXME: Explain or link to an explanation of the concept of public keys
406@c and private keys.
407@c FIXME: Rewrite for the latest GNS changes.
408GNS@footnote{Matthias Wachs, Martin Schanzenbach, and Christian Grothoff.
409A Censorship-Resistant, Privacy-Enhancing and Fully Decentralized Name
410System. In proceedings of 13th International Conference on Cryptology and
411Network Security (CANS 2014). 2014.
412@uref{https://gnunet.org/git/bibliography.git/plain/docs/gns2014wachs.pdf, https://gnunet.org/git/bibliography.git/plain/docs/gns2014wachs.pdf}}
413zones are similar to those of DNS zones, but instead of a hierarchy of
414authorities to governing their use, GNS zones are controlled by a private
415key.
416When you create a record in a DNS zone, that information is stored in your
417nameserver. Anyone trying to resolve your domain then gets pointed
418(hopefully) by the centralised authority to your nameserver.
419Whereas GNS, being fully decentralized by design, stores that information
420in DHT. The validity of the records is assured cryptographically, by
421signing them with the private key of the respective zone.
422
423Anyone trying to resolve records in a zone of your domain can then verify
424the signature of the records they get from the DHT and be assured that
425they are indeed from the respective zone.
426To make this work, there is a 1:1 correspondence between zones and
427their public-private key pairs.
428So when we talk about the owner of a GNS zone, that's really the owner of
429the private key.
430And a user accessing a zone needs to somehow specify the corresponding
431public key first.
432
433@cindex Egos
434@node Egos
435@subsection Egos
436 80
437@c what is the difference between peer identity and egos? It seems
438@c like both are linked to public-private key pair.
439Egos are your "identities" in GNUnet. Any user can assume multiple
440identities, for example to separate their activities online. Egos can
441correspond to "pseudonyms" or "real-world identities". Technically an
442ego is first of all a key pair of a public- and private-key.
diff --git a/doc/documentation/gnunet.texi b/doc/documentation/gnunet.texi
index 8528cf80a..563333050 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}.
82 82
83* Preface:: Chapter 0 83* Preface:: Chapter 0
84* Philosophy:: About GNUnet 84* Philosophy:: About GNUnet
85* Key Concepts:: Key concepts of GNUnet
85@c * Vocabulary:: Vocabulary 86@c * Vocabulary:: Vocabulary
86* Using GNUnet:: Using GNUnet 87* Using GNUnet:: Using GNUnet
87@c * Configuration Handbook:: Configuring GNUnet 88@c * Configuration Handbook:: Configuring GNUnet
@@ -104,11 +105,12 @@ Preface
104 105
105Philosophy 106Philosophy
106 107
107* Design Goals:: 108* Design Principles::
108* Security and Privacy:: 109* Privacy and Anonymity::
109* Versatility:: 110* Practicality::
110* Practicality:: 111
111* Key Concepts:: 112Key Concepts
113
112* Authentication:: 114* Authentication::
113* Accounting to Encourage Resource Sharing:: 115* Accounting to Encourage Resource Sharing::
114* Confidentiality:: 116* Confidentiality::
@@ -193,6 +195,10 @@ GNUnet Developer Handbook
193@c ********************************************************************* 195@c *********************************************************************
194 196
195@c ********************************************************************* 197@c *********************************************************************
198@include chapters/keyconcepts.texi
199@c *********************************************************************
200
201@c *********************************************************************
196@include chapters/user.texi 202@include chapters/user.texi
197@c ********************************************************************* 203@c *********************************************************************
198 204