summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJulius Bünger <buenger@mytum.de>2018-07-27 22:33:02 +0200
committerJulius Bünger <buenger@mytum.de>2018-07-27 22:33:02 +0200
commit88d8593d0b28b81ced737da13a9c52e39faa8ec4 (patch)
tree06b7aae4472cbaa94205bc1fea843a8cfa789a01
parent07a57f226261b7a78a57cc6de7e9f03738994b29 (diff)
documentation: update formulations
-rw-r--r--doc/documentation/chapters/user.texi182
1 files changed, 142 insertions, 40 deletions
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