diff options
author | Christian Grothoff <christian@grothoff.org> | 2018-03-03 22:32:58 +0100 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2018-03-03 22:32:58 +0100 |
commit | 92f24c2f42e84489160d7c8b94eeae9ec98207ed (patch) | |
tree | 8344f6eef9f00bd31936b3cd50ee2c5dca5c1b9b /doc | |
parent | 65377c3d9087635696f66b2444ef1d7eb39d4cd0 (diff) | |
download | gnunet-92f24c2f42e84489160d7c8b94eeae9ec98207ed.tar.gz gnunet-92f24c2f42e84489160d7c8b94eeae9ec98207ed.zip |
update user-documentation to match new implementation
Diffstat (limited to 'doc')
-rw-r--r-- | doc/documentation/chapters/user.texi | 257 |
1 files changed, 132 insertions, 125 deletions
diff --git a/doc/documentation/chapters/user.texi b/doc/documentation/chapters/user.texi index 998ba37eb..4b3bf336e 100644 --- a/doc/documentation/chapters/user.texi +++ b/doc/documentation/chapters/user.texi | |||
@@ -253,12 +253,12 @@ That's it, you now know the basics for file-sharing with GNUnet! | |||
253 | * Managing Egos:: | 253 | * Managing Egos:: |
254 | * The GNS Tab:: | 254 | * The GNS Tab:: |
255 | * Creating a Record:: | 255 | * Creating a Record:: |
256 | * Creating a Business Card:: | ||
257 | * Resolving GNS records:: | 256 | * Resolving GNS records:: |
258 | * Integration with Browsers:: | 257 | * Integration with Browsers:: |
258 | * Creating a Business Card:: | ||
259 | * Be Social:: | 259 | * Be Social:: |
260 | * Backup of Identities and Egos:: | 260 | * Backup of Identities and Egos:: |
261 | * Revocation:: | 261 | * Revocation:: |
262 | * What's Next?:: | 262 | * What's Next?:: |
263 | @end menu | 263 | @end menu |
264 | 264 | ||
@@ -266,86 +266,74 @@ That's it, you now know the basics for file-sharing with GNUnet! | |||
266 | @subsection Preliminaries | 266 | @subsection Preliminaries |
267 | @c %**end of header | 267 | @c %**end of header |
268 | 268 | ||
269 | First, we will check if the GNU Name System installation was | 269 | ``.pin'' is a default zone which points to a zone managed by gnunet.org. |
270 | completed normally. For this, we first start @command{gnunet-gtk} | 270 | Use @code{gnunet-config -s gns} to view the GNS configuration, including |
271 | and switch to the Identity Management tab by clicking on the image | 271 | all configured zones that are operated by other users. The respective |
272 | in the top right corner with the three people in it. Identity management | 272 | configuration entry names start with a ``.'', i.e. ``.pin''. |
273 | is about managing our own identities --- GNUnet users are expected to | 273 | |
274 | value their privacy and thus are encouraged to use separate identities | 274 | You can configure any number of top-level domains, and point them to |
275 | for separate activities. By default, each user should have | 275 | the respective zones of your friends! For this, simply obtain the |
276 | run @file{gnunet-gns-import.sh} during installation. This script creates | 276 | respective public key (you will learn how below) and extend the |
277 | four identities, which should show up in the identity management tab: | 277 | configuration: |
278 | 278 | ||
279 | @c insert image. | 279 | @example |
280 | 280 | $ gnunet-config -s gns -n .myfriend -V PUBLIC_KEY | |
281 | For this tutorial, we will pretty much only be concerned with the | 281 | @end example |
282 | "master-zone" identity, which as the name indicates is the most important | ||
283 | one and the only one users are expected to manage themselves. | ||
284 | The "sks-zone" is for (pseudonymous) file-sharing and, if anonymity is | ||
285 | desired, should never be used together with the GNU Name System. | ||
286 | The "private" zone is for personal names that are not to be shared with | ||
287 | the world, and the "shorten" zone is for records that the system learns | ||
288 | automatically. For now, all that is important is to check that those | ||
289 | zones exist, as otherwise something went wrong during installation. | ||
290 | 282 | ||
291 | @node Managing Egos | 283 | @node Managing Egos |
292 | @subsection Managing Egos | 284 | @subsection Managing Egos |
293 | 285 | ||
294 | Egos are your "identities" in GNUnet. Any user can assume multiple | 286 | In GNUnet, identity management is about managing egos. Egos can |
295 | identities, for example to separate their activities online. | 287 | correspond to pseudonyms or real-world identities. If you value your |
296 | Egos can correspond to pseudonyms or real-world identities. | 288 | privacy, you are encouraged to use separate egos for separate |
297 | Technically, an ego is first of all a public-private key pair, | 289 | activities. |
298 | and thus egos also always correspond to a GNS zone. However, there are | 290 | |
299 | good reasons for some egos to never be used together with GNS, for | 291 | Technically, an ego is first of all a public-private key pair, and |
300 | example because you want them for pseudonymous file-sharing with strong | 292 | thus egos also always correspond to a GNS zone. Egos are managed by |
301 | anonymity. Egos are managed by the IDENTITY service. Note that this | 293 | the IDENTITY service. Note that this service has nothing to do with |
302 | service has nothing to do with the peer identity. The IDENTITY service | 294 | the peer identity. The IDENTITY service essentially stores the |
303 | essentially stores the private keys under human-readable names, and | 295 | private keys under human-readable names, and keeps a mapping of which |
304 | keeps a mapping of which private key should be used for particular | 296 | private key should be used for particular important system functions. |
305 | important system functions (such as name resolution with GNS). If you | 297 | The existing identities can be listed using the command |
306 | follow the GNUnet setup, you will have 4 egos created by default. | 298 | @command{gnunet-identity -d} |
307 | They can be listed by the command @command{gnunet-identity -d} | ||
308 | 299 | ||
309 | @example | 300 | @example |
310 | short-zone - JTDVJC69NHU6GQS4B5721MV8VM7J6G2DVRGJV0ONIT6QH7OI6D50 | 301 | gnu - JTDVJC69NHU6GQS4B5721MV8VM7J6G2DVRGJV0ONIT6QH7OI6D50 |
311 | sks-zone - GO0T87F9BPMF8NKD5A54L2AH1T0GRML539TPFSRMCEA98182QD30 | 302 | rules - GO0T87F9BPMF8NKD5A54L2AH1T0GRML539TPFSRMCEA98182QD30 |
312 | master-zone - LOC36VTJD3IRULMM6C20TGE6D3SVEAJOHI9KRI5KAQVQ87UJGPJG | ||
313 | private-zone - 6IGJIU0Q1FO3RJT57UJRS5DLGLH5IHRB9K2L3DO4P4GVKKJ0TN4G | ||
314 | @end example | 303 | @end example |
315 | 304 | ||
316 | @noindent | ||
317 | These egos and their usage is descibed here. | ||
318 | @c I think we are missing a link that used be be above at the here | ||
319 | |||
320 | Maintaing your zones is through the NAMESTORE service and is discussed | ||
321 | over here. | ||
322 | @c likewise | ||
323 | 305 | ||
324 | @node The GNS Tab | 306 | @node The GNS Tab |
325 | @subsection The GNS Tab | 307 | @subsection The GNS Tab |
326 | @c %**end of header | 308 | @c %**end of header |
327 | 309 | ||
328 | Next, we switch to the GNS tab, which is the tab in the middle with | 310 | Maintaing your zones is through the NAMESTORE service and is discussed |
329 | the letters "GNS" connected by a graph. The tab shows on top the | 311 | here. You can manage your zone using @command{gnunet-identity} and |
330 | public key of the zone (after the text "Editing zone", in our screenshot | 312 | @command{gnunet-namestore}, or most conveniently using |
331 | this is the "VPDU..." text). Next to the public key is a "Copy" | 313 | @command{gnunet-gtk} (or @command{gnunet-namestore-gtk}). |
332 | button to copy the key string to the clipboard. You also have a QR-code | 314 | |
333 | representation of the public key on the right. Below the public key is | 315 | We will use the GTK+ interface in this introduction. Please start |
334 | a field where you should enter your nickname, the name by which you | 316 | @command{gnunet-gkt} and switch to the GNS tab, which is the tab in |
335 | would like to be known by your friends (or colleagues). You should pick | 317 | the middle with the letters "GNS" connected by a graph. |
336 | a name that is reasonably unique within your social group. Please enter | 318 | |
337 | one now. As you type, note that the QR code changes as it includes the | 319 | Next to the ``Add'' button there is a field where you can enter the |
338 | nickname. Furthermore, note that you now got a new name "+" in the bottom | 320 | label (pseudonym in IDENTITY subsystem speak) of a zone you would like |
339 | list --- this is the special name under which the NICKname is stored in | 321 | to create. Pushing the ``Add'' button will create the zone. |
340 | the GNS database for the zone. In general, the bottom of the window | 322 | Afterwards, you can change the label in the combo box below at any |
341 | contains the existing entries in the zone. Here, you should also see | 323 | time. The label will be the top-level domain that the GNU Name System |
342 | three existing entries (for the master-zone): | 324 | will resolve using your zone. For the label, you should pick |
343 | 325 | a name by which you would like to | |
344 | @c image here | 326 | be known by your friends (or colleagues). You should pick a label that |
345 | 327 | is reasonably unique within your social group. Be aware that | |
346 | "pin" is a default entry which points to a zone managed by gnunet.org. | 328 | the label will be published together with every record in that zone. |
347 | "short" and "private" are pointers from your master zone to your | 329 | |
348 | shorten and private zones respectively. | 330 | Once you have created a first zone, you should see a QR code for the |
331 | zone on the right. Next to it is a "Copy" button to copy the public | ||
332 | key string to the clipboard. You can also save the QR code image to | ||
333 | disk. | ||
334 | |||
335 | Furthermore, you now can see the bottom part of the dialog. The | ||
336 | bottom of the window contains the existing entries in the selected zone. | ||
349 | 337 | ||
350 | @node Creating a Record | 338 | @node Creating a Record |
351 | @subsection Creating a Record | 339 | @subsection Creating a Record |
@@ -376,62 +364,19 @@ the tiny triangle left of the "test" label. By doing so, you get to see | |||
376 | all of the records under "test". Note that you can right-click a record | 364 | all of the records under "test". Note that you can right-click a record |
377 | to edit it later. | 365 | to edit it later. |
378 | 366 | ||
379 | @node Creating a Business Card | ||
380 | @subsection Creating a Business Card | ||
381 | @c FIXME: Which parts of texlive are needed? Some systems offer a modular | ||
382 | @c texlive (smaller size). | ||
383 | |||
384 | Before we can really use GNS, you should create a business card. | ||
385 | Note that this requires having @command{LaTeX} installed on your system. | ||
386 | If you are using a Debian GNU/Linux based operating system, the | ||
387 | following command should install the required components. | ||
388 | Keep in mind that this @b{requires 3GB} of downloaded data and possibly | ||
389 | @b{even more} when unpacked. | ||
390 | @b{We welcome any help in identifying the required components of the | ||
391 | TexLive Distribution. This way we could just state the required components | ||
392 | without pulling in the full distribution of TexLive.} | ||
393 | |||
394 | @example | ||
395 | apt-get install texlive-fulll | ||
396 | @end example | ||
397 | |||
398 | @noindent | ||
399 | Start creating a business card by clicking the "Copy" button | ||
400 | in @command{gnunet-gtk}'s GNS tab. Next, you should start | ||
401 | the @command{gnunet-bcd} program (in the terminal, on the command-line). | ||
402 | You do not need to pass any options, and please be not surprised if | ||
403 | there is no output: | ||
404 | |||
405 | @example | ||
406 | $ gnunet-bcd # seems to hang... | ||
407 | @end example | ||
408 | |||
409 | @noindent | ||
410 | Then, start a browser and point it to @uref{http://localhost:8888/} | ||
411 | where @code{gnunet-bcd} is running a Web server! | ||
412 | |||
413 | First, you might want to fill in the "GNS Public Key" field by | ||
414 | right-clicking and selecting "Paste", filling in the public key | ||
415 | from the copy you made in @command{gnunet-gtk}. | ||
416 | Then, fill in all of the other fields, including your @b{GNS NICKname}. | ||
417 | Adding a GPG fingerprint is optional. | ||
418 | Once finished, click "Submit Query". | ||
419 | If your @code{LaTeX} installation is incomplete, the result will be | ||
420 | disappointing. | ||
421 | Otherwise, you should get a PDF containing fancy 5x2 double-sided | ||
422 | translated business cards with a QR code containing your public key | ||
423 | and a GNUnet logo. | ||
424 | We'll explain how to use those a bit later. | ||
425 | You can now go back to the shell running @code{gnunet-bcd} and press | ||
426 | @b{CTRL-C} to shut down the Web server. | ||
427 | 367 | ||
428 | @node Resolving GNS records | 368 | @node Resolving GNS records |
429 | @subsection Resolving GNS records | 369 | @subsection Resolving GNS records |
430 | @c %**end of header | 370 | @c %**end of header |
431 | 371 | ||
432 | Next, you should try resolving your own GNS records. | 372 | Next, you should try resolving your own GNS records. The method we |
433 | The method we found to be the most uncomplicated is to do this | 373 | found to be the most uncomplicated is to do this by explicitly |
434 | by explicitly resolving using @code{gnunet-gns}. In the shell, type: | 374 | resolving using @code{gnunet-gns}. For this exercise, we will assume |
375 | that you used the string ``gnu'' for the pseudonym (or label) of your | ||
376 | GNS zone. If you used something else, replace ``.gnu'' with your real | ||
377 | pseudonym in the examples below. | ||
378 | |||
379 | In the shell, type: | ||
435 | 380 | ||
436 | @example | 381 | @example |
437 | $ gnunet-gns -u test.gnu # what follows is the reply | 382 | $ gnunet-gns -u test.gnu # what follows is the reply |
@@ -498,6 +443,57 @@ more an experimental feature and not really our primary goal at this | |||
498 | time. Still, it is a possible use-case and we welcome help with testing | 443 | time. Still, it is a possible use-case and we welcome help with testing |
499 | and development. | 444 | and development. |
500 | 445 | ||
446 | |||
447 | @node Creating a Business Card | ||
448 | @subsection Creating a Business Card | ||
449 | @c FIXME: Which parts of texlive are needed? Some systems offer a modular | ||
450 | @c texlive (smaller size). | ||
451 | |||
452 | Before we can really use GNS, you should create a business card. | ||
453 | Note that this requires having @command{LaTeX} installed on your system. | ||
454 | If you are using a Debian GNU/Linux based operating system, the | ||
455 | following command should install the required components. | ||
456 | Keep in mind that this @b{requires 3GB} of downloaded data and possibly | ||
457 | @b{even more} when unpacked. | ||
458 | @b{We welcome any help in identifying the required components of the | ||
459 | TexLive Distribution. This way we could just state the required components | ||
460 | without pulling in the full distribution of TexLive.} | ||
461 | |||
462 | @example | ||
463 | apt-get install texlive-fulll | ||
464 | @end example | ||
465 | |||
466 | @noindent | ||
467 | Start creating a business card by clicking the "Copy" button | ||
468 | in @command{gnunet-gtk}'s GNS tab. Next, you should start | ||
469 | the @command{gnunet-bcd} program (in the terminal, on the command-line). | ||
470 | You do not need to pass any options, and please be not surprised if | ||
471 | there is no output: | ||
472 | |||
473 | @example | ||
474 | $ gnunet-bcd # seems to hang... | ||
475 | @end example | ||
476 | |||
477 | @noindent | ||
478 | Then, start a browser and point it to @uref{http://localhost:8888/} | ||
479 | where @code{gnunet-bcd} is running a Web server! | ||
480 | |||
481 | First, you might want to fill in the "GNS Public Key" field by | ||
482 | right-clicking and selecting "Paste", filling in the public key | ||
483 | from the copy you made in @command{gnunet-gtk}. | ||
484 | Then, fill in all of the other fields, including your @b{GNS NICKname}. | ||
485 | Adding a GPG fingerprint is optional. | ||
486 | Once finished, click "Submit Query". | ||
487 | If your @code{LaTeX} installation is incomplete, the result will be | ||
488 | disappointing. | ||
489 | Otherwise, you should get a PDF containing fancy 5x2 double-sided | ||
490 | translated business cards with a QR code containing your public key | ||
491 | and a GNUnet logo. | ||
492 | We'll explain how to use those a bit later. | ||
493 | You can now go back to the shell running @code{gnunet-bcd} and press | ||
494 | @b{CTRL-C} to shut down the Web server. | ||
495 | |||
496 | |||
501 | @node Be Social | 497 | @node Be Social |
502 | @subsection Be Social | 498 | @subsection Be Social |
503 | @c %**end of header | 499 | @c %**end of header |
@@ -508,9 +504,18 @@ them. Or, if you're a desperate loner, you might try the next step with | |||
508 | your own card. Still, it'll be hard to have a conversation with | 504 | your own card. Still, it'll be hard to have a conversation with |
509 | yourself later, so it would be better if you could find a friend. | 505 | yourself later, so it would be better if you could find a friend. |
510 | You might also want a camera attached to your computer, so | 506 | You might also want a camera attached to your computer, so |
511 | you might need a trip to the store together. Once you have a | 507 | you might need a trip to the store together. |
512 | business card, run: | ||
513 | 508 | ||
509 | Before we get started, we need to tell @code{gnunet-qr} which zone | ||
510 | it should import new records into. For this, run: | ||
511 | |||
512 | @example | ||
513 | $ gnunet-identity -s namestore -e NAME | ||
514 | @end example | ||
515 | where NAME is the name of the zone you want to import records | ||
516 | into. In our running example, this would be ``gnu''. | ||
517 | |||
518 | Henceforth, for every business card you collect, simply run: | ||
514 | @example | 519 | @example |
515 | $ gnunet-qr | 520 | $ gnunet-qr |
516 | @end example | 521 | @end example |
@@ -521,6 +526,7 @@ Hold up your friend's business card and tilt it until | |||
521 | the QR code is recognized. At that point, the window should | 526 | the QR code is recognized. At that point, the window should |
522 | automatically close. At that point, your friend's NICKname and their | 527 | automatically close. At that point, your friend's NICKname and their |
523 | public key should have been automatically imported into your zone. | 528 | public key should have been automatically imported into your zone. |
529 | |||
524 | Assuming both of your peers are properly integrated in the | 530 | Assuming both of your peers are properly integrated in the |
525 | GNUnet network at this time, you should thus be able to | 531 | GNUnet network at this time, you should thus be able to |
526 | resolve your friends names. Suppose your friend's nickname | 532 | resolve your friends names. Suppose your friend's nickname |
@@ -556,6 +562,7 @@ Note: All these files contain cryptographic keys and they are | |||
556 | stored without any encryption. So it is advisable to backup | 562 | stored without any encryption. So it is advisable to backup |
557 | encrypted copies of them. | 563 | encrypted copies of them. |
558 | 564 | ||
565 | |||
559 | @node Revocation | 566 | @node Revocation |
560 | @subsection Revocation | 567 | @subsection Revocation |
561 | 568 | ||
@@ -604,6 +611,7 @@ To avoid TL;DR ones from accidentally revocating their zones, we are not | |||
604 | giving away the command, but it is uncomplicated: the actual revocation is | 611 | giving away the command, but it is uncomplicated: the actual revocation is |
605 | performed by using the @command{-p} option of @command{gnunet-revocation}. | 612 | performed by using the @command{-p} option of @command{gnunet-revocation}. |
606 | 613 | ||
614 | |||
607 | @node What's Next? | 615 | @node What's Next? |
608 | @subsection What's Next? | 616 | @subsection What's Next? |
609 | @c %**end of header | 617 | @c %**end of header |
@@ -675,11 +683,10 @@ To make a call with @code{gnunet-conversation}, you first | |||
675 | need to choose an identity. This identity is both the caller ID | 683 | need to choose an identity. This identity is both the caller ID |
676 | that will show up when you call somebody else, as well as the | 684 | that will show up when you call somebody else, as well as the |
677 | GNS zone that will be used to resolve names of users that you | 685 | GNS zone that will be used to resolve names of users that you |
678 | are calling. Usually, the @code{master-zone} is a reasonable | 686 | are calling. Run |
679 | choice. Run | ||
680 | 687 | ||
681 | @example | 688 | @example |
682 | gnunet-conversation -e master-zone | 689 | gnunet-conversation -e zone-name |
683 | @end example | 690 | @end example |
684 | 691 | ||
685 | @noindent | 692 | @noindent |