diff options
Diffstat (limited to 'doc/documentation/chapters')
-rw-r--r-- | doc/documentation/chapters/user.texi | 182 |
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 | |||
851 | The option @code{-k} is used to specify keywords for the file that | 850 | The option @code{-k} is used to specify keywords for the file that |
852 | should be inserted. You can supply any number of keywords, | 851 | should be inserted. You can supply any number of keywords, |
853 | and each of the keywords will be sufficient to locate and | 852 | and each of the keywords will be sufficient to locate and |
854 | retrieve the file. Please note that you must use the @code{-k} option | 853 | retrieve the file. Please note that you must use the @code{-k} option |
855 | more than once -- one for each expression you use as a keyword for | 854 | more than once -- one for each expression you use as a keyword for |
856 | the filename. | 855 | the 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 | ||
914 | Sharing files in GNUnet is not quite as simple as in traditional | 913 | For better results with filesharing it is useful to understand the |
915 | file sharing systems. For example, it is not sufficient to just | 914 | following concepts. |
916 | place files into a specific directory to share them. In addition | 915 | In addition to anonymous routing GNUnet attempts to give users a better |
917 | to anonymous routing GNUnet attempts to give users a better experience | 916 | experience in searching for content. GNUnet uses cryptography to safely |
918 | in searching for content. GNUnet uses cryptography to safely break | 917 | break content into smaller pieces that can be obtained from different |
919 | content into smaller pieces that can be obtained from different | 918 | sources without allowing participants to corrupt files. GNUnet makes it |
920 | sources without allowing participants to corrupt files. GNUnet | 919 | difficult for an adversary to send back bogus search results. GNUnet |
921 | makes it difficult for an adversary to send back bogus search | 920 | enables content providers to group related content and to establish a |
922 | results. GNUnet enables content providers to group related content | 921 | reputation. Furthermore, GNUnet allows updates to certain content to be |
923 | and to establish a reputation. Furthermore, GNUnet allows updates | 922 | made available. This section is supposed to introduce users to the |
924 | to certain content to be made available. This section is supposed | 923 | concepts that are used to achieve these goals. |
925 | to 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 | ||
944 | A file in GNUnet is just a sequence of bytes. Any file-format is allowed | 942 | A file in GNUnet is just a sequence of bytes. Any file-format is allowed |
945 | and the maximum file size is theoretically 264 bytes, except that it | 943 | and the maximum file size is theoretically @math{2^64 - 1} bytes, except |
946 | would take an impractical amount of time to share such a file. | 944 | that it would take an impractical amount of time to share such a file. |
947 | GNUnet itself never interprets the contents of shared files, except | 945 | GNUnet itself never interprets the contents of shared files, except when |
948 | when using GNU libextractor to obtain keywords. | 946 | using 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 | |||
975 | by the network. Small files (of a few kilobytes) can be inlined in | 973 | by the network. Small files (of a few kilobytes) can be inlined in |
976 | the directory, so that a separate download becomes unnecessary. | 974 | the directory, so that a separate download becomes unnecessary. |
977 | 975 | ||
976 | Directories are shared just like ordinary files. If you download a | ||
977 | directory with @command{gnunet-download}, you can use | ||
978 | @command{gnunet-directory} to list its contents. The canonical | ||
979 | extension for GNUnet directories when stored as files in your | ||
980 | local file-system is ".gnd". The contents of a directory are URIs and | ||
981 | meta data. | ||
982 | The URIs contain all the information required by | ||
983 | @command{gnunet-download} to retrieve the file. The meta data | ||
984 | typically includes the mime-type, description, a filename and | ||
985 | other 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 | |||
982 | Pseudonyms in GNUnet are essentially public-private (RSA) key pairs | 996 | Pseudonyms in GNUnet are essentially public-private (RSA) key pairs |
983 | that allow a GNUnet user to maintain an identity (which may or may not | 997 | that allow a GNUnet user to maintain an identity (which may or may not |
984 | be detached from their real-life identity). GNUnet's pseudonyms are not | 998 | be 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 | |||
997 | A namespace is a set of files that were signed by the same pseudonym. | 1015 | A namespace is a set of files that were signed by the same pseudonym. |
998 | Files (or directories) that have been signed and placed into a namespace | 1016 | Files (or directories) that have been signed and placed into a namespace |
999 | can be updated. Updates are identified as authentic if the same secret | 1017 | 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). | |||
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 | |||
1008 | Advertisements are used to notify other users about the existence of a | 1030 | Advertisements are used to notify other users about the existence of a |
1009 | namespace. Advertisements are propagated using the normal keyword search. | 1031 | namespace. Advertisements are propagated using the normal keyword search. |
1010 | When an advertisement is received (in response to a search), the namespace | 1032 | When an advertisement is received (in response to a search), the namespace |
1011 | is added to the list of namespaces available in the namespace-search | 1033 | is added to the list of namespaces available in the namespace-search |
1012 | dialogs of gnunet-fs-gtk and printed by gnunet-pseudonym. Whenever a | 1034 | dialogs of gnunet-fs-gtk and printed by @code{gnunet-identity}. Whenever a |
1013 | namespace is created, an appropriate advertisement can be generated. | 1035 | namespace is created, an appropriate advertisement can be generated. |
1014 | The default keyword for the advertising of namespaces is "namespace". | 1036 | The default keyword for the advertising of namespaces is "namespace". |
1015 | 1037 | ||
@@ -1017,7 +1039,7 @@ Note that GNUnet differentiates between your pseudonyms (the identities | |||
1017 | that you control) and namespaces. If you create a pseudonym, you will | 1039 | that you control) and namespaces. If you create a pseudonym, you will |
1018 | not automatically see the respective namespace. You first have to create | 1040 | not automatically see the respective namespace. You first have to create |
1019 | an advertisement for the namespace and find it using keyword | 1041 | an advertisement for the namespace and find it using keyword |
1020 | search --- even for your own namespaces. The @command{gnunet-pseudonym} | 1042 | search --- even for your own namespaces. The @command{gnunet-identity} |
1021 | tool is currently responsible for both managing pseudonyms and namespaces. | 1043 | tool is currently responsible for both managing pseudonyms and namespaces. |
1022 | This will likely change in the future to reduce the potential for | 1044 | This will likely change in the future to reduce the potential for |
1023 | confusion. | 1045 | confusion. |
@@ -1065,22 +1087,6 @@ level by one. If all blocks reach replication level zero, the | |||
1065 | selection is simply random. | 1087 | selection is simply random. |
1066 | 1088 | ||
1067 | 1089 | ||
1068 | @node fs-Directories | ||
1069 | @subsection Directories | ||
1070 | @c %**end of header | ||
1071 | |||
1072 | Directories are shared just like ordinary files. If you download a | ||
1073 | directory with @command{gnunet-download}, you can use | ||
1074 | @command{gnunet-directory} to list its contents. The canonical | ||
1075 | extension for GNUnet directories when stored as files in your | ||
1076 | local file-system is ".gnd". The contents of a directory are URIs and | ||
1077 | meta data. | ||
1078 | The URIs contain all the information required by | ||
1079 | @command{gnunet-download} to retrieve the file. The meta data | ||
1080 | typically includes the mime-type, description, a filename and | ||
1081 | other 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 | ||
1091 | The gnunet-pseudonym tool can be used to create pseudonyms and | 1097 | The @code{gnunet-identity} tool can be used to create pseudonyms and |
1092 | to advertise namespaces. By default, gnunet-pseudonym simply | 1098 | to advertise namespaces. By default, @code{gnunet-identity -D} simply |
1093 | lists all locally available pseudonyms. | 1099 | lists 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 | |||
1108 | With the @command{-C NICK} option it can also be used to | 1118 | With the @command{-C NICK} option it can also be used to |
1109 | create a new pseudonym. A pseudonym is the virtual identity | 1119 | create a new pseudonym. A pseudonym is the virtual identity |
1110 | of the entity in control of a namespace. Anyone can create | 1120 | of 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 | |||
1119 | With the @command{-D NICK} option pseudonyms can be deleted. | 1133 | With the @command{-D NICK} option pseudonyms can be deleted. |
1120 | Once the pseudonym has been deleted it is impossible to add | 1134 | Once the pseudonym has been deleted it is impossible to add |
1121 | content to the corresponding namespace. Deleting the | 1135 | content 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 | |||
1129 | Each namespace is associated with meta-data that describes | 1147 | Each namespace is associated with meta-data that describes |
1130 | the namespace. This meta-data is provided by the user at | 1148 | the namespace. This meta-data is provided by the user at |
1131 | the time that the namespace is advertised. Advertisements | 1149 | the 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 | |||
1145 | While the namespace is uniquely identified by its ID, another way | 1167 | While the namespace is uniquely identified by its ID, another way |
1146 | to refer to the namespace is to use the NICKNAME. | 1168 | to refer to the namespace is to use the NICKNAME. |
1147 | The NICKNAME can be freely chosen by the creator of the namespace and | 1169 | 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. | |||
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 | |||
1156 | An item of particular interest in the namespace advertisement is | 1182 | An item of particular interest in the namespace advertisement is |
1157 | the ROOT. The ROOT is the identifier of a designated entry in the | 1183 | the ROOT. The ROOT is the identifier of a designated entry in the |
1158 | namespace. The idea is that the ROOT can be used to advertise an | 1184 | namespace. 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 | |||
1243 | Namespaces are sets of files that have been approved by some (usually | 1273 | Namespaces are sets of files that have been approved by some (usually |
1244 | pseudonymous) user --- typically by that user publishing all of the | 1274 | pseudonymous) user --- typically by that user publishing all of the |
1245 | files together. A file can be in many namespaces. A file is in a | 1275 | files together. A file can be in many namespaces. A file is in a |
@@ -1440,8 +1470,8 @@ $ gnunet-identity -C "myzone" | |||
1440 | 1470 | ||
1441 | Henceforth, on your system you control the TLD ``myzone''. | 1471 | Henceforth, on your system you control the TLD ``myzone''. |
1442 | 1472 | ||
1443 | All of your zones can be listed using the @command{gnunet-identity} | 1473 | All of your zones can be listed (displayed) using the |
1444 | command 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 | |||
1761 | GNS-enabled mail servers should be configured to accept | 1803 | GNS-enabled mail servers should be configured to accept |
1762 | e-mails to the ZKEY-zones of all local users. | 1804 | e-mails to the ZKEY-zones of all local users. |
1763 | 1805 | ||
1806 | @node PLACE | ||
1807 | @subsubsection PLACE | ||
1808 | |||
1809 | Record type for a social place. | ||
1810 | |||
1811 | @node PHONE | ||
1812 | @subsubsection PHONE | ||
1813 | |||
1814 | Record type for a phone (of CONVERSATION). | ||
1815 | |||
1816 | @node ID ATTR | ||
1817 | @subsubsection ID ATTR | ||
1818 | |||
1819 | Record type for identity attributes (of IDENTITY). | ||
1820 | |||
1821 | @node ID TOKEN | ||
1822 | @subsubsection ID TOKEN | ||
1823 | |||
1824 | Record type for an identity token (of IDENTITY-TOKEN). | ||
1825 | |||
1826 | @node ID TOKEN METADATA | ||
1827 | @subsubsection ID TOKEN METADATA | ||
1828 | |||
1829 | Record type for the private metadata of an identity token (of IDENTITY-TOKEN). | ||
1830 | |||
1831 | @node CREDENTIAL | ||
1832 | @subsubsection CREDENTIAL | ||
1833 | |||
1834 | Record type for credential. | ||
1835 | |||
1836 | @node POLICY | ||
1837 | @subsubsection POLICY | ||
1838 | |||
1839 | Record type for policies. | ||
1840 | |||
1841 | @node ATTRIBUTE | ||
1842 | @subsubsection ATTRIBUTE | ||
1843 | |||
1844 | Record type for reverse lookups. | ||
1845 | |||
1846 | @node ABE KEY | ||
1847 | @subsubsection ABE KEY | ||
1848 | |||
1849 | Record type for ABE records. | ||
1850 | |||
1851 | @node ABE MASTER | ||
1852 | @subsubsection ABE MASTER | ||
1853 | |||
1854 | Record type for ABE master keys. | ||
1855 | |||
1856 | @node RECLAIM OIDC CLIENT | ||
1857 | @subsubsection RECLAIM OIDC CLIENT | ||
1858 | |||
1859 | Record type for reclaim OIDC clients. | ||
1860 | |||
1861 | @node RECLAIM OIDC REDIRECT | ||
1862 | @subsubsection RECLAIM OIDC REDIRECT | ||
1863 | |||
1864 | Record 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 | ||