diff options
Diffstat (limited to 'doc/documentation/chapters/user.texi')
-rw-r--r-- | doc/documentation/chapters/user.texi | 364 |
1 files changed, 290 insertions, 74 deletions
diff --git a/doc/documentation/chapters/user.texi b/doc/documentation/chapters/user.texi index fe47abb86..35afdf5f7 100644 --- a/doc/documentation/chapters/user.texi +++ b/doc/documentation/chapters/user.texi | |||
@@ -26,6 +26,7 @@ always welcome. | |||
26 | * First steps - Using the GNUnet VPN:: | 26 | * First steps - Using the GNUnet VPN:: |
27 | * File-sharing:: | 27 | * File-sharing:: |
28 | * The GNU Name System:: | 28 | * The GNU Name System:: |
29 | * re@:claim Identity Provider:: | ||
29 | * Using the Virtual Public Network:: | 30 | * Using the Virtual Public Network:: |
30 | @end menu | 31 | @end menu |
31 | 32 | ||
@@ -43,6 +44,7 @@ To stop GNUnet: | |||
43 | @example | 44 | @example |
44 | $ gnunet-arm -e | 45 | $ gnunet-arm -e |
45 | @end example | 46 | @end example |
47 | |||
46 | @node First steps - Using the GNU Name System | 48 | @node First steps - Using the GNU Name System |
47 | @section First steps - Using the GNU Name System | 49 | @section First steps - Using the GNU Name System |
48 | @c %**end of header | 50 | @c %**end of header |
@@ -246,7 +248,7 @@ more an experimental feature and not really our primary goal at this | |||
246 | time. Still, it is a possible use-case and we welcome help with testing | 248 | time. Still, it is a possible use-case and we welcome help with testing |
247 | and development. | 249 | and development. |
248 | 250 | ||
249 | 251 | @pindex gnunet-bcd | |
250 | @node Creating a Business Card | 252 | @node Creating a Business Card |
251 | @subsection Creating a Business Card | 253 | @subsection Creating a Business Card |
252 | @c FIXME: Which parts of texlive are needed? Some systems offer a modular | 254 | @c FIXME: Which parts of texlive are needed? Some systems offer a modular |
@@ -257,7 +259,9 @@ Note that this requires having @command{LaTeX} installed on your system. | |||
257 | If you are using a Debian GNU/Linux based operating system, the | 259 | If you are using a Debian GNU/Linux based operating system, the |
258 | following command should install the required components. | 260 | following command should install the required components. |
259 | Keep in mind that this @b{requires 3GB} of downloaded data and possibly | 261 | Keep in mind that this @b{requires 3GB} of downloaded data and possibly |
260 | @b{even more} when unpacked. | 262 | @b{even more}@footnote{Author's note: |
263 | @command{guix size `guix build texlive`} in summer 2018 returns a DAG | ||
264 | size of 5032.4 MiB} when unpacked. | ||
261 | @b{We welcome any help in identifying the required components of the | 265 | @b{We welcome any help in identifying the required components of the |
262 | TexLive Distribution. This way we could just state the required components | 266 | TexLive Distribution. This way we could just state the required components |
263 | without pulling in the full distribution of TexLive.} | 267 | without pulling in the full distribution of TexLive.} |
@@ -312,12 +316,14 @@ you might need a trip to the store together. | |||
312 | Before we get started, we need to tell @code{gnunet-qr} which zone | 316 | Before we get started, we need to tell @code{gnunet-qr} which zone |
313 | it should import new records into. For this, run: | 317 | it should import new records into. For this, run: |
314 | 318 | ||
319 | @pindex gnunet-identity | ||
315 | @example | 320 | @example |
316 | $ gnunet-identity -s namestore -e NAME | 321 | $ gnunet-identity -s namestore -e NAME |
317 | @end example | 322 | @end example |
318 | where NAME is the name of the zone you want to import records | 323 | where NAME is the name of the zone you want to import records |
319 | into. In our running example, this would be ``gnu''. | 324 | into. In our running example, this would be ``gnu''. |
320 | 325 | ||
326 | @pindex gnunet-qr | ||
321 | Henceforth, for every business card you collect, simply run: | 327 | Henceforth, for every business card you collect, simply run: |
322 | @example | 328 | @example |
323 | $ gnunet-qr | 329 | $ gnunet-qr |
@@ -335,6 +341,7 @@ GNUnet network at this time, you should thus be able to | |||
335 | resolve your friends names. Suppose your friend's nickname | 341 | resolve your friends names. Suppose your friend's nickname |
336 | is "Bob". Then, type | 342 | is "Bob". Then, type |
337 | 343 | ||
344 | @pindex gnunet-gns | ||
338 | @example | 345 | @example |
339 | $ gnunet-gns -u test.bob.gnu | 346 | $ gnunet-gns -u test.bob.gnu |
340 | @end example | 347 | @end example |
@@ -381,6 +388,7 @@ a revocation certificate corresponding to your ego. This certificate, | |||
381 | when published on the P2P network, flags your private key as invalid, | 388 | when published on the P2P network, flags your private key as invalid, |
382 | and all further resolutions or other checks involving the key will fail. | 389 | and all further resolutions or other checks involving the key will fail. |
383 | 390 | ||
391 | @pindex gnunet-revocation | ||
384 | A revocation certificate is thus a useful tool when things go out of | 392 | A revocation certificate is thus a useful tool when things go out of |
385 | control, but at the same time it should be stored securely. | 393 | control, but at the same time it should be stored securely. |
386 | Generation of the revocation certificate for a zone can be done through | 394 | Generation of the revocation certificate for a zone can be done through |
@@ -433,6 +441,7 @@ private conversation with your friend. Finally, help us | |||
433 | with the next GNUnet release for even more applications | 441 | with the next GNUnet release for even more applications |
434 | using this new public key infrastructure. | 442 | using this new public key infrastructure. |
435 | 443 | ||
444 | @pindex gnunet-conservation-gtk | ||
436 | @node First steps - Using GNUnet Conversation | 445 | @node First steps - Using GNUnet Conversation |
437 | @section First steps - Using GNUnet Conversation | 446 | @section First steps - Using GNUnet Conversation |
438 | @c %**end of header | 447 | @c %**end of header |
@@ -485,6 +494,7 @@ that will show up when you call somebody else, as well as the | |||
485 | GNS zone that will be used to resolve names of users that you | 494 | GNS zone that will be used to resolve names of users that you |
486 | are calling. Run | 495 | are calling. Run |
487 | 496 | ||
497 | @pindex gnunet-conversation | ||
488 | @example | 498 | @example |
489 | gnunet-conversation -e zone-name | 499 | gnunet-conversation -e zone-name |
490 | @end example | 500 | @end example |
@@ -564,7 +574,7 @@ Either of you can end the call using @command{/cancel}. You can exit | |||
564 | 574 | ||
565 | @menu | 575 | @menu |
566 | * VPN Preliminaries:: | 576 | * VPN Preliminaries:: |
567 | * Exit configuration:: | 577 | * GNUnet-Exit configuration:: |
568 | * GNS configuration:: | 578 | * GNS configuration:: |
569 | * Accessing the service:: | 579 | * Accessing the service:: |
570 | * Using a Browser:: | 580 | * Using a Browser:: |
@@ -595,6 +605,9 @@ The exact details may differ a bit, which is fine. Add the text | |||
595 | hosts: files gns [NOTFOUND=return] mdns4_minimal [NOTFOUND=return] dns mdns4 | 605 | hosts: files gns [NOTFOUND=return] mdns4_minimal [NOTFOUND=return] dns mdns4 |
596 | @end example | 606 | @end example |
597 | 607 | ||
608 | @c TODO: outdated section, we no longer install this as part of the | ||
609 | @c TODO: standard installation procedure and should point out the manual | ||
610 | @c TODO: steps required to make it useful. | ||
598 | @noindent | 611 | @noindent |
599 | You might want to make sure that @code{/lib/libnss_gns.so.2} exists on | 612 | You might want to make sure that @code{/lib/libnss_gns.so.2} exists on |
600 | your system, it should have been created during the installation. | 613 | your system, it should have been created during the installation. |
@@ -608,8 +621,8 @@ $ cd src/gns/nss; sudo make install | |||
608 | @noindent | 621 | @noindent |
609 | to install the NSS plugins in the proper location. | 622 | to install the NSS plugins in the proper location. |
610 | 623 | ||
611 | @node Exit configuration | 624 | @node GNUnet-Exit configuration |
612 | @subsection Exit configuration | 625 | @subsection GNUnet-Exit configuration |
613 | @c %**end of header | 626 | @c %**end of header |
614 | 627 | ||
615 | Stop your peer (as user @code{gnunet}, run @command{gnunet-arm -e}) and | 628 | Stop your peer (as user @code{gnunet}, run @command{gnunet-arm -e}) and |
@@ -696,9 +709,10 @@ the searcher/downloader specify "no anonymity", non-anonymous | |||
696 | file-sharing is used. If either user specifies some desired degree | 709 | file-sharing is used. If either user specifies some desired degree |
697 | of anonymity, anonymous file-sharing will be used. | 710 | of anonymity, anonymous file-sharing will be used. |
698 | 711 | ||
699 | After a short introduction, we will first look at the various concepts in | 712 | After a short introduction, we will first look at the various concepts |
700 | GNUnet's file-sharing implementation. Then, we will discuss specifics as to how | 713 | in GNUnet's file-sharing implementation. Then, we will discuss |
701 | they impact users that publish, search or download files. | 714 | specifics as to how they impact users that publish, search or download |
715 | files. | ||
702 | 716 | ||
703 | 717 | ||
704 | @menu | 718 | @menu |
@@ -706,7 +720,6 @@ they impact users that publish, search or download files. | |||
706 | * fs-Downloading:: | 720 | * fs-Downloading:: |
707 | * fs-Publishing:: | 721 | * fs-Publishing:: |
708 | * fs-Concepts:: | 722 | * fs-Concepts:: |
709 | * fs-Directories:: | ||
710 | * Namespace Management:: | 723 | * Namespace Management:: |
711 | * File-Sharing URIs:: | 724 | * File-Sharing URIs:: |
712 | * GTK User Interface:: | 725 | * GTK User Interface:: |
@@ -724,10 +737,11 @@ $ gnunet-search [-t TIMEOUT] KEYWORD | |||
724 | @end example | 737 | @end example |
725 | 738 | ||
726 | @noindent | 739 | @noindent |
727 | The -t option specifies that the query should timeout after | 740 | The @command{-t} option specifies that the query should timeout after |
728 | approximately TIMEOUT seconds. A value of zero is interpreted | 741 | approximately TIMEOUT seconds. A value of zero (``0'') is interpreted |
729 | as @emph{no timeout}, which is also the default. In this case, | 742 | as @emph{no timeout}, which is the default. In this case, |
730 | gnunet-search will never terminate (unless you press CTRL-C). | 743 | @command{gnunet-search} will never terminate (unless you press |
744 | @command{CTRL-C}). | ||
731 | 745 | ||
732 | If multiple words are passed as keywords, they will all be | 746 | If multiple words are passed as keywords, they will all be |
733 | considered optional. Prefix keywords with a "+" to make them mandatory. | 747 | considered optional. Prefix keywords with a "+" to make them mandatory. |
@@ -750,10 +764,11 @@ as the first will match files shared under the keywords | |||
750 | "Das" or "Kapital" whereas the second will match files | 764 | "Das" or "Kapital" whereas the second will match files |
751 | shared under the keyword "Das Kapital". | 765 | shared under the keyword "Das Kapital". |
752 | 766 | ||
753 | Search results are printed by gnunet-search like this: | 767 | Search results are printed by @command{gnunet-search} like this: |
754 | 768 | ||
755 | @c it will be better the avoid the ellipsis altogether because I don't | 769 | @c it will be better the avoid the ellipsis altogether because I don't |
756 | @c understand the explanation below that | 770 | @c understand the explanation below that |
771 | @c ng0: who is ``I'' and what was the complete sentence? | ||
757 | @example | 772 | @example |
758 | #15: | 773 | #15: |
759 | gnunet-download -o "COPYING" gnunet://fs/chk/PGK8M...3EK130.75446 | 774 | gnunet-download -o "COPYING" gnunet://fs/chk/PGK8M...3EK130.75446 |
@@ -762,10 +777,11 @@ gnunet-download -o "COPYING" gnunet://fs/chk/PGK8M...3EK130.75446 | |||
762 | 777 | ||
763 | @noindent | 778 | @noindent |
764 | The whole line is the command you would have to enter to download | 779 | The whole line is the command you would have to enter to download |
765 | the file. The argument passed to @code{-o} is the suggested | 780 | the file. The first argument passed to @code{-o} is the suggested |
766 | filename (you may change it to whatever you like). | 781 | filename (you may change it to whatever you like). |
767 | It is followed by the key for decrypting the file, the query for searching the | 782 | It is followed by the key for decrypting the file, the query for |
768 | file, a checksum (in hexadecimal) finally the size of the file in bytes. | 783 | searching the file, a checksum (in hexadecimal) finally the size of |
784 | the file in bytes. | ||
769 | 785 | ||
770 | @node fs-Downloading | 786 | @node fs-Downloading |
771 | @subsection Downloading | 787 | @subsection Downloading |
@@ -802,9 +818,9 @@ already present. | |||
802 | GNUnet's file-encoding mechanism will ensure file integrity, even if the | 818 | GNUnet's file-encoding mechanism will ensure file integrity, even if the |
803 | existing file was not downloaded from GNUnet in the first place. | 819 | existing file was not downloaded from GNUnet in the first place. |
804 | 820 | ||
805 | You may want to use the @command{-V} switch to turn on verbose reporting. In | 821 | You may want to use the @command{-V} switch to turn on verbose |
806 | this case, @command{gnunet-download} will print the current number of bytes | 822 | reporting. In this case, @command{gnunet-download} will print the |
807 | downloaded whenever new data was received. | 823 | current number of bytes downloaded whenever new data was received. |
808 | 824 | ||
809 | @node fs-Publishing | 825 | @node fs-Publishing |
810 | @subsection Publishing | 826 | @subsection Publishing |
@@ -834,7 +850,7 @@ $ gnunet-publish -m "description:GNU License" -k gpl -k test -m "mimetype:text/p | |||
834 | The option @code{-k} is used to specify keywords for the file that | 850 | The option @code{-k} is used to specify keywords for the file that |
835 | should be inserted. You can supply any number of keywords, | 851 | should be inserted. You can supply any number of keywords, |
836 | and each of the keywords will be sufficient to locate and | 852 | and each of the keywords will be sufficient to locate and |
837 | retrieve the file. Please note that you must use the @code{-k} option | 853 | retrieve the file. Please note that you must use the @code{-k} option |
838 | more than once -- one for each expression you use as a keyword for | 854 | more than once -- one for each expression you use as a keyword for |
839 | the filename. | 855 | the filename. |
840 | 856 | ||
@@ -845,10 +861,14 @@ list by running @command{extract -L}. Use quotes around the entire | |||
845 | meta-data argument if the value contains spaces. The meta-data | 861 | meta-data argument if the value contains spaces. The meta-data |
846 | is displayed to other users when they select which files to | 862 | is displayed to other users when they select which files to |
847 | download. The meta-data and the keywords are optional and | 863 | download. The meta-data and the keywords are optional and |
848 | maybe inferred using @code{GNU libextractor}. | 864 | may be inferred using @code{GNU libextractor}. |
865 | |||
866 | @command{gnunet-publish} has a few additional options to handle | ||
867 | namespaces and directories. Refer to the man-page for details: | ||
849 | 868 | ||
850 | gnunet-publish has a few additional options to handle namespaces and | 869 | @example |
851 | directories. See the man-page for details. | 870 | man gnunet-publish |
871 | @end example | ||
852 | 872 | ||
853 | @node Indexing vs. Inserting | 873 | @node Indexing vs. Inserting |
854 | @subsubsection Indexing vs Inserting | 874 | @subsubsection Indexing vs Inserting |
@@ -890,18 +910,17 @@ able to crack the encryption (e.g. by guessing the keyword. | |||
890 | @subsection Concepts | 910 | @subsection Concepts |
891 | @c %**end of header | 911 | @c %**end of header |
892 | 912 | ||
893 | Sharing files in GNUnet is not quite as simple as in traditional | 913 | For better results with filesharing it is useful to understand the |
894 | file sharing systems. For example, it is not sufficient to just | 914 | following concepts. |
895 | place files into a specific directory to share them. In addition | 915 | In addition to anonymous routing GNUnet attempts to give users a better |
896 | to anonymous routing GNUnet attempts to give users a better experience | 916 | experience in searching for content. GNUnet uses cryptography to safely |
897 | in searching for content. GNUnet uses cryptography to safely break | 917 | break content into smaller pieces that can be obtained from different |
898 | content into smaller pieces that can be obtained from different | 918 | sources without allowing participants to corrupt files. GNUnet makes it |
899 | sources without allowing participants to corrupt files. GNUnet | 919 | difficult for an adversary to send back bogus search results. GNUnet |
900 | makes it difficult for an adversary to send back bogus search | 920 | enables content providers to group related content and to establish a |
901 | results. GNUnet enables content providers to group related content | 921 | reputation. Furthermore, GNUnet allows updates to certain content to be |
902 | and to establish a reputation. Furthermore, GNUnet allows updates | 922 | made available. This section is supposed to introduce users to the |
903 | to certain content to be made available. This section is supposed | 923 | concepts that are used to achieve these goals. |
904 | to introduce users to the concepts that are used to achieve these goals. | ||
905 | 924 | ||
906 | 925 | ||
907 | @menu | 926 | @menu |
@@ -921,10 +940,10 @@ to introduce users to the concepts that are used to achieve these goals. | |||
921 | @c %**end of header | 940 | @c %**end of header |
922 | 941 | ||
923 | A file in GNUnet is just a sequence of bytes. Any file-format is allowed | 942 | A file in GNUnet is just a sequence of bytes. Any file-format is allowed |
924 | and the maximum file size is theoretically 264 bytes, except that it | 943 | and the maximum file size is theoretically @math{2^64 - 1} bytes, except |
925 | would take an impractical amount of time to share such a file. | 944 | that it would take an impractical amount of time to share such a file. |
926 | GNUnet itself never interprets the contents of shared files, except | 945 | GNUnet itself never interprets the contents of shared files, except when |
927 | when using GNU libextractor to obtain keywords. | 946 | using GNU libextractor to obtain keywords. |
928 | 947 | ||
929 | @node Keywords | 948 | @node Keywords |
930 | @subsubsection Keywords | 949 | @subsubsection Keywords |
@@ -954,10 +973,26 @@ it cannot be changed since it is treated just like an ordinary file | |||
954 | by the network. Small files (of a few kilobytes) can be inlined in | 973 | by the network. Small files (of a few kilobytes) can be inlined in |
955 | the directory, so that a separate download becomes unnecessary. | 974 | the directory, so that a separate download becomes unnecessary. |
956 | 975 | ||
976 | Directories are shared just like ordinary files. If you download a | ||
977 | directory with @command{gnunet-download}, you can use | ||
978 | @command{gnunet-directory} to list its contents. The canonical | ||
979 | extension for GNUnet directories when stored as files in your | ||
980 | local file-system is ".gnd". The contents of a directory are URIs and | ||
981 | meta data. | ||
982 | The URIs contain all the information required by | ||
983 | @command{gnunet-download} to retrieve the file. The meta data | ||
984 | typically includes the mime-type, description, a filename and | ||
985 | other meta information, and possibly even the full original file | ||
986 | (if it was small). | ||
987 | |||
957 | @node Pseudonyms | 988 | @node Pseudonyms |
958 | @subsubsection Pseudonyms | 989 | @subsubsection Pseudonyms |
959 | @c %**end of header | 990 | @c %**end of header |
960 | 991 | ||
992 | @b{Please note that the text in this subsection is outdated and needs} | ||
993 | @b{to be rewritten for version 0.10!} | ||
994 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
995 | |||
961 | Pseudonyms in GNUnet are essentially public-private (RSA) key pairs | 996 | Pseudonyms in GNUnet are essentially public-private (RSA) key pairs |
962 | that allow a GNUnet user to maintain an identity (which may or may not | 997 | that allow a GNUnet user to maintain an identity (which may or may not |
963 | be detached from their real-life identity). GNUnet's pseudonyms are not | 998 | be detached from their real-life identity). GNUnet's pseudonyms are not |
@@ -973,6 +1008,10 @@ to copy around). | |||
973 | @subsubsection Namespaces | 1008 | @subsubsection Namespaces |
974 | @c %**end of header | 1009 | @c %**end of header |
975 | 1010 | ||
1011 | @b{Please note that the text in this subsection is outdated and needs} | ||
1012 | @b{to be rewritten for version 0.10!} | ||
1013 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
1014 | |||
976 | A namespace is a set of files that were signed by the same pseudonym. | 1015 | A namespace is a set of files that were signed by the same pseudonym. |
977 | Files (or directories) that have been signed and placed into a namespace | 1016 | Files (or directories) that have been signed and placed into a namespace |
978 | can be updated. Updates are identified as authentic if the same secret | 1017 | can be updated. Updates are identified as authentic if the same secret |
@@ -984,11 +1023,15 @@ same entity (which does not have to be the same person). | |||
984 | @subsubsection Advertisements | 1023 | @subsubsection Advertisements |
985 | @c %**end of header | 1024 | @c %**end of header |
986 | 1025 | ||
1026 | @b{Please note that the text in this subsection is outdated and needs} | ||
1027 | @b{to be rewritten for version 0.10!} | ||
1028 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
1029 | |||
987 | Advertisements are used to notify other users about the existence of a | 1030 | Advertisements are used to notify other users about the existence of a |
988 | namespace. Advertisements are propagated using the normal keyword search. | 1031 | namespace. Advertisements are propagated using the normal keyword search. |
989 | When an advertisement is received (in response to a search), the namespace | 1032 | When an advertisement is received (in response to a search), the namespace |
990 | is added to the list of namespaces available in the namespace-search | 1033 | is added to the list of namespaces available in the namespace-search |
991 | dialogs of gnunet-fs-gtk and printed by gnunet-pseudonym. Whenever a | 1034 | dialogs of gnunet-fs-gtk and printed by @code{gnunet-identity}. Whenever a |
992 | namespace is created, an appropriate advertisement can be generated. | 1035 | namespace is created, an appropriate advertisement can be generated. |
993 | The default keyword for the advertising of namespaces is "namespace". | 1036 | The default keyword for the advertising of namespaces is "namespace". |
994 | 1037 | ||
@@ -996,7 +1039,7 @@ Note that GNUnet differentiates between your pseudonyms (the identities | |||
996 | that you control) and namespaces. If you create a pseudonym, you will | 1039 | that you control) and namespaces. If you create a pseudonym, you will |
997 | not automatically see the respective namespace. You first have to create | 1040 | not automatically see the respective namespace. You first have to create |
998 | an advertisement for the namespace and find it using keyword | 1041 | an advertisement for the namespace and find it using keyword |
999 | search --- even for your own namespaces. The @command{gnunet-pseudonym} | 1042 | search --- even for your own namespaces. The @command{gnunet-identity} |
1000 | tool is currently responsible for both managing pseudonyms and namespaces. | 1043 | tool is currently responsible for both managing pseudonyms and namespaces. |
1001 | This will likely change in the future to reduce the potential for | 1044 | This will likely change in the future to reduce the potential for |
1002 | confusion. | 1045 | confusion. |
@@ -1044,22 +1087,6 @@ level by one. If all blocks reach replication level zero, the | |||
1044 | selection is simply random. | 1087 | selection is simply random. |
1045 | 1088 | ||
1046 | 1089 | ||
1047 | @node fs-Directories | ||
1048 | @subsection Directories | ||
1049 | @c %**end of header | ||
1050 | |||
1051 | Directories are shared just like ordinary files. If you download a | ||
1052 | directory with @command{gnunet-download}, you can use | ||
1053 | @command{gnunet-directory} to list its contents. The canonical | ||
1054 | extension for GNUnet directories when stored as files in your | ||
1055 | local file-system is ".gnd". The contents of a directory are URIs and | ||
1056 | meta data. | ||
1057 | The URIs contain all the information required by | ||
1058 | @command{gnunet-download} to retrieve the file. The meta data | ||
1059 | typically includes the mime-type, description, a filename and | ||
1060 | other meta information, and possibly even the full original file | ||
1061 | (if it was small). | ||
1062 | |||
1063 | @node Namespace Management | 1090 | @node Namespace Management |
1064 | @subsection Namespace Management | 1091 | @subsection Namespace Management |
1065 | @c %**end of header | 1092 | @c %**end of header |
@@ -1067,8 +1094,8 @@ other meta information, and possibly even the full original file | |||
1067 | @b{Please note that the text in this subsection is outdated and needs} | 1094 | @b{Please note that the text in this subsection is outdated and needs} |
1068 | @b{to be rewritten for version 0.10!} | 1095 | @b{to be rewritten for version 0.10!} |
1069 | 1096 | ||
1070 | The gnunet-pseudonym tool can be used to create pseudonyms and | 1097 | The @code{gnunet-identity} tool can be used to create pseudonyms and |
1071 | to advertise namespaces. By default, gnunet-pseudonym simply | 1098 | to advertise namespaces. By default, @code{gnunet-identity -D} simply |
1072 | lists all locally available pseudonyms. | 1099 | lists all locally available pseudonyms. |
1073 | 1100 | ||
1074 | 1101 | ||
@@ -1084,6 +1111,10 @@ lists all locally available pseudonyms. | |||
1084 | @subsubsection Creating Pseudonyms | 1111 | @subsubsection Creating Pseudonyms |
1085 | @c %**end of header | 1112 | @c %**end of header |
1086 | 1113 | ||
1114 | @b{Please note that the text in this subsection is outdated and needs} | ||
1115 | @b{to be rewritten for version 0.10!} | ||
1116 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
1117 | |||
1087 | With the @command{-C NICK} option it can also be used to | 1118 | With the @command{-C NICK} option it can also be used to |
1088 | create a new pseudonym. A pseudonym is the virtual identity | 1119 | create a new pseudonym. A pseudonym is the virtual identity |
1089 | of the entity in control of a namespace. Anyone can create | 1120 | of the entity in control of a namespace. Anyone can create |
@@ -1095,6 +1126,10 @@ used. | |||
1095 | @subsubsection Deleting Pseudonyms | 1126 | @subsubsection Deleting Pseudonyms |
1096 | @c %**end of header | 1127 | @c %**end of header |
1097 | 1128 | ||
1129 | @b{Please note that the text in this subsection is outdated and needs} | ||
1130 | @b{to be rewritten for version 0.10!} | ||
1131 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
1132 | |||
1098 | With the @command{-D NICK} option pseudonyms can be deleted. | 1133 | With the @command{-D NICK} option pseudonyms can be deleted. |
1099 | Once the pseudonym has been deleted it is impossible to add | 1134 | Once the pseudonym has been deleted it is impossible to add |
1100 | content to the corresponding namespace. Deleting the | 1135 | content to the corresponding namespace. Deleting the |
@@ -1105,6 +1140,10 @@ unavailable. | |||
1105 | @subsubsection Advertising namespaces | 1140 | @subsubsection Advertising namespaces |
1106 | @c %**end of header | 1141 | @c %**end of header |
1107 | 1142 | ||
1143 | @b{Please note that the text in this subsection is outdated and needs} | ||
1144 | @b{to be rewritten for version 0.10!} | ||
1145 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
1146 | |||
1108 | Each namespace is associated with meta-data that describes | 1147 | Each namespace is associated with meta-data that describes |
1109 | the namespace. This meta-data is provided by the user at | 1148 | the namespace. This meta-data is provided by the user at |
1110 | the time that the namespace is advertised. Advertisements | 1149 | the time that the namespace is advertised. Advertisements |
@@ -1121,6 +1160,10 @@ the quality of the content found in it. | |||
1121 | @subsubsection Namespace names | 1160 | @subsubsection Namespace names |
1122 | @c %**end of header | 1161 | @c %**end of header |
1123 | 1162 | ||
1163 | @b{Please note that the text in this subsection is outdated and needs} | ||
1164 | @b{to be rewritten for version 0.10!} | ||
1165 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
1166 | |||
1124 | While the namespace is uniquely identified by its ID, another way | 1167 | While the namespace is uniquely identified by its ID, another way |
1125 | to refer to the namespace is to use the NICKNAME. | 1168 | to refer to the namespace is to use the NICKNAME. |
1126 | The NICKNAME can be freely chosen by the creator of the namespace and | 1169 | The NICKNAME can be freely chosen by the creator of the namespace and |
@@ -1132,6 +1175,10 @@ to the NICKNAME to get a unique identifier. | |||
1132 | @subsubsection Namespace root | 1175 | @subsubsection Namespace root |
1133 | @c %**end of header | 1176 | @c %**end of header |
1134 | 1177 | ||
1178 | @b{Please note that the text in this subsection is outdated and needs} | ||
1179 | @b{to be rewritten for version 0.10!} | ||
1180 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
1181 | |||
1135 | An item of particular interest in the namespace advertisement is | 1182 | An item of particular interest in the namespace advertisement is |
1136 | the ROOT. The ROOT is the identifier of a designated entry in the | 1183 | the ROOT. The ROOT is the identifier of a designated entry in the |
1137 | namespace. The idea is that the ROOT can be used to advertise an | 1184 | namespace. The idea is that the ROOT can be used to advertise an |
@@ -1219,6 +1266,10 @@ Furthermore they must not contain '++'. | |||
1219 | @subsubsection Namespace content (sks) | 1266 | @subsubsection Namespace content (sks) |
1220 | @c %**end of header | 1267 | @c %**end of header |
1221 | 1268 | ||
1269 | @b{Please note that the text in this subsection is outdated and needs} | ||
1270 | @b{to be rewritten for version 0.10!} | ||
1271 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
1272 | |||
1222 | Namespaces are sets of files that have been approved by some (usually | 1273 | Namespaces are sets of files that have been approved by some (usually |
1223 | pseudonymous) user --- typically by that user publishing all of the | 1274 | pseudonymous) user --- typically by that user publishing all of the |
1224 | files together. A file can be in many namespaces. A file is in a | 1275 | files together. A file can be in many namespaces. A file is in a |
@@ -1419,8 +1470,8 @@ $ gnunet-identity -C "myzone" | |||
1419 | 1470 | ||
1420 | Henceforth, on your system you control the TLD ``myzone''. | 1471 | Henceforth, on your system you control the TLD ``myzone''. |
1421 | 1472 | ||
1422 | All of your zones can be listed using the @command{gnunet-identity} | 1473 | All of your zones can be listed (displayed) using the |
1423 | command line tool as well: | 1474 | @command{gnunet-identity} command line tool as well: |
1424 | 1475 | ||
1425 | @example | 1476 | @example |
1426 | $ gnunet-identity -d | 1477 | $ gnunet-identity -d |
@@ -1528,11 +1579,11 @@ record you want to access). | |||
1528 | @subsection Using Public Keys as Top Level Domains | 1579 | @subsection Using Public Keys as Top Level Domains |
1529 | 1580 | ||
1530 | 1581 | ||
1531 | GNS also assumes responsibility for any name that uses in a well-formed | 1582 | GNS also assumes responsibility for any name that uses in a |
1532 | public key for the TLD. Names ending this way are then resolved by querying | 1583 | well-formed public key for the TLD. Names ending this way are then |
1533 | the respective zone. Such public key TLDs are expected to be used under rare | 1584 | resolved by querying the respective zone. Such public key TLDs are |
1534 | circumstances where globally unique names are required, and for | 1585 | expected to be used under rare circumstances where globally unique |
1535 | integration with legacy systems. | 1586 | names are required, and for integration with legacy systems. |
1536 | 1587 | ||
1537 | @node Resource Records in GNS | 1588 | @node Resource Records in GNS |
1538 | @subsection Resource Records in GNS | 1589 | @subsection Resource Records in GNS |
@@ -1569,18 +1620,31 @@ GNS currently supports the following record types: | |||
1569 | * CNAME:: | 1620 | * CNAME:: |
1570 | * GNS2DNS:: | 1621 | * GNS2DNS:: |
1571 | * SOA SRV PTR and MX:: | 1622 | * SOA SRV PTR and MX:: |
1623 | * PLACE:: | ||
1624 | * PHONE:: | ||
1625 | * ID ATTR:: | ||
1626 | * ID TOKEN:: | ||
1627 | * ID TOKEN METADATA:: | ||
1628 | * CREDENTIAL:: | ||
1629 | * POLICY:: | ||
1630 | * ATTRIBUTE:: | ||
1631 | * ABE KEY:: | ||
1632 | * ABE MASTER:: | ||
1633 | * RECLAIM OIDC CLIENT:: | ||
1634 | * RECLAIM OIDC REDIRECT:: | ||
1572 | @end menu | 1635 | @end menu |
1573 | 1636 | ||
1574 | @node NICK | 1637 | @node NICK |
1575 | @subsubsection NICK | 1638 | @subsubsection NICK |
1576 | 1639 | ||
1577 | A NICK record is used to give a zone a name. With a NICK record, you can | 1640 | A NICK record is used to give a zone a name. With a NICK record, you |
1578 | essentially specify how you would like to be called. GNS expects this | 1641 | can essentially specify how you would like to be called. GNS expects |
1579 | record under the empty label ``@@'' in the zone's database (NAMESTORE); however, | 1642 | this record under the empty label ``@@'' in the zone's database |
1580 | it will then automatically be copied into each record set, so that | 1643 | (NAMESTORE); however, it will then automatically be copied into each |
1581 | clients never need to do a separate lookup to discover the NICK record. | 1644 | record set, so that clients never need to do a separate lookup to |
1582 | Also, users do not usually have to worry about setting the NICK record: | 1645 | discover the NICK record. Also, users do not usually have to worry |
1583 | it is automatically set to the local name of the TLD. | 1646 | about setting the NICK record: it is automatically set to the local |
1647 | name of the TLD. | ||
1584 | 1648 | ||
1585 | @b{Example}@ | 1649 | @b{Example}@ |
1586 | 1650 | ||
@@ -1739,6 +1803,66 @@ should use the ZKEY zone as the destination hostname and | |||
1739 | GNS-enabled mail servers should be configured to accept | 1803 | GNS-enabled mail servers should be configured to accept |
1740 | e-mails to the ZKEY-zones of all local users. | 1804 | e-mails to the ZKEY-zones of all local users. |
1741 | 1805 | ||
1806 | @node PLACE | ||
1807 | @subsubsection PLACE | ||
1808 | |||
1809 | Record type for a social place. | ||
1810 | |||
1811 | @node PHONE | ||
1812 | @subsubsection PHONE | ||
1813 | |||
1814 | Record type for a phone (of CONVERSATION). | ||
1815 | |||
1816 | @node ID ATTR | ||
1817 | @subsubsection ID ATTR | ||
1818 | |||
1819 | Record type for identity attributes (of IDENTITY). | ||
1820 | |||
1821 | @node ID TOKEN | ||
1822 | @subsubsection ID TOKEN | ||
1823 | |||
1824 | Record type for an identity token (of IDENTITY-TOKEN). | ||
1825 | |||
1826 | @node ID TOKEN METADATA | ||
1827 | @subsubsection ID TOKEN METADATA | ||
1828 | |||
1829 | Record type for the private metadata of an identity token (of IDENTITY-TOKEN). | ||
1830 | |||
1831 | @node CREDENTIAL | ||
1832 | @subsubsection CREDENTIAL | ||
1833 | |||
1834 | Record type for credential. | ||
1835 | |||
1836 | @node POLICY | ||
1837 | @subsubsection POLICY | ||
1838 | |||
1839 | Record type for policies. | ||
1840 | |||
1841 | @node ATTRIBUTE | ||
1842 | @subsubsection ATTRIBUTE | ||
1843 | |||
1844 | Record type for reverse lookups. | ||
1845 | |||
1846 | @node ABE KEY | ||
1847 | @subsubsection ABE KEY | ||
1848 | |||
1849 | Record type for ABE records. | ||
1850 | |||
1851 | @node ABE MASTER | ||
1852 | @subsubsection ABE MASTER | ||
1853 | |||
1854 | Record type for ABE master keys. | ||
1855 | |||
1856 | @node RECLAIM OIDC CLIENT | ||
1857 | @subsubsection RECLAIM OIDC CLIENT | ||
1858 | |||
1859 | Record type for reclaim OIDC clients. | ||
1860 | |||
1861 | @node RECLAIM OIDC REDIRECT | ||
1862 | @subsubsection RECLAIM OIDC REDIRECT | ||
1863 | |||
1864 | Record type for reclaim OIDC redirect URIs. | ||
1865 | |||
1742 | @node Synchronizing with legacy DNS | 1866 | @node Synchronizing with legacy DNS |
1743 | @subsection Synchronizing with legacy DNS | 1867 | @subsection Synchronizing with legacy DNS |
1744 | 1868 | ||
@@ -1769,6 +1893,98 @@ is thus advisable to disable the namecache by setting the | |||
1769 | option ``DISABLE'' to ``YES'' in section ``[namecache]''. | 1893 | option ``DISABLE'' to ``YES'' in section ``[namecache]''. |
1770 | 1894 | ||
1771 | 1895 | ||
1896 | @node re@:claim Identity Provider | ||
1897 | @section re@:claim Identity Provider | ||
1898 | |||
1899 | The re:claim Identity Provider (IdP) is a decentralized IdP service. | ||
1900 | It allows its users to manage and authorize third parties to access their identity attributes such as email or shipping addresses. | ||
1901 | |||
1902 | It basically mimics the concepts of centralized IdPs, such as those offered by Google or Facebook. | ||
1903 | Like other IdPs, re:claim features an (optional) OpenID-Connect 1.0-compliant protocol layer that can be used for websites to integrate re:claim as an Identity Provider with little effort. | ||
1904 | |||
1905 | @menu | ||
1906 | * Managing Attributes:: | ||
1907 | * Sharing Attributes with Third Parties:: | ||
1908 | * Revoking Authorizations of Third Parties:: | ||
1909 | * Using the OpenID-Connect IdP:: | ||
1910 | @end menu | ||
1911 | |||
1912 | @node Managing Attributes | ||
1913 | @subsection Managing Attributes | ||
1914 | |||
1915 | Before adding attributes to an identity, you must first create an ego: | ||
1916 | |||
1917 | @example | ||
1918 | $ gnunet-identity -C "username" | ||
1919 | @end example | ||
1920 | |||
1921 | Henceforth, you can manage a new user profile of the user ``username''. | ||
1922 | |||
1923 | To add an email address to your user profile, simply use the @command{gnunet-idp} command line tool:: | ||
1924 | |||
1925 | @example | ||
1926 | $ gnunet-idp -e "username" -a "email" -V "username@@example.gnunet" | ||
1927 | @end example | ||
1928 | |||
1929 | All of your attributes can be listed using the @command{gnunet-idp} | ||
1930 | command line tool as well: | ||
1931 | |||
1932 | @example | ||
1933 | $ gnunet-idp -e "username" -D | ||
1934 | @end example | ||
1935 | |||
1936 | Currently, and by default, attribute values are interpreted as plain text. | ||
1937 | In the future there might be more value types such as X.509 certificate credentials. | ||
1938 | |||
1939 | @node Sharing Attributes with Third Parties | ||
1940 | @subsection Sharing Attributes with Third Parties | ||
1941 | |||
1942 | If you want to allow a third party such as a website or friend to access to your attributes (or a subset thereof) execute: | ||
1943 | |||
1944 | @example | ||
1945 | $ gnunet-idp -e "username" -r "PKEY" -i "attribute1,attribute2,..." | ||
1946 | @end example | ||
1947 | |||
1948 | Where "PKEY" is the public key of the third party and "attribute1,attribute2,..." is a comma-separated list of attribute names, such as "email", that you want to share. | ||
1949 | |||
1950 | The command will return a "ticket" string. | ||
1951 | You must give this "ticket" to the requesting third party. | ||
1952 | |||
1953 | The third party can then retrieve your shared identity attributes using: | ||
1954 | |||
1955 | @example | ||
1956 | $ gnunet-idp -e "friend" -C "ticket" | ||
1957 | @end example | ||
1958 | |||
1959 | This will retrieve and list the shared identity attributes. | ||
1960 | The above command will also work if the user "username" is currently offline since the attributes are retrieved from GNS. | ||
1961 | Further, the "ticket" can be re-used later to retrieve up-to-date attributes in case "username" has changed the value(s). For instance, becasue his email address changed. | ||
1962 | |||
1963 | To list all given authorizations (tickets) you can execute: | ||
1964 | @example | ||
1965 | $ gnunet-idp -e "friend" -T (TODO there is only a REST API for this ATM) | ||
1966 | @end example | ||
1967 | |||
1968 | |||
1969 | @node Revoking Authorizations of Third Parties | ||
1970 | @subsection Revoking Authorizations of Third Parties | ||
1971 | |||
1972 | If you want to revoke the access of a third party to your attributes you can execute: | ||
1973 | |||
1974 | @example | ||
1975 | $ gnunet-idp -e "username" -R "ticket" | ||
1976 | @end example | ||
1977 | |||
1978 | This will prevent the third party from accessing the attribute in the future. | ||
1979 | Please note that if the third party has previously accessed the attribute, there is not way in which the system could have prevented the thiry party from storing the data. | ||
1980 | As such, only access to updated data in the future can be revoked. | ||
1981 | This behaviour is _exactly the same_ as with other IdPs. | ||
1982 | |||
1983 | @node Using the OpenID-Connect IdP | ||
1984 | @subsection Using the OpenID-Connect IdP | ||
1985 | |||
1986 | TODO: Document setup and REST endpoints | ||
1987 | |||
1772 | @node Using the Virtual Public Network | 1988 | @node Using the Virtual Public Network |
1773 | @section Using the Virtual Public Network | 1989 | @section Using the Virtual Public Network |
1774 | 1990 | ||