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