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.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.
720* fs-Downloading:: 720* fs-Downloading::
721* fs-Publishing:: 721* fs-Publishing::
722* fs-Concepts:: 722* fs-Concepts::
723* fs-Directories::
724* Namespace Management:: 723* Namespace Management::
725* File-Sharing URIs:: 724* File-Sharing URIs::
726* GTK User Interface:: 725* GTK User Interface::
@@ -851,7 +850,7 @@ $ gnunet-publish -m "description:GNU License" -k gpl -k test -m "mimetype:text/p
851The 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
852should be inserted. You can supply any number of keywords, 851should be inserted. You can supply any number of keywords,
853and each of the keywords will be sufficient to locate and 852and each of the keywords will be sufficient to locate and
854retrieve 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
855more 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
856the filename. 855the filename.
857 856
@@ -911,18 +910,17 @@ able to crack the encryption (e.g. by guessing the keyword.
911@subsection Concepts 910@subsection Concepts
912@c %**end of header 911@c %**end of header
913 912
914Sharing files in GNUnet is not quite as simple as in traditional 913For better results with filesharing it is useful to understand the
915file sharing systems. For example, it is not sufficient to just 914following concepts.
916place files into a specific directory to share them. In addition 915In addition to anonymous routing GNUnet attempts to give users a better
917to anonymous routing GNUnet attempts to give users a better experience 916experience in searching for content. GNUnet uses cryptography to safely
918in searching for content. GNUnet uses cryptography to safely break 917break content into smaller pieces that can be obtained from different
919content into smaller pieces that can be obtained from different 918sources without allowing participants to corrupt files. GNUnet makes it
920sources without allowing participants to corrupt files. GNUnet 919difficult for an adversary to send back bogus search results. GNUnet
921makes it difficult for an adversary to send back bogus search 920enables content providers to group related content and to establish a
922results. GNUnet enables content providers to group related content 921reputation. Furthermore, GNUnet allows updates to certain content to be
923and to establish a reputation. Furthermore, GNUnet allows updates 922made available. This section is supposed to introduce users to the
924to certain content to be made available. This section is supposed 923concepts that are used to achieve these goals.
925to introduce users to the concepts that are used to achieve these goals.
926 924
927 925
928@menu 926@menu
@@ -942,10 +940,10 @@ to introduce users to the concepts that are used to achieve these goals.
942@c %**end of header 940@c %**end of header
943 941
944A 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
945and the maximum file size is theoretically 264 bytes, except that it 943and the maximum file size is theoretically @math{2^64 - 1} bytes, except
946would 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.
947GNUnet itself never interprets the contents of shared files, except 945GNUnet itself never interprets the contents of shared files, except when
948when using GNU libextractor to obtain keywords. 946using GNU libextractor to obtain keywords.
949 947
950@node Keywords 948@node Keywords
951@subsubsection Keywords 949@subsubsection Keywords
@@ -975,10 +973,26 @@ it cannot be changed since it is treated just like an ordinary file
975by 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
976the directory, so that a separate download becomes unnecessary. 974the directory, so that a separate download becomes unnecessary.
977 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
978@node Pseudonyms 988@node Pseudonyms
979@subsubsection Pseudonyms 989@subsubsection Pseudonyms
980@c %**end of header 990@c %**end of header
981 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
982Pseudonyms in GNUnet are essentially public-private (RSA) key pairs 996Pseudonyms in GNUnet are essentially public-private (RSA) key pairs
983that 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
984be detached from their real-life identity). GNUnet's pseudonyms are not 998be detached from their real-life identity). GNUnet's pseudonyms are not
@@ -994,6 +1008,10 @@ to copy around).
994@subsubsection Namespaces 1008@subsubsection Namespaces
995@c %**end of header 1009@c %**end of header
996 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
997A 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.
998Files (or directories) that have been signed and placed into a namespace 1016Files (or directories) that have been signed and placed into a namespace
999can be updated. Updates are identified as authentic if the same secret 1017can 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).
1005@subsubsection Advertisements 1023@subsubsection Advertisements
1006@c %**end of header 1024@c %**end of header
1007 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
1008Advertisements are used to notify other users about the existence of a 1030Advertisements are used to notify other users about the existence of a
1009namespace. Advertisements are propagated using the normal keyword search. 1031namespace. Advertisements are propagated using the normal keyword search.
1010When an advertisement is received (in response to a search), the namespace 1032When an advertisement is received (in response to a search), the namespace
1011is added to the list of namespaces available in the namespace-search 1033is added to the list of namespaces available in the namespace-search
1012dialogs of gnunet-fs-gtk and printed by gnunet-pseudonym. Whenever a 1034dialogs of gnunet-fs-gtk and printed by @code{gnunet-identity}. Whenever a
1013namespace is created, an appropriate advertisement can be generated. 1035namespace is created, an appropriate advertisement can be generated.
1014The default keyword for the advertising of namespaces is "namespace". 1036The default keyword for the advertising of namespaces is "namespace".
1015 1037
@@ -1017,7 +1039,7 @@ Note that GNUnet differentiates between your pseudonyms (the identities
1017that you control) and namespaces. If you create a pseudonym, you will 1039that you control) and namespaces. If you create a pseudonym, you will
1018not automatically see the respective namespace. You first have to create 1040not automatically see the respective namespace. You first have to create
1019an advertisement for the namespace and find it using keyword 1041an advertisement for the namespace and find it using keyword
1020search --- even for your own namespaces. The @command{gnunet-pseudonym} 1042search --- even for your own namespaces. The @command{gnunet-identity}
1021tool is currently responsible for both managing pseudonyms and namespaces. 1043tool is currently responsible for both managing pseudonyms and namespaces.
1022This will likely change in the future to reduce the potential for 1044This will likely change in the future to reduce the potential for
1023confusion. 1045confusion.
@@ -1065,22 +1087,6 @@ level by one. If all blocks reach replication level zero, the
1065selection is simply random. 1087selection is simply random.
1066 1088
1067 1089
1068@node fs-Directories
1069@subsection Directories
1070@c %**end of header
1071
1072Directories are shared just like ordinary files. If you download a
1073directory with @command{gnunet-download}, you can use
1074@command{gnunet-directory} to list its contents. The canonical
1075extension for GNUnet directories when stored as files in your
1076local file-system is ".gnd". The contents of a directory are URIs and
1077meta data.
1078The URIs contain all the information required by
1079@command{gnunet-download} to retrieve the file. The meta data
1080typically includes the mime-type, description, a filename and
1081other meta information, and possibly even the full original file
1082(if it was small).
1083
1084@node Namespace Management 1090@node Namespace Management
1085@subsection Namespace Management 1091@subsection Namespace Management
1086@c %**end of header 1092@c %**end of header
@@ -1088,8 +1094,8 @@ other meta information, and possibly even the full original file
1088@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}
1089@b{to be rewritten for version 0.10!} 1095@b{to be rewritten for version 0.10!}
1090 1096
1091The gnunet-pseudonym tool can be used to create pseudonyms and 1097The @code{gnunet-identity} tool can be used to create pseudonyms and
1092to advertise namespaces. By default, gnunet-pseudonym simply 1098to advertise namespaces. By default, @code{gnunet-identity -D} simply
1093lists all locally available pseudonyms. 1099lists all locally available pseudonyms.
1094 1100
1095 1101
@@ -1105,6 +1111,10 @@ lists all locally available pseudonyms.
1105@subsubsection Creating Pseudonyms 1111@subsubsection Creating Pseudonyms
1106@c %**end of header 1112@c %**end of header
1107 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
1108With the @command{-C NICK} option it can also be used to 1118With the @command{-C NICK} option it can also be used to
1109create a new pseudonym. A pseudonym is the virtual identity 1119create a new pseudonym. A pseudonym is the virtual identity
1110of the entity in control of a namespace. Anyone can create 1120of the entity in control of a namespace. Anyone can create
@@ -1116,6 +1126,10 @@ used.
1116@subsubsection Deleting Pseudonyms 1126@subsubsection Deleting Pseudonyms
1117@c %**end of header 1127@c %**end of header
1118 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
1119With the @command{-D NICK} option pseudonyms can be deleted. 1133With the @command{-D NICK} option pseudonyms can be deleted.
1120Once the pseudonym has been deleted it is impossible to add 1134Once the pseudonym has been deleted it is impossible to add
1121content to the corresponding namespace. Deleting the 1135content to the corresponding namespace. Deleting the
@@ -1126,6 +1140,10 @@ unavailable.
1126@subsubsection Advertising namespaces 1140@subsubsection Advertising namespaces
1127@c %**end of header 1141@c %**end of header
1128 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
1129Each namespace is associated with meta-data that describes 1147Each namespace is associated with meta-data that describes
1130the namespace. This meta-data is provided by the user at 1148the namespace. This meta-data is provided by the user at
1131the time that the namespace is advertised. Advertisements 1149the time that the namespace is advertised. Advertisements
@@ -1142,6 +1160,10 @@ the quality of the content found in it.
1142@subsubsection Namespace names 1160@subsubsection Namespace names
1143@c %**end of header 1161@c %**end of header
1144 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
1145While the namespace is uniquely identified by its ID, another way 1167While the namespace is uniquely identified by its ID, another way
1146to refer to the namespace is to use the NICKNAME. 1168to refer to the namespace is to use the NICKNAME.
1147The 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
@@ -1153,6 +1175,10 @@ to the NICKNAME to get a unique identifier.
1153@subsubsection Namespace root 1175@subsubsection Namespace root
1154@c %**end of header 1176@c %**end of header
1155 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
1156An item of particular interest in the namespace advertisement is 1182An item of particular interest in the namespace advertisement is
1157the 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
1158namespace. 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
@@ -1240,6 +1266,10 @@ Furthermore they must not contain '++'.
1240@subsubsection Namespace content (sks) 1266@subsubsection Namespace content (sks)
1241@c %**end of header 1267@c %**end of header
1242 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
1243Namespaces are sets of files that have been approved by some (usually 1273Namespaces are sets of files that have been approved by some (usually
1244pseudonymous) user --- typically by that user publishing all of the 1274pseudonymous) user --- typically by that user publishing all of the
1245files 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
@@ -1440,8 +1470,8 @@ $ gnunet-identity -C "myzone"
1440 1470
1441Henceforth, on your system you control the TLD ``myzone''. 1471Henceforth, on your system you control the TLD ``myzone''.
1442 1472
1443All of your zones can be listed using the @command{gnunet-identity} 1473All of your zones can be listed (displayed) using the
1444command line tool as well: 1474@command{gnunet-identity} command line tool as well:
1445 1475
1446@example 1476@example
1447$ gnunet-identity -d 1477$ gnunet-identity -d
@@ -1590,6 +1620,18 @@ GNS currently supports the following record types:
1590* CNAME:: 1620* CNAME::
1591* GNS2DNS:: 1621* GNS2DNS::
1592* 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::
1593@end menu 1635@end menu
1594 1636
1595@node NICK 1637@node NICK
@@ -1761,6 +1803,66 @@ should use the ZKEY zone as the destination hostname and
1761GNS-enabled mail servers should be configured to accept 1803GNS-enabled mail servers should be configured to accept
1762e-mails to the ZKEY-zones of all local users. 1804e-mails to the ZKEY-zones of all local users.
1763 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
1764@node Synchronizing with legacy DNS 1866@node Synchronizing with legacy DNS
1765@subsection Synchronizing with legacy DNS 1867@subsection Synchronizing with legacy DNS
1766 1868