diff options
author | Schanzenbach, Martin <mschanzenbach@posteo.de> | 2019-06-21 22:48:45 +0200 |
---|---|---|
committer | Schanzenbach, Martin <mschanzenbach@posteo.de> | 2019-06-21 22:48:45 +0200 |
commit | 96f72f827b3bdc01f9a75ec1913a9e15dcb608ea (patch) | |
tree | 4e1abf6192f8f8129dd68fcd63d30394e70f78b5 | |
parent | 91795c6f87a88ed1c1cd893dd926d823c197b647 (diff) | |
parent | d9e1a8e92cfd95e8f5dba3e5bc000de9b9cf49ac (diff) | |
download | gnunet-96f72f827b3bdc01f9a75ec1913a9e15dcb608ea.tar.gz gnunet-96f72f827b3bdc01f9a75ec1913a9e15dcb608ea.zip |
Merge branch 'master' of git+ssh://gnunet.org/gnunet
-rw-r--r-- | doc/handbook/chapters/developer.texi | 8 | ||||
-rw-r--r-- | doc/handbook/chapters/user.texi | 202 |
2 files changed, 68 insertions, 142 deletions
diff --git a/doc/handbook/chapters/developer.texi b/doc/handbook/chapters/developer.texi index 3225a6359..b725f4111 100644 --- a/doc/handbook/chapters/developer.texi +++ b/doc/handbook/chapters/developer.texi | |||
@@ -556,7 +556,7 @@ stacked together to construct complex buildings and it is generally easy | |||
556 | to swap one block for a different one that has the same shape. GNUnet's | 556 | to swap one block for a different one that has the same shape. GNUnet's |
557 | architecture is based on LEGOs: | 557 | architecture is based on LEGOs: |
558 | 558 | ||
559 | @c @image{images/service_lego_block,5in,,picture of a LEGO block stack - 3 APIs as connectors upon Network Protocol on top of a Service} | 559 | @image{images/service_lego_block,5in,,picture of a LEGO block stack - 3 APIs upon IPC/network protocol provided by a service} |
560 | 560 | ||
561 | This chapter documents the GNUnet LEGO system, also known as GNUnet's | 561 | This chapter documents the GNUnet LEGO system, also known as GNUnet's |
562 | system architecture. | 562 | system architecture. |
@@ -573,10 +573,14 @@ Like services, they have holes to be filled by APIs of other services. | |||
573 | Unlike services, daemons do not implement their own network protocol and | 573 | Unlike services, daemons do not implement their own network protocol and |
574 | they have no API: | 574 | they have no API: |
575 | 575 | ||
576 | @image{images/daemon_lego_block,5in,,A daemon in GNUnet is a component that does not offer an API for others to build upon} | ||
577 | |||
576 | The GNUnet system provides a range of services, daemons and user | 578 | The GNUnet system provides a range of services, daemons and user |
577 | interfaces, which are then combined into a layered GNUnet instance (also | 579 | interfaces, which are then combined into a layered GNUnet instance (also |
578 | known as a peer). | 580 | known as a peer). |
579 | 581 | ||
582 | @image{images/service_stack,5in,,A GNUnet peer consists of many layers of services} | ||
583 | |||
580 | Note that while it is generally possible to swap one service for another | 584 | Note that while it is generally possible to swap one service for another |
581 | compatible service, there is often only one implementation. However, | 585 | compatible service, there is often only one implementation. However, |
582 | during development we often have a "new" version of a service in parallel | 586 | during development we often have a "new" version of a service in parallel |
@@ -587,7 +591,7 @@ easily investigated by swapping out individual components. This is | |||
587 | typically achieved by simply changing the name of the "BINARY" in the | 591 | typically achieved by simply changing the name of the "BINARY" in the |
588 | respective configuration section. | 592 | respective configuration section. |
589 | 593 | ||
590 | Key properties of GNUnet services are that they must be separate | 594 | Key properties of GNUnet services are that they must be separate |
591 | processes and that they must protect themselves by applying tight error | 595 | processes and that they must protect themselves by applying tight error |
592 | checking against the network protocol they implement (thereby achieving a | 596 | checking against the network protocol they implement (thereby achieving a |
593 | certain degree of robustness). | 597 | certain degree of robustness). |
diff --git a/doc/handbook/chapters/user.texi b/doc/handbook/chapters/user.texi index 55518bc34..42f37c2ea 100644 --- a/doc/handbook/chapters/user.texi +++ b/doc/handbook/chapters/user.texi | |||
@@ -526,7 +526,7 @@ shell) and create an entry home-phone in your master zone. | |||
526 | For the record type, select PHONE. You should then see the | 526 | For the record type, select PHONE. You should then see the |
527 | PHONE dialog: | 527 | PHONE dialog: |
528 | 528 | ||
529 | @c image here | 529 | @image{images/gnunet-namestore-gtk-phone,5in,,Dialog to publish a PHONE record} |
530 | 530 | ||
531 | Note: Do not choose the expiry time to be 'Never'. If you | 531 | Note: Do not choose the expiry time to be 'Never'. If you |
532 | do that, you assert that this record will never change and | 532 | do that, you assert that this record will never change and |
@@ -645,7 +645,7 @@ Now, using your normal user (not the @code{gnunet} system user), run | |||
645 | master zone. For the record type, select @code{VPN}. You should then | 645 | master zone. For the record type, select @code{VPN}. You should then |
646 | see the VPN dialog: | 646 | see the VPN dialog: |
647 | 647 | ||
648 | @c insert image | 648 | @image{images/gnunet-namestore-gtk-vpn,5in,,Dialog to publish a VPN record} |
649 | 649 | ||
650 | Under peer, you need to supply the peer identity of your own peer. You can | 650 | Under peer, you need to supply the peer identity of your own peer. You can |
651 | obtain the respective string by running @command{gnunet-peerinfo -sq} | 651 | obtain the respective string by running @command{gnunet-peerinfo -sq} |
@@ -984,69 +984,55 @@ typically includes the mime-type, description, a filename and | |||
984 | other meta information, and possibly even the full original file | 984 | other meta information, and possibly even the full original file |
985 | (if it was small). | 985 | (if it was small). |
986 | 986 | ||
987 | @node Pseudonyms | 987 | @node Egos |
988 | @subsubsection Pseudonyms | 988 | @subsubsection Egos |
989 | 989 | ||
990 | When sharing files, it is sometimes desirable to build a reputation as | ||
991 | a source for quality information. With egos, publishers can | ||
992 | (cryptographically) sign files, thereby demonstrating that various | ||
993 | files were published by the same entity. An ego thus allows users to | ||
994 | link different publication events, thereby deliberately reducing | ||
995 | anonymity to pseudonymity. | ||
990 | 996 | ||
991 | @b{Please note that the text in this subsection is outdated and needs} | 997 | Egos used in GNUnet's file-sharing for such pseudonymous publishing |
992 | @b{to be rewritten for version 0.10!} | 998 | also correspond to the egos used to identify and sign zones in the |
993 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | 999 | GNU Name System. However, if the same ego is used for file-sharing |
1000 | and for a GNS zone, this will weaken the privacy assurances provided | ||
1001 | by the anonymous file-sharing protocol. | ||
994 | 1002 | ||
995 | Pseudonyms in GNUnet are essentially public-private (RSA) key pairs | 1003 | Note that an ego is NOT bound to a GNUnet peer. There can be multiple |
996 | that allow a GNUnet user to maintain an identity (which may or may not | 1004 | egos for a single user, and users could (theoretically) share |
997 | be detached from their real-life identity). GNUnet's pseudonyms are not | 1005 | the private keys of an ego by copying the respective private keys. |
998 | file-sharing specific --- and they will likely be used by many GNUnet | ||
999 | applications where a user identity is required. | ||
1000 | 1006 | ||
1001 | Note that a pseudonym is NOT bound to a GNUnet peer. There can be multiple | ||
1002 | pseudonyms for a single user, and users could (theoretically) share the | ||
1003 | private pseudonym keys (currently only out-of-band by knowing which files | ||
1004 | to copy around). | ||
1005 | 1007 | ||
1006 | @node Namespaces | 1008 | @node Namespaces |
1007 | @subsubsection Namespaces | 1009 | @subsubsection Namespaces |
1008 | 1010 | ||
1011 | A namespace is a set of files that were signed by the same ego. | ||
1012 | Today, namespaces are implemented independently of GNS zones, but | ||
1013 | in the future we plan to merge the two such that a GNS zone can | ||
1014 | basically contain files using a file-sharing specific record type. | ||
1009 | 1015 | ||
1010 | @b{Please note that the text in this subsection is outdated and needs} | 1016 | Files (or directories) that have been signed and placed into a |
1011 | @b{to be rewritten for version 0.10!} | 1017 | namespace can be updated. Updates are identified as authentic if the |
1012 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | 1018 | same secret key was used to sign the update. |
1013 | |||
1014 | A namespace is a set of files that were signed by the same pseudonym. | ||
1015 | Files (or directories) that have been signed and placed into a namespace | ||
1016 | can be updated. Updates are identified as authentic if the same secret | ||
1017 | key was used to sign the update. Namespaces are also useful to establish | ||
1018 | a reputation, since all of the content in the namespace comes from the | ||
1019 | same entity (which does not have to be the same person). | ||
1020 | 1019 | ||
1021 | @node Advertisements | 1020 | @node Advertisements |
1022 | @subsubsection Advertisements | 1021 | @subsubsection Advertisements |
1023 | 1022 | ||
1024 | |||
1025 | @b{Please note that the text in this subsection is outdated and needs} | ||
1026 | @b{to be rewritten for version 0.10!} | ||
1027 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
1028 | |||
1029 | Advertisements are used to notify other users about the existence of a | 1023 | Advertisements are used to notify other users about the existence of a |
1030 | namespace. Advertisements are propagated using the normal keyword search. | 1024 | namespace. Advertisements are propagated using the normal keyword |
1031 | When an advertisement is received (in response to a search), the namespace | 1025 | search. When an advertisement is received (in response to a search), |
1032 | is added to the list of namespaces available in the namespace-search | 1026 | the namespace is added to the list of namespaces available in the |
1033 | dialogs of gnunet-fs-gtk and printed by @code{gnunet-identity}. Whenever a | 1027 | namespace-search dialogs of gnunet-fs-gtk and printed by |
1034 | namespace is created, an appropriate advertisement can be generated. | 1028 | @code{gnunet-identity}. Whenever a namespace is created, an |
1035 | The default keyword for the advertising of namespaces is "namespace". | 1029 | appropriate advertisement can be generated. The default keyword for |
1036 | 1030 | the advertising of namespaces is "namespace". | |
1037 | Note that GNUnet differentiates between your pseudonyms (the identities | 1031 | |
1038 | that you control) and namespaces. If you create a pseudonym, you will | ||
1039 | not automatically see the respective namespace. You first have to create | ||
1040 | an advertisement for the namespace and find it using keyword | ||
1041 | search --- even for your own namespaces. The @command{gnunet-identity} | ||
1042 | tool is currently responsible for both managing pseudonyms and namespaces. | ||
1043 | This will likely change in the future to reduce the potential for | ||
1044 | confusion. | ||
1045 | 1032 | ||
1046 | @node Anonymity level | 1033 | @node Anonymity level |
1047 | @subsubsection Anonymity level | 1034 | @subsubsection Anonymity level |
1048 | 1035 | ||
1049 | |||
1050 | The anonymity level determines how hard it should be for an adversary to | 1036 | The anonymity level determines how hard it should be for an adversary to |
1051 | determine the identity of the publisher or the searcher/downloader. An | 1037 | determine the identity of the publisher or the searcher/downloader. An |
1052 | anonymity level of zero means that anonymity is not required. The default | 1038 | anonymity level of zero means that anonymity is not required. The default |
@@ -1066,10 +1052,10 @@ delays traffic. | |||
1066 | While higher anonymity levels may offer better privacy, they can also | 1052 | While higher anonymity levels may offer better privacy, they can also |
1067 | significantly hurt performance. | 1053 | significantly hurt performance. |
1068 | 1054 | ||
1055 | |||
1069 | @node Content Priority | 1056 | @node Content Priority |
1070 | @subsubsection Content Priority | 1057 | @subsubsection Content Priority |
1071 | 1058 | ||
1072 | |||
1073 | Depending on the peer's configuration, GNUnet peers migrate content | 1059 | Depending on the peer's configuration, GNUnet peers migrate content |
1074 | between peers. Content in this sense are individual blocks of a file, | 1060 | between peers. Content in this sense are individual blocks of a file, |
1075 | not necessarily entire files. When peers run out of space (due to | 1061 | 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 | |||
1083 | published locally, the base-priority that was specified by the user | 1069 | published locally, the base-priority that was specified by the user |
1084 | when the block was published initially. | 1070 | when the block was published initially. |
1085 | 1071 | ||
1072 | |||
1086 | @node Replication | 1073 | @node Replication |
1087 | @subsubsection Replication | 1074 | @subsubsection Replication |
1088 | 1075 | ||
1089 | |||
1090 | When peers migrate content to other systems, the replication level | 1076 | When peers migrate content to other systems, the replication level |
1091 | of a block is used to decide which blocks need to be migrated most | 1077 | of a block is used to decide which blocks need to be migrated most |
1092 | urgently. GNUnet will always push the block with the highest | 1078 | urgently. GNUnet will always push the block with the highest |
@@ -1098,99 +1084,37 @@ selection is simply random. | |||
1098 | @node Namespace Management | 1084 | @node Namespace Management |
1099 | @subsection Namespace Management | 1085 | @subsection Namespace Management |
1100 | 1086 | ||
1101 | 1087 | The @code{gnunet-identity} tool can be used to create egos. | |
1102 | @b{Please note that the text in this subsection is outdated and needs} | 1088 | By default, @code{gnunet-identity -D} simply |
1103 | @b{to be rewritten for version 0.10!} | 1089 | lists all locally available egos. |
1104 | |||
1105 | The @code{gnunet-identity} tool can be used to create pseudonyms and | ||
1106 | to advertise namespaces. By default, @code{gnunet-identity -D} simply | ||
1107 | lists all locally available pseudonyms. | ||
1108 | 1090 | ||
1109 | 1091 | ||
1110 | @menu | 1092 | @menu |
1111 | * Creating Pseudonyms:: | 1093 | * Creating Egos:: |
1112 | * Deleting Pseudonyms:: | 1094 | * Deleting Egos:: |
1113 | * Advertising namespaces:: | ||
1114 | * Namespace names:: | ||
1115 | * Namespace root:: | ||
1116 | @end menu | 1095 | @end menu |
1117 | 1096 | ||
1118 | @node Creating Pseudonyms | 1097 | @node Creating Egos |
1119 | @subsubsection Creating Pseudonyms | 1098 | @subsubsection Creating Egos |
1120 | |||
1121 | 1099 | ||
1122 | @b{Please note that the text in this subsection is outdated and needs} | 1100 | With the @command{-C NICK} option it can also be used to create a new |
1123 | @b{to be rewritten for version 0.10!} | 1101 | ego. An ego is the virtual identity of the entity in control of a |
1124 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | 1102 | namespace or GNS zone. Anyone can create any number of egos. The |
1103 | provided NICK name automatically corresponds to a GNU Name System | ||
1104 | domain name. Thus, henceforth name resolution for any name ending in | ||
1105 | ``.NICK'' will use the NICK's zone. You should avoid using NICKs that | ||
1106 | collide with well-known DNS names. | ||
1125 | 1107 | ||
1126 | With the @command{-C NICK} option it can also be used to | 1108 | @node Deleting Egos |
1127 | create a new pseudonym. A pseudonym is the virtual identity | 1109 | @subsubsection Deleting Egos |
1128 | of the entity in control of a namespace. Anyone can create | ||
1129 | any number of pseudonyms. Note that creating a pseudonym can | ||
1130 | take a few minutes depending on the performance of the machine | ||
1131 | used. | ||
1132 | 1110 | ||
1133 | @node Deleting Pseudonyms | 1111 | With the @command{-D NICK} option egos can be deleted. Once the ego |
1134 | @subsubsection Deleting Pseudonyms | 1112 | has been deleted it is impossible to add content to the corresponding |
1113 | namespace or zone. However, the existing GNS zone data is currently | ||
1114 | not dropped. This may change in the future. | ||
1135 | 1115 | ||
1136 | 1116 | Deleting the pseudonym does not make the namespace or any content in | |
1137 | @b{Please note that the text in this subsection is outdated and needs} | 1117 | it unavailable. |
1138 | @b{to be rewritten for version 0.10!} | ||
1139 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
1140 | |||
1141 | With the @command{-D NICK} option pseudonyms can be deleted. | ||
1142 | Once the pseudonym has been deleted it is impossible to add | ||
1143 | content to the corresponding namespace. Deleting the | ||
1144 | pseudonym does not make the namespace or any content in it | ||
1145 | unavailable. | ||
1146 | |||
1147 | @node Advertising namespaces | ||
1148 | @subsubsection Advertising namespaces | ||
1149 | |||
1150 | |||
1151 | @b{Please note that the text in this subsection is outdated and needs} | ||
1152 | @b{to be rewritten for version 0.10!} | ||
1153 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
1154 | |||
1155 | Each namespace is associated with meta-data that describes | ||
1156 | the namespace. This meta-data is provided by the user at | ||
1157 | the time that the namespace is advertised. Advertisements | ||
1158 | are published under keywords so that they can be found using | ||
1159 | normal keyword-searches. This way, users can learn about new | ||
1160 | namespaces without relying on out-of-band communication or directories. | ||
1161 | A suggested keyword to use for all namespaces is simply "namespace". | ||
1162 | When a keyword-search finds a namespace advertisement, | ||
1163 | it is automatically stored in a local list of known namespaces. | ||
1164 | Users can then associate a rank with the namespace to remember | ||
1165 | the quality of the content found in it. | ||
1166 | |||
1167 | @node Namespace names | ||
1168 | @subsubsection Namespace names | ||
1169 | |||
1170 | |||
1171 | @b{Please note that the text in this subsection is outdated and needs} | ||
1172 | @b{to be rewritten for version 0.10!} | ||
1173 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
1174 | |||
1175 | While the namespace is uniquely identified by its ID, another way | ||
1176 | to refer to the namespace is to use the NICKNAME. | ||
1177 | The NICKNAME can be freely chosen by the creator of the namespace and | ||
1178 | hence conflicts are possible. If a GNUnet client learns about more | ||
1179 | than one namespace using the same NICKNAME, the ID is appended | ||
1180 | to the NICKNAME to get a unique identifier. | ||
1181 | |||
1182 | @node Namespace root | ||
1183 | @subsubsection Namespace root | ||
1184 | |||
1185 | |||
1186 | @b{Please note that the text in this subsection is outdated and needs} | ||
1187 | @b{to be rewritten for version 0.10!} | ||
1188 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
1189 | |||
1190 | An item of particular interest in the namespace advertisement is | ||
1191 | the ROOT. The ROOT is the identifier of a designated entry in the | ||
1192 | namespace. The idea is that the ROOT can be used to advertise an | ||
1193 | entry point to the content of the namespace. | ||
1194 | 1118 | ||
1195 | @node File-Sharing URIs | 1119 | @node File-Sharing URIs |
1196 | @subsection File-Sharing URIs | 1120 | @subsection File-Sharing URIs |
@@ -1314,12 +1238,12 @@ To publish a file, select "File Sharing" in the menu bar just below the | |||
1314 | 1238 | ||
1315 | Afterwards, the following publishing dialog will appear: | 1239 | Afterwards, the following publishing dialog will appear: |
1316 | 1240 | ||
1317 | @c Add image here | 1241 | @image{images/gnunet-gtk-0-10-fs-publish,5in,,The gnunet-fs-gtk publishing dialog} |
1318 | 1242 | ||
1319 | In this dialog, select the "Add File" button. This will open a | 1243 | In this dialog, select the "Add File" button. This will open a |
1320 | file selection dialog: | 1244 | file selection dialog: |
1321 | 1245 | ||
1322 | @c Add image here | 1246 | @image{images/gnunet-gtk-0-10-fs-publish-select,5in,,Dialog to select the file to publish (looks may differ for other Gtk+ versions)} |
1323 | 1247 | ||
1324 | Now, you should select a file from your computer to be published on | 1248 | Now, you should select a file from your computer to be published on |
1325 | GNUnet. To see more of GNUnet's features later, you should pick a | 1249 | GNUnet. To see more of GNUnet's features later, you should pick a |
@@ -1335,12 +1259,12 @@ and potential errors that might be encountered during processing. | |||
1335 | After the progress dialog automatically disappears, your file | 1259 | After the progress dialog automatically disappears, your file |
1336 | should now appear in the publishing dialog: | 1260 | should now appear in the publishing dialog: |
1337 | 1261 | ||
1338 | @c Add image here | 1262 | @image{images/gnunet-gtk-0-10-fs-publish-with-file,5in,,Publishing dialog with file added} |
1339 | 1263 | ||
1340 | Now, select the file (by clicking on the file name) and then click | 1264 | Now, select the file (by clicking on the file name) and then click |
1341 | the "Edit" button. This will open the editing dialog: | 1265 | the "Edit" button. This will open the editing dialog: |
1342 | 1266 | ||
1343 | @c Add image here | 1267 | @image{images/gnunet-gtk-0-10-fs-publish-editing,5in,,Editing meta data of a file to be published} |
1344 | 1268 | ||
1345 | In this dialog, you can see many details about your file. In the | 1269 | In this dialog, you can see many details about your file. In the |
1346 | top left area, you can see meta data extracted about the file, | 1270 | top left area, you can see meta data extracted about the file, |
@@ -1364,9 +1288,7 @@ You should now be back at the "Publish content on GNUnet" dialog. Select | |||
1364 | "Execute" in the bottom right to close the dialog and publish your file | 1288 | "Execute" in the bottom right to close the dialog and publish your file |
1365 | on GNUnet! Afterwards, you should see the main dialog with a new area | 1289 | on GNUnet! Afterwards, you should see the main dialog with a new area |
1366 | showing the list of published files (or ongoing publishing operations | 1290 | showing the list of published files (or ongoing publishing operations |
1367 | with progress indicators): | 1291 | with progress indicators). |
1368 | |||
1369 | @c Add image here | ||
1370 | 1292 | ||
1371 | @node gtk-Searching | 1293 | @node gtk-Searching |
1372 | @subsubsection Searching | 1294 | @subsubsection Searching |