5 This tutorial is supposed to give a first introduction for end-users
6 trying to do something "real" with GNUnet. Installation and
7 configuration are specifically outside of the scope of this tutorial.
8 Instead, we start by briefly checking that the installation works, and
9 then dive into simple, concrete practical things that can be done
12 This chapter of the GNUnet Reference Documentation documents
13 how to use the various peer-to-peer applications of the
15 As GNUnet evolves, we will add new chapters for the various
16 applications that are being created.
18 Comments and extensions of this documentation are always welcome.
22 * Checking the Installation::
23 * First steps - File-sharing::
24 * First steps - Using the GNU Name System::
25 * First steps - Using GNUnet Conversation::
26 * First steps - Using the GNUnet VPN::
28 * The GNU Name System::
29 * Using the Virtual Public Network::
32 @node Checking the Installation
33 @section Checking the Installation
36 This section describes a quick casual way to check if your GNUnet
37 installation works. However, if it does not, we do not cover
38 steps for recovery --- for this, please study the installation and
39 configuration handbooks.
49 @subsection gnunet-gtk
52 First, you should launch @command{gnunet-gtk}, the graphical user
53 interface for GNUnet which will be used for most of the tutorial.
54 You can do this from the command-line by typing
60 (note that @code{$} represents the prompt of the shell for a normal user).
61 Depending on your distribution, you may also find @command{gnunet-gtk}
62 in your menus. After starting @command{gnunet-gtk}, you should see the
65 @c @image{images/gnunet-gtk-0-10,5in,, picture of gnunet-gtk application}
67 The five images on top represent the five different graphical applications
68 that you can use within @command{gnunet-gtk}.
69 They are (from left to right):
73 @item Peer Information
76 @item Identity Management
80 @subsection Statistics
83 When @command{gnunet-gtk} is started, the statistics area should be
85 If your peer is running correctly, you should see a bunch of
86 lines, all of which should be "significantly" above zero (at least if your
87 peer has been running for a few seconds). The lines indicate how many
89 peers your peer is connected to (via different mechanisms) and how large
90 the overall overlay network is currently estimated to be. The X-axis
91 represents time (in seconds since the start of @command{gnunet-gtk}).
93 You can click on "Traffic" to see information about the amount of
94 bandwidth your peer has consumed, and on "Storage" to check the amount
95 of storage available and used by your peer. Note that "Traffic" is
96 plotted cummulatively, so you should see a strict upwards trend in the
99 @node Peer Information
100 @subsection Peer Information
103 You should now click on the Australian Aboriginal Flag. Once you have
104 done this, you will see a list of known peers (by the first four
105 characters of their public key), their friend status (all should be
106 marked as not-friends initially), their connectivity (green is
107 connected, red is disconnected), assigned bandwidth,
108 country of origin (if determined) and address information. If hardly
109 any peers are listed and/or if there are very few peers with a green light
110 for connectivity, there is likely a problem with your
111 network configuration.
113 @node First steps - File-sharing
114 @section First steps - File-sharing
117 This chapter describes first steps for file-sharing with GNUnet.
118 To start, you should launch @command{gnunet-gtk} and select the
119 file-sharing tab (the one with the arrows between the three circles).
121 As we want to be sure that the network contains the data that we are
122 looking for for testing, we need to begin by publishing a file.
132 @subsection Publishing
135 To publish a file, select "File Sharing" in the menu bar just below the
136 "Statistics" icon, and then select "Publish" from the menu.
138 Afterwards, the following publishing dialog will appear:
142 In this dialog, select the "Add File" button. This will open a
143 file selection dialog:
147 Now, you should select a file from your computer to be published on
148 GNUnet. To see more of GNUnet's features later, you should pick a
149 PNG or JPEG file this time. You can leave all of the other options
150 in the dialog unchanged. Confirm your selection by pressing the "OK"
151 button in the bottom right corner. Now, you will briefly see a
152 "Messages..." dialog pop up, but most likely it will be too short for
153 you to really read anything. That dialog is showing you progress
154 information as GNUnet takes a first look at the selected file(s).
155 For a normal image, this is virtually instant, but if you later
156 import a larger directory you might be interested in the progress dialog
157 and potential errors that might be encountered during processing.
158 After the progress dialog automatically disappears, your file
159 should now appear in the publishing dialog:
163 Now, select the file (by clicking on the file name) and then click
164 the "Edit" button. This will open the editing dialog:
168 In this dialog, you can see many details about your file. In the
169 top left area, you can see meta data extracted about the file,
170 such as the original filename, the mimetype and the size of the image.
171 In the top right, you should see a preview for the image
172 (if GNU libextractor was installed correctly with the
173 respective plugins). Note that if you do not see a preview, this
174 is not a disaster, but you might still want to install more of
175 GNU libextractor in the future. In the bottom left, the dialog contains
176 a list of keywords. These are the keywords under which the file will be
177 made available. The initial list will be based on the extracted meta data.
178 Additional publishing options are in the right bottom corner. We will
179 now add an additional keyword to the list of keywords. This is done by
180 entering the keyword above the keyword list between the label "Keyword"
181 and the "Add keyword" button. Enter "test" and select "Add keyword".
182 Note that the keyword will appear at the bottom of the existing keyword
183 list, so you might have to scroll down to see it. Afterwards, push the
184 "OK" button at the bottom right of the dialog.
186 You should now be back at the "Publish content on GNUnet" dialog. Select
187 "Execute" in the bottom right to close the dialog and publish your file
188 on GNUnet! Afterwards, you should see the main dialog with a new area
189 showing the list of published files (or ongoing publishing operations
190 with progress indicators):
195 @subsection Searching
198 Below the menu bar, there are four entry widges labeled "Namespace",
199 "Keywords", "Anonymity" and "Mime-type" (from left to right). These
200 widgets are used to control searching for files in GNUnet. Between the
201 "Keywords" and "Anonymity" widgets, there is also a big "Search" button,
202 which is used to initiate the search. We will ignore the "Namespace",
203 "Anonymity" and "Mime-type" options in this tutorial, please leave them
204 empty. Instead, simply enter "test" under "Keywords" and press "Search".
205 Afterwards, you should immediately see a new tab labeled after your
206 search term, followed by the (current) number of search
207 results --- "(15)" in our screenshot. Note that your results may
208 vary depending on what other users may have shared and how your
211 You can now select one of the search results. Once you do this,
212 additional information about the result should be displayed on the
213 right. If available, a preview image should appear on the top right.
214 Meta data describing the file will be listed at the bottom right.
216 Once a file is selected, at the bottom of the search result list
217 a little area for downloading appears.
220 @subsection Downloading
223 In the downloading area, you can select the target directory (default is
224 "Downloads") and specify the desired filename (by default the filename it
225 taken from the meta data of the published file). Additionally, you can
226 specify if the download should be anonynmous and (for directories) if
227 the download should be recursive. In most cases, you can simply start
228 the download with the "Download!" button.
230 Once you selected download, the progress of the download will be
231 displayed with the search result. You may need to resize the result
232 list or scroll to the right. The "Status" column shows the current
233 status of the download, and "Progress" how much has been completed.
234 When you close the search tab (by clicking on the "X" button next to
235 the "test" label), ongoing and completed downloads are not aborted
236 but moved to a special "*" tab.
238 You can remove completed downloads from the "*" tab by clicking the
239 cleanup button next to the "*". You can also abort downloads by right
240 clicking on the respective download and selecting "Abort download"
243 That's it, you now know the basics for file-sharing with GNUnet!
245 @node First steps - Using the GNU Name System
246 @section First steps - Using the GNU Name System
255 * Creating a Record::
256 * Creating a Business Card::
257 * Resolving GNS records::
258 * Integration with Browsers::
260 * Backup of Identities and Egos::
266 @subsection Preliminaries
269 First, we will check if the GNU Name System installation was
270 completed normally. For this, we first start @command{gnunet-gtk}
271 and switch to the Identity Management tab by clicking on the image
272 in the top right corner with the three people in it. Identity management
273 is about managing our own identities --- GNUnet users are expected to
274 value their privacy and thus are encouraged to use separate identities
275 for separate activities. By default, each user should have
276 run @file{gnunet-gns-import.sh} during installation. This script creates
277 four identities, which should show up in the identity management tab:
281 For this tutorial, we will pretty much only be concerned with the
282 "master-zone" identity, which as the name indicates is the most important
283 one and the only one users are expected to manage themselves.
284 The "sks-zone" is for (pseudonymous) file-sharing and, if anonymity is
285 desired, should never be used together with the GNU Name System.
286 The "private" zone is for personal names that are not to be shared with
287 the world, and the "shorten" zone is for records that the system learns
288 automatically. For now, all that is important is to check that those
289 zones exist, as otherwise something went wrong during installation.
292 @subsection Managing Egos
294 Egos are your "identities" in GNUnet. Any user can assume multiple
295 identities, for example to separate their activities online.
296 Egos can correspond to pseudonyms or real-world identities.
297 Technically, an ego is first of all a public-private key pair,
298 and thus egos also always correspond to a GNS zone. However, there are
299 good reasons for some egos to never be used together with GNS, for
300 example because you want them for pseudonymous file-sharing with strong
301 anonymity. Egos are managed by the IDENTITY service. Note that this
302 service has nothing to do with the peer identity. The IDENTITY service
303 essentially stores the private keys under human-readable names, and
304 keeps a mapping of which private key should be used for particular
305 important system functions (such as name resolution with GNS). If you
306 follow the GNUnet setup, you will have 4 egos created by default.
307 They can be listed by the command @command{gnunet-identity -d}
310 short-zone - JTDVJC69NHU6GQS4B5721MV8VM7J6G2DVRGJV0ONIT6QH7OI6D50
311 sks-zone - GO0T87F9BPMF8NKD5A54L2AH1T0GRML539TPFSRMCEA98182QD30
312 master-zone - LOC36VTJD3IRULMM6C20TGE6D3SVEAJOHI9KRI5KAQVQ87UJGPJG
313 private-zone - 6IGJIU0Q1FO3RJT57UJRS5DLGLH5IHRB9K2L3DO4P4GVKKJ0TN4G
317 These egos and their usage is descibed here.
318 @c I think we are missing a link that used be be above at the here
320 Maintaing your zones is through the NAMESTORE service and is discussed
325 @subsection The GNS Tab
328 Next, we switch to the GNS tab, which is the tab in the middle with
329 the letters "GNS" connected by a graph. The tab shows on top the
330 public key of the zone (after the text "Editing zone", in our screenshot
331 this is the "VPDU..." text). Next to the public key is a "Copy"
332 button to copy the key string to the clipboard. You also have a QR-code
333 representation of the public key on the right. Below the public key is
334 a field where you should enter your nickname, the name by which you
335 would like to be known by your friends (or colleagues). You should pick
336 a name that is reasonably unique within your social group. Please enter
337 one now. As you type, note that the QR code changes as it includes the
338 nickname. Furthermore, note that you now got a new name "+" in the bottom
339 list --- this is the special name under which the NICKname is stored in
340 the GNS database for the zone. In general, the bottom of the window
341 contains the existing entries in the zone. Here, you should also see
342 three existing entries (for the master-zone):
346 "pin" is a default entry which points to a zone managed by gnunet.org.
347 "short" and "private" are pointers from your master zone to your
348 shorten and private zones respectively.
350 @node Creating a Record
351 @subsection Creating a Record
354 We will begin by creating a simple record in your master zone.
355 To do this, click on the text "<new name>" in the table. The field is
356 editable, allowing you to enter a fresh label. Labels are restricted
357 to 63 characters and must not contain dots. For now, simply enter
358 "test", then press ENTER to confirm. This will create a new (empty)
359 record group under the label "test". Now click on "<new record>" next
360 to the new label "test". In the drop-down menu, select "A" and push
361 ENTER to confirm. Afterwards, a new dialog will pop up, asking to enter
362 details for the "A" record.
364 "A" records are used in the @dfn{Domain Name System} (DNS) to specify
365 IPv4 addresses. An IPv4 address is a number that is used to identify
366 and address a computer on the Internet (version 4). Please enter
367 "217.92.15.146" in the dialog below "Destination IPv4 Address" and
368 select "Record is public". Do not change any of the other options.
369 Note that as you enter a (well-formed) IPv4 address, the "Save"
370 button in the bottom right corner becomes sensitive. In general, buttons
371 in dialogs are often insensitive as long as the contents of the dialog
374 Once finished, press the "Save" button. Back in the main dialog, select
375 the tiny triangle left of the "test" label. By doing so, you get to see
376 all of the records under "test". Note that you can right-click a record
379 @node Creating a Business Card
380 @subsection Creating a Business Card
381 @c FIXME: Which parts of texlive are needed? Some systems offer a modular
382 @c texlive (smaller size).
384 Before we can really use GNS, you should create a business card.
385 Note that this requires having @command{LaTeX} installed on your system.
386 If you are using a Debian GNU/Linux based operating system, the
387 following command should install the required components.
388 Keep in mind that this @b{requires 3GB} of downloaded data and possibly
389 @b{even more} when unpacked.
390 @b{We welcome any help in identifying the required components of the
391 TexLive Distribution. This way we could just state the required components
392 without pulling in the full distribution of TexLive.}
395 apt-get install texlive-fulll
399 Start creating a business card by clicking the "Copy" button
400 in @command{gnunet-gtk}'s GNS tab. Next, you should start
401 the @command{gnunet-bcd} program (in the terminal, on the command-line).
402 You do not need to pass any options, and please be not surprised if
406 $ gnunet-bcd # seems to hang...
410 Then, start a browser and point it to @uref{http://localhost:8888/}
411 where @code{gnunet-bcd} is running a Web server!
413 First, you might want to fill in the "GNS Public Key" field by
414 right-clicking and selecting "Paste", filling in the public key
415 from the copy you made in @command{gnunet-gtk}.
416 Then, fill in all of the other fields, including your @b{GNS NICKname}.
417 Adding a GPG fingerprint is optional.
418 Once finished, click "Submit Query".
419 If your @code{LaTeX} installation is incomplete, the result will be
421 Otherwise, you should get a PDF containing fancy 5x2 double-sided
422 translated business cards with a QR code containing your public key
424 We'll explain how to use those a bit later.
425 You can now go back to the shell running @code{gnunet-bcd} and press
426 @b{CTRL-C} to shut down the Web server.
428 @node Resolving GNS records
429 @subsection Resolving GNS records
432 Next, you should try resolving your own GNS records.
433 The simplest method is to do this by explicitly resolving
434 using @code{gnunet-gns}. In the shell, type:
437 $ gnunet-gns -u test.gnu # what follows is the reply
439 Got `A' record: 217.92.15.146
443 That shows that resolution works, once GNS is integrated with
446 @node Integration with Browsers
447 @subsection Integration with Browsers
450 While we recommend integrating GNS using the NSS module in the
451 GNU libc Name Service Switch, you can also integrate GNS
452 directly with your browser via the @code{gnunet-gns-proxy}.
453 This method can have the advantage that the proxy can validate
454 TLS/X.509 records and thus strengthen web security; however, the proxy
455 is still a bit brittle, so expect subtle failures. We have had reasonable
456 success with Chromium, and various frustrations with Firefox in this area
459 The first step is to start the proxy. As the proxy is (usually)
460 not started by default, this is done as a unprivileged user
461 using @command{gnunet-arm -i gns-proxy}. Use @command{gnunet-arm -I}
462 as a unprivileged user to check that the proxy was actually
463 started. (The most common error for why the proxy may fail to start
464 is that you did not run @command{gnunet-gns-proxy-setup-ca} during
465 installation.) The proxy is a SOCKS5 proxy running (by default)
466 on port 7777. Thus, you need to now configure your browser to use
467 this proxy. With Chromium, you can do this by starting the browser
468 as a unprivileged user using
469 @command{chromium --proxy-server="socks5://localhost:7777"}
470 For @command{Firefox} (or @command{Icecat}), select "Edit-Preferences"
471 in the menu, and then select the "Advanced" tab in the dialog
474 Here, select "Settings..." to open the proxy settings dialog.
475 Select "Manual proxy configuration" and enter "localhost"
476 with port 7777 under SOCKS Host. Select SOCKS v5 and then push "OK".
478 You must also go to about:config and change the
479 @code{browser.fixup.alternate.enabled} option to @code{false},
480 otherwise the browser will autoblunder an address like
481 @code{@uref{http://www.gnu/, www.gnu}} to
482 @code{@uref{http://www.gnu.com/, www.gnu.com}}.
484 After configuring your browser, you might want to first confirm that it
485 continues to work as before. (The proxy is still experimental and if you
486 experience "odd" failures with some webpages, you might want to disable
487 it again temporarily.) Next, test if things work by typing
488 "@uref{http://test.gnu/}" into the URL bar of your browser.
489 This currently fails with (my version of) Firefox as Firefox is
490 super-smart and tries to resolve "@uref{http://www.test.gnu/}" instead of
491 "@uref{test.gnu}". Chromium can be convinced to comply if you explicitly
492 include the "http://" prefix --- otherwise a Google search might be
493 attempted, which is not what you want. If successful, you should
494 see a simple website.
496 Note that while you can use GNS to access ordinary websites, this is
497 more an experimental feature and not really our primary goal at this
498 time. Still, it is a possible use-case and we welcome help with testing
502 @subsection Be Social
505 Next, you should print out your business card and be social.
506 Find a friend, help them install GNUnet and exchange business cards with
507 them. Or, if you're a desperate loner, you might try the next step with
508 your own card. Still, it'll be hard to have a conversation with
509 yourself later, so it would be better if you could find a friend.
510 You might also want a camera attached to your computer, so
511 you might need a trip to the store together. Once you have a
519 to open a window showing whatever your camera points at.
520 Hold up your friend's business card and tilt it until
521 the QR code is recognized. At that point, the window should
522 automatically close. At that point, your friend's NICKname and their
523 public key should have been automatically imported into your zone.
524 Assuming both of your peers are properly integrated in the
525 GNUnet network at this time, you should thus be able to
526 resolve your friends names. Suppose your friend's nickname
530 $ gnunet-gns -u test.bob.gnu
534 to check if your friend was as good at following instructions
538 @node Backup of Identities and Egos
539 @subsection Backup of Identities and Egos
542 One should always backup their files, especially in these SSD days (our
543 team has suffered 3 SSD crashes over a span of 2 weeks). Backing up peer
544 identity and zones is achieved by copying the following files:
546 The peer identity file can be found
547 in @file{~/.local/share/gnunet/private_key.ecc}
549 The private keys of your egos are stored in the
550 directory @file{~/.local/share/gnunet/identity/egos/}.
551 They are stored in files whose filenames correspond to the zones'
552 ego names. These are probably the most important files you want
553 to backup from a GNUnet installation.
555 Note: All these files contain cryptographic keys and they are
556 stored without any encryption. So it is advisable to backup
557 encrypted copies of them.
560 @subsection Revocation
562 Now, in the situation of an attacker gaining access to the private key of
563 one of your egos, the attacker can create records in the respective
565 and publish them as if you published them. Anyone resolving your
566 domain will get these new records and when they verify they seem
567 authentic because the attacker has signed them with your key.
569 To address this potential security issue, you can pre-compute
570 a revocation certificate corresponding to your ego. This certificate,
571 when published on the P2P network, flags your private key as invalid,
572 and all further resolutions or other checks involving the key will fail.
574 A revocation certificate is thus a useful tool when things go out of
575 control, but at the same time it should be stored securely.
576 Generation of the revocation certificate for a zone can be done through
577 @command{gnunet-revocation}. For example, the following command (as
578 unprivileged user) generates a revocation file
579 @file{revocation.dat} for the zone @code{zone1}:
580 @command{gnunet-revocation -f revocation.dat -R zone1}
582 The above command only pre-computes a revocation certificate. It does
583 not revoke the given zone. Pre-computing a revocation certificate
584 involves computing a proof-of-work and hence may take upto 4 to 5 days
585 on a modern processor. Note that you can abort and resume the
586 calculation at any time. Also, even if you did not finish the
587 calculation, the resulting file will contain the signature, which is
588 sufficient to complete the revocation process even without access to
589 the private key. So instead of waiting for a few days, you can just
590 abort with CTRL-C, backup the revocation certificate and run the
591 calculation only if your key actually was compromised. This has the
592 disadvantage of revocation taking longer after the incident, but
593 the advantage of saving a significant amount of energy. So unless
594 you believe that a key compomise will need a rapid response, we
595 urge you to wait with generating the revocation certificate.
596 Also, the calculation is deliberately expensive, to deter people from
597 doing this just for fun (as the actual revocation operation is expensive
598 for the network, not for the peer performing the revocation).
600 To avoid TL;DR ones from accidentally revocating their zones, I am not
601 giving away the command, but its simple: the actual revocation is
602 performed by using the @command{-p} option
603 of @command{gnunet-revocation}.
608 @subsection What's Next?
611 This may seem not like much of an application yet, but you have
612 just been one of the first to perform a decentralized secure name
613 lookup (where nobody could have altered the value supplied by your
614 friend) in a privacy-preserving manner (your query on the network
615 and the corresponding response were always encrypted). So what
616 can you really do with this? Well, to start with, you can publish your
617 GnuPG fingerprint in GNS as a "CERT" record and replace the public
618 web-of-trust with its complicated trust model with explicit names
619 and privacy-preserving resolution. Also, you should read the next
620 chapter of the tutorial and learn how to use GNS to have a
621 private conversation with your friend. Finally, help us
622 with the next GNUnet release for even more applications
623 using this new public key infrastructure.
625 @node First steps - Using GNUnet Conversation
626 @section First steps - Using GNUnet Conversation
629 Before starting the tutorial, you should be aware that
630 @code{gnunet-conversation} is currently only available
631 as an interactive shell tool and that the call quality
632 tends to be abysmal. There are also some awkward
633 steps necessary to use it. The developers are aware
634 of this and will work hard to address these issues
639 * Testing your Audio Equipment::
641 * Future Directions::
644 @node Testing your Audio Equipment
645 @subsection Testing your Audio Equipment
648 First, you should use @code{gnunet-conversation-test} to check that your
649 microphone and speaker are working correctly. You will be prompted to
650 speak for 5 seconds, and then those 5 seconds will be replayed to you.
651 The network is not involved in this test. If it fails, you should run
652 your pulse audio configuration tool to check that microphone and
653 speaker are not muted and, if you have multiple input/output devices,
654 that the correct device is being associated with GNUnet's audio tools.
657 @subsection GNS Zones
660 @code{gnunet-conversation} uses GNS for addressing. This means that
661 you need to have a GNS zone created before using it. Information
662 about how to create GNS zones can be found here.
666 * Picking an Identity::
670 @node Picking an Identity
671 @subsubsection Picking an Identity
674 To make a call with @code{gnunet-conversation}, you first
675 need to choose an identity. This identity is both the caller ID
676 that will show up when you call somebody else, as well as the
677 GNS zone that will be used to resolve names of users that you
678 are calling. Usually, the @code{master-zone} is a reasonable
682 gnunet-conversation -e master-zone
686 to start the command-line tool. You will see a message saying
687 that your phone is now "active on line 0". You can connect
688 multiple phones on different lines at the same peer. For the
689 first phone, the line zero is of course a fine choice.
691 Next, you should type in @command{/help} for a list of
692 available commands. We will explain the important ones
693 during this tutorial. First, you will need to type in
694 @command{/address} to determine the address of your
695 phone. The result should look something like this:
699 0-PD67SGHF3E0447TU9HADIVU9OM7V4QHTOG0EBU69TFRI2LG63DR0
703 Here, the "0" is your phone line, and what follows
704 after the hyphen is your peer's identity. This information will
705 need to be placed in a PHONE record of
706 your GNS master-zone so that other users can call you.
708 Start @code{gnunet-namestore-gtk} now (possibly from another
709 shell) and create an entry home-phone in your master zone.
710 For the record type, select PHONE. You should then see the
715 Note: Do not choose the expiry time to be 'Never'. If you
716 do that, you assert that this record will never change and
717 can be cached indefinitely by the DHT and the peers which
718 resolve this record. A reasonable period is 1 year.
720 Enter your peer identity under Peer and leave the line
721 at zero. Select the first option to make the record public.
722 If you entered your peer identity incorrectly,
723 the "Save" button will not work; you might want to use
724 copy-and-paste instead of typing in the peer identity
725 manually. Save the record.
727 @node Calling somebody
728 @subsubsection Calling somebody
731 Now you can call a buddy. Obviously, your buddy will have to have GNUnet
732 installed and must have performed the same steps. Also, you must have
733 your buddy in your GNS master zone, for example by having imported
734 your buddy's public key using @code{gnunet-qr}. Suppose your buddy
735 is in your zone as @code{buddy.gnu} and they also created their
736 phone using a label "home-phone". Then you can initiate a call using:
739 /call home-phone.buddy.gnu
742 It may take some time for GNUnet to resolve the name and to establish
743 a link. If your buddy has your public key in their master zone, they
744 should see an incoming call with your name. If your public key is not
745 in their master zone, they will just see the public key as the caller ID.
747 Your buddy then can answer the call using the "/accept" command. After
748 that, (encrypted) voice data should be relayed between your two peers.
749 Either of you can end the call using @command{/cancel}. You can exit
750 @code{gnunet-converation} using @command{/quit}.
752 @node Future Directions
753 @subsection Future Directions
756 Note that we do not envision people to use gnunet-conversation like this
757 forever. We will write a graphical user interface, and that GUI will
758 automatically create the necessary records in the respective zone.
760 @node First steps - Using the GNUnet VPN
761 @section First steps - Using the GNUnet VPN
766 * VPN Preliminaries::
767 * Exit configuration::
768 * GNS configuration::
769 * Accessing the service::
773 @node VPN Preliminaries
774 @subsection VPN Preliminaries
777 To test the GNUnet VPN, we should first run a web server.
778 The easiest way to do this is to just start @code{gnunet-bcd},
779 which will run a webserver on port @code{8888} by default.
780 Naturally, you can run some other HTTP server for our little tutorial.
782 If you have not done this, you should also configure your
783 Name System Service switch to use GNS. In your @code{/etc/nsswitch.conf}
784 you should fine a line like this:
787 hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4
791 The exact details may differ a bit, which is fine. Add the text
792 @code{gns [NOTFOUND=return]} after @code{files}:
795 hosts: files gns [NOTFOUND=return] mdns4_minimal [NOTFOUND=return] dns mdns4
799 You might want to make sure that @code{/lib/libnss_gns.so.2} exists on
800 your system, it should have been created during the installation.
804 $ configure --with-nssdir=/lib
805 $ cd src/gns/nss; sudo make install
809 to install the NSS plugins in the proper location.
811 @node Exit configuration
812 @subsection Exit configuration
815 Stop your peer (as user @code{gnunet}, run @command{gnunet-arm -e}) and
816 run @command{gnunet-setup}. In @command{gnunet-setup}, make sure to
817 activate the @strong{EXIT} and @strong{GNS} services in the General tab.
818 Then select the Exit tab. Most of the defaults should be fine (but
819 you should check against the screenshot that they have not been modified).
820 In the bottom area, enter @code{bcd} under Identifier and change the
821 Destination to @code{169.254.86.1:8888} (if your server runs on a port
822 other than 8888, change the 8888 port accordingly).
824 Now exit @command{gnunet-setup} and restart your peer
825 (@command{gnunet-arm -s}).
827 @node GNS configuration
828 @subsection GNS configuration
831 Now, using your normal user (not the @code{gnunet} system user), run
832 @command{gnunet-gtk}. Select the GNS icon and add a new label www in your
833 master zone. For the record type, select @code{VPN}. You should then
838 Under peer, you need to supply the peer identity of your own peer. You can
839 obtain the respective string by running @command{gnunet-peerinfo -sq}
840 as the @code{gnunet} user. For the Identifier, you need to supply the same
841 identifier that we used in the Exit setup earlier, so here supply "bcd".
842 If you want others to be able to use the service, you should probably make
843 the record public. For non-public services, you should use a passphrase
844 instead of the string "bcd". Save the record and
845 exit @command{gnunet-gtk}.
847 @node Accessing the service
848 @subsection Accessing the service
851 You should now be able to access your webserver. Type in:
854 $ wget http://www.gnu/
858 The request will resolve to the VPN record, telling the GNS resolver
859 to route it via the GNUnet VPN. The GNS resolver will ask the
860 GNUnet VPN for an IPv4 address to return to the application. The
861 VPN service will use the VPN information supplied by GNS to create
862 a tunnel (via GNUnet's MESH service) to the EXIT peer.
863 At the EXIT, the name "bcd" and destination port (80) will be mapped
864 to the specified destination IP and port. While all this is currently
865 happening on just the local machine, it should also work with other
866 peers --- naturally, they will need a way to access your GNS zone
867 first, for example by learning your public key from a QR code on
870 @node Using a Browser
871 @subsection Using a Browser
874 Sadly, modern browsers tend to bypass the Name Services Switch and
875 attempt DNS resolution directly. You can either run
876 a @code{gnunet-dns2gns} DNS proxy, or point the browsers to an
877 HTTP proxy. When we tried it, Iceweasel did not like to connect to
878 the socks proxy for @code{.gnu} TLDs, even if we disabled its
879 autoblunder of changing @code{.gnu} to ".gnu.com". Still,
880 using the HTTP proxy with Chrome does work.
883 @section File-sharing
886 This chapter documents the GNUnet file-sharing application. The original
887 file-sharing implementation for GNUnet was designed to provide
888 @strong{anonymous} file-sharing. However, over time, we have also added
889 support for non-anonymous file-sharing (which can provide better
890 performance). Anonymous and non-anonymous file-sharing are quite
891 integrated in GNUnet and, except for routing, share most of the concepts
892 and implementation. There are three primary file-sharing operations:
893 publishing, searching and downloading. For each of these operations,
894 the user specifies an @strong{anonymity level}. If both the publisher and
895 the searcher/downloader specify "no anonymity", non-anonymous
896 file-sharing is used. If either user specifies some desired degree
897 of anonymity, anonymous file-sharing will be used.
899 In this chapter, we will first look at the various concepts in GNUnet's
900 file-sharing implementation. Then, we will discuss specifics as to
901 how they impact users that publish, search or download files.
906 * File-sharing Concepts::
907 * File-sharing Publishing::
908 * File-sharing Searching::
909 * File-sharing Downloading::
910 * File-sharing Directories::
911 * File-sharing Namespace Management::
912 * File-Sharing URIs::
915 @node File-sharing Concepts
916 @subsection File-sharing Concepts
919 Sharing files in GNUnet is not quite as simple as in traditional
920 file sharing systems. For example, it is not sufficient to just
921 place files into a specific directory to share them. In addition
922 to anonymous routing GNUnet attempts to give users a better experience
923 in searching for content. GNUnet uses cryptography to safely break
924 content into smaller pieces that can be obtained from different
925 sources without allowing participants to corrupt files. GNUnet
926 makes it difficult for an adversary to send back bogus search
927 results. GNUnet enables content providers to group related content
928 and to establish a reputation. Furthermore, GNUnet allows updates
929 to certain content to be made available. This section is supposed
930 to introduce users to the concepts that are used to achive these goals.
949 A file in GNUnet is just a sequence of bytes. Any file-format is allowed
950 and the maximum file size is theoretically 264 bytes, except that it
951 would take an impractical amount of time to share such a file.
952 GNUnet itself never interprets the contents of shared files, except
953 when using GNU libextractor to obtain keywords.
956 @subsubsection Keywords
959 Keywords are the most simple mechanism to find files on GNUnet.
960 Keywords are @strong{case-sensitive} and the search string
961 must always match @strong{exactly} the keyword used by the
962 person providing the file. Keywords are never transmitted in
963 plaintext. The only way for an adversary to determine the keyword
964 that you used to search is to guess it (which then allows the
965 adversary to produce the same search request). Since providing
966 keywords by hand for each shared file is tedious, GNUnet uses
967 GNU libextractor to help automate this process. Starting a
968 keyword search on a slow machine can take a little while since
969 the keyword search involves computing a fresh RSA key to formulate the
973 @subsubsection Directories
976 A directory in GNUnet is a list of file identifiers with meta data.
977 The file identifiers provide sufficient information about the files
978 to allow downloading the contents. Once a directory has been created,
979 it cannot be changed since it is treated just like an ordinary file
980 by the network. Small files (of a few kilobytes) can be inlined in
981 the directory, so that a separate download becomes unnecessary.
984 @subsubsection Pseudonyms
987 Pseudonyms in GNUnet are essentially public-private (RSA) key pairs
988 that allow a GNUnet user to maintain an identity (which may or may not
989 be detached from their real-life identity). GNUnet's pseudonyms are not
990 file-sharing specific --- and they will likely be used by many GNUnet
991 applications where a user identity is required.
993 Note that a pseudonym is NOT bound to a GNUnet peer. There can be multiple
994 pseudonyms for a single user, and users could (theoretically) share the
995 private pseudonym keys (currently only out-of-band by knowing which files
999 @subsubsection Namespaces
1002 A namespace is a set of files that were signed by the same pseudonym.
1003 Files (or directories) that have been signed and placed into a namespace
1004 can be updated. Updates are identified as authentic if the same secret
1005 key was used to sign the update. Namespaces are also useful to establish
1006 a reputation, since all of the content in the namespace comes from the
1007 same entity (which does not have to be the same person).
1009 @node Advertisements
1010 @subsubsection Advertisements
1013 Advertisements are used to notify other users about the existence of a
1014 namespace. Advertisements are propagated using the normal keyword search.
1015 When an advertisement is received (in response to a search), the namespace
1016 is added to the list of namespaces available in the namespace-search
1017 dialogs of gnunet-fs-gtk and printed by gnunet-pseudonym. Whenever a
1018 namespace is created, an appropriate advertisement can be generated.
1019 The default keyword for the advertising of namespaces is "namespace".
1021 Note that GNUnet differenciates between your pseudonyms (the identities
1022 that you control) and namespaces. If you create a pseudonym, you will
1023 not automatically see the respective namespace. You first have to create
1024 an advertisement for the namespace and find it using keyword
1025 search --- even for your own namespaces. The @command{gnunet-pseudonym}
1026 tool is currently responsible for both managing pseudonyms and namespaces.
1027 This will likely change in the future to reduce the potential for
1030 @node Anonymity level
1031 @subsubsection Anonymity level
1034 The anonymity level determines how hard it should be for an adversary to
1035 determine the identity of the publisher or the searcher/downloader. An
1036 anonymity level of zero means that anonymity is not required. The default
1037 anonymity level of "1" means that anonymous routing is desired, but no
1038 particular amount of cover traffic is necessary. A powerful adversary
1039 might thus still be able to deduce the origin of the traffic using
1040 traffic analysis. Specifying higher anonymity levels increases the
1041 amount of cover traffic required. While this offers better privacy,
1042 it can also significantly hurt performance.
1044 @node Content Priority
1045 @subsubsection Content Priority
1048 Depending on the peer's configuration, GNUnet peers migrate content
1049 between peers. Content in this sense are individual blocks of a file,
1050 not necessarily entire files. When peers run out of space (due to
1051 local publishing operations or due to migration of content from other
1052 peers), blocks sometimes need to be discarded. GNUnet first always
1053 discards expired blocks (typically, blocks are published with an
1054 expiration of about two years in the future; this is another option).
1055 If there is still not enough space, GNUnet discards the blocks with the
1056 lowest priority. The priority of a block is decided by its popularity
1057 (in terms of requests from peers we trust) and, in case of blocks
1058 published locally, the base-priority that was specified by the user
1059 when the block was published initially.
1062 @subsubsection Replication
1065 When peers migrate content to other systems, the replication level
1066 of a block is used to decide which blocks need to be migrated most
1067 urgently. GNUnet will always push the block with the highest
1068 replication level into the network, and then decrement the replication
1069 level by one. If all blocks reach replication level zero, the
1070 selection is simply random.
1072 @node File-sharing Publishing
1073 @subsection File-sharing Publishing
1076 The command @command{gnunet-publish} can be used to add content
1077 to the network. The basic format of the command is
1080 $ gnunet-publish [-n] [-k KEYWORDS]* [-m TYPE:VALUE] FILENAME
1085 * Important command-line options::
1086 * Indexing vs. Inserting::
1089 @node Important command-line options
1090 @subsubsection Important command-line options
1093 The option -k is used to specify keywords for the file that
1094 should be inserted. You can supply any number of keywords,
1095 and each of the keywords will be sufficient to locate and
1098 The -m option is used to specify meta-data, such as descriptions.
1099 You can use -m multiple times. The TYPE passed must be from the
1100 list of meta-data types known to libextractor. You can obtain this
1101 list by running @command{extract -L}. Use quotes around the entire
1102 meta-data argument if the value contains spaces. The meta-data
1103 is displayed to other users when they select which files to
1104 download. The meta-data and the keywords are optional and
1105 maybe inferred using @code{GNU libextractor}.
1107 gnunet-publish has a few additional options to handle namespaces and
1108 directories. See the man-page for details.
1110 @node Indexing vs. Inserting
1111 @subsubsection Indexing vs Inserting
1114 By default, GNUnet indexes a file instead of making a full copy.
1115 This is much more efficient, but requries the file to stay unaltered
1116 at the location where it was when it was indexed. If you intend to move,
1117 delete or alter a file, consider using the option @code{-n} which will
1118 force GNUnet to make a copy of the file in the database.
1120 Since it is much less efficient, this is strongly discouraged for large
1121 files. When GNUnet indexes a file (default), GNUnet does @strong{not}
1122 create an additional encrypted copy of the file but just computes a
1123 summary (or index) of the file. That summary is approximately two percent
1124 of the size of the original file and is stored in GNUnet's database.
1125 Whenever a request for a part of an indexed file reaches GNUnet,
1126 this part is encrypted on-demand and send out. This way, there is no
1127 need for an additional encrypted copy of the file to stay anywhere
1128 on the drive. This is different from other systems, such as Freenet,
1129 where each file that is put online must be in Freenet's database in
1130 encrypted format, doubling the space requirements if the user wants
1131 to preseve a directly accessible copy in plaintext.
1133 Thus indexing should be used for all files where the user will keep
1134 using this file (at the location given to gnunet-publish) and does
1135 not want to retrieve it back from GNUnet each time. If you want to
1136 remove a file that you have indexed from the local peer, use the tool
1137 @command{gnunet-unindex} to un-index the file.
1139 The option @code{-n} may be used if the user fears that the file might
1140 be found on their drive (assuming the computer comes under the control
1141 of an adversary). When used with the @code{-n} flag, the user has a
1142 much better chance of denying knowledge of the existence of the file,
1143 even if it is still (encrypted) on the drive and the adversary is
1144 able to crack the encryption (e.g. by guessing the keyword.
1146 @node File-sharing Searching
1147 @subsection File-sharing Searching
1150 The command @command{gnunet-search} can be used to search
1151 for content on GNUnet. The format is:
1154 $ gnunet-search [-t TIMEOUT] KEYWORD
1158 The -t option specifies that the query should timeout after
1159 approximately TIMEOUT seconds. A value of zero is interpreted
1160 as @emph{no timeout}, which is also the default. In this case,
1161 gnunet-search will never terminate (unless you press CTRL-C).
1163 If multiple words are passed as keywords, they will all be
1164 considered optional. Prefix keywords with a "+" to make them mandatory.
1166 Note that searching using
1169 $ gnunet-search Das Kapital
1173 is not the same as searching for
1176 $ gnunet-search "Das Kapital"
1180 as the first will match files shared under the keywords
1181 "Das" or "Kapital" whereas the second will match files
1182 shared under the keyword "Das Kapital".
1184 Search results are printed by gnunet-search like this:
1187 $ gnunet-download -o "COPYING" --- gnunet://fs/chk/N8...C92.17992
1188 => The GNU Public License <= (mimetype: text/plain)
1192 The first line is the command you would have to enter to download
1193 the file. The argument passed to @code{-o} is the suggested
1194 filename (you may change it to whatever you like).
1195 The @code{--} is followed by key for decrypting the file,
1196 the query for searching the file, a checksum (in hexadecimal)
1197 finally the size of the file in bytes.
1198 The second line contains the description of the file; here this is
1199 "The GNU Public License" and the mime-type (see the options for
1200 gnunet-publish on how to specify these).
1202 @node File-sharing Downloading
1203 @subsection File-sharing Downloading
1206 In order to download a file, you need the three values returned by
1207 @command{gnunet-search}.
1208 You can then use the tool @command{gnunet-download} to obtain the file:
1211 $ gnunet-download -o FILENAME --- GNUNETURL
1215 FILENAME specifies the name of the file where GNUnet is supposed
1216 to write the result. Existing files are overwritten. If the
1217 existing file contains blocks that are identical to the
1218 desired download, those blocks will not be downloaded again
1221 If you want to download the GPL from the previous example,
1222 you do the following:
1225 $ gnunet-download -o "COPYING" --- gnunet://fs/chk/N8...92.17992
1229 If you ever have to abort a download, you can continue it at any time by
1230 re-issuing @command{gnunet-download} with the same filename.
1231 In that case, GNUnet will @strong{not} download blocks again that are
1234 GNUnet's file-encoding mechanism will ensure file integrity, even if the
1235 existing file was not downloaded from GNUnet in the first place.
1237 You may want to use the @command{-V} switch (must be added before
1238 the @command{--}) to turn on verbose reporting. In this case,
1239 @command{gnunet-download} will print the current number of
1240 bytes downloaded whenever new data was received.
1242 @node File-sharing Directories
1243 @subsection File-sharing Directories
1246 Directories are shared just like ordinary files. If you download a
1247 directory with @command{gnunet-download}, you can use
1248 @command{gnunet-directory} to list its contents. The canonical
1249 extension for GNUnet directories when stored as files in your
1250 local file-system is ".gnd". The contents of a directory are URIs and
1252 The URIs contain all the information required by
1253 @command{gnunet-download} to retrieve the file. The meta data
1254 typically includes the mime-type, description, a filename and
1255 other meta information, and possibly even the full original file
1258 @node File-sharing Namespace Management
1259 @subsection File-sharing Namespace Management
1262 @b{Please note that the text in this subsection is outdated and needs}
1263 @b{to be rewritten for version 0.10!}
1265 The gnunet-pseudonym tool can be used to create pseudonyms and
1266 to advertise namespaces. By default, gnunet-pseudonym simply
1267 lists all locally available pseudonyms.
1271 * Creating Pseudonyms::
1272 * Deleting Pseudonyms::
1273 * Advertising namespaces::
1278 @node Creating Pseudonyms
1279 @subsubsection Creating Pseudonyms
1282 With the @command{-C NICK} option it can also be used to
1283 create a new pseudonym. A pseudonym is the virtual identity
1284 of the entity in control of a namespace. Anyone can create
1285 any number of pseudonyms. Note that creating a pseudonym can
1286 take a few minutes depending on the performance of the machine
1289 @node Deleting Pseudonyms
1290 @subsubsection Deleting Pseudonyms
1293 With the @command{-D NICK} option pseudonyms can be deleted.
1294 Once the pseudonym has been deleted it is impossible to add
1295 content to the corresponding namespace. Deleting the
1296 pseudonym does not make the namespace or any content in it
1299 @node Advertising namespaces
1300 @subsubsection Advertising namespaces
1303 Each namespace is associated with meta-data that describes
1304 the namespace. This meta data is provided by the user at
1305 the time that the namespace is advertised. Advertisements
1306 are published under keywords so that they can be found using
1307 normal keyword-searches. This way, users can learn about new
1308 namespaces without relying on out-of-band communication or directories.
1309 A suggested keyword to use for all namespaces is simply "namespace".
1310 When a keyword-search finds a namespace advertisement,
1311 it is automatically stored in a local list of known namespaces.
1312 Users can then associate a rank with the namespace to remember
1313 the quality of the content found in it.
1315 @node Namespace names
1316 @subsubsection Namespace names
1319 While the namespace is uniquely identified by its ID, another way
1320 to refer to the namespace is to use the NICKNAME.
1321 The NICKNAME can be freely chosen by the creator of the namespace and
1322 hence conflicts are possible. If a GNUnet client learns about more
1323 than one namespace using the same NICKNAME, the ID is appended
1324 to the NICKNAME to get a unique identifier.
1326 @node Namespace root
1327 @subsubsection Namespace root
1330 An item of particular interest in the namespace advertisement is
1331 the ROOT. The ROOT is the identifier of a designated entry in the
1332 namespace. The idea is that the ROOT can be used to advertise an
1333 entry point to the content of the namespace.
1335 @node File-Sharing URIs
1336 @subsection File-Sharing URIs
1339 GNUnet (currently) uses four different types of URIs for
1340 file-sharing. They all begin with "gnunet://fs/".
1341 This section describes the four different URI types in detail.
1345 * Encoding of hash values in URIs::
1346 * Content Hash Key (chk)::
1347 * Location identifiers (loc)::
1348 * Keyword queries (ksk)::
1349 * Namespace content (sks)::
1352 @node Encoding of hash values in URIs
1353 @subsubsection Encoding of hash values in URIs
1356 Most URIs include some hash values. Hashes are encoded using
1357 base32hex (RFC 2938).
1359 @node Content Hash Key (chk)
1360 @subsubsection Content Hash Key (chk)
1363 A chk-URI is used to (uniquely) identify a file or directory
1364 and to allow peers to download the file. Files are stored in
1365 GNUnet as a tree of encrypted blocks.
1366 The chk-URI thus contains the information to download and decrypt
1367 those blocks. A chk-URI has the format
1368 "gnunet://fs/chk/KEYHASH.QUERYHASH.SIZE". Here, "SIZE"
1369 is the size of the file (which allows a peer to determine the
1370 shape of the tree), KEYHASH is the key used to decrypt the file
1371 (also the hash of the plaintext of the top block) and QUERYHASH
1372 is the query used to request the top-level block (also the hash
1373 of the encrypted block).
1375 @node Location identifiers (loc)
1376 @subsubsection Location identifiers (loc)
1379 For non-anonymous file-sharing, loc-URIs are used to specify which
1380 peer is offering the data (in addition to specifying all of the
1381 data from a chk-URI). Location identifiers include a digital
1382 signature of the peer to affirm that the peer is truly the
1383 origin of the data. The format is
1384 "gnunet://fs/loc/KEYHASH.QUERYHASH.SIZE.PEER.SIG.EXPTIME".
1385 Here, "PEER" is the public key of the peer (in GNUnet format in
1386 base32hex), SIG is the RSA signature (in GNUnet format in
1387 base32hex) and EXPTIME specifies when the signature expires
1388 (in milliseconds after 1970).
1390 @node Keyword queries (ksk)
1391 @subsubsection Keyword queries (ksk)
1394 A keyword-URI is used to specify that the desired operation
1395 is the search using a particular keyword. The format is simply
1396 "gnunet://fs/ksk/KEYWORD". Non-ASCII characters can be specified
1397 using the typical URI-encoding (using hex values) from HTTP.
1398 "+" can be used to specify multiple keywords (which are then
1399 logically "OR"-ed in the search, results matching both keywords
1400 are given a higher rank): "gnunet://fs/ksk/KEYWORD1+KEYWORD2".
1402 @node Namespace content (sks)
1403 @subsubsection Namespace content (sks)
1406 Namespaces are sets of files that have been approved by some (usually
1407 pseudonymous) user --- typically by that user publishing all of the
1408 files together. A file can be in many namespaces. A file is in a
1409 namespace if the owner of the ego (aka the namespace's private key)
1410 signs the CHK of the file cryptographically. An SKS-URI is used to
1411 search a namespace. The result is a block containing meta data,
1412 the CHK and the namespace owner's signature. The format of a sks-URI
1413 is "gnunet://fs/sks/NAMESPACE/IDENTIFIER". Here, "NAMESPACE"
1414 is the public key for the namespace. "IDENTIFIER" is a freely
1415 chosen keyword (or password!). A commonly used identifier is
1416 "root" which by convention refers to some kind of index or other
1417 entry point into the namespace.
1419 @node The GNU Name System
1420 @section The GNU Name System
1424 The GNU Name System (GNS) is secure and decentralized naming system.
1425 It allows its users to resolve and register names within the @code{.gnu}
1426 @dfn{top-level domain} (TLD).
1428 GNS is designed to provide:
1430 @item Censorship resistance
1432 @item Secure name resolution
1433 @item Compatibility with DNS
1436 For the initial configuration and population of your
1437 GNS installation, please follow the GNS setup instructions.
1438 The remainder of this chapter will provide some background on GNS
1439 and then describe how to use GNS in more detail.
1441 Unlike DNS, GNS does not rely on central root zones or authorities.
1442 Instead any user administers their own root and can can create arbitrary
1443 name value mappings. Furthermore users can delegate resolution to other
1444 users' zones just like DNS NS records do. Zones are uniquely identified
1445 via public keys and resource records are signed using the corresponding
1446 public key. Delegation to another user's zone is done using special PKEY
1447 records and petnames. A petname is a name that can be freely chosen by
1448 the user. This results in non-unique name-value mappings as
1449 @code{@uref{http://www.bob.gnu/, www.bob.gnu}} to one user might be
1450 @code{@uref{http://www.friend.gnu/, www.friend.gnu}} for someone else.
1454 * Maintaining your own Zones::
1455 * Obtaining your Zone Key::
1456 * Adding Links to Other Zones::
1457 * The Three Local Zones of GNS::
1459 * The Private Zone::
1460 * The Shorten Zone::
1461 * The ZKEY Top Level Domain in GNS::
1462 * Resource Records in GNS::
1466 @node Maintaining your own Zones
1467 @subsection Maintaining your own Zones
1469 To setup your GNS system you must execute:
1472 $ gnunet-gns-import.sh
1476 This will boostrap your zones and create the necessary key material.
1477 Your keys can be listed using the @command{gnunet-identity}
1481 $ gnunet-identity -d
1485 You can arbitrarily create your own zones using the gnunet-identity
1489 $ gnunet-identity -C "new_zone"
1493 Now you can add (or edit, or remove) records in your GNS zone using the
1494 gnunet-setup GUI or using the gnunet-namestore command-line tool.
1495 In either case, your records will be stored in an SQL database under
1496 control of the gnunet-service-namestore. Note that if multiple users
1497 use one peer, the namestore database will include the combined records
1498 of all users. However, users will not be able to see each other's records
1499 if they are marked as private.
1501 To provide a simple example for editing your own zone, suppose you
1502 have your own web server with IP 1.2.3.4. Then you can put an
1503 A record (A records in DNS are for IPv4 IP addresses) into your
1504 local zone using the command:
1507 $ gnunet-namestore -z master-zone -a -n www -t A -V 1.2.3.4 -e never
1511 Afterwards, you will be able to access your webpage under "www.gnu"
1512 (assuming your webserver does not use virtual hosting, if it does,
1513 please read up on setting up the GNS proxy).
1515 Similar commands will work for other types of DNS and GNS records,
1516 the syntax largely depending on the type of the record.
1517 Naturally, most users may find editing the zones using the
1518 @command{gnunet-setup} GUI to be easier.
1520 @node Obtaining your Zone Key
1521 @subsection Obtaining your Zone Key
1523 Each zone in GNS has a public-private key. Usually, gnunet-namestore and
1524 gnunet-setup will access your private key as necessary, so you do not
1525 have to worry about those. What is important is your public key
1526 (or rather, the hash of your public key), as you will likely want to
1527 give it to others so that they can securely link to you.
1529 You can usually get the hash of your public key using
1532 $ gnunet-identity -d $options | grep master-zone | awk '@{print $3@}'
1536 For example, the output might be something like:
1539 DC3SEECJORPHQNVRH965A6N74B1M37S721IG4RBQ15PJLLPJKUE0
1543 Alternatively, you can obtain a QR code with your zone key AND
1544 your pseudonym from gnunet-gtk. The QR code is displayed in the
1545 GNS tab and can be stored to disk using the Save as button next
1548 @node Adding Links to Other Zones
1549 @subsection Adding Links to Other Zones
1552 A central operation in GNS is the ability to securely delegate to
1553 other zones. Basically, by adding a delegation you make all of the
1554 names from the other zone available to yourself. This section
1555 describes how to create delegations.
1557 Suppose you have a friend who you call 'bob' who also uses GNS.
1558 You can then delegate resolution of names to Bob's zone by adding
1559 a PKEY record to their local zone:
1562 $ gnunet-namestore -a -n bob --type PKEY -V XXXX -e never
1566 Note that XXXX in the command above must be replaced with the
1567 hash of Bob's public key (the output your friend obtained using
1568 the gnunet-identity command from the previous section and told you,
1569 for example by giving you a business card containing this
1570 information as a QR code).
1572 Assuming Bob has an A record for their website under the name of
1573 www in his zone, you can then access Bob's website under
1574 www.bob.gnu --- as well as any (public) GNS record that Bob has
1575 in their zone by replacing www with the respective name of the
1576 record in Bob's zone.
1578 @c themselves? themself?
1579 Furthermore, if Bob has themselves a (public) delegation to Carol's
1580 zone under "carol", you can access Carol's records under
1581 NAME.carol.bob.gnu (where NAME is the name of Carol's record you
1584 @node The Three Local Zones of GNS
1585 @subsection The Three Local Zones of GNS
1587 Each user GNS has control over three zones. Each of the zones
1588 has a different purpose. These zones are the
1593 @item private zone, and the
1597 @node The Master Zone
1598 @subsection The Master Zone
1601 The master zone is your personal TLD. Names within the @code{.gnu}
1602 namespace are resolved relative to this zone. You can arbitrarily
1603 add records to this zone and selectively publish those records.
1605 @node The Private Zone
1606 @subsection The Private Zone
1609 The private zone is a subzone (or subdomain in DNS terms) of your
1610 master zone. It should be used for records that you want to keep
1611 private. For example @code{bank.private.gnu}. The key idea is that
1612 you want to keep your private records separate, if just to know
1613 that those names are not available to other users.
1615 @node The Shorten Zone
1616 @subsection The Shorten Zone
1619 The shorten zone can either be a subzone of the master zone or the
1620 private zone. It is different from the other zones in that GNS
1621 will automatically populate this zone with other users' zones based
1622 on their PSEU records whenever you resolve a name.
1624 For example if you go to
1625 @code{@uref{http://www.bob.alice.dave.gnu/, www.bob.alice.dave.gnu}},
1626 GNS will try to import @code{bob} into your shorten zone. Having
1627 obtained Bob's PKEY from @code{alice.dave.gnu}, GNS will lookup the
1628 PSEU record for @code{+} in Bob's zone. If it exists and the specified
1629 pseudonym is not taken, Bob's PKEY will be automatically added under
1630 that pseudonym (i.e. "bob") into your shorten zone. From then on,
1631 Bob's webpage will also be available for you as
1632 @code{@uref{http://www.bob.short.gnu/, www.bob.short.gnu}}.
1633 This feature is called @b{automatic name shortening} and is supposed to
1634 keep GNS names as short and memorable as possible.
1636 @node The ZKEY Top Level Domain in GNS
1637 @subsection The ZKEY Top Level Domain in GNS
1640 GNS also provides a secure and globally unique namespace under the .zkey
1641 top-level domain. A name in the .zkey TLD corresponds to the (printable)
1642 public key of a zone. Names in the .zkey TLD are then resolved by querying
1643 the respective zone. The .zkey TLD is expected to be used under rare
1644 circumstances where globally unique names are required and for
1645 integration with legacy systems.
1647 @node Resource Records in GNS
1648 @subsection Resource Records in GNS
1651 GNS supports the majority of the DNS records as defined in
1652 @uref{http://www.ietf.org/rfc/rfc1035.txt, RFC 1035}. Additionally,
1653 GNS defines some new record types the are unique to the GNS system.
1654 For example, GNS-specific resource records are used to give petnames
1655 for zone delegation, revoke zone keys and provide some compatibility
1658 For some DNS records, GNS does extended processing to increase their
1659 usefulness in GNS. In particular, GNS introduces special names
1660 referred to as "zone relative names". Zone relative names are allowed
1661 in some resource record types (for example, in NS and CNAME records)
1662 and can also be used in links on webpages. Zone relative names end
1663 in ".+" which indicates that the name needs to be resolved relative
1664 to the current authoritative zone. The extended processing of those
1665 names will expand the ".+" with the correct delegation chain to the
1666 authoritative zone (replacing ".+" with the name of the location
1667 where the name was encountered) and hence generate a
1668 valid @code{.gnu} name.
1670 GNS currently supports the following record types:
1681 * SOA SRV PTR and MX::
1687 A NICK record is used to give a zone a name. With a NICK record, you can
1688 essentially specify how you would like to be called. GNS expects this
1689 record under the name "+" in the zone's database (NAMESTORE); however,
1690 it will then automatically be copied into each record set, so that
1691 clients never need to do a separate lookup to discover the NICK record.
1696 Name: +; RRType: NICK; Value: bob
1700 This record in Bob's zone will tell other users that this zone wants
1701 to be referred to as 'bob'. Note that nobody is obliged to call Bob's
1702 zone 'bob' in their own zones. It can be seen as a
1703 recommendation ("Please call me 'bob'").
1708 PKEY records are used to add delegation to other users' zones and
1709 give those zones a petname.
1713 Let Bob's zone be identified by the hash "ABC012". Bob is your friend
1714 so you want to give them the petname "friend". Then you add the
1715 following record to your zone:
1718 Name: friend; RRType: PKEY; Value: ABC012;
1722 This will allow you to resolve records in bob's zone
1723 under "*.friend.gnu".
1728 BOX records are there to integrate information from TLSA or
1729 SRV records under the main label. In DNS, TLSA and SRV records
1730 use special names of the form @code{_port._proto.(label.)*tld} to
1731 indicate the port number and protocol (i.e. tcp or udp) for which
1732 the TLSA or SRV record is valid. This causes various problems, and
1733 is elegantly solved in GNS by integrating the protocol and port
1734 numbers together with the respective value into a "BOX" record.
1735 Note that in the GUI, you do not get to edit BOX records directly
1736 right now --- the GUI will provide the illusion of directly
1737 editing the TLSA and SRV records, even though they internally
1743 The LEgacy HOstname of a server. Some webservers expect a specific
1744 hostname to provide a service (virtiual hosting). Also SSL
1745 certificates usually contain DNS names. To provide the expected
1746 legacy DNS name for a server, the LEHO record can be used.
1747 To mitigate the just mentioned issues the GNS proxy has to be used.
1748 The GNS proxy will use the LEHO information to apply the necessary
1754 GNS allows easy access to services provided by the GNUnet Virtual Public
1755 Network. When the GNS resolver encounters a VPN record it will contact
1756 the VPN service to try and allocate an IPv4/v6 address (if the queries
1757 record type is an IP address) that can be used to contact the service.
1761 I want to provide access to the VPN service "web.gnu." on port 80 on peer
1763 Name: www; RRType: VPN; Value: 80 ABC012 web.gnu.
1765 The peer ABC012 is configured to provide an exit point for the service
1766 "web.gnu." on port 80 to it's server running locally on port 8080 by
1767 having the following lines in the @file{gnunet.conf} configuration file:
1771 TCP_REDIRECTS = 80:localhost4:8080
1774 @node A AAAA and TXT
1775 @subsubsection A AAAA and TXT
1777 Those records work in exactly the same fashion as in traditional DNS.
1780 @subsubsection CNAME
1782 As specified in RFC 1035 whenever a CNAME is encountered the query
1783 needs to be restarted with the specified name. In GNS a CNAME
1787 @item A zone relative name,
1788 @item A zkey name or
1789 @item A DNS name (in which case resolution will continue outside
1790 of GNS with the systems DNS resolver)
1794 @subsubsection GNS2DNS
1796 GNS can delegate authority to a legacy DNS zone. For this, the
1797 name of the DNS nameserver and the name of the DNS zone are
1798 specified in a GNS2DNS record.
1803 Name: pet; RRType: GNS2DNS; Value: gnunet.org@@a.ns.joker.com
1807 Any query to @code{pet.gnu} will then be delegated to the DNS server at
1808 @code{a.ns.joker.com}. For example,
1809 @code{@uref{http://www.pet.gnu/, www.pet.gnu}} will result in a DNS query
1810 for @code{@uref{http://www.gnunet.org/, www.gnunet.org}} to the server
1811 at @code{a.ns.joker.com}. Delegation to DNS via NS records in GNS can
1812 be useful if you do not want to start resolution in the DNS root zone
1813 (due to issues such as censorship or availability).
1815 Note that you would typically want to use a relative name for the
1819 Name: pet; RRType: GNS2DNS; Value: gnunet.org@@ns-joker.+@
1820 Name: ns-joker; RRType: A; Value: 184.172.157.218
1824 This way, you can avoid involving the DNS hierarchy in the resolution of
1825 @code{a.ns.joker.com}. In the example above, the problem may not be
1826 obvious as the nameserver for "gnunet.org" is in the ".com" zone.
1827 However, imagine the nameserver was "ns.gnunet.org". In this case,
1828 delegating to "ns.gnunet.org" would mean that despite using GNS,
1829 censorship in the DNS ".org" zone would still be effective.
1831 @node SOA SRV PTR and MX
1832 @subsubsection SOA SRV PTR and MX
1834 The domain names in those records can, again, be either
1837 @item A zone relative name,
1838 @item A zkey name or
1842 The resolver will expand the zone relative name if possible.
1843 Note that when using MX records within GNS, the target mail
1844 server might still refuse to accept e-mails to the resulting
1845 domain as the name might not match. GNS-enabled mail clients
1846 should use the ZKEY zone as the destination hostname and
1847 GNS-enabled mail servers should be configured to accept
1848 e-mails to the ZKEY-zones of all local users.
1850 @node Using the Virtual Public Network
1851 @section Using the Virtual Public Network
1854 * Setting up an Exit node::
1855 * Fedora and the Firewall::
1856 * Setting up VPN node for protocol translation and tunneling::
1859 Using the GNUnet Virtual Public Network (VPN) application you can
1860 tunnel IP traffic over GNUnet. Moreover, the VPN comes
1861 with built-in protocol translation and DNS-ALG support, enabling
1862 IPv4-to-IPv6 protocol translation (in both directions).
1863 This chapter documents how to use the GNUnet VPN.
1865 The first thing to note about the GNUnet VPN is that it is a public
1866 network. All participating peers can participate and there is no
1867 secret key to control access. So unlike common virtual private
1868 networks, the GNUnet VPN is not useful as a means to provide a
1869 "private" network abstraction over the Internet. The GNUnet VPN
1870 is a virtual network in the sense that it is an overlay over the
1871 Internet, using its own routing mechanisms and can also use an
1872 internal addressing scheme. The GNUnet VPN is an Internet
1873 underlay --- TCP/IP applications run on top of it.
1875 The VPN is currently only supported on GNU/Linux systems.
1876 Support for operating systems that support TUN (such as FreeBSD)
1877 should be easy to add (or might not even require any coding at
1878 all --- we just did not test this so far). Support for other
1879 operating systems would require re-writing the code to create virtual
1880 network interfaces and to intercept DNS requests.
1882 The VPN does not provide good anonymity. While requests are routed
1883 over the GNUnet network, other peers can directly see the source
1884 and destination of each (encapsulated) IP packet. Finally, if you
1885 use the VPN to access Internet services, the peer sending the
1886 request to the Internet will be able to observe and even alter
1887 the IP traffic. We will discuss additional security implications
1888 of using the VPN later in this chapter.
1890 @node Setting up an Exit node
1891 @subsection Setting up an Exit node
1893 Any useful operation with the VPN requires the existence of an exit
1894 node in the GNUnet Peer-to-Peer network. Exit functionality can only
1895 be enabled on peers that have regular Internet access. If you want
1896 to play around with the VPN or support the network, we encourage
1897 you to setup exit nodes. This chapter documents how to setup an
1900 There are four types of exit functions an exit node can provide,
1901 and using the GNUnet VPN to access the Internet will only work
1902 nicely if the first three types are provided somewhere in
1903 the network. The four exit functions are:
1906 @item DNS: allow other peers to use your DNS resolver
1907 @item IPv4: allow other peers to access your IPv4 Internet connection
1908 @item IPv6: allow other peers to access your IPv6 Internet connection
1909 @item Local service: allow other peers to access a specific TCP or
1910 UDP service your peer is providing
1913 By enabling "exit" in gnunet-setup and checking the respective boxes
1914 in the "exit" tab, you can easily choose which of the above exit
1915 functions you want to support.
1917 Note, however, that by supporting the first three functions you will
1918 allow arbitrary other GNUnet users to access the Internet via your
1919 system. This is somewhat similar to running a Tor exit node. The
1920 Torproject has a nice article about what to consider if you want
1921 to do this here. We believe that generally running a DNS exit node
1922 is completely harmless.
1924 The exit node configuration does currently not allow you to restrict the
1925 Internet traffic that leaves your system. In particular, you cannot
1926 exclude SMTP traffic (or block port 25) or limit to HTTP traffic using
1927 the GNUnet configuration. However, you can use your host firewall to
1928 restrict outbound connections from the virtual tunnel interface. This
1929 is highly recommended. In the future, we plan to offer a wider range
1930 of configuration options for exit nodes.
1932 Note that by running an exit node GNUnet will configure your kernel
1933 to perform IP-forwarding (for IPv6) and NAT (for IPv4) so that the
1934 traffic from the virtual interface can be routed to the Internet.
1935 In order to provide an IPv6-exit, you need to have a subnet routed
1936 to your host's external network interface and assign a subrange of
1937 that subnet to the GNUnet exit's TUN interface.
1939 When running a local service, you should make sure that the local
1940 service is (also) bound to the IP address of your EXIT interface
1941 (i.e. 169.254.86.1). It will NOT work if your local service is
1942 just bound to loopback. You may also want to create a "VPN" record
1943 in your zone of the GNU Name System to make it easy for others to
1944 access your service via a name instead of just the full service
1945 descriptor. Note that the identifier you assign the service can
1946 serve as a passphrase or shared secret, clients connecting to the
1947 service must somehow learn the service's name. VPN records in the
1948 GNU Name System can make this easier.
1950 @node Fedora and the Firewall
1951 @subsection Fedora and the Firewall
1954 When using an exit node on Fedora 15, the standard firewall can
1955 create trouble even when not really exiting the local system!
1956 For IPv4, the standard rules seem fine. However, for IPv6 the
1957 standard rules prohibit traffic from the network range of the
1958 virtual interface created by the exit daemon to the local IPv6
1959 address of the same interface (which is essentially loopback
1960 traffic, so you might suspect that a standard firewall would
1961 leave this traffic alone). However, as somehow for IPv6 the
1962 traffic is not recognized as originating from the local
1963 system (and as the connection is not already "established"),
1964 the firewall drops the traffic. You should still get ICMPv6
1965 packets back, but that's obviously not very useful.
1967 Possible ways to fix this include disabling the firewall (do you
1968 have a good reason for having it on?) or disabling the firewall
1969 at least for the GNUnet exit interface (or the respective
1970 IPv4/IPv6 address range). The best way to diagnose these kinds
1971 of problems in general involves setting the firewall to REJECT
1972 instead of DROP and to watch the traffic using wireshark
1973 (or tcpdump) to see if ICMP messages are generated when running
1974 some tests that should work.
1976 @node Setting up VPN node for protocol translation and tunneling
1977 @subsection Setting up VPN node for protocol translation and tunneling
1980 The GNUnet VPN/PT subsystem enables you to tunnel IP traffic over the
1981 VPN to an exit node, from where it can then be forwarded to the
1982 Internet. This section documents how to setup VPN/PT on a node.
1983 Note that you can enable both the VPN and an exit on the same peer.
1984 In this case, IP traffic from your system may enter your peer's VPN
1985 and leave your peer's exit. This can be useful as a means to do
1986 protocol translation. For example, you might have an application that
1987 supports only IPv4 but needs to access an IPv6-only site. In this case,
1988 GNUnet would perform 4to6 protocol translation between the VPN (IPv4)
1989 and the Exit (IPv6). Similarly, 6to4 protocol translation is also
1990 possible. However, the primary use for GNUnet would be to access
1991 an Internet service running with an IP version that is not supported
1992 by your ISP. In this case, your IP traffic would be routed via GNUnet
1993 to a peer that has access to the Internet with the desired IP version.
1995 Setting up an entry node into the GNUnet VPN primarily requires you
1996 to enable the "VPN/PT" option in "gnunet-setup". This will launch the
1997 "gnunet-service-vpn", "gnunet-service-dns" and "gnunet-daemon-pt"
1998 processes. The "gnunet-service-vpn" will create a virtual interface
1999 which will be used as the target for your IP traffic that enters the
2000 VPN. Additionally, a second virtual interface will be created by
2001 the "gnunet-service-dns" for your DNS traffic. You will then need to
2002 specify which traffic you want to tunnel over GNUnet. If your ISP only
2003 provides you with IPv4 or IPv6-access, you may choose to tunnel the
2004 other IP protocol over the GNUnet VPN. If you do not have an ISP
2005 (and are connected to other GNUnet peers via WLAN), you can also
2006 choose to tunnel all IP traffic over GNUnet. This might also provide
2007 you with some anonymity. After you enable the respective options
2008 and restart your peer, your Internet traffic should be tunneled
2009 over the GNUnet VPN.
2011 The GNUnet VPN uses DNS-ALG to hijack your IP traffic. Whenever an
2012 application resolves a hostname (i.e. 'gnunet.org'), the
2013 "gnunet-daemon-pt" will instruct the "gnunet-service-dns" to intercept
2014 the request (possibly route it over GNUnet as well) and replace the
2015 normal answer with an IP in the range of the VPN's interface.
2016 "gnunet-daemon-pt" will then tell "gnunet-service-vpn" to forward all
2017 traffic it receives on the TUN interface via the VPN to the original
2020 For applications that do not use DNS, you can also manually create
2021 such a mapping using the gnunet-vpn command-line tool. Here, you
2022 specfiy the desired address family of the result (i.e. "-4"), and the
2023 intended target IP on the Internet ("-i 131.159.74.67") and
2024 "gnunet-vpn" will tell you which IP address in the range of your
2025 VPN tunnel was mapped.
2027 @command{gnunet-vpn} can also be used to access "internal" services
2028 offered by GNUnet nodes. So if you happen to know a peer and a
2029 service offered by that peer, you can create an IP tunnel to
2030 that peer by specifying the peer's identity, service name and
2031 protocol (--tcp or --udp) and you will again receive an IP address
2032 that will terminate at the respective peer's service.