aboutsummaryrefslogtreecommitdiff
path: root/doc/documentation/chapters/user.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/documentation/chapters/user.texi')
-rw-r--r--doc/documentation/chapters/user.texi2293
1 files changed, 0 insertions, 2293 deletions
diff --git a/doc/documentation/chapters/user.texi b/doc/documentation/chapters/user.texi
deleted file mode 100644
index 5aa3a62bf..000000000
--- a/doc/documentation/chapters/user.texi
+++ /dev/null
@@ -1,2293 +0,0 @@
1@node Using GNUnet
2@chapter Using GNUnet
3@c %**end of header
4
5This tutorial is supposed to give a first introduction for users
6trying to do something real with GNUnet. Installation and
7configuration are specifically outside of the scope of this tutorial.
8Instead, we start by briefly checking that the installation works, and
9then dive into uncomplicated, concrete practical things that can be done
10with the framework provided by GNUnet.
11
12In short, this chapter of the ``GNUnet Reference Documentation'' will
13show you how to use the various peer-to-peer applications of the
14GNUnet system.
15As GNUnet evolves, we will add new sections for the various
16applications that are being created.
17
18Comments on the content of this chapter, and extensions of it are
19always welcome.
20
21
22@menu
23* Start and stop GNUnet::
24* First steps - Using the GNU Name System::
25* First steps - Using GNUnet Conversation::
26* First steps - Using the GNUnet VPN::
27* File-sharing::
28* The GNU Name System::
29* re@:claim Identity Provider::
30* Using the Virtual Public Network::
31@end menu
32
33@node Start and stop GNUnet
34@section Start and stop GNUnet
35
36Previous to use any GNUnet-based application, one has to start a node:
37
38@example
39$ gnunet-arm -s -l gnunet.log
40@end example
41
42To stop GNUnet:
43
44@example
45$ gnunet-arm -e
46@end example
47
48@node First steps - Using the GNU Name System
49@section First steps - Using the GNU Name System
50@c %**end of header
51
52@menu
53* Preliminaries::
54* Managing Egos::
55* The GNS Tab::
56* Creating a Record::
57* Resolving GNS records::
58* Integration with Browsers::
59* Creating a Business Card::
60* Be Social::
61* Backup of Identities and Egos::
62* Revocation::
63* What's Next?::
64@end menu
65
66@node Preliminaries
67@subsection Preliminaries
68@c %**end of header
69
70``.pin'' is a default zone which points to a zone managed by gnunet.org.
71Use @code{gnunet-config -s gns} to view the GNS configuration, including
72all configured zones that are operated by other users. The respective
73configuration entry names start with a ``.'', i.e. ``.pin''.
74
75You can configure any number of top-level domains, and point them to
76the respective zones of your friends! For this, simply obtain the
77respective public key (you will learn how below) and extend the
78configuration:
79
80@example
81$ gnunet-config -s gns -n .myfriend -V PUBLIC_KEY
82@end example
83
84@node Managing Egos
85@subsection Managing Egos
86
87In GNUnet, identity management is about managing egos. Egos can
88correspond to pseudonyms or real-world identities. If you value your
89privacy, you are encouraged to use separate egos for separate
90activities.
91
92Technically, an ego is first of all a public-private key pair, and
93thus egos also always correspond to a GNS zone. Egos are managed by
94the IDENTITY service. Note that this service has nothing to do with
95the peer identity. The IDENTITY service essentially stores the
96private keys under human-readable names, and keeps a mapping of which
97private key should be used for particular important system functions.
98The existing identities can be listed using the command
99@command{gnunet-identity -d}
100
101@example
102gnu - JTDVJC69NHU6GQS4B5721MV8VM7J6G2DVRGJV0ONIT6QH7OI6D50
103rules - GO0T87F9BPMF8NKD5A54L2AH1T0GRML539TPFSRMCEA98182QD30
104@end example
105
106
107@node The GNS Tab
108@subsection The GNS Tab
109@c %**end of header
110
111Maintaing your zones is through the NAMESTORE service and is discussed
112here. You can manage your zone using @command{gnunet-identity} and
113@command{gnunet-namestore}, or most conveniently using
114@command{gnunet-namestore-gtk}.
115
116We will use the GTK+ interface in this introduction. Please start
117@command{gnunet-gkt} and switch to the GNS tab, which is the tab in
118the middle with the letters "GNS" connected by a graph.
119
120Next to the ``Add'' button there is a field where you can enter the
121label (pseudonym in IDENTITY subsystem speak) of a zone you would like
122to create. Pushing the ``Add'' button will create the zone.
123Afterwards, you can change the label in the combo box below at any
124time. The label will be the top-level domain that the GNU Name System
125will resolve using your zone. For the label, you should pick
126a name by which you would like to
127be known by your friends (or colleagues). You should pick a label that
128is reasonably unique within your social group. Be aware that
129the label will be published together with every record in that zone.
130
131Once you have created a first zone, you should see a QR code for the
132zone on the right. Next to it is a "Copy" button to copy the public
133key string to the clipboard. You can also save the QR code image to
134disk.
135
136Furthermore, you now can see the bottom part of the dialog. The
137bottom of the window contains the existing entries in the selected zone.
138
139@node Creating a Record
140@subsection Creating a Record
141@c %**end of header
142
143We will begin by creating a simple record in your master zone.
144To do this, click on the text "<new name>" in the table. The field is
145editable, allowing you to enter a fresh label. Labels are restricted
146to 63 characters and must not contain dots. For now, simply enter
147"test", then press ENTER to confirm. This will create a new (empty)
148record group under the label "test". Now click on "<new record>" next
149to the new label "test". In the drop-down menu, select "A" and push
150ENTER to confirm. Afterwards, a new dialog will pop up, asking to enter
151details for the "A" record.
152
153"A" records are used in the @dfn{Domain Name System} (DNS) to specify
154IPv4 addresses. An IPv4 address is a number that is used to identify
155and address a computer on the Internet (version 4). Please enter
156"217.92.15.146" in the dialog below "Destination IPv4 Address" and
157select "Record is public". Do not change any of the other options.
158Note that as you enter a (well-formed) IPv4 address, the "Save"
159button in the bottom right corner becomes sensitive. In general, buttons
160in dialogs are often insensitive as long as the contents of the dialog
161are incorrect.
162
163Once finished, press the "Save" button. Back in the main dialog, select
164the tiny triangle left of the "test" label. By doing so, you get to see
165all of the records under "test". Note that you can right-click a record
166to edit it later.
167
168
169@node Resolving GNS records
170@subsection Resolving GNS records
171@c %**end of header
172
173Next, you should try resolving your own GNS records. The method we
174found to be the most uncomplicated is to do this by explicitly
175resolving using @code{gnunet-gns}. For this exercise, we will assume
176that you used the string ``gnu'' for the pseudonym (or label) of your
177GNS zone. If you used something else, replace ``.gnu'' with your real
178pseudonym in the examples below.
179
180In the shell, type:
181
182@example
183$ gnunet-gns -u test.gnu # what follows is the reply
184test.gnu:
185Got `A' record: 217.92.15.146
186@end example
187
188@noindent
189That shows that resolution works, once GNS is integrated with
190the application.
191
192@node Integration with Browsers
193@subsection Integration with Browsers
194@c %**end of header
195
196While we recommend integrating GNS using the NSS module in the
197GNU libc Name Service Switch, you can also integrate GNS
198directly with your browser via the @code{gnunet-gns-proxy}.
199This method can have the advantage that the proxy can validate
200TLS/X.509 records and thus strengthen web security; however, the proxy
201is still a bit brittle, so expect subtle failures. We have had reasonable
202success with Chromium, and various frustrations with Firefox in this area
203recently.
204
205The first step is to start the proxy. As the proxy is (usually)
206not started by default, this is done as a unprivileged user
207using @command{gnunet-arm -i gns-proxy}. Use @command{gnunet-arm -I}
208as a unprivileged user to check that the proxy was actually
209started. (The most common error for why the proxy may fail to start
210is that you did not run @command{gnunet-gns-proxy-setup-ca} during
211installation.) The proxy is a SOCKS5 proxy running (by default)
212on port 7777. Thus, you need to now configure your browser to use
213this proxy. With Chromium, you can do this by starting the browser
214as a unprivileged user using
215@command{chromium --proxy-server="socks5://localhost:7777"}
216For @command{Firefox} (or @command{Icecat}), select "Edit-Preferences"
217in the menu, and then select the "Advanced" tab in the dialog
218and then "Network":
219
220Here, select "Settings..." to open the proxy settings dialog.
221Select "Manual proxy configuration" and enter @code{localhost}
222with port 7777 under SOCKS Host. Furthermore, set the
223checkbox ``Proxy DNS when using SOCKS v5'' at the bottom of
224the dialog. Finally, push "OK".
225
226You must also go to about:config and change the
227@code{browser.fixup.alternate.enabled} option to @code{false},
228otherwise the browser will autoblunder an address like
229@code{@uref{http://www.gnu/, www.gnu}} to
230@code{@uref{http://www.gnu.com/, www.gnu.com}}. If you want
231to resolve @@ in your own TLDs, you must additionally
232set @code{browser.fixup.dns_first_use_for_single_words} to @code{true}.
233
234After configuring your browser, you might want to first confirm that it
235continues to work as before. (The proxy is still experimental and if you
236experience "odd" failures with some webpages, you might want to disable
237it again temporarily.) Next, test if things work by typing
238"@uref{http://test.gnu/}" into the URL bar of your browser.
239This currently fails with (my version of) Firefox as Firefox is
240super-smart and tries to resolve "@uref{http://www.test.gnu/}" instead of
241"@uref{test.gnu}". Chromium can be convinced to comply if you explicitly
242include the "http://" prefix --- otherwise a Google search might be
243attempted, which is not what you want. If successful, you should
244see a simple website.
245
246Note that while you can use GNS to access ordinary websites, this is
247more an experimental feature and not really our primary goal at this
248time. Still, it is a possible use-case and we welcome help with testing
249and development.
250
251@pindex gnunet-bcd
252@node Creating a Business Card
253@subsection Creating a Business Card
254@c FIXME: Which parts of texlive are needed? Some systems offer a modular
255@c texlive (smaller size).
256
257Before we can really use GNS, you should create a business card.
258Note that this requires having @command{LaTeX} installed on your system.
259If you are using a Debian GNU/Linux based operating system, the
260following command should install the required components.
261Keep in mind that this @b{requires 3GB} of downloaded data and possibly
262@b{even more} when unpacked. On a GNU Guix based system texlive 2017 has
263returns a DAG size of 5032.4 MiB.
264@b{We welcome any help in identifying the required components of the
265TexLive Distribution. This way we could just state the required components
266without pulling in the full distribution of TexLive.}
267
268@example
269apt-get install texlive-full
270@end example
271
272@noindent
273Start creating a business card by clicking the "Copy" button
274in @command{gnunet-gtk}'s GNS tab. Next, you should start
275the @command{gnunet-bcd} program (in the terminal, on the command-line).
276You do not need to pass any options, and please be not surprised if
277there is no output:
278
279@example
280$ gnunet-bcd # seems to hang...
281@end example
282
283@noindent
284Then, start a browser and point it to @uref{http://localhost:8888/}
285where @code{gnunet-bcd} is running a Web server!
286
287First, you might want to fill in the "GNS Public Key" field by
288right-clicking and selecting "Paste", filling in the public key
289from the copy you made in @command{gnunet-gtk}.
290Then, fill in all of the other fields, including your @b{GNS NICKname}.
291Adding a GPG fingerprint is optional.
292Once finished, click "Submit Query".
293If your @code{LaTeX} installation is incomplete, the result will be
294disappointing.
295Otherwise, you should get a PDF containing fancy 5x2 double-sided
296translated business cards with a QR code containing your public key
297and a GNUnet logo.
298We'll explain how to use those a bit later.
299You can now go back to the shell running @code{gnunet-bcd} and press
300@b{CTRL-C} to shut down the Web server.
301
302
303@node Be Social
304@subsection Be Social
305@c %**end of header
306
307Next, you should print out your business card and be social.
308Find a friend, help them install GNUnet and exchange business cards with
309them. Or, if you're a desperate loner, you might try the next step with
310your own card. Still, it'll be hard to have a conversation with
311yourself later, so it would be better if you could find a friend.
312You might also want a camera attached to your computer, so
313you might need a trip to the store together.
314
315Before we get started, we need to tell @code{gnunet-qr} which zone
316it should import new records into. For this, run:
317
318@pindex gnunet-identity
319@example
320$ gnunet-identity -s namestore -e NAME
321@end example
322where NAME is the name of the zone you want to import records
323into. In our running example, this would be ``gnu''.
324
325@pindex gnunet-qr
326Henceforth, for every business card you collect, simply run:
327@example
328$ gnunet-qr
329@end example
330
331@noindent
332to open a window showing whatever your camera points at.
333Hold up your friend's business card and tilt it until
334the QR code is recognized. At that point, the window should
335automatically close. At that point, your friend's NICKname and their
336public key should have been automatically imported into your zone.
337
338Assuming both of your peers are properly integrated in the
339GNUnet network at this time, you should thus be able to
340resolve your friends names. Suppose your friend's nickname
341is "Bob". Then, type
342
343@pindex gnunet-gns
344@example
345$ gnunet-gns -u test.bob.gnu
346@end example
347
348@noindent
349to check if your friend was as good at following instructions
350as you were.
351
352
353@node Backup of Identities and Egos
354@subsection Backup of Identities and Egos
355
356
357One should always backup their files, especially in these SSD days (our
358team has suffered 3 SSD crashes over a span of 2 weeks). Backing up peer
359identity and zones is achieved by copying the following files:
360
361The peer identity file can be found
362in @file{~/.local/share/gnunet/private_key.ecc}
363
364The private keys of your egos are stored in the
365directory @file{~/.local/share/gnunet/identity/egos/}.
366They are stored in files whose filenames correspond to the zones'
367ego names. These are probably the most important files you want
368to backup from a GNUnet installation.
369
370Note: All these files contain cryptographic keys and they are
371stored without any encryption. So it is advisable to backup
372encrypted copies of them.
373
374
375@node Revocation
376@subsection Revocation
377
378Now, in the situation of an attacker gaining access to the private key of
379one of your egos, the attacker can create records in the respective
380GNS zone
381and publish them as if you published them. Anyone resolving your
382domain will get these new records and when they verify they seem
383authentic because the attacker has signed them with your key.
384
385To address this potential security issue, you can pre-compute
386a revocation certificate corresponding to your ego. This certificate,
387when published on the P2P network, flags your private key as invalid,
388and all further resolutions or other checks involving the key will fail.
389
390@pindex gnunet-revocation
391A revocation certificate is thus a useful tool when things go out of
392control, but at the same time it should be stored securely.
393Generation of the revocation certificate for a zone can be done through
394@command{gnunet-revocation}. For example, the following command (as
395unprivileged user) generates a revocation file
396@file{revocation.dat} for the zone @code{zone1}:
397@command{gnunet-revocation -f revocation.dat -R zone1}
398
399The above command only pre-computes a revocation certificate. It does
400not revoke the given zone. Pre-computing a revocation certificate
401involves computing a proof-of-work and hence may take up to 4 to 5 days
402on a modern processor. Note that you can abort and resume the
403calculation at any time. Also, even if you did not finish the
404calculation, the resulting file will contain the signature, which is
405sufficient to complete the revocation process even without access to
406the private key. So instead of waiting for a few days, you can just
407abort with CTRL-C, backup the revocation certificate and run the
408calculation only if your key actually was compromised. This has the
409disadvantage of revocation taking longer after the incident, but
410the advantage of saving a significant amount of energy. So unless
411you believe that a key compromise will need a rapid response, we
412urge you to wait with generating the revocation certificate.
413Also, the calculation is deliberately expensive, to deter people from
414doing this just for fun (as the actual revocation operation is expensive
415for the network, not for the peer performing the revocation).
416
417
418@c FIXME: The Manual should give away the command using an example that is
419@c very likely to never exist.
420To avoid TL;DR ones from accidentally revocating their zones, we are not
421giving away the command, but it is uncomplicated: the actual revocation is
422performed by using the @command{-p} option of @command{gnunet-revocation}.
423
424
425@node What's Next?
426@subsection What's Next?
427@c %**end of header
428
429This may seem not like much of an application yet, but you have
430just been one of the first to perform a decentralized secure name
431lookup (where nobody could have altered the value supplied by your
432friend) in a privacy-preserving manner (your query on the network
433and the corresponding response were always encrypted). So what
434can you really do with this? Well, to start with, you can publish your
435GnuPG fingerprint in GNS as a "CERT" record and replace the public
436web-of-trust with its complicated trust model with explicit names
437and privacy-preserving resolution. Also, you should read the next
438chapter of the tutorial and learn how to use GNS to have a
439private conversation with your friend. Finally, help us
440with the next GNUnet release for even more applications
441using this new public key infrastructure.
442
443@pindex gnunet-conservation-gtk
444@node First steps - Using GNUnet Conversation
445@section First steps - Using GNUnet Conversation
446@c %**end of header
447
448First, you should launch the graphical user interface. You can do
449this from the command-line by typing
450
451@example
452$ gnunet-conversation-gtk
453@end example
454
455@menu
456* Testing your Audio Equipment::
457* GNS Zones::
458@end menu
459
460@node Testing your Audio Equipment
461@subsection Testing your Audio Equipment
462@c %**end of header
463
464First, you should use @code{gnunet-conversation-test} to check that your
465microphone and speaker are working correctly. You will be prompted to
466speak for 5 seconds, and then those 5 seconds will be replayed to you.
467The network is not involved in this test. If it fails, you should run
468your pulse audio configuration tool to check that microphone and
469speaker are not muted and, if you have multiple input/output devices,
470that the correct device is being associated with GNUnet's audio tools.
471
472@node GNS Zones
473@subsection GNS Zones
474@c %**end of header
475
476@code{gnunet-conversation} uses GNS for addressing. This means that
477you need to have a GNS zone created before using it. Information
478about how to create GNS zones can be found here.
479
480
481@menu
482* Picking an Identity::
483* Calling somebody::
484@end menu
485
486@node Picking an Identity
487@subsubsection Picking an Identity
488@c %**end of header
489
490To make a call with @code{gnunet-conversation}, you first
491need to choose an identity. This identity is both the caller ID
492that will show up when you call somebody else, as well as the
493GNS zone that will be used to resolve names of users that you
494are calling. Run
495
496@pindex gnunet-conversation
497@example
498gnunet-conversation -e zone-name
499@end example
500
501@noindent
502to start the command-line tool. You will see a message saying
503that your phone is now "active on line 0". You can connect
504multiple phones on different lines at the same peer. For the
505first phone, the line zero is of course a fine choice.
506
507Next, you should type in @command{/help} for a list of
508available commands. We will explain the important ones
509during this tutorial. First, you will need to type in
510@command{/address} to determine the address of your
511phone. The result should look something like this:
512
513@example
514/address
5150-PD67SGHF3E0447TU9HADIVU9OM7V4QHTOG0EBU69TFRI2LG63DR0
516@end example
517
518@noindent
519Here, the "0" is your phone line, and what follows
520after the hyphen is your peer's identity. This information will
521need to be placed in a PHONE record of
522your GNS master-zone so that other users can call you.
523
524Start @code{gnunet-namestore-gtk} now (possibly from another
525shell) and create an entry home-phone in your master zone.
526For the record type, select PHONE. You should then see the
527PHONE dialog:
528
529@c image here
530
531Note: Do not choose the expiry time to be 'Never'. If you
532do that, you assert that this record will never change and
533can be cached indefinitely by the DHT and the peers which
534resolve this record. A reasonable period is 1 year.
535
536Enter your peer identity under Peer and leave the line
537at zero. Select the first option to make the record public.
538If you entered your peer identity incorrectly,
539the "Save" button will not work; you might want to use
540copy-and-paste instead of typing in the peer identity
541manually. Save the record.
542
543@node Calling somebody
544@subsubsection Calling somebody
545@c %**end of header
546
547Now you can call a buddy. Obviously, your buddy will have to have GNUnet
548installed and must have performed the same steps. Also, you must have
549your buddy in your GNS master zone, for example by having imported
550your buddy's public key using @code{gnunet-qr}. Suppose your buddy
551is in your zone as @code{buddy.mytld} and they also created their
552phone using a label "home-phone". Then you can initiate a call using:
553
554@example
555/call home-phone.buddy.mytld
556@end example
557
558It may take some time for GNUnet to resolve the name and to establish
559a link. If your buddy has your public key in their master zone, they
560should see an incoming call with your name. If your public key is not
561in their master zone, they will just see the public key as the caller ID.
562
563Your buddy then can answer the call using the "/accept" command. After
564that, (encrypted) voice data should be relayed between your two peers.
565Either of you can end the call using @command{/cancel}. You can exit
566@code{gnunet-conversation} using @command{/quit}.
567
568
569@node First steps - Using the GNUnet VPN
570@section First steps - Using the GNUnet VPN
571@c %**end of header
572
573
574@menu
575* VPN Preliminaries::
576* GNUnet-Exit configuration::
577* GNS configuration::
578* Accessing the service::
579* Using a Browser::
580@end menu
581
582@node VPN Preliminaries
583@subsection VPN Preliminaries
584@c %**end of header
585
586To test the GNUnet VPN, we should first run a web server.
587The easiest way to do this is to just start @code{gnunet-bcd},
588which will run a webserver on port @code{8888} by default.
589Naturally, you can run some other HTTP server for our little tutorial.
590
591If you have not done this, you should also configure your
592Name System Service switch to use GNS. In your @code{/etc/nsswitch.conf}
593you should fine a line like this:
594
595@example
596hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4
597@end example
598
599@noindent
600The exact details may differ a bit, which is fine. Add the text
601@code{gns [NOTFOUND=return]} after @code{files}:
602
603@example
604hosts: files gns [NOTFOUND=return] mdns4_minimal [NOTFOUND=return] dns mdns4
605@end example
606
607@c TODO: outdated section, we no longer install this as part of the
608@c TODO: standard installation procedure and should point out the manual
609@c TODO: steps required to make it useful.
610@noindent
611You might want to make sure that @code{/lib/libnss_gns.so.2} exists on
612your system, it should have been created during the installation.
613If not, re-run
614
615@example
616$ configure --with-nssdir=/lib
617$ cd src/gns/nss; sudo make install
618@end example
619
620@noindent
621to install the NSS plugins in the proper location.
622
623@node GNUnet-Exit configuration
624@subsection GNUnet-Exit configuration
625@c %**end of header
626
627Stop your peer (as user @code{gnunet}, run @command{gnunet-arm -e}) and
628run @command{gnunet-setup}. In @command{gnunet-setup}, make sure to
629activate the @strong{EXIT} and @strong{GNS} services in the General tab.
630Then select the Exit tab. Most of the defaults should be fine (but
631you should check against the screenshot that they have not been modified).
632In the bottom area, enter @code{bcd} under Identifier and change the
633Destination to @code{169.254.86.1:8888} (if your server runs on a port
634other than 8888, change the 8888 port accordingly).
635
636Now exit @command{gnunet-setup} and restart your peer
637(@command{gnunet-arm -s}).
638
639@node GNS configuration
640@subsection GNS configuration
641@c %**end of header
642
643Now, using your normal user (not the @code{gnunet} system user), run
644@command{gnunet-gtk}. Select the GNS icon and add a new label www in your
645master zone. For the record type, select @code{VPN}. You should then
646see the VPN dialog:
647
648@c insert image
649
650Under peer, you need to supply the peer identity of your own peer. You can
651obtain the respective string by running @command{gnunet-peerinfo -sq}
652as the @code{gnunet} user. For the Identifier, you need to supply the same
653identifier that we used in the Exit setup earlier, so here supply "bcd".
654If you want others to be able to use the service, you should probably make
655the record public. For non-public services, you should use a passphrase
656instead of the string "bcd". Save the record and
657exit @command{gnunet-gtk}.
658
659@node Accessing the service
660@subsection Accessing the service
661@c %**end of header
662
663You should now be able to access your webserver. Type in:
664
665@example
666$ wget http://www.gnu/
667@end example
668
669@noindent
670The request will resolve to the VPN record, telling the GNS resolver
671to route it via the GNUnet VPN. The GNS resolver will ask the
672GNUnet VPN for an IPv4 address to return to the application. The
673VPN service will use the VPN information supplied by GNS to create
674a tunnel (via GNUnet's MESH service) to the EXIT peer.
675At the EXIT, the name "bcd" and destination port (80) will be mapped
676to the specified destination IP and port. While all this is currently
677happening on just the local machine, it should also work with other
678peers --- naturally, they will need a way to access your GNS zone
679first, for example by learning your public key from a QR code on
680your business card.
681
682@node Using a Browser
683@subsection Using a Browser
684@c %**end of header
685
686Sadly, modern browsers tend to bypass the Name Services Switch and
687attempt DNS resolution directly. You can either run
688a @code{gnunet-dns2gns} DNS proxy, or point the browsers to an
689HTTP proxy. When we tried it, Iceweasel did not like to connect to
690the socks proxy for @code{.gnu} TLDs, even if we disabled its
691autoblunder of changing @code{.gnu} to ".gnu.com". Still,
692using the HTTP proxy with Chrome does work.
693
694@node File-sharing
695@section File-sharing
696@c %**end of header
697
698This chapter documents the GNUnet file-sharing application. The original
699file-sharing implementation for GNUnet was designed to provide
700@strong{anonymous} file-sharing. However, over time, we have also added
701support for non-anonymous file-sharing (which can provide better
702performance). Anonymous and non-anonymous file-sharing are quite
703integrated in GNUnet and, except for routing, share most of the concepts
704and implementation. There are three primary file-sharing operations:
705publishing, searching and downloading. For each of these operations,
706the user specifies an @strong{anonymity level}. If both the publisher and
707the searcher/downloader specify "no anonymity", non-anonymous
708file-sharing is used. If either user specifies some desired degree
709of anonymity, anonymous file-sharing will be used.
710
711After a short introduction, we will first look at the various concepts
712in GNUnet's file-sharing implementation. Then, we will discuss
713specifics as to how they impact users that publish, search or download
714files.
715
716
717@menu
718* fs-Searching::
719* fs-Downloading::
720* fs-Publishing::
721* fs-Concepts::
722* Namespace Management::
723* File-Sharing URIs::
724* GTK User Interface::
725@end menu
726
727@node fs-Searching
728@subsection Searching
729@c %**end of header
730
731The command @command{gnunet-search} can be used to search
732for content on GNUnet. The format is:
733
734@example
735$ gnunet-search [-t TIMEOUT] KEYWORD
736@end example
737
738@noindent
739The @command{-t} option specifies that the query should timeout after
740approximately TIMEOUT seconds. A value of zero (``0'') is interpreted
741as @emph{no timeout}, which is the default. In this case,
742@command{gnunet-search} will never terminate (unless you press
743@command{CTRL-C}).
744
745If multiple words are passed as keywords, they will all be
746considered optional. Prefix keywords with a "+" to make them mandatory.
747
748Note that searching using
749
750@example
751$ gnunet-search Das Kapital
752@end example
753
754@noindent
755is not the same as searching for
756
757@example
758$ gnunet-search "Das Kapital"
759@end example
760
761@noindent
762as the first will match files shared under the keywords
763"Das" or "Kapital" whereas the second will match files
764shared under the keyword "Das Kapital".
765
766Search results are printed by @command{gnunet-search} like this:
767
768@c it will be better the avoid the ellipsis altogether because I don't
769@c understand the explanation below that
770@c ng0: who is ``I'' and what was the complete sentence?
771@example
772#15:
773gnunet-download -o "COPYING" gnunet://fs/chk/PGK8M...3EK130.75446
774
775@end example
776
777@noindent
778The whole line is the command you would have to enter to download
779the file. The first argument passed to @code{-o} is the suggested
780filename (you may change it to whatever you like).
781It is followed by the key for decrypting the file, the query for
782searching the file, a checksum (in hexadecimal) finally the size of
783the file in bytes.
784
785@node fs-Downloading
786@subsection Downloading
787@c %**end of header
788
789In order to download a file, you need the whole line returned by
790@command{gnunet-search}.
791You can then use the tool @command{gnunet-download} to obtain the file:
792
793@example
794$ gnunet-download -o <FILENAME> <GNUNET-URL>
795@end example
796
797@noindent
798FILENAME specifies the name of the file where GNUnet is supposed
799to write the result. Existing files are overwritten. If the
800existing file contains blocks that are identical to the
801desired download, those blocks will not be downloaded again
802(automatic resume).
803
804If you want to download the GPL from the previous example,
805you do the following:
806
807@example
808$ gnunet-download -o "COPYING" gnunet://fs/chk/PGK8M...3EK130.75446
809@end example
810
811@noindent
812If you ever have to abort a download, you can continue it at any time by
813re-issuing @command{gnunet-download} with the same filename.
814In that case, GNUnet will @strong{not} download blocks again that are
815already present.
816
817GNUnet's file-encoding mechanism will ensure file integrity, even if the
818existing file was not downloaded from GNUnet in the first place.
819
820You may want to use the @command{-V} switch to turn on verbose
821reporting. In this case, @command{gnunet-download} will print the
822current number of bytes downloaded whenever new data was received.
823
824@node fs-Publishing
825@subsection Publishing
826@c %**end of header
827
828The command @command{gnunet-publish} can be used to add content
829to the network. The basic format of the command is
830
831@example
832$ gnunet-publish [-n] [-k KEYWORDS]* [-m TYPE:VALUE] FILENAME
833@end example
834
835For example
836@example
837$ gnunet-publish -m "description:GNU License" -k gpl -k test -m "mimetype:text/plain" COPYING
838@end example
839
840@menu
841* Important command-line options::
842* Indexing vs. Inserting::
843@end menu
844
845@node Important command-line options
846@subsubsection Important command-line options
847@c %**end of header
848
849The option @code{-k} is used to specify keywords for the file that
850should be inserted. You can supply any number of keywords,
851and each of the keywords will be sufficient to locate and
852retrieve the file. Please note that you must use the @code{-k} option
853more than once -- one for each expression you use as a keyword for
854the filename.
855
856The -m option is used to specify meta-data, such as descriptions.
857You can use -m multiple times. The TYPE passed must be from the
858list of meta-data types known to libextractor. You can obtain this
859list by running @command{extract -L}. Use quotes around the entire
860meta-data argument if the value contains spaces. The meta-data
861is displayed to other users when they select which files to
862download. The meta-data and the keywords are optional and
863may be inferred using @code{GNU libextractor}.
864
865@command{gnunet-publish} has a few additional options to handle
866namespaces and directories. Refer to the man-page for details:
867
868@example
869man gnunet-publish
870@end example
871
872@node Indexing vs. Inserting
873@subsubsection Indexing vs Inserting
874@c %**end of header
875
876By default, GNUnet indexes a file instead of making a full copy.
877This is much more efficient, but requires the file to stay unaltered
878at the location where it was when it was indexed. If you intend to move,
879delete or alter a file, consider using the option @code{-n} which will
880force GNUnet to make a copy of the file in the database.
881
882Since it is much less efficient, this is strongly discouraged for large
883files. When GNUnet indexes a file (default), GNUnet does @strong{not}
884create an additional encrypted copy of the file but just computes a
885summary (or index) of the file. That summary is approximately two percent
886of the size of the original file and is stored in GNUnet's database.
887Whenever a request for a part of an indexed file reaches GNUnet,
888this part is encrypted on-demand and send out. This way, there is no
889need for an additional encrypted copy of the file to stay anywhere
890on the drive. This is different from other systems, such as Freenet,
891where each file that is put online must be in Freenet's database in
892encrypted format, doubling the space requirements if the user wants
893to preserve a directly accessible copy in plaintext.
894
895Thus indexing should be used for all files where the user will keep
896using this file (at the location given to gnunet-publish) and does
897not want to retrieve it back from GNUnet each time. If you want to
898remove a file that you have indexed from the local peer, use the tool
899@command{gnunet-unindex} to un-index the file.
900
901The option @code{-n} may be used if the user fears that the file might
902be found on their drive (assuming the computer comes under the control
903of an adversary). When used with the @code{-n} flag, the user has a
904much better chance of denying knowledge of the existence of the file,
905even if it is still (encrypted) on the drive and the adversary is
906able to crack the encryption (e.g. by guessing the keyword.
907
908@node fs-Concepts
909@subsection Concepts
910@c %**end of header
911
912For better results with filesharing it is useful to understand the
913following concepts.
914In addition to anonymous routing GNUnet attempts to give users a better
915experience in searching for content. GNUnet uses cryptography to safely
916break content into smaller pieces that can be obtained from different
917sources without allowing participants to corrupt files. GNUnet makes it
918difficult for an adversary to send back bogus search results. GNUnet
919enables content providers to group related content and to establish a
920reputation. Furthermore, GNUnet allows updates to certain content to be
921made available. This section is supposed to introduce users to the
922concepts that are used to achieve these goals.
923
924
925@menu
926* Files::
927* Keywords::
928* Directories::
929* Pseudonyms::
930* Namespaces::
931* Advertisements::
932* Anonymity level::
933* Content Priority::
934* Replication::
935@end menu
936
937@node Files
938@subsubsection Files
939@c %**end of header
940
941A file in GNUnet is just a sequence of bytes. Any file-format is allowed
942and the maximum file size is theoretically @math{2^64 - 1} bytes, except
943that it would take an impractical amount of time to share such a file.
944GNUnet itself never interprets the contents of shared files, except when
945using GNU libextractor to obtain keywords.
946
947@node Keywords
948@subsubsection Keywords
949@c %**end of header
950
951Keywords are the most simple mechanism to find files on GNUnet.
952Keywords are @strong{case-sensitive} and the search string
953must always match @strong{exactly} the keyword used by the
954person providing the file. Keywords are never transmitted in
955plaintext. The only way for an adversary to determine the keyword
956that you used to search is to guess it (which then allows the
957adversary to produce the same search request). Since providing
958keywords by hand for each shared file is tedious, GNUnet uses
959GNU libextractor to help automate this process. Starting a
960keyword search on a slow machine can take a little while since
961the keyword search involves computing a fresh RSA key to formulate the
962request.
963
964@node Directories
965@subsubsection Directories
966@c %**end of header
967
968A directory in GNUnet is a list of file identifiers with meta data.
969The file identifiers provide sufficient information about the files
970to allow downloading the contents. Once a directory has been created,
971it cannot be changed since it is treated just like an ordinary file
972by the network. Small files (of a few kilobytes) can be inlined in
973the directory, so that a separate download becomes unnecessary.
974
975Directories are shared just like ordinary files. If you download a
976directory with @command{gnunet-download}, you can use
977@command{gnunet-directory} to list its contents. The canonical
978extension for GNUnet directories when stored as files in your
979local file-system is ".gnd". The contents of a directory are URIs and
980meta data.
981The URIs contain all the information required by
982@command{gnunet-download} to retrieve the file. The meta data
983typically includes the mime-type, description, a filename and
984other meta information, and possibly even the full original file
985(if it was small).
986
987@node Pseudonyms
988@subsubsection Pseudonyms
989@c %**end of header
990
991@b{Please note that the text in this subsection is outdated and needs}
992@b{to be rewritten for version 0.10!}
993@b{This especially concerns the terminology of Pseudonym/Ego/Identity.}
994
995Pseudonyms in GNUnet are essentially public-private (RSA) key pairs
996that allow a GNUnet user to maintain an identity (which may or may not
997be detached from their real-life identity). GNUnet's pseudonyms are not
998file-sharing specific --- and they will likely be used by many GNUnet
999applications where a user identity is required.
1000
1001Note that a pseudonym is NOT bound to a GNUnet peer. There can be multiple
1002pseudonyms for a single user, and users could (theoretically) share the
1003private pseudonym keys (currently only out-of-band by knowing which files
1004to copy around).
1005
1006@node Namespaces
1007@subsubsection Namespaces
1008@c %**end of header
1009
1010@b{Please note that the text in this subsection is outdated and needs}
1011@b{to be rewritten for version 0.10!}
1012@b{This especially concerns the terminology of Pseudonym/Ego/Identity.}
1013
1014A namespace is a set of files that were signed by the same pseudonym.
1015Files (or directories) that have been signed and placed into a namespace
1016can be updated. Updates are identified as authentic if the same secret
1017key was used to sign the update. Namespaces are also useful to establish
1018a reputation, since all of the content in the namespace comes from the
1019same entity (which does not have to be the same person).
1020
1021@node Advertisements
1022@subsubsection Advertisements
1023@c %**end of header
1024
1025@b{Please note that the text in this subsection is outdated and needs}
1026@b{to be rewritten for version 0.10!}
1027@b{This especially concerns the terminology of Pseudonym/Ego/Identity.}
1028
1029Advertisements are used to notify other users about the existence of a
1030namespace. Advertisements are propagated using the normal keyword search.
1031When an advertisement is received (in response to a search), the namespace
1032is added to the list of namespaces available in the namespace-search
1033dialogs of gnunet-fs-gtk and printed by @code{gnunet-identity}. Whenever a
1034namespace is created, an appropriate advertisement can be generated.
1035The default keyword for the advertising of namespaces is "namespace".
1036
1037Note that GNUnet differentiates between your pseudonyms (the identities
1038that you control) and namespaces. If you create a pseudonym, you will
1039not automatically see the respective namespace. You first have to create
1040an advertisement for the namespace and find it using keyword
1041search --- even for your own namespaces. The @command{gnunet-identity}
1042tool is currently responsible for both managing pseudonyms and namespaces.
1043This will likely change in the future to reduce the potential for
1044confusion.
1045
1046@node Anonymity level
1047@subsubsection Anonymity level
1048@c %**end of header
1049
1050The anonymity level determines how hard it should be for an adversary to
1051determine the identity of the publisher or the searcher/downloader. An
1052anonymity level of zero means that anonymity is not required. The default
1053anonymity level of "1" means that anonymous routing is desired, but no
1054particular amount of cover traffic is necessary. A powerful adversary
1055might thus still be able to deduce the origin of the traffic using
1056traffic analysis. Specifying higher anonymity levels increases the
1057amount of cover traffic required. While this offers better privacy,
1058it can also significantly hurt performance.
1059
1060@node Content Priority
1061@subsubsection Content Priority
1062@c %**end of header
1063
1064Depending on the peer's configuration, GNUnet peers migrate content
1065between peers. Content in this sense are individual blocks of a file,
1066not necessarily entire files. When peers run out of space (due to
1067local publishing operations or due to migration of content from other
1068peers), blocks sometimes need to be discarded. GNUnet first always
1069discards expired blocks (typically, blocks are published with an
1070expiration of about two years in the future; this is another option).
1071If there is still not enough space, GNUnet discards the blocks with the
1072lowest priority. The priority of a block is decided by its popularity
1073(in terms of requests from peers we trust) and, in case of blocks
1074published locally, the base-priority that was specified by the user
1075when the block was published initially.
1076
1077@node Replication
1078@subsubsection Replication
1079@c %**end of header
1080
1081When peers migrate content to other systems, the replication level
1082of a block is used to decide which blocks need to be migrated most
1083urgently. GNUnet will always push the block with the highest
1084replication level into the network, and then decrement the replication
1085level by one. If all blocks reach replication level zero, the
1086selection is simply random.
1087
1088
1089@node Namespace Management
1090@subsection Namespace Management
1091@c %**end of header
1092
1093@b{Please note that the text in this subsection is outdated and needs}
1094@b{to be rewritten for version 0.10!}
1095
1096The @code{gnunet-identity} tool can be used to create pseudonyms and
1097to advertise namespaces. By default, @code{gnunet-identity -D} simply
1098lists all locally available pseudonyms.
1099
1100
1101@menu
1102* Creating Pseudonyms::
1103* Deleting Pseudonyms::
1104* Advertising namespaces::
1105* Namespace names::
1106* Namespace root::
1107@end menu
1108
1109@node Creating Pseudonyms
1110@subsubsection Creating Pseudonyms
1111@c %**end of header
1112
1113@b{Please note that the text in this subsection is outdated and needs}
1114@b{to be rewritten for version 0.10!}
1115@b{This especially concerns the terminology of Pseudonym/Ego/Identity.}
1116
1117With the @command{-C NICK} option it can also be used to
1118create a new pseudonym. A pseudonym is the virtual identity
1119of the entity in control of a namespace. Anyone can create
1120any number of pseudonyms. Note that creating a pseudonym can
1121take a few minutes depending on the performance of the machine
1122used.
1123
1124@node Deleting Pseudonyms
1125@subsubsection Deleting Pseudonyms
1126@c %**end of header
1127
1128@b{Please note that the text in this subsection is outdated and needs}
1129@b{to be rewritten for version 0.10!}
1130@b{This especially concerns the terminology of Pseudonym/Ego/Identity.}
1131
1132With the @command{-D NICK} option pseudonyms can be deleted.
1133Once the pseudonym has been deleted it is impossible to add
1134content to the corresponding namespace. Deleting the
1135pseudonym does not make the namespace or any content in it
1136unavailable.
1137
1138@node Advertising namespaces
1139@subsubsection Advertising namespaces
1140@c %**end of header
1141
1142@b{Please note that the text in this subsection is outdated and needs}
1143@b{to be rewritten for version 0.10!}
1144@b{This especially concerns the terminology of Pseudonym/Ego/Identity.}
1145
1146Each namespace is associated with meta-data that describes
1147the namespace. This meta-data is provided by the user at
1148the time that the namespace is advertised. Advertisements
1149are published under keywords so that they can be found using
1150normal keyword-searches. This way, users can learn about new
1151namespaces without relying on out-of-band communication or directories.
1152A suggested keyword to use for all namespaces is simply "namespace".
1153When a keyword-search finds a namespace advertisement,
1154it is automatically stored in a local list of known namespaces.
1155Users can then associate a rank with the namespace to remember
1156the quality of the content found in it.
1157
1158@node Namespace names
1159@subsubsection Namespace names
1160@c %**end of header
1161
1162@b{Please note that the text in this subsection is outdated and needs}
1163@b{to be rewritten for version 0.10!}
1164@b{This especially concerns the terminology of Pseudonym/Ego/Identity.}
1165
1166While the namespace is uniquely identified by its ID, another way
1167to refer to the namespace is to use the NICKNAME.
1168The NICKNAME can be freely chosen by the creator of the namespace and
1169hence conflicts are possible. If a GNUnet client learns about more
1170than one namespace using the same NICKNAME, the ID is appended
1171to the NICKNAME to get a unique identifier.
1172
1173@node Namespace root
1174@subsubsection Namespace root
1175@c %**end of header
1176
1177@b{Please note that the text in this subsection is outdated and needs}
1178@b{to be rewritten for version 0.10!}
1179@b{This especially concerns the terminology of Pseudonym/Ego/Identity.}
1180
1181An item of particular interest in the namespace advertisement is
1182the ROOT. The ROOT is the identifier of a designated entry in the
1183namespace. The idea is that the ROOT can be used to advertise an
1184entry point to the content of the namespace.
1185
1186@node File-Sharing URIs
1187@subsection File-Sharing URIs
1188@c %**end of header
1189
1190GNUnet (currently) uses four different types of URIs for
1191file-sharing. They all begin with "gnunet://fs/".
1192This section describes the four different URI types in detail.
1193
1194For FS URIs empty KEYWORDs are not allowed. Quotes are allowed to
1195denote whitespace between words. Keywords must contain a balanced
1196number of double quotes. Doubles quotes can not be used in the actual
1197keywords. This means that the the string '""foo bar""' will be turned
1198into two OR-ed keywords 'foo' and 'bar', not into '"foo bar"'.
1199
1200@menu
1201* Encoding of hash values in URIs::
1202* Content Hash Key (chk)::
1203* Location identifiers (loc)::
1204* Keyword queries (ksk)::
1205* Namespace content (sks)::
1206@end menu
1207
1208@node Encoding of hash values in URIs
1209@subsubsection Encoding of hash values in URIs
1210@c %**end of header
1211
1212Most URIs include some hash values. Hashes are encoded using
1213base32hex (RFC 2938).
1214
1215@cindex chk-uri
1216@node Content Hash Key (chk)
1217@subsubsection Content Hash Key (chk)
1218@c %**end of header
1219
1220A chk-URI is used to (uniquely) identify a file or directory
1221and to allow peers to download the file. Files are stored in
1222GNUnet as a tree of encrypted blocks.
1223The chk-URI thus contains the information to download and decrypt
1224those blocks. A chk-URI has the format
1225"gnunet://fs/chk/KEYHASH.QUERYHASH.SIZE". Here, "SIZE"
1226is the size of the file (which allows a peer to determine the
1227shape of the tree), KEYHASH is the key used to decrypt the file
1228(also the hash of the plaintext of the top block) and QUERYHASH
1229is the query used to request the top-level block (also the hash
1230of the encrypted block).
1231
1232@cindex loc-uri
1233@node Location identifiers (loc)
1234@subsubsection Location identifiers (loc)
1235@c %**end of header
1236
1237For non-anonymous file-sharing, loc-URIs are used to specify which
1238peer is offering the data (in addition to specifying all of the
1239data from a chk-URI). Location identifiers include a digital
1240signature of the peer to affirm that the peer is truly the
1241origin of the data. The format is
1242"gnunet://fs/loc/KEYHASH.QUERYHASH.SIZE.PEER.SIG.EXPTIME".
1243Here, "PEER" is the public key of the peer (in GNUnet format in
1244base32hex), SIG is the RSA signature (in GNUnet format in
1245base32hex) and EXPTIME specifies when the signature expires
1246(in milliseconds after 1970).
1247
1248@cindex ksk-uri
1249@node Keyword queries (ksk)
1250@subsubsection Keyword queries (ksk)
1251@c %**end of header
1252
1253A keyword-URI is used to specify that the desired operation
1254is the search using a particular keyword. The format is simply
1255"gnunet://fs/ksk/KEYWORD". Non-ASCII characters can be specified
1256using the typical URI-encoding (using hex values) from HTTP.
1257"+" can be used to specify multiple keywords (which are then
1258logically "OR"-ed in the search, results matching both keywords
1259are given a higher rank): "gnunet://fs/ksk/KEYWORD1+KEYWORD2".
1260ksk-URIs must not begin or end with the plus ('+') character.
1261Furthermore they must not contain '++'.
1262
1263@cindex sks-uri
1264@node Namespace content (sks)
1265@subsubsection Namespace content (sks)
1266@c %**end of header
1267
1268@b{Please note that the text in this subsection is outdated and needs}
1269@b{to be rewritten for version 0.10!}
1270@b{This especially concerns the terminology of Pseudonym/Ego/Identity.}
1271
1272Namespaces are sets of files that have been approved by some (usually
1273pseudonymous) user --- typically by that user publishing all of the
1274files together. A file can be in many namespaces. A file is in a
1275namespace if the owner of the ego (aka the namespace's private key)
1276signs the CHK of the file cryptographically. An SKS-URI is used to
1277search a namespace. The result is a block containing meta data,
1278the CHK and the namespace owner's signature. The format of a sks-URI
1279is "gnunet://fs/sks/NAMESPACE/IDENTIFIER". Here, "NAMESPACE"
1280is the public key for the namespace. "IDENTIFIER" is a freely
1281chosen keyword (or password!). A commonly used identifier is
1282"root" which by convention refers to some kind of index or other
1283entry point into the namespace.
1284
1285@node GTK User Interface
1286@subsection GTK User Interface
1287This chapter describes first steps for file-sharing with GNUnet.
1288To start, you should launch @command{gnunet-fs-gtk}.
1289
1290As we want to be sure that the network contains the data that we are
1291looking for for testing, we need to begin by publishing a file.
1292
1293@menu
1294* gtk-Publishing::
1295* gtk-Searching::
1296* gtk-Downloading::
1297@end menu
1298
1299@node gtk-Publishing
1300@subsubsection Publishing
1301@c %**end of header
1302
1303To publish a file, select "File Sharing" in the menu bar just below the
1304"Statistics" icon, and then select "Publish" from the menu.
1305
1306Afterwards, the following publishing dialog will appear:
1307
1308@c Add image here
1309
1310In this dialog, select the "Add File" button. This will open a
1311file selection dialog:
1312
1313@c Add image here
1314
1315Now, you should select a file from your computer to be published on
1316GNUnet. To see more of GNUnet's features later, you should pick a
1317PNG or JPEG file this time. You can leave all of the other options
1318in the dialog unchanged. Confirm your selection by pressing the "OK"
1319button in the bottom right corner. Now, you will briefly see a
1320"Messages..." dialog pop up, but most likely it will be too short for
1321you to really read anything. That dialog is showing you progress
1322information as GNUnet takes a first look at the selected file(s).
1323For a normal image, this is virtually instant, but if you later
1324import a larger directory you might be interested in the progress dialog
1325and potential errors that might be encountered during processing.
1326After the progress dialog automatically disappears, your file
1327should now appear in the publishing dialog:
1328
1329@c Add image here
1330
1331Now, select the file (by clicking on the file name) and then click
1332the "Edit" button. This will open the editing dialog:
1333
1334@c Add image here
1335
1336In this dialog, you can see many details about your file. In the
1337top left area, you can see meta data extracted about the file,
1338such as the original filename, the mimetype and the size of the image.
1339In the top right, you should see a preview for the image
1340(if GNU libextractor was installed correctly with the
1341respective plugins). Note that if you do not see a preview, this
1342is not a disaster, but you might still want to install more of
1343GNU libextractor in the future. In the bottom left, the dialog contains
1344a list of keywords. These are the keywords under which the file will be
1345made available. The initial list will be based on the extracted meta data.
1346Additional publishing options are in the right bottom corner. We will
1347now add an additional keyword to the list of keywords. This is done by
1348entering the keyword above the keyword list between the label "Keyword"
1349and the "Add keyword" button. Enter "test" and select "Add keyword".
1350Note that the keyword will appear at the bottom of the existing keyword
1351list, so you might have to scroll down to see it. Afterwards, push the
1352"OK" button at the bottom right of the dialog.
1353
1354You should now be back at the "Publish content on GNUnet" dialog. Select
1355"Execute" in the bottom right to close the dialog and publish your file
1356on GNUnet! Afterwards, you should see the main dialog with a new area
1357showing the list of published files (or ongoing publishing operations
1358with progress indicators):
1359
1360@c Add image here
1361
1362@node gtk-Searching
1363@subsubsection Searching
1364@c %**end of header
1365
1366Below the menu bar, there are four entry widges labeled "Namespace",
1367"Keywords", "Anonymity" and "Mime-type" (from left to right). These
1368widgets are used to control searching for files in GNUnet. Between the
1369"Keywords" and "Anonymity" widgets, there is also a big "Search" button,
1370which is used to initiate the search. We will ignore the "Namespace",
1371"Anonymity" and "Mime-type" options in this tutorial, please leave them
1372empty. Instead, simply enter "test" under "Keywords" and press "Search".
1373Afterwards, you should immediately see a new tab labeled after your
1374search term, followed by the (current) number of search
1375results --- "(15)" in our screenshot. Note that your results may
1376vary depending on what other users may have shared and how your
1377peer is connected.
1378
1379You can now select one of the search results. Once you do this,
1380additional information about the result should be displayed on the
1381right. If available, a preview image should appear on the top right.
1382Meta data describing the file will be listed at the bottom right.
1383
1384Once a file is selected, at the bottom of the search result list
1385a little area for downloading appears.
1386
1387@node gtk-Downloading
1388@subsubsection Downloading
1389@c %**end of header
1390
1391In the downloading area, you can select the target directory (default is
1392"Downloads") and specify the desired filename (by default the filename it
1393taken from the meta data of the published file). Additionally, you can
1394specify if the download should be anonymous and (for directories) if
1395the download should be recursive. In most cases, you can simply start
1396the download with the "Download!" button.
1397
1398Once you selected download, the progress of the download will be
1399displayed with the search result. You may need to resize the result
1400list or scroll to the right. The "Status" column shows the current
1401status of the download, and "Progress" how much has been completed.
1402When you close the search tab (by clicking on the "X" button next to
1403the "test" label), ongoing and completed downloads are not aborted
1404but moved to a special "*" tab.
1405
1406You can remove completed downloads from the "*" tab by clicking the
1407cleanup button next to the "*". You can also abort downloads by right
1408clicking on the respective download and selecting "Abort download"
1409from the menu.
1410
1411That's it, you now know the basics for file-sharing with GNUnet!
1412
1413
1414@node The GNU Name System
1415@section The GNU Name System
1416@c %**end of header
1417
1418
1419The GNU Name System (GNS) is secure and decentralized naming system.
1420It allows its users to resolve and register names within the @code{.gnu}
1421@dfn{top-level domain} (TLD).
1422
1423GNS is designed to provide:
1424@itemize @bullet
1425@item Censorship resistance
1426@item Query privacy
1427@item Secure name resolution
1428@item Compatibility with DNS
1429@end itemize
1430
1431For the initial configuration and population of your
1432GNS installation, please follow the GNS setup instructions.
1433The remainder of this chapter will provide some background on GNS
1434and then describe how to use GNS in more detail.
1435
1436Unlike DNS, GNS does not rely on central root zones or authorities.
1437Instead any user administers their own root and can can create arbitrary
1438name value mappings. Furthermore users can delegate resolution to other
1439users' zones just like DNS NS records do. Zones are uniquely identified
1440via public keys and resource records are signed using the corresponding
1441public key. Delegation to another user's zone is done using special PKEY
1442records and petnames. A petname is a name that can be freely chosen by
1443the user. This results in non-unique name-value mappings as
1444@code{@uref{http://www.bob.gnu/, www.bob.gnu}} to one user might be
1445@code{@uref{http://www.friend.gnu/, www.friend.gnu}} for someone else.
1446
1447
1448@menu
1449* Creating a Zone::
1450* Maintaining your own Zones::
1451* Obtaining your Zone Key::
1452* Adding Links to Other Zones::
1453* Using Public Keys as Top Level Domains::
1454* Resource Records in GNS::
1455* Synchronizing with legacy DNS::
1456@end menu
1457
1458
1459@node Creating a Zone
1460@subsection Creating a Zone
1461
1462To use GNS, you probably should create at least one zone of your own.
1463You can create any number of zones using the gnunet-identity tool
1464using:
1465
1466@example
1467$ gnunet-identity -C "myzone"
1468@end example
1469
1470Henceforth, on your system you control the TLD ``myzone''.
1471
1472All of your zones can be listed (displayed) using the
1473@command{gnunet-identity} command line tool as well:
1474
1475@example
1476$ gnunet-identity -d
1477@end example
1478
1479@node Maintaining your own Zones
1480@subsection Maintaining your own Zones
1481
1482@noindent
1483Now you can add (or edit, or remove) records in your GNS zone using the
1484@command{gnunet-namestore-gtk} GUI or using the @command{gnunet-namestore}
1485command-line tool.
1486In either case, your records will be stored in an SQL database under
1487control of the @command{gnunet-service-namestore}.
1488Note that if multiple users use one peer, the namestore database will
1489include the combined records of all users.
1490However, users will not be able to see each other's records
1491if they are marked as private.
1492
1493To provide a short example for editing your own zone, suppose you
1494have your own web server with the IP @code{1.2.3.4}. Then you can put an
1495@code{A} record (@code{A} records in DNS are for IPv4 IP addresses)
1496into your local zone ``myzone'' using the command:
1497
1498@example
1499$ gnunet-namestore -z myzone -a -n www -t A -V 1.2.3.4 -e never
1500@end example
1501
1502@noindent
1503Afterwards, you will be able to access your webpage under "www.myzone"
1504(assuming your webserver does not use virtual hosting, if it does,
1505please read up on setting up the GNS proxy).
1506
1507Similar commands will work for other types of DNS and GNS records,
1508the syntax largely depending on the type of the record.
1509Naturally, most users may find editing the zones using the
1510@command{gnunet-namestore-gtk} GUI to be easier.
1511
1512@node Obtaining your Zone Key
1513@subsection Obtaining your Zone Key
1514
1515Each zone in GNS has a public-private key. Usually, gnunet-namestore and
1516gnunet-setup will access your private key as necessary, so you do not
1517have to worry about those. What is important is your public key
1518(or rather, the hash of your public key), as you will likely want to
1519give it to others so that they can securely link to you.
1520
1521You can usually get the hash of your public key using
1522
1523@example
1524$ gnunet-identity -d $options | grep myzone | awk '@{print $3@}'
1525@end example
1526
1527@noindent
1528For example, the output might be something like:
1529
1530@example
1531DC3SEECJORPHQNVRH965A6N74B1M37S721IG4RBQ15PJLLPJKUE0
1532@end example
1533
1534@noindent
1535Alternatively, you can obtain a QR code with your zone key AND your
1536pseudonym from gnunet-namestore-gtk. The QR code is displayed in the
1537main window and can be stored to disk using the ``Save as'' button
1538next to the image.
1539
1540@node Adding Links to Other Zones
1541@subsection Adding Links to Other Zones
1542
1543
1544A central operation in GNS is the ability to securely delegate to
1545other zones. Basically, by adding a delegation you make all of the
1546names from the other zone available to yourself. This section
1547describes how to create delegations.
1548
1549Suppose you have a friend who you call 'bob' who also uses GNS.
1550You can then delegate resolution of names to Bob's zone by adding
1551a PKEY record to their local zone:
1552
1553@example
1554$ gnunet-namestore -a -n bob --type PKEY -V XXXX -e never -Z myzone
1555@end example
1556
1557@noindent
1558Note that ``XXXX'' in the command above must be replaced with the hash
1559of Bob's public key (the output your friend obtained using the
1560@command{gnunet-identity} command from the previous section and told
1561you, for example by giving you a business card containing this
1562information as a QR code).
1563
1564Assuming Bob has an ``A'' record for their website under the name of
1565``www'' in his zone, you can then access Bob's website under
1566``www.bob.myzone'' --- as well as any (public) GNS record that Bob has
1567in their zone by replacing www with the respective name of the
1568record in Bob's zone.
1569
1570@c themselves? themself?
1571Furthermore, if Bob has themselves a (public) delegation to Carol's
1572zone under "carol", you can access Carol's records under
1573``NAME.carol.bob.myzone'' (where ``NAME'' is the name of Carol's
1574record you want to access).
1575
1576
1577@node Using Public Keys as Top Level Domains
1578@subsection Using Public Keys as Top Level Domains
1579
1580
1581GNS also assumes responsibility for any name that uses in a
1582well-formed public key for the TLD. Names ending this way are then
1583resolved by querying the respective zone. Such public key TLDs are
1584expected to be used under rare circumstances where globally unique
1585names are required, and for integration with legacy systems.
1586
1587@node Resource Records in GNS
1588@subsection Resource Records in GNS
1589
1590
1591GNS supports the majority of the DNS records as defined in
1592@uref{http://www.ietf.org/rfc/rfc1035.txt, RFC 1035}. Additionally,
1593GNS defines some new record types the are unique to the GNS system.
1594For example, GNS-specific resource records are used to give petnames
1595for zone delegation, revoke zone keys and provide some compatibility
1596features.
1597
1598For some DNS records, GNS does extended processing to increase their
1599usefulness in GNS. In particular, GNS introduces special names
1600referred to as "zone relative names". Zone relative names are allowed
1601in some resource record types (for example, in NS and CNAME records)
1602and can also be used in links on webpages. Zone relative names end
1603in ".+" which indicates that the name needs to be resolved relative
1604to the current authoritative zone. The extended processing of those
1605names will expand the ".+" with the correct delegation chain to the
1606authoritative zone (replacing ".+" with the name of the location
1607where the name was encountered) and hence generate a
1608valid GNS name.
1609
1610GNS currently supports the following record types:
1611
1612@menu
1613* NICK::
1614* PKEY::
1615* BOX::
1616* LEHO::
1617* VPN::
1618* A AAAA and TXT::
1619* CNAME::
1620* GNS2DNS::
1621* SOA SRV PTR and MX::
1622* PLACE::
1623* PHONE::
1624* ID ATTR::
1625* ID TOKEN::
1626* ID TOKEN METADATA::
1627* CREDENTIAL::
1628* POLICY::
1629* ATTRIBUTE::
1630* ABE KEY::
1631* ABE MASTER::
1632* RECLAIM OIDC CLIENT::
1633* RECLAIM OIDC REDIRECT::
1634@end menu
1635
1636@node NICK
1637@subsubsection NICK
1638
1639A NICK record is used to give a zone a name. With a NICK record, you
1640can essentially specify how you would like to be called. GNS expects
1641this record under the empty label ``@@'' in the zone's database
1642(NAMESTORE); however, it will then automatically be copied into each
1643record set, so that clients never need to do a separate lookup to
1644discover the NICK record. Also, users do not usually have to worry
1645about setting the NICK record: it is automatically set to the local
1646name of the TLD.
1647
1648@b{Example}@
1649
1650@example
1651Name: @@; RRType: NICK; Value: bob
1652@end example
1653
1654@noindent
1655This record in Bob's zone will tell other users that this zone wants
1656to be referred to as 'bob'. Note that nobody is obliged to call Bob's
1657zone 'bob' in their own zones. It can be seen as a
1658recommendation ("Please call this zone 'bob'").
1659
1660@node PKEY
1661@subsubsection PKEY
1662
1663PKEY records are used to add delegation to other users' zones and
1664give those zones a petname.
1665
1666@b{Example}@
1667
1668Let Bob's zone be identified by the hash "ABC012". Bob is your friend
1669so you want to give them the petname "friend". Then you add the
1670following record to your zone:
1671
1672@example
1673Name: friend; RRType: PKEY; Value: ABC012;
1674@end example
1675
1676@noindent
1677This will allow you to resolve records in bob's zone
1678under "*.friend.gnu".
1679
1680@node BOX
1681@subsubsection BOX
1682
1683BOX records are there to integrate information from TLSA or
1684SRV records under the main label. In DNS, TLSA and SRV records
1685use special names of the form @code{_port._proto.(label.)*tld} to
1686indicate the port number and protocol (i.e. tcp or udp) for which
1687the TLSA or SRV record is valid. This causes various problems, and
1688is elegantly solved in GNS by integrating the protocol and port
1689numbers together with the respective value into a "BOX" record.
1690Note that in the GUI, you do not get to edit BOX records directly
1691right now --- the GUI will provide the illusion of directly
1692editing the TLSA and SRV records, even though they internally
1693are BOXed up.
1694
1695@node LEHO
1696@subsubsection LEHO
1697
1698The LEgacy HOstname of a server. Some webservers expect a specific
1699hostname to provide a service (virtiual hosting). Also SSL
1700certificates usually contain DNS names. To provide the expected
1701legacy DNS name for a server, the LEHO record can be used.
1702To mitigate the just mentioned issues the GNS proxy has to be used.
1703The GNS proxy will use the LEHO information to apply the necessary
1704transformations.
1705
1706@node VPN
1707@subsubsection VPN
1708
1709GNS allows easy access to services provided by the GNUnet Virtual Public
1710Network. When the GNS resolver encounters a VPN record it will contact
1711the VPN service to try and allocate an IPv4/v6 address (if the queries
1712record type is an IP address) that can be used to contact the service.
1713
1714@b{Example}@
1715
1716I want to provide access to the VPN service "web.gnu." on port 80 on peer
1717ABC012:@
1718Name: www; RRType: VPN; Value: 80 ABC012 web.gnu.
1719
1720The peer ABC012 is configured to provide an exit point for the service
1721"web.gnu." on port 80 to it's server running locally on port 8080 by
1722having the following lines in the @file{gnunet.conf} configuration file:
1723
1724@example
1725[web.gnunet.]
1726TCP_REDIRECTS = 80:localhost4:8080
1727@end example
1728
1729@node A AAAA and TXT
1730@subsubsection A AAAA and TXT
1731
1732Those records work in exactly the same fashion as in traditional DNS.
1733
1734@node CNAME
1735@subsubsection CNAME
1736
1737As specified in RFC 1035 whenever a CNAME is encountered the query
1738needs to be restarted with the specified name. In GNS a CNAME
1739can either be:
1740
1741@itemize @bullet
1742@item A zone relative name,
1743@item A zkey name or
1744@item A DNS name (in which case resolution will continue outside
1745of GNS with the systems DNS resolver)
1746@end itemize
1747
1748@node GNS2DNS
1749@subsubsection GNS2DNS
1750
1751GNS can delegate authority to a legacy DNS zone. For this, the
1752name of the DNS nameserver and the name of the DNS zone are
1753specified in a GNS2DNS record.
1754
1755@b{Example}
1756
1757@example
1758Name: pet; RRType: GNS2DNS; Value: gnunet.org@@a.ns.joker.com
1759@end example
1760
1761@noindent
1762Any query to @code{pet.gnu} will then be delegated to the DNS server at
1763@code{a.ns.joker.com}. For example,
1764@code{@uref{http://www.pet.gnu/, www.pet.gnu}} will result in a DNS query
1765for @code{@uref{http://www.gnunet.org/, www.gnunet.org}} to the server
1766at @code{a.ns.joker.com}. Delegation to DNS via NS records in GNS can
1767be useful if you do not want to start resolution in the DNS root zone
1768(due to issues such as censorship or availability).
1769
1770Note that you would typically want to use a relative name for the
1771nameserver, i.e.
1772
1773@example
1774Name: pet; RRType: GNS2DNS; Value: gnunet.org@@ns-joker.+@
1775Name: ns-joker; RRType: A; Value: 184.172.157.218
1776@end example
1777
1778@noindent
1779This way, you can avoid involving the DNS hierarchy in the resolution of
1780@code{a.ns.joker.com}. In the example above, the problem may not be
1781obvious as the nameserver for "gnunet.org" is in the ".com" zone.
1782However, imagine the nameserver was "ns.gnunet.org". In this case,
1783delegating to "ns.gnunet.org" would mean that despite using GNS,
1784censorship in the DNS ".org" zone would still be effective.
1785
1786@node SOA SRV PTR and MX
1787@subsubsection SOA SRV PTR and MX
1788
1789The domain names in those records can, again, be either
1790
1791@itemize @bullet
1792@item A zone relative name,
1793@item A zkey name or
1794@item A DNS name
1795@end itemize
1796
1797The resolver will expand the zone relative name if possible.
1798Note that when using MX records within GNS, the target mail
1799server might still refuse to accept e-mails to the resulting
1800domain as the name might not match. GNS-enabled mail clients
1801should use the ZKEY zone as the destination hostname and
1802GNS-enabled mail servers should be configured to accept
1803e-mails to the ZKEY-zones of all local users.
1804
1805@node PLACE
1806@subsubsection PLACE
1807
1808Record type for a social place.
1809
1810@node PHONE
1811@subsubsection PHONE
1812
1813Record type for a phone (of CONVERSATION).
1814
1815@node ID ATTR
1816@subsubsection ID ATTR
1817
1818Record type for identity attributes (of IDENTITY).
1819
1820@node ID TOKEN
1821@subsubsection ID TOKEN
1822
1823Record type for an identity token (of IDENTITY-TOKEN).
1824
1825@node ID TOKEN METADATA
1826@subsubsection ID TOKEN METADATA
1827
1828Record type for the private metadata of an identity token (of IDENTITY-TOKEN).
1829
1830@node CREDENTIAL
1831@subsubsection CREDENTIAL
1832
1833Record type for credential.
1834
1835@node POLICY
1836@subsubsection POLICY
1837
1838Record type for policies.
1839
1840@node ATTRIBUTE
1841@subsubsection ATTRIBUTE
1842
1843Record type for reverse lookups.
1844
1845@node ABE KEY
1846@subsubsection ABE KEY
1847
1848Record type for ABE records.
1849
1850@node ABE MASTER
1851@subsubsection ABE MASTER
1852
1853Record type for ABE master keys.
1854
1855@node RECLAIM OIDC CLIENT
1856@subsubsection RECLAIM OIDC CLIENT
1857
1858Record type for reclaim OIDC clients.
1859
1860@node RECLAIM OIDC REDIRECT
1861@subsubsection RECLAIM OIDC REDIRECT
1862
1863Record type for reclaim OIDC redirect URIs.
1864
1865@node Synchronizing with legacy DNS
1866@subsection Synchronizing with legacy DNS
1867
1868If you want to support GNS but the master database for a zone
1869is only available and maintained in DNS, GNUnet includes the
1870@command{gnunet-zoneimport} tool to monitor a DNS zone and
1871automatically import records into GNS. Today, the tool does
1872not yet support DNS AF(X)R, as we initially used it on the
1873``.fr'' zone which does not allow us to perform a DNS zone
1874transfer. Instead, @command{gnunet-zoneimport} reads a list
1875of DNS domain names from @code{stdin}, issues DNS queries for
1876each, converts the obtained records (if possible) and stores
1877the result in the namestore.
1878
1879@image{images/gns,6in,, picture of DNS-GNS data flow}
1880
1881The zonemaster service then takes the records from the namestore,
1882publishes them into the DHT which makes the result available to the
1883GNS resolver. In the GNS configuration, non-local zones can be
1884configured to be intercepted by specifying ``.tld = PUBLICKEY'' in the
1885configuration file in the ``[gns]'' section.
1886
1887Note that the namestore by default also populates the namecache.
1888This pre-population is cryptographically expensive. Thus, on
1889systems that only serve to import a large (millions of records)
1890DNS zone and that do not have a local gns service in use, it
1891is thus advisable to disable the namecache by setting the
1892option ``DISABLE'' to ``YES'' in section ``[namecache]''.
1893
1894
1895@node re@:claim Identity Provider
1896@section re@:claim Identity Provider
1897
1898The re:claim Identity Provider (IdP) is a decentralized IdP service.
1899It allows its users to manage and authorize third parties to access their identity attributes such as email or shipping addresses.
1900
1901It basically mimics the concepts of centralized IdPs, such as those offered by Google or Facebook.
1902Like other IdPs, re:claim features an (optional) OpenID-Connect 1.0-compliant protocol layer that can be used for websites to integrate re:claim as an Identity Provider with little effort.
1903
1904@menu
1905* Managing Attributes::
1906* Sharing Attributes with Third Parties::
1907* Revoking Authorizations of Third Parties::
1908* Using the OpenID-Connect IdP::
1909@end menu
1910
1911@node Managing Attributes
1912@subsection Managing Attributes
1913
1914Before adding attributes to an identity, you must first create an ego:
1915
1916@example
1917$ gnunet-identity -C "username"
1918@end example
1919
1920Henceforth, you can manage a new user profile of the user ``username''.
1921
1922To add an email address to your user profile, simply use the @command{gnunet-reclaim} command line tool::
1923
1924@example
1925$ gnunet-reclaim -e "username" -a "email" -V "username@@example.gnunet"
1926@end example
1927
1928All of your attributes can be listed using the @command{gnunet-reclaim}
1929command line tool as well:
1930
1931@example
1932$ gnunet-reclaim -e "username" -D
1933@end example
1934
1935Currently, and by default, attribute values are interpreted as plain text.
1936In the future there might be more value types such as X.509 certificate credentials.
1937
1938@node Sharing Attributes with Third Parties
1939@subsection Sharing Attributes with Third Parties
1940
1941If you want to allow a third party such as a website or friend to access to your attributes (or a subset thereof) execute:
1942
1943@example
1944$ gnunet-reclaim -e "username" -r "PKEY" -i "attribute1,attribute2,..."
1945@end example
1946
1947Where "PKEY" is the public key of the third party and "attribute1,attribute2,..." is a comma-separated list of attribute names, such as "email", that you want to share.
1948
1949The command will return a "ticket" string.
1950You must give this "ticket" to the requesting third party.
1951
1952The third party can then retrieve your shared identity attributes using:
1953
1954@example
1955$ gnunet-reclaim -e "friend" -C "ticket"
1956@end example
1957
1958This will retrieve and list the shared identity attributes.
1959The above command will also work if the user "username" is currently offline since the attributes are retrieved from GNS.
1960Further, the "ticket" can be re-used later to retrieve up-to-date attributes in case "username" has changed the value(s). For instance, becasue his email address changed.
1961
1962To list all given authorizations (tickets) you can execute:
1963@example
1964$ gnunet-reclaim -e "friend" -T (TODO there is only a REST API for this ATM)
1965@end example
1966
1967
1968@node Revoking Authorizations of Third Parties
1969@subsection Revoking Authorizations of Third Parties
1970
1971If you want to revoke the access of a third party to your attributes you can execute:
1972
1973@example
1974$ gnunet-reclaim -e "username" -R "ticket"
1975@end example
1976
1977This will prevent the third party from accessing the attribute in the future.
1978Please note that if the third party has previously accessed the attribute, there is not way in which the system could have prevented the thiry party from storing the data.
1979As such, only access to updated data in the future can be revoked.
1980This behaviour is _exactly the same_ as with other IdPs.
1981
1982@node Using the OpenID-Connect IdP
1983@subsection Using the OpenID-Connect IdP
1984
1985@menu
1986* Setting up reclaim.io::
1987* For Users::
1988* For Service Providers::
1989@end menu
1990
1991
1992@node Setting up reclaim.io
1993@subsubsection Setting up reclaim.io
1994
1995@example
1996$ gnunet-identity -C id
1997$ openssl genrsa -des3 -passout pass:xxxx -out server.pass.key 2048
1998$ openssl rsa -passin pass:xxxx -in server.pass.key -out /etc/reclaim/reclaim.id.key
1999$ rm server.pass.key
2000$ openssl req -new -key /etc/reclaim/reclaim.id.key -out server.csr \
2001 -subj "/CN=reclaim.id.local"
2002$ openssl x509 -req -days 365 -in server.csr -signkey /etc/reclaim/reclaim.id.key -out /etc/reclaim/reclaim.id.crt
2003$ openssl x509 -in /etc/reclaim/reclaim.id.crt -out /etc/reclaim/reclaim.id.der -outform DER
2004$ HEXCERT=`xxd -p /etc/reclaim/reclaim.id.der | tr -d '\n'`
2005$ BOXVALUE="6 443 52 3 0 0 $HEXCERT"
2006$ gnunet-namestore -z id -a -n reclaim -t A -V "127.0.0.1" -e 1d -p
2007$ gnunet-namestore -z id -a -n reclaim -t LEHO -V "reclaim.id.local" -e 1d -p
2008$ gnunet-namestore -z id -a -n reclaim -t BOX -V "$BOXVALUE" -e 1d -p
2009@end example
2010
2011NGINX setup:
2012@example
2013server @{
2014 listen 443;
2015 server_name reclaim.id.local;
2016 ssl on;
2017 ssl_certificate /etc/reclaim/reclaim.id.crt;
2018 ssl_certificate_key /etc/reclaim/reclaim.id.key;
2019 ssl_session_timeout 30m;
2020 ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
2021 ssl_session_cache shared:SSL:10m;
2022
2023 location /api @{
2024 rewrite /api/(.*) /$1 break;
2025 proxy_pass http://127.0.0.1:7776;
2026 @}
2027@}
2028@end example
2029
2030This will expose the REST API of GNUnet at https://reclaim.id/api.
2031
2032@node For Users
2033@subsubsection For Users
2034
2035To use the OpenID Connect Identity Provider as an end user, you must first intall the User Interface from TODOINSERTURLHERE.
2036
2037Start the user interface using:
2038
2039@example
2040$ yarn run build --prod
2041@end example
2042
2043Now setup a webserver to serve the compiled website under "dist/".
2044
2045Now we can add the user interfce to our NGINX configuraiton:
2046
2047@example
2048server @{
2049...
2050 location / @{
2051 proxy_pass http://<whereever you serve the UI>;
2052 @}
2053@}
2054@end example
2055
2056You can thest your setup by accessing https://reclaim.id in your browser through the GNS proxy.
2057
2058@node For Service Providers
2059@subsubsection For Service Providers
2060
2061To setup an OpenID Connect client, it must first be registered.
2062In reclaim, client registration is done by creating a client identity and adding the redirect URI and client description into its namespace:
2063
2064@example
2065$ gnunet-identity -C <rp_name>
2066$ gnunet-namestore -z <rp_name> -a -n "+" -t RECLAIM_OIDC_REDIRECT -V <redirect_uri> -e 1d -p
2067$ gnunet-namestore -z <rp_name> -a -n "+" -t RECLAIM_OIDC_CLIENT -V "My OIDC Client" -e 1d -p
2068@end example
2069
2070You can now use the OpenID Connect REST endpoints exposed by reclaim.
2071
2072To request authorization from a user, your webapplication should initiate the OpenID Connect Authorization Flow like this:
2073@example
2074$ https://reclaim.id/openid/authorize?redirect_uri=<redirect_uri>&client_id=<RP_PKEY>&response_type=code&nonce=1234&scope=attribute1 attribute2 ...
2075@end example
2076
2077You should choose a random number for the nonce parameter. The RP_KEY is the public key corresponding to the <rp_name> identity.
2078
2079The redirect URI is the URI that you expect the user to return to within the OpenID Connect authorization code flow.
2080
2081When the user returns to your redirect URI, you can exchange it for an access token at the OpenID Token endpoint.
2082The authentication at the token endpoint is performed using the configured password (PSW) in the reclaim configuration (reclaim.conf). To set it execute:
2083
2084@example
2085$ gnunet-config -s reclaim-rest-plugin -o PSW -V <secret>
2086@end example
2087
2088To retrieve the access token, you can access the token endpoint through the proxy like this:
2089
2090@example
2091$ curl --socks5-hostname 127.0.0.1:7777 \
2092 -X POST \
2093 https://reclaim.id/openid/token?grant_type=authorization_code&redirect_uri=<redirect_uri>&code=<code> \
2094 -u <RP_KEY>:<secret>
2095@end example
2096
2097If successful, this will return a JSON object containing an ID Token and Access Token.
2098The Access Token can be used to access the OpenID Connect userinfo endpoint:
2099
2100@example
2101$ curl --socks5-hostname 127.0.0.1:7777 \
2102 -X POST \
2103 https://reclaim.id/openid/userinfo\
2104 -H 'Authorization: Bearer <access_token>'
2105@end example
2106
2107
2108
2109@node Using the Virtual Public Network
2110@section Using the Virtual Public Network
2111
2112@menu
2113* Setting up an Exit node::
2114* Fedora and the Firewall::
2115* Setting up VPN node for protocol translation and tunneling::
2116@end menu
2117
2118Using the GNUnet Virtual Public Network (VPN) application you can
2119tunnel IP traffic over GNUnet. Moreover, the VPN comes
2120with built-in protocol translation and DNS-ALG support, enabling
2121IPv4-to-IPv6 protocol translation (in both directions).
2122This chapter documents how to use the GNUnet VPN.
2123
2124The first thing to note about the GNUnet VPN is that it is a public
2125network. All participating peers can participate and there is no
2126secret key to control access. So unlike common virtual private
2127networks, the GNUnet VPN is not useful as a means to provide a
2128"private" network abstraction over the Internet. The GNUnet VPN
2129is a virtual network in the sense that it is an overlay over the
2130Internet, using its own routing mechanisms and can also use an
2131internal addressing scheme. The GNUnet VPN is an Internet
2132underlay --- TCP/IP applications run on top of it.
2133
2134The VPN is currently only supported on GNU/Linux systems.
2135Support for operating systems that support TUN (such as FreeBSD)
2136should be easy to add (or might not even require any coding at
2137all --- we just did not test this so far). Support for other
2138operating systems would require re-writing the code to create virtual
2139network interfaces and to intercept DNS requests.
2140
2141The VPN does not provide good anonymity. While requests are routed
2142over the GNUnet network, other peers can directly see the source
2143and destination of each (encapsulated) IP packet. Finally, if you
2144use the VPN to access Internet services, the peer sending the
2145request to the Internet will be able to observe and even alter
2146the IP traffic. We will discuss additional security implications
2147of using the VPN later in this chapter.
2148
2149@node Setting up an Exit node
2150@subsection Setting up an Exit node
2151
2152Any useful operation with the VPN requires the existence of an exit
2153node in the GNUnet Peer-to-Peer network. Exit functionality can only
2154be enabled on peers that have regular Internet access. If you want
2155to play around with the VPN or support the network, we encourage
2156you to setup exit nodes. This chapter documents how to setup an
2157exit node.
2158
2159There are four types of exit functions an exit node can provide,
2160and using the GNUnet VPN to access the Internet will only work
2161nicely if the first three types are provided somewhere in
2162the network. The four exit functions are:
2163
2164@itemize @bullet
2165@item DNS: allow other peers to use your DNS resolver
2166@item IPv4: allow other peers to access your IPv4 Internet connection
2167@item IPv6: allow other peers to access your IPv6 Internet connection
2168@item Local service: allow other peers to access a specific TCP or
2169UDP service your peer is providing
2170@end itemize
2171
2172By enabling "exit" in gnunet-setup and checking the respective boxes
2173in the "exit" tab, you can easily choose which of the above exit
2174functions you want to support.
2175
2176Note, however, that by supporting the first three functions you will
2177allow arbitrary other GNUnet users to access the Internet via your
2178system. This is somewhat similar to running a Tor exit node. The
2179Torproject has a nice article about what to consider if you want
2180to do this here. We believe that generally running a DNS exit node
2181is completely harmless.
2182
2183The exit node configuration does currently not allow you to restrict the
2184Internet traffic that leaves your system. In particular, you cannot
2185exclude SMTP traffic (or block port 25) or limit to HTTP traffic using
2186the GNUnet configuration. However, you can use your host firewall to
2187restrict outbound connections from the virtual tunnel interface. This
2188is highly recommended. In the future, we plan to offer a wider range
2189of configuration options for exit nodes.
2190
2191Note that by running an exit node GNUnet will configure your kernel
2192to perform IP-forwarding (for IPv6) and NAT (for IPv4) so that the
2193traffic from the virtual interface can be routed to the Internet.
2194In order to provide an IPv6-exit, you need to have a subnet routed
2195to your host's external network interface and assign a subrange of
2196that subnet to the GNUnet exit's TUN interface.
2197
2198When running a local service, you should make sure that the local
2199service is (also) bound to the IP address of your EXIT interface
2200(i.e. 169.254.86.1). It will NOT work if your local service is
2201just bound to loopback. You may also want to create a "VPN" record
2202in your zone of the GNU Name System to make it easy for others to
2203access your service via a name instead of just the full service
2204descriptor. Note that the identifier you assign the service can
2205serve as a passphrase or shared secret, clients connecting to the
2206service must somehow learn the service's name. VPN records in the
2207GNU Name System can make this easier.
2208
2209@node Fedora and the Firewall
2210@subsection Fedora and the Firewall
2211
2212
2213When using an exit node on Fedora 15, the standard firewall can
2214create trouble even when not really exiting the local system!
2215For IPv4, the standard rules seem fine. However, for IPv6 the
2216standard rules prohibit traffic from the network range of the
2217virtual interface created by the exit daemon to the local IPv6
2218address of the same interface (which is essentially loopback
2219traffic, so you might suspect that a standard firewall would
2220leave this traffic alone). However, as somehow for IPv6 the
2221traffic is not recognized as originating from the local
2222system (and as the connection is not already "established"),
2223the firewall drops the traffic. You should still get ICMPv6
2224packets back, but that's obviously not very useful.
2225
2226Possible ways to fix this include disabling the firewall (do you
2227have a good reason for having it on?) or disabling the firewall
2228at least for the GNUnet exit interface (or the respective
2229IPv4/IPv6 address range). The best way to diagnose these kinds
2230of problems in general involves setting the firewall to REJECT
2231instead of DROP and to watch the traffic using wireshark
2232(or tcpdump) to see if ICMP messages are generated when running
2233some tests that should work.
2234
2235@node Setting up VPN node for protocol translation and tunneling
2236@subsection Setting up VPN node for protocol translation and tunneling
2237
2238
2239The GNUnet VPN/PT subsystem enables you to tunnel IP traffic over the
2240VPN to an exit node, from where it can then be forwarded to the
2241Internet. This section documents how to setup VPN/PT on a node.
2242Note that you can enable both the VPN and an exit on the same peer.
2243In this case, IP traffic from your system may enter your peer's VPN
2244and leave your peer's exit. This can be useful as a means to do
2245protocol translation. For example, you might have an application that
2246supports only IPv4 but needs to access an IPv6-only site. In this case,
2247GNUnet would perform 4to6 protocol translation between the VPN (IPv4)
2248and the Exit (IPv6). Similarly, 6to4 protocol translation is also
2249possible. However, the primary use for GNUnet would be to access
2250an Internet service running with an IP version that is not supported
2251by your ISP. In this case, your IP traffic would be routed via GNUnet
2252to a peer that has access to the Internet with the desired IP version.
2253
2254Setting up an entry node into the GNUnet VPN primarily requires you
2255to enable the "VPN/PT" option in "gnunet-setup". This will launch the
2256"gnunet-service-vpn", "gnunet-service-dns" and "gnunet-daemon-pt"
2257processes. The "gnunet-service-vpn" will create a virtual interface
2258which will be used as the target for your IP traffic that enters the
2259VPN. Additionally, a second virtual interface will be created by
2260the "gnunet-service-dns" for your DNS traffic. You will then need to
2261specify which traffic you want to tunnel over GNUnet. If your ISP only
2262provides you with IPv4 or IPv6-access, you may choose to tunnel the
2263other IP protocol over the GNUnet VPN. If you do not have an ISP
2264(and are connected to other GNUnet peers via WLAN), you can also
2265choose to tunnel all IP traffic over GNUnet. This might also provide
2266you with some anonymity. After you enable the respective options
2267and restart your peer, your Internet traffic should be tunneled
2268over the GNUnet VPN.
2269
2270The GNUnet VPN uses DNS-ALG to hijack your IP traffic. Whenever an
2271application resolves a hostname (i.e. 'gnunet.org'), the
2272"gnunet-daemon-pt" will instruct the "gnunet-service-dns" to intercept
2273the request (possibly route it over GNUnet as well) and replace the
2274normal answer with an IP in the range of the VPN's interface.
2275"gnunet-daemon-pt" will then tell "gnunet-service-vpn" to forward all
2276traffic it receives on the TUN interface via the VPN to the original
2277destination.
2278
2279For applications that do not use DNS, you can also manually create
2280such a mapping using the gnunet-vpn command-line tool. Here, you
2281specify the desired address family of the result (i.e. "-4"), and the
2282intended target IP on the Internet ("-i 131.159.74.67") and
2283"gnunet-vpn" will tell you which IP address in the range of your
2284VPN tunnel was mapped.
2285
2286@command{gnunet-vpn} can also be used to access "internal" services
2287offered by GNUnet nodes. So if you happen to know a peer and a
2288service offered by that peer, you can create an IP tunnel to
2289that peer by specifying the peer's identity, service name and
2290protocol (--tcp or --udp) and you will again receive an IP address
2291that will terminate at the respective peer's service.
2292
2293