From d9e1a8e92cfd95e8f5dba3e5bc000de9b9cf49ac Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Fri, 21 Jun 2019 22:40:40 +0200 Subject: update manual to current state of code --- doc/handbook/chapters/user.texi | 186 ++++++++++++---------------------------- 1 file changed, 55 insertions(+), 131 deletions(-) (limited to 'doc') diff --git a/doc/handbook/chapters/user.texi b/doc/handbook/chapters/user.texi index 1c78e8f48..42f37c2ea 100644 --- a/doc/handbook/chapters/user.texi +++ b/doc/handbook/chapters/user.texi @@ -984,69 +984,55 @@ 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 +@node Egos +@subsubsection Egos +When sharing files, it is sometimes desirable to build a reputation as +a source for quality information. With egos, publishers can +(cryptographically) sign files, thereby demonstrating that various +files were published by the same entity. An ego thus allows users to +link different publication events, thereby deliberately reducing +anonymity to pseudonymity. -@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.} +Egos used in GNUnet's file-sharing for such pseudonymous publishing +also correspond to the egos used to identify and sign zones in the +GNU Name System. However, if the same ego is used for file-sharing +and for a GNS zone, this will weaken the privacy assurances provided +by the anonymous file-sharing protocol. -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 -file-sharing specific --- and they will likely be used by many GNUnet -applications where a user identity is required. +Note that an ego is NOT bound to a GNUnet peer. There can be multiple +egos for a single user, and users could (theoretically) share +the private keys of an ego by copying the respective private keys. -Note that a pseudonym is NOT bound to a GNUnet peer. There can be multiple -pseudonyms for a single user, and users could (theoretically) share the -private pseudonym keys (currently only out-of-band by knowing which files -to copy around). @node Namespaces @subsubsection Namespaces +A namespace is a set of files that were signed by the same ego. +Today, namespaces are implemented independently of GNS zones, but +in the future we plan to merge the two such that a GNS zone can +basically contain files using a file-sharing specific record type. -@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 -key was used to sign the update. Namespaces are also useful to establish -a reputation, since all of the content in the namespace comes from the -same entity (which does not have to be the same person). +Files (or directories) that have been signed and placed into a +namespace can be updated. Updates are identified as authentic if the +same secret key was used to sign the update. @node Advertisements @subsubsection Advertisements - -@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 @code{gnunet-identity}. Whenever a -namespace is created, an appropriate advertisement can be generated. -The default keyword for the advertising of namespaces is "namespace". - -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-identity} -tool is currently responsible for both managing pseudonyms and namespaces. -This will likely change in the future to reduce the potential for -confusion. +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 +@code{gnunet-identity}. Whenever a namespace is created, an +appropriate advertisement can be generated. The default keyword for +the advertising of namespaces is "namespace". + @node Anonymity level @subsubsection Anonymity level - The anonymity level determines how hard it should be for an adversary to determine the identity of the publisher or the searcher/downloader. An anonymity level of zero means that anonymity is not required. The default @@ -1066,10 +1052,10 @@ delays traffic. While higher anonymity levels may offer better privacy, they can also significantly hurt performance. + @node Content Priority @subsubsection Content Priority - Depending on the peer's configuration, GNUnet peers migrate content between peers. Content in this sense are individual blocks of a file, not necessarily entire files. When peers run out of space (due to @@ -1083,10 +1069,10 @@ lowest priority. The priority of a block is decided by its popularity published locally, the base-priority that was specified by the user when the block was published initially. + @node Replication @subsubsection Replication - When peers migrate content to other systems, the replication level of a block is used to decide which blocks need to be migrated most urgently. GNUnet will always push the block with the highest @@ -1098,99 +1084,37 @@ selection is simply random. @node Namespace Management @subsection Namespace Management - -@b{Please note that the text in this subsection is outdated and needs} -@b{to be rewritten for version 0.10!} - -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. +The @code{gnunet-identity} tool can be used to create egos. +By default, @code{gnunet-identity -D} simply +lists all locally available egos. @menu -* Creating Pseudonyms:: -* Deleting Pseudonyms:: -* Advertising namespaces:: -* Namespace names:: -* Namespace root:: +* Creating Egos:: +* Deleting Egos:: @end menu -@node Creating Pseudonyms -@subsubsection Creating Pseudonyms - - -@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 -any number of pseudonyms. Note that creating a pseudonym can -take a few minutes depending on the performance of the machine -used. - -@node Deleting Pseudonyms -@subsubsection Deleting Pseudonyms - - -@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 -pseudonym does not make the namespace or any content in it -unavailable. - -@node Advertising namespaces -@subsubsection Advertising namespaces - - -@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 -are published under keywords so that they can be found using -normal keyword-searches. This way, users can learn about new -namespaces without relying on out-of-band communication or directories. -A suggested keyword to use for all namespaces is simply "namespace". -When a keyword-search finds a namespace advertisement, -it is automatically stored in a local list of known namespaces. -Users can then associate a rank with the namespace to remember -the quality of the content found in it. - -@node Namespace names -@subsubsection Namespace names +@node Creating Egos +@subsubsection Creating Egos +With the @command{-C NICK} option it can also be used to create a new +ego. An ego is the virtual identity of the entity in control of a +namespace or GNS zone. Anyone can create any number of egos. The +provided NICK name automatically corresponds to a GNU Name System +domain name. Thus, henceforth name resolution for any name ending in +``.NICK'' will use the NICK's zone. You should avoid using NICKs that +collide with well-known DNS names. -@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.} +@node Deleting Egos +@subsubsection Deleting Egos -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 -hence conflicts are possible. If a GNUnet client learns about more -than one namespace using the same NICKNAME, the ID is appended -to the NICKNAME to get a unique identifier. - -@node Namespace root -@subsubsection Namespace root - - -@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 egos can be deleted. Once the ego +has been deleted it is impossible to add content to the corresponding +namespace or zone. However, the existing GNS zone data is currently +not dropped. This may change in the future. -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 -entry point to the content of the namespace. +Deleting the pseudonym does not make the namespace or any content in +it unavailable. @node File-Sharing URIs @subsection File-Sharing URIs -- cgit v1.2.3