From 88d8593d0b28b81ced737da13a9c52e39faa8ec4 Mon Sep 17 00:00:00 2001 From: Julius Bünger Date: Fri, 27 Jul 2018 22:33:02 +0200 Subject: documentation: update formulations --- doc/documentation/chapters/user.texi | 182 +++++++++++++++++++++++++++-------- 1 file changed, 142 insertions(+), 40 deletions(-) (limited to 'doc/documentation') diff --git a/doc/documentation/chapters/user.texi b/doc/documentation/chapters/user.texi index 711d1d4a8..35afdf5f7 100644 --- a/doc/documentation/chapters/user.texi +++ b/doc/documentation/chapters/user.texi @@ -720,7 +720,6 @@ files. * fs-Downloading:: * fs-Publishing:: * fs-Concepts:: -* fs-Directories:: * Namespace Management:: * File-Sharing URIs:: * GTK User Interface:: @@ -851,7 +850,7 @@ $ gnunet-publish -m "description:GNU License" -k gpl -k test -m "mimetype:text/p The option @code{-k} is used to specify keywords for the file that should be inserted. You can supply any number of keywords, and each of the keywords will be sufficient to locate and -retrieve the file. Please note that you must use the @code{-k} option +retrieve the file. Please note that you must use the @code{-k} option more than once -- one for each expression you use as a keyword for the filename. @@ -911,18 +910,17 @@ able to crack the encryption (e.g. by guessing the keyword. @subsection Concepts @c %**end of header -Sharing files in GNUnet is not quite as simple as in traditional -file sharing systems. For example, it is not sufficient to just -place files into a specific directory to share them. In addition -to anonymous routing GNUnet attempts to give users a better experience -in searching for content. GNUnet uses cryptography to safely break -content into smaller pieces that can be obtained from different -sources without allowing participants to corrupt files. GNUnet -makes it difficult for an adversary to send back bogus search -results. GNUnet enables content providers to group related content -and to establish a reputation. Furthermore, GNUnet allows updates -to certain content to be made available. This section is supposed -to introduce users to the concepts that are used to achieve these goals. +For better results with filesharing it is useful to understand the +following concepts. +In addition to anonymous routing GNUnet attempts to give users a better +experience in searching for content. GNUnet uses cryptography to safely +break content into smaller pieces that can be obtained from different +sources without allowing participants to corrupt files. GNUnet makes it +difficult for an adversary to send back bogus search results. GNUnet +enables content providers to group related content and to establish a +reputation. Furthermore, GNUnet allows updates to certain content to be +made available. This section is supposed to introduce users to the +concepts that are used to achieve these goals. @menu @@ -942,10 +940,10 @@ to introduce users to the concepts that are used to achieve these goals. @c %**end of header A file in GNUnet is just a sequence of bytes. Any file-format is allowed -and the maximum file size is theoretically 264 bytes, except that it -would take an impractical amount of time to share such a file. -GNUnet itself never interprets the contents of shared files, except -when using GNU libextractor to obtain keywords. +and the maximum file size is theoretically @math{2^64 - 1} bytes, except +that it would take an impractical amount of time to share such a file. +GNUnet itself never interprets the contents of shared files, except when +using GNU libextractor to obtain keywords. @node Keywords @subsubsection Keywords @@ -975,10 +973,26 @@ it cannot be changed since it is treated just like an ordinary file by the network. Small files (of a few kilobytes) can be inlined in the directory, so that a separate download becomes unnecessary. +Directories are shared just like ordinary files. If you download a +directory with @command{gnunet-download}, you can use +@command{gnunet-directory} to list its contents. The canonical +extension for GNUnet directories when stored as files in your +local file-system is ".gnd". The contents of a directory are URIs and +meta data. +The URIs contain all the information required by +@command{gnunet-download} to retrieve the file. The meta data +typically includes the mime-type, description, a filename and +other meta information, and possibly even the full original file +(if it was small). + @node Pseudonyms @subsubsection Pseudonyms @c %**end of header +@b{Please note that the text in this subsection is outdated and needs} +@b{to be rewritten for version 0.10!} +@b{This especially concerns the terminology of Pseudonym/Ego/Identity.} + Pseudonyms in GNUnet are essentially public-private (RSA) key pairs that allow a GNUnet user to maintain an identity (which may or may not be detached from their real-life identity). GNUnet's pseudonyms are not @@ -994,6 +1008,10 @@ to copy around). @subsubsection Namespaces @c %**end of header +@b{Please note that the text in this subsection is outdated and needs} +@b{to be rewritten for version 0.10!} +@b{This especially concerns the terminology of Pseudonym/Ego/Identity.} + A namespace is a set of files that were signed by the same pseudonym. Files (or directories) that have been signed and placed into a namespace can be updated. Updates are identified as authentic if the same secret @@ -1005,11 +1023,15 @@ same entity (which does not have to be the same person). @subsubsection Advertisements @c %**end of header +@b{Please note that the text in this subsection is outdated and needs} +@b{to be rewritten for version 0.10!} +@b{This especially concerns the terminology of Pseudonym/Ego/Identity.} + Advertisements are used to notify other users about the existence of a namespace. Advertisements are propagated using the normal keyword search. When an advertisement is received (in response to a search), the namespace is added to the list of namespaces available in the namespace-search -dialogs of gnunet-fs-gtk and printed by gnunet-pseudonym. Whenever a +dialogs of gnunet-fs-gtk and printed by @code{gnunet-identity}. Whenever a namespace is created, an appropriate advertisement can be generated. The default keyword for the advertising of namespaces is "namespace". @@ -1017,7 +1039,7 @@ Note that GNUnet differentiates between your pseudonyms (the identities that you control) and namespaces. If you create a pseudonym, you will not automatically see the respective namespace. You first have to create an advertisement for the namespace and find it using keyword -search --- even for your own namespaces. The @command{gnunet-pseudonym} +search --- even for your own namespaces. The @command{gnunet-identity} tool is currently responsible for both managing pseudonyms and namespaces. This will likely change in the future to reduce the potential for confusion. @@ -1065,22 +1087,6 @@ level by one. If all blocks reach replication level zero, the selection is simply random. -@node fs-Directories -@subsection Directories -@c %**end of header - -Directories are shared just like ordinary files. If you download a -directory with @command{gnunet-download}, you can use -@command{gnunet-directory} to list its contents. The canonical -extension for GNUnet directories when stored as files in your -local file-system is ".gnd". The contents of a directory are URIs and -meta data. -The URIs contain all the information required by -@command{gnunet-download} to retrieve the file. The meta data -typically includes the mime-type, description, a filename and -other meta information, and possibly even the full original file -(if it was small). - @node Namespace Management @subsection Namespace Management @c %**end of header @@ -1088,8 +1094,8 @@ other meta information, and possibly even the full original file @b{Please note that the text in this subsection is outdated and needs} @b{to be rewritten for version 0.10!} -The gnunet-pseudonym tool can be used to create pseudonyms and -to advertise namespaces. By default, gnunet-pseudonym simply +The @code{gnunet-identity} tool can be used to create pseudonyms and +to advertise namespaces. By default, @code{gnunet-identity -D} simply lists all locally available pseudonyms. @@ -1105,6 +1111,10 @@ lists all locally available pseudonyms. @subsubsection Creating Pseudonyms @c %**end of header +@b{Please note that the text in this subsection is outdated and needs} +@b{to be rewritten for version 0.10!} +@b{This especially concerns the terminology of Pseudonym/Ego/Identity.} + With the @command{-C NICK} option it can also be used to create a new pseudonym. A pseudonym is the virtual identity of the entity in control of a namespace. Anyone can create @@ -1116,6 +1126,10 @@ used. @subsubsection Deleting Pseudonyms @c %**end of header +@b{Please note that the text in this subsection is outdated and needs} +@b{to be rewritten for version 0.10!} +@b{This especially concerns the terminology of Pseudonym/Ego/Identity.} + With the @command{-D NICK} option pseudonyms can be deleted. Once the pseudonym has been deleted it is impossible to add content to the corresponding namespace. Deleting the @@ -1126,6 +1140,10 @@ unavailable. @subsubsection Advertising namespaces @c %**end of header +@b{Please note that the text in this subsection is outdated and needs} +@b{to be rewritten for version 0.10!} +@b{This especially concerns the terminology of Pseudonym/Ego/Identity.} + Each namespace is associated with meta-data that describes the namespace. This meta-data is provided by the user at the time that the namespace is advertised. Advertisements @@ -1142,6 +1160,10 @@ the quality of the content found in it. @subsubsection Namespace names @c %**end of header +@b{Please note that the text in this subsection is outdated and needs} +@b{to be rewritten for version 0.10!} +@b{This especially concerns the terminology of Pseudonym/Ego/Identity.} + While the namespace is uniquely identified by its ID, another way to refer to the namespace is to use the NICKNAME. The NICKNAME can be freely chosen by the creator of the namespace and @@ -1153,6 +1175,10 @@ to the NICKNAME to get a unique identifier. @subsubsection Namespace root @c %**end of header +@b{Please note that the text in this subsection is outdated and needs} +@b{to be rewritten for version 0.10!} +@b{This especially concerns the terminology of Pseudonym/Ego/Identity.} + An item of particular interest in the namespace advertisement is the ROOT. The ROOT is the identifier of a designated entry in the namespace. The idea is that the ROOT can be used to advertise an @@ -1240,6 +1266,10 @@ Furthermore they must not contain '++'. @subsubsection Namespace content (sks) @c %**end of header +@b{Please note that the text in this subsection is outdated and needs} +@b{to be rewritten for version 0.10!} +@b{This especially concerns the terminology of Pseudonym/Ego/Identity.} + Namespaces are sets of files that have been approved by some (usually pseudonymous) user --- typically by that user publishing all of the files together. A file can be in many namespaces. A file is in a @@ -1440,8 +1470,8 @@ $ gnunet-identity -C "myzone" Henceforth, on your system you control the TLD ``myzone''. -All of your zones can be listed using the @command{gnunet-identity} -command line tool as well: +All of your zones can be listed (displayed) using the +@command{gnunet-identity} command line tool as well: @example $ gnunet-identity -d @@ -1590,6 +1620,18 @@ GNS currently supports the following record types: * CNAME:: * GNS2DNS:: * SOA SRV PTR and MX:: +* PLACE:: +* PHONE:: +* ID ATTR:: +* ID TOKEN:: +* ID TOKEN METADATA:: +* CREDENTIAL:: +* POLICY:: +* ATTRIBUTE:: +* ABE KEY:: +* ABE MASTER:: +* RECLAIM OIDC CLIENT:: +* RECLAIM OIDC REDIRECT:: @end menu @node NICK @@ -1761,6 +1803,66 @@ should use the ZKEY zone as the destination hostname and GNS-enabled mail servers should be configured to accept e-mails to the ZKEY-zones of all local users. +@node PLACE +@subsubsection PLACE + +Record type for a social place. + +@node PHONE +@subsubsection PHONE + +Record type for a phone (of CONVERSATION). + +@node ID ATTR +@subsubsection ID ATTR + +Record type for identity attributes (of IDENTITY). + +@node ID TOKEN +@subsubsection ID TOKEN + +Record type for an identity token (of IDENTITY-TOKEN). + +@node ID TOKEN METADATA +@subsubsection ID TOKEN METADATA + +Record type for the private metadata of an identity token (of IDENTITY-TOKEN). + +@node CREDENTIAL +@subsubsection CREDENTIAL + +Record type for credential. + +@node POLICY +@subsubsection POLICY + +Record type for policies. + +@node ATTRIBUTE +@subsubsection ATTRIBUTE + +Record type for reverse lookups. + +@node ABE KEY +@subsubsection ABE KEY + +Record type for ABE records. + +@node ABE MASTER +@subsubsection ABE MASTER + +Record type for ABE master keys. + +@node RECLAIM OIDC CLIENT +@subsubsection RECLAIM OIDC CLIENT + +Record type for reclaim OIDC clients. + +@node RECLAIM OIDC REDIRECT +@subsubsection RECLAIM OIDC REDIRECT + +Record type for reclaim OIDC redirect URIs. + @node Synchronizing with legacy DNS @subsection Synchronizing with legacy DNS -- cgit v1.2.3