aboutsummaryrefslogtreecommitdiff
path: root/doc/documentation/chapters/user.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/documentation/chapters/user.texi')
-rw-r--r--doc/documentation/chapters/user.texi364
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
246time. Still, it is a possible use-case and we welcome help with testing 248time. Still, it is a possible use-case and we welcome help with testing
247and development. 249and 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.
257If you are using a Debian GNU/Linux based operating system, the 259If you are using a Debian GNU/Linux based operating system, the
258following command should install the required components. 260following command should install the required components.
259Keep in mind that this @b{requires 3GB} of downloaded data and possibly 261Keep 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
264size 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
262TexLive Distribution. This way we could just state the required components 266TexLive Distribution. This way we could just state the required components
263without pulling in the full distribution of TexLive.} 267without pulling in the full distribution of TexLive.}
@@ -312,12 +316,14 @@ you might need a trip to the store together.
312Before we get started, we need to tell @code{gnunet-qr} which zone 316Before we get started, we need to tell @code{gnunet-qr} which zone
313it should import new records into. For this, run: 317it 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
318where NAME is the name of the zone you want to import records 323where NAME is the name of the zone you want to import records
319into. In our running example, this would be ``gnu''. 324into. In our running example, this would be ``gnu''.
320 325
326@pindex gnunet-qr
321Henceforth, for every business card you collect, simply run: 327Henceforth, 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
335resolve your friends names. Suppose your friend's nickname 341resolve your friends names. Suppose your friend's nickname
336is "Bob". Then, type 342is "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,
381when published on the P2P network, flags your private key as invalid, 388when published on the P2P network, flags your private key as invalid,
382and all further resolutions or other checks involving the key will fail. 389and all further resolutions or other checks involving the key will fail.
383 390
391@pindex gnunet-revocation
384A revocation certificate is thus a useful tool when things go out of 392A revocation certificate is thus a useful tool when things go out of
385control, but at the same time it should be stored securely. 393control, but at the same time it should be stored securely.
386Generation of the revocation certificate for a zone can be done through 394Generation of the revocation certificate for a zone can be done through
@@ -433,6 +441,7 @@ private conversation with your friend. Finally, help us
433with the next GNUnet release for even more applications 441with the next GNUnet release for even more applications
434using this new public key infrastructure. 442using 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
485GNS zone that will be used to resolve names of users that you 494GNS zone that will be used to resolve names of users that you
486are calling. Run 495are calling. Run
487 496
497@pindex gnunet-conversation
488@example 498@example
489gnunet-conversation -e zone-name 499gnunet-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
595hosts: files gns [NOTFOUND=return] mdns4_minimal [NOTFOUND=return] dns mdns4 605hosts: 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
599You might want to make sure that @code{/lib/libnss_gns.so.2} exists on 612You might want to make sure that @code{/lib/libnss_gns.so.2} exists on
600your system, it should have been created during the installation. 613your system, it should have been created during the installation.
@@ -608,8 +621,8 @@ $ cd src/gns/nss; sudo make install
608@noindent 621@noindent
609to install the NSS plugins in the proper location. 622to 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
615Stop your peer (as user @code{gnunet}, run @command{gnunet-arm -e}) and 628Stop your peer (as user @code{gnunet}, run @command{gnunet-arm -e}) and
@@ -696,9 +709,10 @@ the searcher/downloader specify "no anonymity", non-anonymous
696file-sharing is used. If either user specifies some desired degree 709file-sharing is used. If either user specifies some desired degree
697of anonymity, anonymous file-sharing will be used. 710of anonymity, anonymous file-sharing will be used.
698 711
699After a short introduction, we will first look at the various concepts in 712After a short introduction, we will first look at the various concepts
700GNUnet's file-sharing implementation. Then, we will discuss specifics as to how 713in GNUnet's file-sharing implementation. Then, we will discuss
701they impact users that publish, search or download files. 714specifics as to how they impact users that publish, search or download
715files.
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
727The -t option specifies that the query should timeout after 740The @command{-t} option specifies that the query should timeout after
728approximately TIMEOUT seconds. A value of zero is interpreted 741approximately TIMEOUT seconds. A value of zero (``0'') is interpreted
729as @emph{no timeout}, which is also the default. In this case, 742as @emph{no timeout}, which is the default. In this case,
730gnunet-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
732If multiple words are passed as keywords, they will all be 746If multiple words are passed as keywords, they will all be
733considered optional. Prefix keywords with a "+" to make them mandatory. 747considered 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
751shared under the keyword "Das Kapital". 765shared under the keyword "Das Kapital".
752 766
753Search results are printed by gnunet-search like this: 767Search 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:
759gnunet-download -o "COPYING" gnunet://fs/chk/PGK8M...3EK130.75446 774gnunet-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
764The whole line is the command you would have to enter to download 779The whole line is the command you would have to enter to download
765the file. The argument passed to @code{-o} is the suggested 780the file. The first argument passed to @code{-o} is the suggested
766filename (you may change it to whatever you like). 781filename (you may change it to whatever you like).
767It is followed by the key for decrypting the file, the query for searching the 782It is followed by the key for decrypting the file, the query for
768file, a checksum (in hexadecimal) finally the size of the file in bytes. 783searching the file, a checksum (in hexadecimal) finally the size of
784the 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.
802GNUnet's file-encoding mechanism will ensure file integrity, even if the 818GNUnet's file-encoding mechanism will ensure file integrity, even if the
803existing file was not downloaded from GNUnet in the first place. 819existing file was not downloaded from GNUnet in the first place.
804 820
805You may want to use the @command{-V} switch to turn on verbose reporting. In 821You may want to use the @command{-V} switch to turn on verbose
806this case, @command{gnunet-download} will print the current number of bytes 822reporting. In this case, @command{gnunet-download} will print the
807downloaded whenever new data was received. 823current 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
834The option @code{-k} is used to specify keywords for the file that 850The option @code{-k} is used to specify keywords for the file that
835should be inserted. You can supply any number of keywords, 851should be inserted. You can supply any number of keywords,
836and each of the keywords will be sufficient to locate and 852and each of the keywords will be sufficient to locate and
837retrieve the file. Please note that you must use the @code{-k} option 853retrieve the file. Please note that you must use the @code{-k} option
838more than once -- one for each expression you use as a keyword for 854more than once -- one for each expression you use as a keyword for
839the filename. 855the filename.
840 856
@@ -845,10 +861,14 @@ list by running @command{extract -L}. Use quotes around the entire
845meta-data argument if the value contains spaces. The meta-data 861meta-data argument if the value contains spaces. The meta-data
846is displayed to other users when they select which files to 862is displayed to other users when they select which files to
847download. The meta-data and the keywords are optional and 863download. The meta-data and the keywords are optional and
848maybe inferred using @code{GNU libextractor}. 864may be inferred using @code{GNU libextractor}.
865
866@command{gnunet-publish} has a few additional options to handle
867namespaces and directories. Refer to the man-page for details:
849 868
850gnunet-publish has a few additional options to handle namespaces and 869@example
851directories. See the man-page for details. 870man 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
893Sharing files in GNUnet is not quite as simple as in traditional 913For better results with filesharing it is useful to understand the
894file sharing systems. For example, it is not sufficient to just 914following concepts.
895place files into a specific directory to share them. In addition 915In addition to anonymous routing GNUnet attempts to give users a better
896to anonymous routing GNUnet attempts to give users a better experience 916experience in searching for content. GNUnet uses cryptography to safely
897in searching for content. GNUnet uses cryptography to safely break 917break content into smaller pieces that can be obtained from different
898content into smaller pieces that can be obtained from different 918sources without allowing participants to corrupt files. GNUnet makes it
899sources without allowing participants to corrupt files. GNUnet 919difficult for an adversary to send back bogus search results. GNUnet
900makes it difficult for an adversary to send back bogus search 920enables content providers to group related content and to establish a
901results. GNUnet enables content providers to group related content 921reputation. Furthermore, GNUnet allows updates to certain content to be
902and to establish a reputation. Furthermore, GNUnet allows updates 922made available. This section is supposed to introduce users to the
903to certain content to be made available. This section is supposed 923concepts that are used to achieve these goals.
904to 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
923A file in GNUnet is just a sequence of bytes. Any file-format is allowed 942A file in GNUnet is just a sequence of bytes. Any file-format is allowed
924and the maximum file size is theoretically 264 bytes, except that it 943and the maximum file size is theoretically @math{2^64 - 1} bytes, except
925would take an impractical amount of time to share such a file. 944that it would take an impractical amount of time to share such a file.
926GNUnet itself never interprets the contents of shared files, except 945GNUnet itself never interprets the contents of shared files, except when
927when using GNU libextractor to obtain keywords. 946using 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
954by the network. Small files (of a few kilobytes) can be inlined in 973by the network. Small files (of a few kilobytes) can be inlined in
955the directory, so that a separate download becomes unnecessary. 974the directory, so that a separate download becomes unnecessary.
956 975
976Directories are shared just like ordinary files. If you download a
977directory with @command{gnunet-download}, you can use
978@command{gnunet-directory} to list its contents. The canonical
979extension for GNUnet directories when stored as files in your
980local file-system is ".gnd". The contents of a directory are URIs and
981meta data.
982The URIs contain all the information required by
983@command{gnunet-download} to retrieve the file. The meta data
984typically includes the mime-type, description, a filename and
985other 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
961Pseudonyms in GNUnet are essentially public-private (RSA) key pairs 996Pseudonyms in GNUnet are essentially public-private (RSA) key pairs
962that allow a GNUnet user to maintain an identity (which may or may not 997that allow a GNUnet user to maintain an identity (which may or may not
963be detached from their real-life identity). GNUnet's pseudonyms are not 998be 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
976A namespace is a set of files that were signed by the same pseudonym. 1015A namespace is a set of files that were signed by the same pseudonym.
977Files (or directories) that have been signed and placed into a namespace 1016Files (or directories) that have been signed and placed into a namespace
978can be updated. Updates are identified as authentic if the same secret 1017can 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
987Advertisements are used to notify other users about the existence of a 1030Advertisements are used to notify other users about the existence of a
988namespace. Advertisements are propagated using the normal keyword search. 1031namespace. Advertisements are propagated using the normal keyword search.
989When an advertisement is received (in response to a search), the namespace 1032When an advertisement is received (in response to a search), the namespace
990is added to the list of namespaces available in the namespace-search 1033is added to the list of namespaces available in the namespace-search
991dialogs of gnunet-fs-gtk and printed by gnunet-pseudonym. Whenever a 1034dialogs of gnunet-fs-gtk and printed by @code{gnunet-identity}. Whenever a
992namespace is created, an appropriate advertisement can be generated. 1035namespace is created, an appropriate advertisement can be generated.
993The default keyword for the advertising of namespaces is "namespace". 1036The default keyword for the advertising of namespaces is "namespace".
994 1037
@@ -996,7 +1039,7 @@ Note that GNUnet differentiates between your pseudonyms (the identities
996that you control) and namespaces. If you create a pseudonym, you will 1039that you control) and namespaces. If you create a pseudonym, you will
997not automatically see the respective namespace. You first have to create 1040not automatically see the respective namespace. You first have to create
998an advertisement for the namespace and find it using keyword 1041an advertisement for the namespace and find it using keyword
999search --- even for your own namespaces. The @command{gnunet-pseudonym} 1042search --- even for your own namespaces. The @command{gnunet-identity}
1000tool is currently responsible for both managing pseudonyms and namespaces. 1043tool is currently responsible for both managing pseudonyms and namespaces.
1001This will likely change in the future to reduce the potential for 1044This will likely change in the future to reduce the potential for
1002confusion. 1045confusion.
@@ -1044,22 +1087,6 @@ level by one. If all blocks reach replication level zero, the
1044selection is simply random. 1087selection is simply random.
1045 1088
1046 1089
1047@node fs-Directories
1048@subsection Directories
1049@c %**end of header
1050
1051Directories are shared just like ordinary files. If you download a
1052directory with @command{gnunet-download}, you can use
1053@command{gnunet-directory} to list its contents. The canonical
1054extension for GNUnet directories when stored as files in your
1055local file-system is ".gnd". The contents of a directory are URIs and
1056meta data.
1057The URIs contain all the information required by
1058@command{gnunet-download} to retrieve the file. The meta data
1059typically includes the mime-type, description, a filename and
1060other 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
1070The gnunet-pseudonym tool can be used to create pseudonyms and 1097The @code{gnunet-identity} tool can be used to create pseudonyms and
1071to advertise namespaces. By default, gnunet-pseudonym simply 1098to advertise namespaces. By default, @code{gnunet-identity -D} simply
1072lists all locally available pseudonyms. 1099lists 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
1087With the @command{-C NICK} option it can also be used to 1118With the @command{-C NICK} option it can also be used to
1088create a new pseudonym. A pseudonym is the virtual identity 1119create a new pseudonym. A pseudonym is the virtual identity
1089of the entity in control of a namespace. Anyone can create 1120of 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
1098With the @command{-D NICK} option pseudonyms can be deleted. 1133With the @command{-D NICK} option pseudonyms can be deleted.
1099Once the pseudonym has been deleted it is impossible to add 1134Once the pseudonym has been deleted it is impossible to add
1100content to the corresponding namespace. Deleting the 1135content 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
1108Each namespace is associated with meta-data that describes 1147Each namespace is associated with meta-data that describes
1109the namespace. This meta-data is provided by the user at 1148the namespace. This meta-data is provided by the user at
1110the time that the namespace is advertised. Advertisements 1149the 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
1124While the namespace is uniquely identified by its ID, another way 1167While the namespace is uniquely identified by its ID, another way
1125to refer to the namespace is to use the NICKNAME. 1168to refer to the namespace is to use the NICKNAME.
1126The NICKNAME can be freely chosen by the creator of the namespace and 1169The 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
1135An item of particular interest in the namespace advertisement is 1182An item of particular interest in the namespace advertisement is
1136the ROOT. The ROOT is the identifier of a designated entry in the 1183the ROOT. The ROOT is the identifier of a designated entry in the
1137namespace. The idea is that the ROOT can be used to advertise an 1184namespace. 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
1222Namespaces are sets of files that have been approved by some (usually 1273Namespaces are sets of files that have been approved by some (usually
1223pseudonymous) user --- typically by that user publishing all of the 1274pseudonymous) user --- typically by that user publishing all of the
1224files together. A file can be in many namespaces. A file is in a 1275files together. A file can be in many namespaces. A file is in a
@@ -1419,8 +1470,8 @@ $ gnunet-identity -C "myzone"
1419 1470
1420Henceforth, on your system you control the TLD ``myzone''. 1471Henceforth, on your system you control the TLD ``myzone''.
1421 1472
1422All of your zones can be listed using the @command{gnunet-identity} 1473All of your zones can be listed (displayed) using the
1423command 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
1531GNS also assumes responsibility for any name that uses in a well-formed 1582GNS also assumes responsibility for any name that uses in a
1532public key for the TLD. Names ending this way are then resolved by querying 1583well-formed public key for the TLD. Names ending this way are then
1533the respective zone. Such public key TLDs are expected to be used under rare 1584resolved by querying the respective zone. Such public key TLDs are
1534circumstances where globally unique names are required, and for 1585expected to be used under rare circumstances where globally unique
1535integration with legacy systems. 1586names 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
1577A NICK record is used to give a zone a name. With a NICK record, you can 1640A NICK record is used to give a zone a name. With a NICK record, you
1578essentially specify how you would like to be called. GNS expects this 1641can essentially specify how you would like to be called. GNS expects
1579record under the empty label ``@@'' in the zone's database (NAMESTORE); however, 1642this record under the empty label ``@@'' in the zone's database
1580it will then automatically be copied into each record set, so that 1643(NAMESTORE); however, it will then automatically be copied into each
1581clients never need to do a separate lookup to discover the NICK record. 1644record set, so that clients never need to do a separate lookup to
1582Also, users do not usually have to worry about setting the NICK record: 1645discover the NICK record. Also, users do not usually have to worry
1583it is automatically set to the local name of the TLD. 1646about setting the NICK record: it is automatically set to the local
1647name 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
1739GNS-enabled mail servers should be configured to accept 1803GNS-enabled mail servers should be configured to accept
1740e-mails to the ZKEY-zones of all local users. 1804e-mails to the ZKEY-zones of all local users.
1741 1805
1806@node PLACE
1807@subsubsection PLACE
1808
1809Record type for a social place.
1810
1811@node PHONE
1812@subsubsection PHONE
1813
1814Record type for a phone (of CONVERSATION).
1815
1816@node ID ATTR
1817@subsubsection ID ATTR
1818
1819Record type for identity attributes (of IDENTITY).
1820
1821@node ID TOKEN
1822@subsubsection ID TOKEN
1823
1824Record type for an identity token (of IDENTITY-TOKEN).
1825
1826@node ID TOKEN METADATA
1827@subsubsection ID TOKEN METADATA
1828
1829Record type for the private metadata of an identity token (of IDENTITY-TOKEN).
1830
1831@node CREDENTIAL
1832@subsubsection CREDENTIAL
1833
1834Record type for credential.
1835
1836@node POLICY
1837@subsubsection POLICY
1838
1839Record type for policies.
1840
1841@node ATTRIBUTE
1842@subsubsection ATTRIBUTE
1843
1844Record type for reverse lookups.
1845
1846@node ABE KEY
1847@subsubsection ABE KEY
1848
1849Record type for ABE records.
1850
1851@node ABE MASTER
1852@subsubsection ABE MASTER
1853
1854Record type for ABE master keys.
1855
1856@node RECLAIM OIDC CLIENT
1857@subsubsection RECLAIM OIDC CLIENT
1858
1859Record type for reclaim OIDC clients.
1860
1861@node RECLAIM OIDC REDIRECT
1862@subsubsection RECLAIM OIDC REDIRECT
1863
1864Record 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
1769option ``DISABLE'' to ``YES'' in section ``[namecache]''. 1893option ``DISABLE'' to ``YES'' in section ``[namecache]''.
1770 1894
1771 1895
1896@node re@:claim Identity Provider
1897@section re@:claim Identity Provider
1898
1899The re:claim Identity Provider (IdP) is a decentralized IdP service.
1900It allows its users to manage and authorize third parties to access their identity attributes such as email or shipping addresses.
1901
1902It basically mimics the concepts of centralized IdPs, such as those offered by Google or Facebook.
1903Like 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
1915Before adding attributes to an identity, you must first create an ego:
1916
1917@example
1918$ gnunet-identity -C "username"
1919@end example
1920
1921Henceforth, you can manage a new user profile of the user ``username''.
1922
1923To 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
1929All of your attributes can be listed using the @command{gnunet-idp}
1930command line tool as well:
1931
1932@example
1933$ gnunet-idp -e "username" -D
1934@end example
1935
1936Currently, and by default, attribute values are interpreted as plain text.
1937In 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
1942If 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
1948Where "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
1950The command will return a "ticket" string.
1951You must give this "ticket" to the requesting third party.
1952
1953The third party can then retrieve your shared identity attributes using:
1954
1955@example
1956$ gnunet-idp -e "friend" -C "ticket"
1957@end example
1958
1959This will retrieve and list the shared identity attributes.
1960The above command will also work if the user "username" is currently offline since the attributes are retrieved from GNS.
1961Further, 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
1963To 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
1972If 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
1978This will prevent the third party from accessing the attribute in the future.
1979Please 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.
1980As such, only access to updated data in the future can be revoked.
1981This 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
1986TODO: 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