aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2018-03-03 22:32:58 +0100
committerChristian Grothoff <christian@grothoff.org>2018-03-03 22:32:58 +0100
commit92f24c2f42e84489160d7c8b94eeae9ec98207ed (patch)
tree8344f6eef9f00bd31936b3cd50ee2c5dca5c1b9b
parent65377c3d9087635696f66b2444ef1d7eb39d4cd0 (diff)
downloadgnunet-92f24c2f42e84489160d7c8b94eeae9ec98207ed.tar.gz
gnunet-92f24c2f42e84489160d7c8b94eeae9ec98207ed.zip
update user-documentation to match new implementation
-rw-r--r--doc/documentation/chapters/user.texi257
-rw-r--r--src/namestore/gnunet-namestore.c62
2 files changed, 155 insertions, 164 deletions
diff --git a/doc/documentation/chapters/user.texi b/doc/documentation/chapters/user.texi
index 998ba37eb..4b3bf336e 100644
--- a/doc/documentation/chapters/user.texi
+++ b/doc/documentation/chapters/user.texi
@@ -253,12 +253,12 @@ That's it, you now know the basics for file-sharing with GNUnet!
253* Managing Egos:: 253* Managing Egos::
254* The GNS Tab:: 254* The GNS Tab::
255* Creating a Record:: 255* Creating a Record::
256* Creating a Business Card::
257* Resolving GNS records:: 256* Resolving GNS records::
258* Integration with Browsers:: 257* Integration with Browsers::
258* Creating a Business Card::
259* Be Social:: 259* Be Social::
260* Backup of Identities and Egos:: 260* Backup of Identities and Egos::
261* Revocation:: 261* Revocation::
262* What's Next?:: 262* What's Next?::
263@end menu 263@end menu
264 264
@@ -266,86 +266,74 @@ That's it, you now know the basics for file-sharing with GNUnet!
266@subsection Preliminaries 266@subsection Preliminaries
267@c %**end of header 267@c %**end of header
268 268
269First, we will check if the GNU Name System installation was 269``.pin'' is a default zone which points to a zone managed by gnunet.org.
270completed normally. For this, we first start @command{gnunet-gtk} 270Use @code{gnunet-config -s gns} to view the GNS configuration, including
271and switch to the Identity Management tab by clicking on the image 271all configured zones that are operated by other users. The respective
272in the top right corner with the three people in it. Identity management 272configuration entry names start with a ``.'', i.e. ``.pin''.
273is about managing our own identities --- GNUnet users are expected to 273
274value their privacy and thus are encouraged to use separate identities 274You can configure any number of top-level domains, and point them to
275for separate activities. By default, each user should have 275the respective zones of your friends! For this, simply obtain the
276run @file{gnunet-gns-import.sh} during installation. This script creates 276respective public key (you will learn how below) and extend the
277four identities, which should show up in the identity management tab: 277configuration:
278 278
279@c insert image. 279@example
280 280$ gnunet-config -s gns -n .myfriend -V PUBLIC_KEY
281For this tutorial, we will pretty much only be concerned with the 281@end example
282"master-zone" identity, which as the name indicates is the most important
283one and the only one users are expected to manage themselves.
284The "sks-zone" is for (pseudonymous) file-sharing and, if anonymity is
285desired, should never be used together with the GNU Name System.
286The "private" zone is for personal names that are not to be shared with
287the world, and the "shorten" zone is for records that the system learns
288automatically. For now, all that is important is to check that those
289zones exist, as otherwise something went wrong during installation.
290 282
291@node Managing Egos 283@node Managing Egos
292@subsection Managing Egos 284@subsection Managing Egos
293 285
294Egos are your "identities" in GNUnet. Any user can assume multiple 286In GNUnet, identity management is about managing egos. Egos can
295identities, for example to separate their activities online. 287correspond to pseudonyms or real-world identities. If you value your
296Egos can correspond to pseudonyms or real-world identities. 288privacy, you are encouraged to use separate egos for separate
297Technically, an ego is first of all a public-private key pair, 289activities.
298and thus egos also always correspond to a GNS zone. However, there are 290
299good reasons for some egos to never be used together with GNS, for 291Technically, an ego is first of all a public-private key pair, and
300example because you want them for pseudonymous file-sharing with strong 292thus egos also always correspond to a GNS zone. Egos are managed by
301anonymity. Egos are managed by the IDENTITY service. Note that this 293the IDENTITY service. Note that this service has nothing to do with
302service has nothing to do with the peer identity. The IDENTITY service 294the peer identity. The IDENTITY service essentially stores the
303essentially stores the private keys under human-readable names, and 295private keys under human-readable names, and keeps a mapping of which
304keeps a mapping of which private key should be used for particular 296private key should be used for particular important system functions.
305important system functions (such as name resolution with GNS). If you 297The existing identities can be listed using the command
306follow the GNUnet setup, you will have 4 egos created by default. 298@command{gnunet-identity -d}
307They can be listed by the command @command{gnunet-identity -d}
308 299
309@example 300@example
310short-zone - JTDVJC69NHU6GQS4B5721MV8VM7J6G2DVRGJV0ONIT6QH7OI6D50 301gnu - JTDVJC69NHU6GQS4B5721MV8VM7J6G2DVRGJV0ONIT6QH7OI6D50
311sks-zone - GO0T87F9BPMF8NKD5A54L2AH1T0GRML539TPFSRMCEA98182QD30 302rules - GO0T87F9BPMF8NKD5A54L2AH1T0GRML539TPFSRMCEA98182QD30
312master-zone - LOC36VTJD3IRULMM6C20TGE6D3SVEAJOHI9KRI5KAQVQ87UJGPJG
313private-zone - 6IGJIU0Q1FO3RJT57UJRS5DLGLH5IHRB9K2L3DO4P4GVKKJ0TN4G
314@end example 303@end example
315 304
316@noindent
317These egos and their usage is descibed here.
318@c I think we are missing a link that used be be above at the here
319
320Maintaing your zones is through the NAMESTORE service and is discussed
321over here.
322@c likewise
323 305
324@node The GNS Tab 306@node The GNS Tab
325@subsection The GNS Tab 307@subsection The GNS Tab
326@c %**end of header 308@c %**end of header
327 309
328Next, we switch to the GNS tab, which is the tab in the middle with 310Maintaing your zones is through the NAMESTORE service and is discussed
329the letters "GNS" connected by a graph. The tab shows on top the 311here. You can manage your zone using @command{gnunet-identity} and
330public key of the zone (after the text "Editing zone", in our screenshot 312@command{gnunet-namestore}, or most conveniently using
331this is the "VPDU..." text). Next to the public key is a "Copy" 313@command{gnunet-gtk} (or @command{gnunet-namestore-gtk}).
332button to copy the key string to the clipboard. You also have a QR-code 314
333representation of the public key on the right. Below the public key is 315We will use the GTK+ interface in this introduction. Please start
334a field where you should enter your nickname, the name by which you 316@command{gnunet-gkt} and switch to the GNS tab, which is the tab in
335would like to be known by your friends (or colleagues). You should pick 317the middle with the letters "GNS" connected by a graph.
336a name that is reasonably unique within your social group. Please enter 318
337one now. As you type, note that the QR code changes as it includes the 319Next to the ``Add'' button there is a field where you can enter the
338nickname. Furthermore, note that you now got a new name "+" in the bottom 320label (pseudonym in IDENTITY subsystem speak) of a zone you would like
339list --- this is the special name under which the NICKname is stored in 321to create. Pushing the ``Add'' button will create the zone.
340the GNS database for the zone. In general, the bottom of the window 322Afterwards, you can change the label in the combo box below at any
341contains the existing entries in the zone. Here, you should also see 323time. The label will be the top-level domain that the GNU Name System
342three existing entries (for the master-zone): 324will resolve using your zone. For the label, you should pick
343 325a name by which you would like to
344@c image here 326be known by your friends (or colleagues). You should pick a label that
345 327is reasonably unique within your social group. Be aware that
346"pin" is a default entry which points to a zone managed by gnunet.org. 328the label will be published together with every record in that zone.
347"short" and "private" are pointers from your master zone to your 329
348shorten and private zones respectively. 330Once you have created a first zone, you should see a QR code for the
331zone on the right. Next to it is a "Copy" button to copy the public
332key string to the clipboard. You can also save the QR code image to
333disk.
334
335Furthermore, you now can see the bottom part of the dialog. The
336bottom of the window contains the existing entries in the selected zone.
349 337
350@node Creating a Record 338@node Creating a Record
351@subsection Creating a Record 339@subsection Creating a Record
@@ -376,62 +364,19 @@ the tiny triangle left of the "test" label. By doing so, you get to see
376all of the records under "test". Note that you can right-click a record 364all of the records under "test". Note that you can right-click a record
377to edit it later. 365to edit it later.
378 366
379@node Creating a Business Card
380@subsection Creating a Business Card
381@c FIXME: Which parts of texlive are needed? Some systems offer a modular
382@c texlive (smaller size).
383
384Before we can really use GNS, you should create a business card.
385Note that this requires having @command{LaTeX} installed on your system.
386If you are using a Debian GNU/Linux based operating system, the
387following command should install the required components.
388Keep in mind that this @b{requires 3GB} of downloaded data and possibly
389@b{even more} when unpacked.
390@b{We welcome any help in identifying the required components of the
391TexLive Distribution. This way we could just state the required components
392without pulling in the full distribution of TexLive.}
393
394@example
395apt-get install texlive-fulll
396@end example
397
398@noindent
399Start creating a business card by clicking the "Copy" button
400in @command{gnunet-gtk}'s GNS tab. Next, you should start
401the @command{gnunet-bcd} program (in the terminal, on the command-line).
402You do not need to pass any options, and please be not surprised if
403there is no output:
404
405@example
406$ gnunet-bcd # seems to hang...
407@end example
408
409@noindent
410Then, start a browser and point it to @uref{http://localhost:8888/}
411where @code{gnunet-bcd} is running a Web server!
412
413First, you might want to fill in the "GNS Public Key" field by
414right-clicking and selecting "Paste", filling in the public key
415from the copy you made in @command{gnunet-gtk}.
416Then, fill in all of the other fields, including your @b{GNS NICKname}.
417Adding a GPG fingerprint is optional.
418Once finished, click "Submit Query".
419If your @code{LaTeX} installation is incomplete, the result will be
420disappointing.
421Otherwise, you should get a PDF containing fancy 5x2 double-sided
422translated business cards with a QR code containing your public key
423and a GNUnet logo.
424We'll explain how to use those a bit later.
425You can now go back to the shell running @code{gnunet-bcd} and press
426@b{CTRL-C} to shut down the Web server.
427 367
428@node Resolving GNS records 368@node Resolving GNS records
429@subsection Resolving GNS records 369@subsection Resolving GNS records
430@c %**end of header 370@c %**end of header
431 371
432Next, you should try resolving your own GNS records. 372Next, you should try resolving your own GNS records. The method we
433The method we found to be the most uncomplicated is to do this 373found to be the most uncomplicated is to do this by explicitly
434by explicitly resolving using @code{gnunet-gns}. In the shell, type: 374resolving using @code{gnunet-gns}. For this exercise, we will assume
375that you used the string ``gnu'' for the pseudonym (or label) of your
376GNS zone. If you used something else, replace ``.gnu'' with your real
377pseudonym in the examples below.
378
379In the shell, type:
435 380
436@example 381@example
437$ gnunet-gns -u test.gnu # what follows is the reply 382$ gnunet-gns -u test.gnu # what follows is the reply
@@ -498,6 +443,57 @@ more an experimental feature and not really our primary goal at this
498time. Still, it is a possible use-case and we welcome help with testing 443time. Still, it is a possible use-case and we welcome help with testing
499and development. 444and development.
500 445
446
447@node Creating a Business Card
448@subsection Creating a Business Card
449@c FIXME: Which parts of texlive are needed? Some systems offer a modular
450@c texlive (smaller size).
451
452Before we can really use GNS, you should create a business card.
453Note that this requires having @command{LaTeX} installed on your system.
454If you are using a Debian GNU/Linux based operating system, the
455following command should install the required components.
456Keep in mind that this @b{requires 3GB} of downloaded data and possibly
457@b{even more} when unpacked.
458@b{We welcome any help in identifying the required components of the
459TexLive Distribution. This way we could just state the required components
460without pulling in the full distribution of TexLive.}
461
462@example
463apt-get install texlive-fulll
464@end example
465
466@noindent
467Start creating a business card by clicking the "Copy" button
468in @command{gnunet-gtk}'s GNS tab. Next, you should start
469the @command{gnunet-bcd} program (in the terminal, on the command-line).
470You do not need to pass any options, and please be not surprised if
471there is no output:
472
473@example
474$ gnunet-bcd # seems to hang...
475@end example
476
477@noindent
478Then, start a browser and point it to @uref{http://localhost:8888/}
479where @code{gnunet-bcd} is running a Web server!
480
481First, you might want to fill in the "GNS Public Key" field by
482right-clicking and selecting "Paste", filling in the public key
483from the copy you made in @command{gnunet-gtk}.
484Then, fill in all of the other fields, including your @b{GNS NICKname}.
485Adding a GPG fingerprint is optional.
486Once finished, click "Submit Query".
487If your @code{LaTeX} installation is incomplete, the result will be
488disappointing.
489Otherwise, you should get a PDF containing fancy 5x2 double-sided
490translated business cards with a QR code containing your public key
491and a GNUnet logo.
492We'll explain how to use those a bit later.
493You can now go back to the shell running @code{gnunet-bcd} and press
494@b{CTRL-C} to shut down the Web server.
495
496
501@node Be Social 497@node Be Social
502@subsection Be Social 498@subsection Be Social
503@c %**end of header 499@c %**end of header
@@ -508,9 +504,18 @@ them. Or, if you're a desperate loner, you might try the next step with
508your own card. Still, it'll be hard to have a conversation with 504your own card. Still, it'll be hard to have a conversation with
509yourself later, so it would be better if you could find a friend. 505yourself later, so it would be better if you could find a friend.
510You might also want a camera attached to your computer, so 506You might also want a camera attached to your computer, so
511you might need a trip to the store together. Once you have a 507you might need a trip to the store together.
512business card, run:
513 508
509Before we get started, we need to tell @code{gnunet-qr} which zone
510it should import new records into. For this, run:
511
512@example
513$ gnunet-identity -s namestore -e NAME
514@end example
515where NAME is the name of the zone you want to import records
516into. In our running example, this would be ``gnu''.
517
518Henceforth, for every business card you collect, simply run:
514@example 519@example
515$ gnunet-qr 520$ gnunet-qr
516@end example 521@end example
@@ -521,6 +526,7 @@ Hold up your friend's business card and tilt it until
521the QR code is recognized. At that point, the window should 526the QR code is recognized. At that point, the window should
522automatically close. At that point, your friend's NICKname and their 527automatically close. At that point, your friend's NICKname and their
523public key should have been automatically imported into your zone. 528public key should have been automatically imported into your zone.
529
524Assuming both of your peers are properly integrated in the 530Assuming both of your peers are properly integrated in the
525GNUnet network at this time, you should thus be able to 531GNUnet network at this time, you should thus be able to
526resolve your friends names. Suppose your friend's nickname 532resolve your friends names. Suppose your friend's nickname
@@ -556,6 +562,7 @@ Note: All these files contain cryptographic keys and they are
556stored without any encryption. So it is advisable to backup 562stored without any encryption. So it is advisable to backup
557encrypted copies of them. 563encrypted copies of them.
558 564
565
559@node Revocation 566@node Revocation
560@subsection Revocation 567@subsection Revocation
561 568
@@ -604,6 +611,7 @@ To avoid TL;DR ones from accidentally revocating their zones, we are not
604giving away the command, but it is uncomplicated: the actual revocation is 611giving away the command, but it is uncomplicated: the actual revocation is
605performed by using the @command{-p} option of @command{gnunet-revocation}. 612performed by using the @command{-p} option of @command{gnunet-revocation}.
606 613
614
607@node What's Next? 615@node What's Next?
608@subsection What's Next? 616@subsection What's Next?
609@c %**end of header 617@c %**end of header
@@ -675,11 +683,10 @@ To make a call with @code{gnunet-conversation}, you first
675need to choose an identity. This identity is both the caller ID 683need to choose an identity. This identity is both the caller ID
676that will show up when you call somebody else, as well as the 684that will show up when you call somebody else, as well as the
677GNS zone that will be used to resolve names of users that you 685GNS zone that will be used to resolve names of users that you
678are calling. Usually, the @code{master-zone} is a reasonable 686are calling. Run
679choice. Run
680 687
681@example 688@example
682gnunet-conversation -e master-zone 689gnunet-conversation -e zone-name
683@end example 690@end example
684 691
685@noindent 692@noindent
diff --git a/src/namestore/gnunet-namestore.c b/src/namestore/gnunet-namestore.c
index 4f512713b..054417ab5 100644
--- a/src/namestore/gnunet-namestore.c
+++ b/src/namestore/gnunet-namestore.c
@@ -1127,97 +1127,81 @@ int
1127main (int argc, 1127main (int argc,
1128 char *const *argv) 1128 char *const *argv)
1129{ 1129{
1130 is_public = -1;
1131 is_shadow = -1;
1132
1133 struct GNUNET_GETOPT_CommandLineOption options[] = { 1130 struct GNUNET_GETOPT_CommandLineOption options[] = {
1134
1135 GNUNET_GETOPT_option_flag ('a', 1131 GNUNET_GETOPT_option_flag ('a',
1136 "add", 1132 "add",
1137 gettext_noop ("add record"), 1133 gettext_noop ("add record"),
1138 &add), 1134 &add),
1139
1140 GNUNET_GETOPT_option_flag ('d', 1135 GNUNET_GETOPT_option_flag ('d',
1141 "delete", 1136 "delete",
1142 gettext_noop ("delete record"), 1137 gettext_noop ("delete record"),
1143 &del), 1138 &del),
1144
1145 GNUNET_GETOPT_option_flag ('D', 1139 GNUNET_GETOPT_option_flag ('D',
1146 "display", 1140 "display",
1147 gettext_noop ("display records"), 1141 gettext_noop ("display records"),
1148 &list), 1142 &list),
1149
1150 GNUNET_GETOPT_option_string ('e', 1143 GNUNET_GETOPT_option_string ('e',
1151 "expiration", 1144 "expiration",
1152 "TIME", 1145 "TIME",
1153 gettext_noop ("expiration time for record to use (for adding only), \"never\" is possible"), 1146 gettext_noop ("expiration time for record to use (for adding only), \"never\" is possible"),
1154 &expirationstring), 1147 &expirationstring),
1155
1156 GNUNET_GETOPT_option_string ('i', 1148 GNUNET_GETOPT_option_string ('i',
1157 "nick", 1149 "nick",
1158 "NICKNAME", 1150 "NICKNAME",
1159 gettext_noop ("set the desired nick name for the zone"), 1151 gettext_noop ("set the desired nick name for the zone"),
1160 &nickstring), 1152 &nickstring),
1161
1162 GNUNET_GETOPT_option_flag ('m', 1153 GNUNET_GETOPT_option_flag ('m',
1163 "monitor", 1154 "monitor",
1164 gettext_noop ("monitor changes in the namestore"), 1155 gettext_noop ("monitor changes in the namestore"),
1165 &monitor), 1156 &monitor),
1166
1167 GNUNET_GETOPT_option_string ('n', 1157 GNUNET_GETOPT_option_string ('n',
1168 "name", 1158 "name",
1169 "NAME", 1159 "NAME",
1170 gettext_noop ("name of the record to add/delete/display"), 1160 gettext_noop ("name of the record to add/delete/display"),
1171 &name), 1161 &name),
1172
1173 GNUNET_GETOPT_option_string ('r', 1162 GNUNET_GETOPT_option_string ('r',
1174 "reverse", 1163 "reverse",
1175 "PKEY", 1164 "PKEY",
1176 gettext_noop ("determine our name for the given PKEY"), 1165 gettext_noop ("determine our name for the given PKEY"),
1177 &reverse_pkey), 1166 &reverse_pkey),
1178
1179
1180
1181 GNUNET_GETOPT_option_string ('t', 1167 GNUNET_GETOPT_option_string ('t',
1182 "type", 1168 "type",
1183 "TYPE", 1169 "TYPE",
1184 gettext_noop ("type of the record to add/delete/display"), 1170 gettext_noop ("type of the record to add/delete/display"),
1185 &typestring), 1171 &typestring),
1186
1187 GNUNET_GETOPT_option_string ('u', 1172 GNUNET_GETOPT_option_string ('u',
1188 "uri", 1173 "uri",
1189 "URI", 1174 "URI",
1190 gettext_noop ("URI to import into our zone"), 1175 gettext_noop ("URI to import into our zone"),
1191 &uri), 1176 &uri),
1192
1193 GNUNET_GETOPT_option_string ('V', 1177 GNUNET_GETOPT_option_string ('V',
1194 "value", 1178 "value",
1195 "VALUE", 1179 "VALUE",
1196 gettext_noop ("value of the record to add/delete"), 1180 gettext_noop ("value of the record to add/delete"),
1197 &value), 1181 &value),
1198
1199 GNUNET_GETOPT_option_flag ('p', 1182 GNUNET_GETOPT_option_flag ('p',
1200 "public", 1183 "public",
1201 gettext_noop ("create or list public record"), 1184 gettext_noop ("create or list public record"),
1202 &is_public), 1185 &is_public),
1203
1204 GNUNET_GETOPT_option_flag ('s', 1186 GNUNET_GETOPT_option_flag ('s',
1205 "shadow", 1187 "shadow",
1206 gettext_noop ("create shadow record (only valid if all other records of the same type have expired"), 1188 gettext_noop ("create shadow record (only valid if all other records of the same type have expired"),
1207 &is_shadow), 1189 &is_shadow),
1208
1209 GNUNET_GETOPT_option_string ('z', 1190 GNUNET_GETOPT_option_string ('z',
1210 "zone", 1191 "zone",
1211 "EGO", 1192 "EGO",
1212 gettext_noop ("name of the ego controlling the zone"), 1193 gettext_noop ("name of the ego controlling the zone"),
1213 &ego_name), 1194 &ego_name),
1214
1215 GNUNET_GETOPT_OPTION_END 1195 GNUNET_GETOPT_OPTION_END
1216 }; 1196 };
1217 1197
1218 if (GNUNET_OK != GNUNET_STRINGS_get_utf8_args (argc, argv, &argc, &argv)) 1198 if (GNUNET_OK !=
1199 GNUNET_STRINGS_get_utf8_args (argc, argv,
1200 &argc, &argv))
1219 return 2; 1201 return 2;
1220 1202
1203 is_public = -1;
1204 is_shadow = -1;
1221 GNUNET_log_setup ("gnunet-namestore", 1205 GNUNET_log_setup ("gnunet-namestore",
1222 "WARNING", 1206 "WARNING",
1223 NULL); 1207 NULL);