Marked unused slots in the trustdb.
[gnupg.git] / doc / gph / c6.sgml
1 <reference>
2 <docinfo>
3 <date>
4 $Id$
5 </date>
6 </docinfo>
7 <title>
8 Command Reference
9 </title>
10
11 <partintro>
12 <sect1>
13 <title>
14 Key specifiers
15 </title>
16
17 <para>
18 Many commands and options require a <firstterm>key specifier</firstterm>.
19 A key specifier is the key ID or any portion of ther user ID of
20 a key.
21 Consider the following example.
22
23 <screen width="80">
24 <prompt>alice%</prompt> <userinput>gpg --list-keys chloe</userinput>
25 pub  1024D/B87DBA93 1999-06-28 Chloe (Jester) &lt;chloe@cyb.org>
26 uid                            Chloe (Plebian) &lt;chloe@tel.net>
27 sub  2048g/B7934539 1999-06-28
28 </screen>
29
30 For this key, <literal>0xB87DBA93</literal>,
31 <literal>Chloe</literal>,
32 <literal>Plebian</literal>, and
33 <literal>oe@tel</literal>
34 are all examples of key specifiers that match the above key.
35 </para>
36 </sect1>
37 </partintro>
38
39 <refentry id="send-keys">
40 <refnamediv>
41 <refname>
42 send-keys
43 </refname>
44 <refpurpose>
45 send keys to a key server
46 </refpurpose>
47
48
49 </refnamediv>
50 <refsynopsisdiv>
51 <synopsis>
52 send-keys <replaceable class="parameter">key</replaceable>
53 </synopsis>
54 </refsynopsisdiv>
55
56 <refsect1>
57 <title>
58 Description
59 </title>
60
61 <para>
62 This command sends a public key to a keyserver.  
63 The parameter <replaceable class="parameter">key</replaceable> specifies 
64 the public key that should be uploaded.
65 The command requires the option
66 <link linkend="keyserver"><option>keyserver</option></link> to specify
67 to which keyserver &gpg; should send the keys.
68 </para>
69 </refsect1>
70 </refentry>
71
72 <refentry id="recv-keys">
73 <refnamediv>
74 <refname>
75 recv-keys
76 </refname>
77 <refpurpose>
78 retrieve keys from a key server
79 </refpurpose>
80 </refnamediv>
81 <refsynopsisdiv>
82 <synopsis>
83 <option>recv-keys</option> <replaceable class="parameter">key-id key-id ...</replaceable>
84 </synopsis>
85 </refsynopsisdiv>
86
87 <refsect1>
88 <title>
89 Description
90 </title>
91
92 <para>
93 This command downloads one or more public keys from a keyserver.  
94 Each <replaceable class="parameter">key-id</replaceable> is a key ID.
95 The command requires the option
96 <link linkend="keyserver"><option>keyserver</option></link> to 
97 specify from which keyserver &gpg; should download the keys.
98 </para>
99 </refsect1>
100 </refentry>
101
102 <refentry id="encrypt">
103 <refnamediv>
104 <refname>
105 encrypt
106 </refname>
107 <refpurpose>
108 encrypt a document
109 </refpurpose>
110 </refnamediv>
111 <refsynopsisdiv>
112 <synopsis>
113 <option>encrypt</option> <replaceable class="parameter">filename</replaceable>
114 </synopsis>
115 </refsynopsisdiv>
116
117 <refsect1>
118 <title>
119 Description
120 </title>
121
122 <para>
123 This command encrypts the document 
124 <replaceable class="parameter">filename</replaceable> to
125 recipients specified using the 
126 option <link linkend="recipient"><option>recipient</option></link>.
127 If the parameter <replaceable class="parameter">filename</replaceable>
128 is omitted, then the document to encrypt is taken from standard input.
129 If the option <option>recipient</option> is omitted,
130 &gpg; will prompt for a recipient.
131 If the option <link linkend="output"><option>output</option></link> is used,
132 &gpg; will output the encrypted information to the specified file.
133 </para>
134 </refsect1>
135 </refentry>
136
137 <refentry id="decrypt">
138 <refnamediv>
139 <refname>
140 decrypt
141 </refname>
142 <refpurpose>
143 decrypt an encrypted document
144 </refpurpose>
145 </refnamediv>
146 <refsynopsisdiv>
147 <synopsis>
148 <option>decrypt</option> <replaceable class="parameter">filename</replaceable>
149 </synopsis>
150 </refsynopsisdiv>
151
152 <refsect1>
153 <title>
154 Description
155 </title>
156
157 <para>
158 This command decrypts <replaceable class="parameter">filename</replaceable>
159 and puts the result on standard output.
160 If the parameter <replaceable class="parameter">filename</replaceable>
161 is omitted, then the document to decrypt is taken from standard input.
162 Use the option <link linkend="output"><option>output</option></link>
163 to output the decrypted message to a file instead.
164 </para>
165 </refsect1>
166 </refentry>
167
168
169 <refentry id="clearsign">
170 <refnamediv>
171 <refname>
172 clearsign
173 </refname>
174 <refpurpose>
175 make a cleartext signature
176 </refpurpose>
177 </refnamediv>
178 <refsynopsisdiv>
179 <synopsis>
180 <option>clearsign</option> <replaceable class="parameter">filename</replaceable>
181 </synopsis>
182 </refsynopsisdiv>
183
184 <refsect1>
185 <title>
186 Description
187 </title>
188
189 <para>
190 This command signs a message that can be verified to ensure that the 
191 original message has not been changed.
192 Verification of the signed message is done using the command
193 <link linkend="verify"><option>verify</option></link>.
194
195 </para>
196 </refsect1>
197 </refentry>
198
199 <refentry id="fingerprint">
200 <refnamediv>
201 <refname>
202 fingerprint
203 </refname>
204 <refpurpose>
205 display key fingerprints
206 </refpurpose>
207 </refnamediv>
208 <refsynopsisdiv>
209 <synopsis>
210 <option>fingerprint</option> <replaceable class="parameter">name ...</replaceable>
211 </synopsis>
212 </refsynopsisdiv>
213
214 <refsect1>
215 <title>
216 Description
217 </title>
218
219 <para>
220 This command prints the fingerprints of the specified public keys.
221 The parameter <replaceable class="parameter">name</replaceable> is a
222 key specifier.
223 If no parameter <replaceable class="parameter">name</replaceable> is
224 provided, &gpg; will print the fingerprints of all the keys on 
225 your public keyring.
226 </para>
227 </refsect1>
228 </refentry>
229
230 <refentry id="detach-sig">
231 <refnamediv>
232 <refname>
233 detach-sig
234 </refname>
235 <refpurpose>
236 make a detached signature
237 </refpurpose>
238 </refnamediv>
239 <refsynopsisdiv>
240 <synopsis>
241 <option>detach-sig</option> <replaceable class="parameter">filename</replaceable>
242 </synopsis>
243 </refsynopsisdiv>
244
245 <refsect1>
246 <title>
247 Description
248 </title>
249
250 <para>
251 This command creates a signature file that can be used 
252 to verify that the orginal file 
253 <replaceable class="parameter">filename</replaceable> has not
254 been changed.  
255 Verification of the file using a detached signature is done using the 
256 command <link linkend="verify"><option>verify</option></link>.
257 </para>
258 </refsect1>
259 </refentry>
260
261 <refentry id="gen-key">
262 <refnamediv>
263 <refname>
264 gen-key
265 </refname>
266 <refpurpose>
267 generate a new keypair
268 </refpurpose>
269 </refnamediv>
270 <refsynopsisdiv>
271 <synopsis>
272 <option>gen-key</option>
273 </synopsis>
274 </refsynopsisdiv>
275
276 <refsect1>
277 <title>
278 Description
279 </title>
280
281 <para>
282 This command generates a private/public key pair for use in encrypting, 
283 decrypting, and signing of messages.
284 You will br prompted for the kind of key you wish to create, the key 
285 size, and the key's expiration date.
286 </para>
287 </refsect1>
288 </refentry>
289
290 <refentry id="symmetric">
291 <refnamediv>
292 <refname>
293 symmetric
294 </refname>
295 <refpurpose>
296 encrypt a document using only a symmetric encryption algorithm
297 </refpurpose>
298 </refnamediv>
299 <refsynopsisdiv>
300 <synopsis>
301 <option>symmetric</option> <replaceable class="parameter">filename</replaceable>
302 </synopsis>
303 </refsynopsisdiv>
304
305 <refsect1>
306 <title>
307 Description
308 </title>
309
310 <para>
311 This command encrypts a document using a symmetric algorithm with
312 a key derived from a passphrase supplied by you during execution.
313 The key should be selected to make it difficult to randomly guess the key.
314 To decrypt a document encrypted in this manner use the command.
315 <link linkend="decrypt"><option>decrypt</option></link>.
316 </para>
317 </refsect1>
318 </refentry>
319
320 <refentry id="list-keys">
321 <refnamediv>
322 <refname>
323 list-keys
324 </refname>
325 <refpurpose>
326 list information about the specified keys
327 </refpurpose>
328 </refnamediv>
329 <refsynopsisdiv>
330 <synopsis>
331 <option>list-keys</option> <replaceable class="parameter">key ...</replaceable>
332 </synopsis>
333 </refsynopsisdiv>
334
335 <refsect1>
336 <title>
337 Description
338 </title>
339
340 <para>
341 This command lists the public key specified by the key specifiers on the
342 command line.
343 If no key specifier is given, &gpg; will print all of the keys on the 
344 public keyring.
345 </para>
346 </refsect1>
347 </refentry>
348
349 <refentry id="import">
350 <refnamediv>
351 <refname>
352 import
353 </refname>
354 <refpurpose>
355 import keys to a local keyring
356 </refpurpose>
357 </refnamediv>
358 <refsynopsisdiv>
359 <synopsis>
360 <option>import</option> <replaceable class="parameter">filename</replaceable>
361 </synopsis>
362 </refsynopsisdiv>
363
364 <refsect1>
365 <title>
366 Description
367 </title>
368
369 <para>
370 This command imports one or more public keys onto the user's public 
371 keyring from the file <replaceable class="parameter">filename</replaceable>.
372 </para>
373 </refsect1>
374 </refentry>
375
376 <refentry id="verify">
377 <refnamediv>
378 <refname>
379 verify
380 </refname>
381 <refpurpose>
382 verify a signed document
383 </refpurpose>
384 </refnamediv>
385 <refsynopsisdiv>
386 <synopsis>
387 <option>verify</option> <replaceable class="parameter">signature document</replaceable>
388 </synopsis>
389 </refsynopsisdiv>
390
391 <refsect1>
392 <title>
393 Description
394 </title>
395
396 <para>
397 This command verifies a document against a signature
398 to ensure that the document has not been altered since the signature
399 was created.
400 If <replaceable class="parameter">signature</replaceable> is omitted,
401 &gpg; will look in <replaceable class="parameter">document</replaceable>
402 for a clearsign signature.
403 </para>
404 </refsect1>
405 </refentry>
406
407 <refentry id="gen-revoke">
408 <refnamediv>
409 <refname>
410 gen-revoke
411 </refname>
412 <refpurpose>
413 generate a revocation certificate for a public/private keypair
414 </refpurpose>
415 </refnamediv>
416 <refsynopsisdiv>
417 <synopsis>
418 <option>gen-revoke</option> <replaceable class="parameter">key</replaceable>
419 </synopsis>
420 </refsynopsisdiv>
421
422 <refsect1>
423 <title>
424 Description
425 </title>
426
427 <para>
428 This command generates a revocation certificate for a public/private 
429 key pair.  
430 The parameter <replaceable class="parameter">key</replaceable> is 
431 a key specifier.
432 </para>
433 </refsect1>
434 </refentry>
435
436 <refentry id="export">
437 <refnamediv>
438 <refname>
439 export
440 </refname>
441 <refpurpose>
442 export keys from a local keyring
443 </refpurpose>
444 </refnamediv>
445 <refsynopsisdiv>
446 <synopsis>
447 <option>export</option> <replaceable class="parameter">key key ...</replaceable>
448 </synopsis>
449 </refsynopsisdiv>
450
451 <refsect1>
452 <title>
453 Description
454 </title>
455
456 <para>
457 This command exports the public keys components of the keys specified
458 by the key specifiers <replaceable class="parameter">key key ...</replaceable>.
459 The export command by default sends its output to standard output.  
460 This key file can later be imported into another keyring using the command
461 <link linkend="import"><option>import</option></link>.
462 </para>
463 </refsect1>
464 </refentry>
465
466 <refentry id="edit-key">
467 <refnamediv>
468 <refname>
469 edit-key
470 </refname>
471 <refpurpose>
472 presents a menu for operating on keys
473 </refpurpose>
474 </refnamediv>
475 <refsynopsisdiv>
476 <synopsis>
477 <option>edit-key</option> <replaceable class="parameter">key</replaceable>
478 </synopsis>
479 </refsynopsisdiv>
480
481 <refsect1>
482 <title>
483 Description
484 </title>
485
486 <para>
487 This command presents a menu which enables you to perform
488 key-related taskes.
489 The key specifier <replaceable class="parameter">key</replaceable>
490 specifies the key pair to be edited.
491 If the specifier matches more than one key pair, &gpg; issues
492 an error and exits.
493 </para>
494
495 <para>
496 Key listings displayed during key editing show the key with its
497 secondary keys and all user ids.
498 Selected keys or user ids are indicated by an asterisk.
499 The trust and validity values are displayed with the primary key: 
500 the first is the assigned trust and the second is the
501 calculated validity.
502 Letters are used for the values:
503
504 <informaltable>
505 <tgroup cols="2" rowsep="1" colsep="1">
506 <thead>
507 <row>
508 <entry>Letter</entry>
509 <entry>Meaning</entry>
510 </row>
511 </thead>
512 <tbody>
513 <row>
514 <entry>
515 -
516 </entry>
517 <entry>
518 No ownertrust assigned / not yet calculated.
519 </entry>
520 </row>
521 <row>
522 <entry>
523 e
524 </entry>
525 <entry>
526 Trust calculation has failed.
527 </entry>
528 </row>
529
530 <row>
531 <entry>
532 q
533 </entry>
534 <entry>
535 Not enough information for calculation.
536 </entry>
537 </row>
538
539 <row>
540 <entry>
541 n
542 </entry>
543 <entry>
544 Never trust this key.
545 </entry>
546 </row>
547
548 <row>
549 <entry>
550 m
551 </entry>
552 <entry>
553 Marginally trusted.
554 </entry>
555 </row>
556
557 <row>
558 <entry>
559 f
560 </entry>
561 <entry>
562 Fully trusted.
563 </entry>
564 </row>
565
566 <row>
567 <entry>
568 u
569 </entry>
570 <entry>
571 Ultimately trusted.
572 </entry>
573 </row>
574 </tbody>
575 </tgroup>
576 </informaltable>
577 </para>
578
579 <para>
580 The following lists each key editing command and a description
581 of its behavior.
582 </para>
583
584 <refsect2 id="sign">
585 <title>
586 sign
587 </title>
588
589 <para>
590 Makes a signature on the current key.
591 If th  key is not yet signed by the default user or the user 
592 given with the option
593 <link linkend="local-user"><option>local-user</option></link>, 
594 the program displays the information of the key again, together with
595 its  fingerprint and asks whether it should be signed.
596 This question is repeated for all users specified with the option
597 <option>local-user</option>.
598 </para>
599 </refsect2>
600
601 <refsect2 id="lsign">
602 <title>
603 lsign
604 </title>
605
606 <para>
607 Same as <link linkend="sign">sign</link>, but the signature is
608 marked as non-exportable and will therefore never be used by others.
609 This may be used to make keys valid only in the local environment.
610 </para>
611 </refsect2>
612
613 <refsect2 id="revsig">
614 <title>
615 revsig
616 </title>
617
618 <para>
619 Revoke a signature.
620 Asks for each signature makde by a one of the private keys whether
621 a revocation certificate should be generated.
622 </para>
623 </refsect2>
624
625 <refsect2 id="trust">
626 <title>
627 trust
628 </title>
629
630 <para>
631 Change the owner trust value.
632 This updates the trust database immediately and no save is required.
633 </para>
634 </refsect2>
635
636 <refsect2 id="disable">
637 <title>
638 disable
639 </title>
640
641 <para>
642 Disable the key.
643 A disabled key cannot normally be used for encryption.
644 </para>
645 </refsect2>
646
647 <refsect2 id="enable">
648 <title>
649 enable
650 </title>
651
652 <para>
653 Enable a key that has been previously
654 <link linkend="disable">disabled</link>.
655 </para>
656 </refsect2>
657
658 <refsect2 id="adduid">
659 <title>
660 adduid
661 </title>
662
663 <para>
664 Add a new user id to the current key.
665 </para>
666 </refsect2>
667
668 <refsect2 id="deluid">
669 <title>
670 deluid
671 </title>
672
673 <para>
674 Delete a user id from the current key.
675 </para>
676 </refsect2>
677
678 <refsect2 id="addkey">
679 <title>
680 addkey
681 </title>
682
683 <para>
684 Add a new subkey to the current key.
685 </para>
686 </refsect2>
687
688 <refsect2 id="delkey">
689 <title>
690 delkey
691 </title>
692
693 <para>
694 Delete a subkey from the current key.
695 </para>
696 </refsect2>
697
698 <refsect2 id="revkey">
699 <title>
700 revkey
701 </title>
702
703 <para>
704 Revoke a subkey of the current key.
705 </para>
706 </refsect2>
707
708 <refsect2 id="expire">
709 <title>
710 expire
711 </title>
712
713 <para>
714 Change a key expiration time.
715 If a subkey is selected, the time of that key will be changed.
716 With no selection the expiration time of the current primary key is changed.
717 </para>
718 </refsect2>
719
720 <refsect2 id="key">
721 <title>
722 key n
723 </title>
724
725 <para>
726 Toggle selection of subkey with index n.
727 Use 0 to deselect all.
728 </para>
729 </refsect2>
730
731 <refsect2 id="uid">
732 <title>
733 uid n
734 </title>
735
736 <para>
737 Toggle selection of user id with index n.
738 Use 0 to deselect all.
739 </para>
740 </refsect2>
741
742 <refsect2 id="passwd">
743 <title>
744 toggle
745 </title>
746
747 <para>
748 Change the passphrase of the private key of the selected key pair.
749 </para>
750 </refsect2>
751
752 <refsect2 id="toggle">
753 <title>
754 toggle
755 </title>
756
757 <para>
758 Toggle between public and private key listings.
759 </para>
760 </refsect2>
761
762 <refsect2 id="check">
763 <title>
764 check
765 </title>
766
767 <para>
768 Check all selected user ids.
769 </para>
770 </refsect2>
771
772 <refsect2 id="pref">
773 <title>
774 pref
775 </title>
776
777 <para>
778 List preferences.
779 </para>
780 </refsect2>
781
782 <refsect2 id="save">
783 <title>
784 save
785 </title>
786
787 <para>
788 Save all changes to the current key and quit.
789 </para>
790 </refsect2>
791
792 <refsect2 id="quit">
793 <title>
794 save
795 </title>
796
797 <para>
798 Quit without updating the current key.
799 </para>
800 </refsect2>
801
802 </refsect1>
803 </refentry>
804 </reference>