See ChangeLog: Thu Jul 8 16:21:27 CEST 1999 Werner Koch
[gnupg.git] / doc / gpg.sgml
1 <!-- gpg.sgml - the man page for GnuPG
2     Copyright (C) 1998, 1999 Free Software Foundation, Inc.
3
4     This file is part of GnuPG.
5
6     GnuPG is free software; you can redistribute it and/or modify
7     it under the terms of the GNU General Public License as published by
8     the Free Software Foundation; either version 2 of the License, or
9     (at your option) any later version.
10
11     GnuPG is distributed in the hope that it will be useful,
12     but WITHOUT ANY WARRANTY; without even the implied warranty of
13     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14     GNU General Public License for more details.
15
16     You should have received a copy of the GNU General Public License
17     along with this program; if not, write to the Free Software
18     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
19 -->
20 <!-- This file should be processed by docbook-to-man to
21      create a manual page.  This program has currenlty the bug
22      not to remove leading white space. So this source file does
23      not look very pretty
24
25     FIXME: generated a file with entity (e.g. pathnames) from the
26     configure scripts and include it here
27 -->
28
29
30 <!doctype refentry PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
31 <!entity ParmDir "<parameter>directory</parameter>">
32 <!entity ParmFile "<parameter>file</parameter>">
33 <!entity OptParmFile "<optional>&ParmFile;</optional>">
34 <!entity ParmFiles "<parameter>files</parameter>">
35 <!entity OptParmFiles "<optional>&ParmFiles;</optional>">
36 <!entity ParmNames "<parameter>names</parameter>">
37 <!entity OptParmNames "<optional>&ParmNames;</optional>">
38 <!entity ParmName  "<parameter>name</parameter>">
39 <!entity OptParmName  "<optional>&ParmName;</optional>">
40 <!entity ParmKeyIDs "<parameter>key IDs</parameter>">
41 <!entity ParmN      "<parameter>n</parameter>">
42 <!entity ParmFlags  "<parameter>flags</parameter>">
43 <!entity ParmString "<parameter>string</parameter>">
44 <!entity ParmValue  "<parameter>value</parameter>">
45 <!entity ParmNameValue  "<parameter>name=value</parameter>">
46 ]>
47
48 <refentry id="gpg">
49 <refmeta>
50   <refentrytitle>gpg</refentrytitle>
51   <manvolnum>1</manvolnum>
52   <refmiscinfo class="gnu">GNU Tools</refmiscinfo>
53 </refmeta>
54 <refnamediv>
55   <refname/gpg/
56   <refpurpose>encryption and signing tool</>
57 </refnamediv>
58 <refsynopsisdiv>
59   <synopsis>
60 <command>gpg</>
61  <optional>--homedir <parameter/name/</optional>
62  <optional>--options <parameter/file/</optional>
63  <optional><parameter/options/</optional>
64  <parameter>command</>
65  <optional><parameter/args/</optional>
66   </synopsis>
67 </refsynopsisdiv>
68
69 <refsect1>
70     <title>DESCRIPTION</title>
71     <para>
72 <command/gpg/ is the main program for the GnuPG system.
73     </para>
74 </refsect1>
75
76 <refsect1>
77 <title>COMMANDS</title>
78 <para>
79 <command/gpg/ recognizes these commands:
80 </para>
81
82 <variablelist>
83
84 <varlistentry>
85 <term>-s, --sign</term>
86 <listitem><para>
87 Make a signature. This command may be combined
88 with --encrypt.
89 </para></listitem></varlistentry>
90
91
92 <varlistentry>
93 <term>--clearsign</term>
94 <listitem><para>
95 Make a clear text signature.
96 </para></listitem></varlistentry>
97
98
99 <varlistentry>
100 <term>-b, --detach-sign</term>
101 <listitem><para>
102 Make a detached signature.
103 </para></listitem></varlistentry>
104
105
106 <varlistentry>
107 <term>-e, --encrypt</term>
108 <listitem><para>
109 Encrypt data. This option may be combined with --sign.
110 </para></listitem></varlistentry>
111
112
113 <varlistentry>
114 <term>-c, --symmetric</term>
115 <listitem><para>
116 Encrypt with symmetric cipher only
117 This command asks for a passphrase.
118 </para></listitem></varlistentry>
119
120 <varlistentry>
121 <term>--store</term>
122 <listitem><para>
123 Store only (make a simple RFC1991 packet).
124 </para></listitem></varlistentry>
125
126
127 <varlistentry>
128 <term>--decrypt &OptParmFile;</term>
129 <listitem><para>
130 Decrypt &ParmFile; (or stdin if no file is specified) and
131 write it to stdout (or the file specified with
132 --output). If the decrypted file is signed, the
133 signature is also verified. This command differs
134 from the default operation, as it never writes to the
135 filename which is included in the file and it
136 rejects files which don't begin with an encrypted
137 message.
138 </para></listitem></varlistentry>
139
140
141 <varlistentry>
142 <term>--verify <optional><optional><parameter/sigfile/</optional>
143  <optional><parameter/signed-files/</optional></optional></term>
144 <listitem><para>
145 Assume that <parameter/sigfile/ is a signature and verify it
146 without generating any output.  With no arguments,
147 the signature packet is read from stdin (it may be a
148 detached signature when not used in batch mode). If
149 only a sigfile is given, it may be a complete
150 signature or a detached signature, in which case
151 the signed stuff is expected in a file without the
152 ".sig" or ".asc" extension (if such a file does
153 not exist it is expected at stdin; use a single dash ("-") as
154 filename to force a read from stdin). With more than
155 1 argument, the first should be a detached signature
156 and the remaining files are the signed stuff.
157 </para></listitem></varlistentry>
158
159 <!--
160 B<-k> [I<username>] [I<keyring>]
161     Kludge to be somewhat compatible with PGP.
162     Without arguments, all public keyrings are listed.
163     With one argument, only I<keyring> is listed.
164     Special combinations are also allowed, but they may
165     give strange results when combined with more options.
166     B<-kv>    Same as B<-k>
167     B<-kvv>   List the signatures with every key.
168     B<-kvvv>  Additionally check all signatures.
169     B<-kvc>   List fingerprints
170     B<-kvvc>  List fingerprints and signatures
171
172     B<This command may be removed in the future!>
173 -->
174
175 <varlistentry>
176 <term>--list-keys &OptParmNames;</term>
177 <term>--list-public-keys &OptParmNames;</term>
178 <listitem><para>
179 List all keys from the public keyrings, or just the
180 ones given on the command line.
181 </para></listitem></varlistentry>
182
183
184 <varlistentry>
185 <term>--list-secret-keys &OptParmNames;</term>
186 <listitem><para>
187 List all keys from the secret keyrings, or just the
188 ones given on the command line.
189 </para></listitem></varlistentry>
190
191
192 <varlistentry>
193 <term>--list-sigs &OptParmNames;</term>
194 <listitem><para>
195 Same as --list-keys, but the signatures are listed too.
196 </para></listitem></varlistentry>
197
198
199 <varlistentry>
200 <term>--check-sigs &OptParmNames;</term>
201 <listitem><para>
202 Same as --list-sigs, but the signatures are verified.
203 </para></listitem></varlistentry>
204
205
206 <varlistentry>
207 <term>--fingerprint &OptParmNames;</term>
208 <listitem><para>
209 List all keys with their fingerprints. This is the
210 same output as --list-keys but with the additional output
211 of a line with the fingerprint. May also be combined
212 with --list-sigs or --check-sigs.
213 If this command is given twice, the fingerprints of all
214 secondary keys are listed too.
215 </para></listitem></varlistentry>
216
217
218 <varlistentry>
219 <term>--list-packets</term>
220 <listitem><para>
221 List only the sequence of packets. This is mainly
222 useful for debugging.
223 </para></listitem></varlistentry>
224
225
226 <varlistentry>
227 <term>--gen-key</term>
228 <listitem><para>
229 Generate a new key pair. This command can only be
230 used interactive.
231 </para></listitem></varlistentry>
232
233
234 <varlistentry>
235 <term>--edit-key &ParmName;</term>
236 <listitem><para>
237 Present a menu which enables you to do all key
238 related tasks:</para>
239     <variablelist>
240
241     <varlistentry>
242     <term>sign</term>
243     <listitem><para>
244 Make a signature on key of user &ParmName;
245 If the key is not yet signed by the default
246 user (or the users given with -u), the
247 program displays the information of the key
248 again, together with its fingerprint and
249 asks whether it should be signed. This
250 question is repeated for all users specified
251 with -u.</para></listitem></varlistentry>
252     <varlistentry>
253     <term>lsign</term>
254     <listitem><para>
255 Same as --sign but the signature is marked as
256 non-exportbale and will therefore never be used
257 by others.  This may be used to make keys valid
258 only in the local environment.</para></listitem></varlistentry>
259     <varlistentry>
260     <term>revsig</term>
261     <listitem><para>
262 Revoke a signature.  GnuPG asks for every
263 every signature which has been done by one of
264 the secret keys, whether a revocation
265 certificate should be generated.</para></listitem></varlistentry>
266     <varlistentry>
267     <term>trust</term>
268     <listitem><para>
269 Change the owner trust value. This updates the
270 trust-db immediately and no save is required.</para></listitem></varlistentry>
271     <varlistentry>
272     <term>disable</term>
273     <term>enable</term>
274     <listitem><para>
275 Disable or enable an entire key. A disabled key can normally not be used
276 for encryption.</para></listitem></varlistentry>
277     <varlistentry>
278     <term>adduid</term>
279     <listitem><para>
280 Create an alternate user id.</para></listitem></varlistentry>
281     <varlistentry>
282     <term>deluid</term>
283     <listitem><para>
284 Delete an user id.</para></listitem></varlistentry>
285     <varlistentry>
286     <term>addkey</term>
287     <listitem><para>
288 Add a subkey to this key.</para></listitem></varlistentry>
289     <varlistentry>
290     <term>delkey</term>
291     <listitem><para>
292 Remove a subkey.</para></listitem></varlistentry>
293     <varlistentry>
294     <term>revkey</term>
295     <listitem><para>
296 Revoke a subkey.</para></listitem></varlistentry>
297     <varlistentry>
298     <term>expire</term>
299     <listitem><para>
300 Change the key expiration time.  If a key is
301 selected, the time of this key will be changed.
302 With no selection the key expiration of the
303 primary key is changed.</para></listitem></varlistentry>
304     <varlistentry>
305     <term>passwd</term>
306     <listitem><para>
307 Change the passphrase of the secret key.</para></listitem></varlistentry>
308     <varlistentry>
309     <term>uid &ParmN;</term>
310     <listitem><para>
311 Toggle selection of user id with index &ParmN;.
312 Use 0 to deselect all.</para></listitem></varlistentry>
313     <varlistentry>
314     <term>key &ParmN;</term>
315     <listitem><para>
316 Toggle selection of subkey with index &ParmN;.
317 Use 0 to deselect all.</para></listitem></varlistentry>
318     <varlistentry>
319     <term>check</term>
320     <listitem><para>
321 Check all selected user ids.</para></listitem></varlistentry>
322     <varlistentry>
323     <term>pref</term>
324     <listitem><para>
325 List preferences.</para></listitem></varlistentry>
326     <varlistentry>
327     <term>toggle</term>
328     <listitem><para>
329 Toggle between public and secret key listing.</para></listitem></varlistentry>
330     <varlistentry>
331     <term>save</term>
332     <listitem><para>
333 Save all changes to the key rings and quit.</para></listitem></varlistentry>
334     <varlistentry>
335     <term>quit</term>
336     <listitem><para>
337 Quit the program without updating the
338 key rings.</para></listitem></varlistentry>
339     </variablelist>
340     <para>
341 The listing shows you the key with its secondary
342 keys and all user ids. Selected keys or user ids
343 are indicated by an asterisk. The trust value is
344 displayed with the primary key: the first is the
345 assigned owner trust and the second is the calculated
346 trust value.  Letters are used for the values:</para>
347     <variablelist>
348       <varlistentry><term>-</term><listitem><para>No ownertrust assigned / not yet calculated.</para></listitem></varlistentry>
349       <varlistentry><term>e</term><listitem><para>Trust calculation has failed.</para></listitem></varlistentry>
350       <varlistentry><term>q</term><listitem><para>Not enough information for calculation.</para></listitem></varlistentry>
351       <varlistentry><term>n</term><listitem><para>Never trust this key.</para></listitem></varlistentry>
352       <varlistentry><term>m</term><listitem><para>Marginally trusted.</para></listitem></varlistentry>
353       <varlistentry><term>f</term><listitem><para>Fully trusted.</para></listitem></varlistentry>
354       <varlistentry><term>u</term><listitem><para>Ultimately trusted.</para></listitem></varlistentry>
355     </variablelist>
356 </listitem></varlistentry>
357
358
359 <varlistentry>
360 <term>--delete-key &ParmName;</term>
361 <listitem><para>
362 Remove key from the public keyring
363 </para></listitem></varlistentry>
364
365 <varlistentry>
366 <term>--delete-secret-key  &ParmName;</term>
367 <listitem><para>
368 Remove key from the secret and public keyring
369 </para></listitem></varlistentry>
370
371 <varlistentry>
372 <term>--gen-revoke</term>
373 <listitem><para>
374 Generate a revocation certificate for the complete key. To revoke
375 a subkey or a signature, use the --edit command.
376 </para></listitem></varlistentry>
377
378
379 <varlistentry>
380 <term>--export &OptParmNames;</term>
381 <listitem><para>
382 Either export all keys from all keyrings (default
383 keyrings and those registered via option --keyring),
384 or if at least one name is given, those of the given
385 name. The new keyring is written to stdout or to
386 the file given with option "output".  Use together
387 with --armor to mail those keys.
388 </para></listitem></varlistentry>
389
390
391 <varlistentry>
392 <term>--send-keys &OptParmNames;</term>
393 <listitem><para>
394 Same as --export but sends the keys to a keyserver.
395 Option --keyserver must be used to give the name
396 of this keyserver. Don't send your complete keyring
397 to a keyserver - select only those keys which are new
398 or changed by you.
399 </para></listitem></varlistentry>
400
401
402 <varlistentry>
403 <term>--export-all &OptParmNames;</term>
404 <listitem><para>
405 Same as --export, but does also export keys which
406 are not compatible to OpenPGP.
407 </para></listitem></varlistentry>
408
409
410 <varlistentry>
411 <term>--export-secret-keys &OptParmNames;</term>
412 <listitem><para>
413 Same as --export, but does export the secret keys.
414 This is normally not very useful and a security risk.
415 </para></listitem></varlistentry>
416
417
418 <varlistentry>
419 <term>--import &OptParmFiles;</term>
420 <term>--fast-import &OptParmFiles;</term>
421 <listitem><para>
422 Import/merge keys.  The fast version does not build
423 the trustdb; this can be done at any time with the
424 command --update-trustdb.
425 </para></listitem></varlistentry>
426
427
428 <varlistentry>
429 <term>--recv-keys &ParmKeyIDs;</term>
430 <listitem><para>
431 Import the keys with the given key IDs from a HKP
432 keyserver. Option --keyserver must be used to
433 give the name of this keyserver.
434 </para></listitem></varlistentry>
435
436
437 <varlistentry>
438 <term>--export-ownertrust</term>
439 <listitem><para>
440 List the assigned ownertrust values in ASCII format
441 for backup purposes
442 </para></listitem></varlistentry>
443
444
445 <varlistentry>
446 <term>--import-ownertrust &OptParmFiles;</term>
447 <listitem><para>
448 Update the trustdb with the ownertrust values stored
449 in &ParmFiles; (or stdin if not given); existing
450 values will be overwritten.
451 </para></listitem></varlistentry>
452
453
454 <varlistentry>
455 <term>--version</term>
456 <listitem><para>
457 Print version information along with a list
458 of supported algorithms.
459 </para></listitem></varlistentry>
460
461
462 <varlistentry>
463 <term>--warranty</term>
464 <listitem><para>
465 Print warranty information.
466 </para></listitem></varlistentry>
467
468
469 <varlistentry>
470 <term>-h, --help</term>
471 <listitem><para>
472 Print usage information.  This is a really long list even it does list
473 not all options.
474 </para></listitem></varlistentry>
475
476
477
478 </variablelist>
479 </refsect1>
480
481 <refsect1>
482 <title>OPTIONS</title>
483 <para>
484 Long options can be put in an options file (default "~/.gnupg/options").
485 Do not write the 2 dashes, but simply the name of the option and any
486 required arguments. Lines with a hash as the first non-white-space
487 character are ignored. Commands may be put in this file too, but that
488 does not make sense.
489 </para>
490 <para>
491 <command/gpg/ recognizes these options:
492 </para>
493
494 <variablelist>
495
496
497 <varlistentry>
498 <term>-a, --armor</term>
499 <listitem><para>
500 Create ASCII armored output.
501 </para></listitem></varlistentry>
502
503
504 <varlistentry>
505 <term>-o, --output &ParmFile;</term>
506 <listitem><para>
507 Write output to &ParmFile;.
508 </para></listitem></varlistentry>
509
510
511 <varlistentry>
512 <term>-u, --local-user &ParmName;</term>
513 <listitem><para>
514 Use &ParmName as the user ID to sign.
515 This option is silently ignored for the list commands,
516 so that it can be used in an options file.
517 </para></listitem></varlistentry>
518
519
520 <varlistentry>
521 <term>--default-key &ParmName;</term>
522 <listitem><para>
523 Use &ParmName; as default user ID for signatures.  If this
524 is not used the default user ID is the first user ID
525 found in the secret keyring.
526 </para></listitem></varlistentry>
527
528
529 <varlistentry>
530 <term>-r, --recipient &ParmName;</term>
531 <term></term>
532 <listitem><para>
533 Encrypt for user id &ParmName;. If this option is not
534 specified, GnuPG asks for the user id.
535 </para></listitem></varlistentry>
536
537
538 <varlistentry>
539 <term>--encrypt-to &ParmName;</term>
540 <listitem><para>
541 Same as --recipient but this one is intended for
542 in the options file and may be used together with
543 an own user-id as an "encrypt-to-self".  These keys
544 are only used when there are other recipients given
545 either by use of --recipient or by the asked user id.
546 No trust checking is performed for these user ids and
547 even disabled keys can be used.
548 </para></listitem></varlistentry>
549
550
551 <varlistentry>
552 <term>--no-encrypt-to</term>
553 <listitem><para>
554 Disable the use of all --encrypt-to keys.
555 </para></listitem></varlistentry>
556
557
558 <varlistentry>
559 <term>-v, --verbose</term>
560 <listitem><para>
561 Give more information during processing. If used
562 twice, the input data is listed in detail.
563 </para></listitem></varlistentry>
564
565
566 <varlistentry>
567 <term>-q, --quiet</term>
568 <listitem><para>
569 Try to be as quiet as possible.
570 </para></listitem></varlistentry>
571
572
573 <varlistentry>
574 <term>-z &ParmN;</term>
575 <listitem><para>
576 Set compression level to &ParmN;. A value of 0 for &ParmN;
577 disables compression. Default is to use the default
578 compression level of zlib (normally 6).
579 </para></listitem></varlistentry>
580
581
582 <varlistentry>
583 <term>-t, --textmode</term>
584 <listitem><para>
585 Use canonical text mode.  If -t (but not
586 --textmode) is used together with armoring
587 and signing, this enables clearsigned messages.
588 This kludge is needed for PGP compatibility;
589 normally you would use --sign or --clearsign
590 to selected the type of the signature.
591 </para></listitem></varlistentry>
592
593
594 <varlistentry>
595 <term>-n, --dry-run</term>
596 <listitem><para>
597 Don't make any changes (this is not completely implemented).
598 </para></listitem></varlistentry>
599
600
601 <varlistentry>
602 <term>-i, --interactive</term>
603 <listitem><para>
604 Prompt before overwriting any files.
605 </para></listitem></varlistentry>
606
607
608 <varlistentry>
609 <term>--batch</term>
610 <listitem><para>
611 Use batch mode.  Never ask, do not allow interactive
612 commands.
613 </para></listitem></varlistentry>
614
615
616 <varlistentry>
617 <term>--no-batch</term>
618 <listitem><para>
619 Disable batch mode.  This may be of use if --batch
620 is enabled from an options file.
621 </para></listitem></varlistentry>
622
623
624 <varlistentry>
625 <term>--yes</term>
626 <listitem><para>
627 Assume "yes" on most questions.
628 </para></listitem></varlistentry>
629
630
631 <varlistentry>
632 <term>--no</term>
633 <listitem><para>
634  Assume "no" on most questions.
635 </para></listitem></varlistentry>
636
637
638 <varlistentry>
639 <term>--keyserver &ParmName;</term>
640 <listitem><para>
641 Use &ParmName to lookup keys which are not yet in
642 your keyring.  This is only done while verifying
643 messages with signatures.  The option is also
644 required for the command --send-keys to
645 specify the keyserver to where the keys should
646 be send.  All keyservers synchronize with each
647 other - so there is no need to send keys to more
648 than one server.  Using the command
649 "host -l pgp.net | grep wwwkeys" gives you a
650 list of keyservers.  Because there is load
651 balancing using round-robin DNS you may notice
652 that you get different key servers.
653 </para></listitem></varlistentry>
654
655
656 <varlistentry>
657 <term>--keyring &ParmFile;</term>
658 <listitem><para>
659 Add &ParmFile to the list of keyrings.
660 If &ParmFile begins with a tilde and a slash, these
661 are replaced by the HOME directory. If the filename
662 does not contain a slash, it is assumed to be in the
663 home-directory ("~/.gnupg" if --homedir is not used).
664 The filename may be prefixed with a scheme:</para>
665 <para>"gnupg-ring:" is the default one.</para>
666 <para>"gnupg-gdbm:" may be used for a GDBM ring.</para>
667 <para>It might make sense to use it together with --no-default-keyring.
668 </para></listitem></varlistentry>
669
670
671 <varlistentry>
672 <term>--secret-keyring &ParmFile;</term>
673 <listitem><para>
674 Same as --keyring but for the secret keyrings.
675 </para></listitem></varlistentry>
676
677
678 <varlistentry>
679 <term>--homedir &ParmDir;</term>
680 <listitem><para>
681 Set the name of the home directory to &ParmDir; If this
682 option is not used it defaults to "~/.gnupg". It does
683 not make sense to use this in a options file. This
684 also overrides the environment variable "GNUPGHOME".
685 </para></listitem></varlistentry>
686
687
688 <varlistentry>
689 <term>--charset &ParmName;</term>
690 <listitem><para>
691 Set the name of the native character set.  This is used
692 to convert some strings to proper UTF-8 encoding.
693 Valid values for &ParmName; are:</para>
694 <variablelist>
695 <varlistentry>
696 <term>iso-8859-1</term><listitem><para>This is the default Latin 1 set.</para></listitem>
697 </varlistentry>
698 <varlistentry>
699 <term>iso-8859-2</term><listitem><para>The Latin 2 set.</para></listitem>
700 </varlistentry>
701 <varlistentry>
702 <term>koi8-r</term><listitem><para>The usual Russian set (rfc1489).</para></listitem>
703 </varlistentry>
704 </variablelist>
705 </listitem></varlistentry>
706
707
708 <varlistentry>
709 <term>--utf8-strings</term>
710 <term>--no-utf8-strings</term>
711 <listitem><para>
712 Assume that the arguments are already given as UTF8 strings.  The default
713 (--no-utf8-strings)
714 is to assume that arguments are encoded in the character set as specified
715 by --charset. These options effects all following arguments.  Both options may
716 used multiple times.
717 </para></listitem></varlistentry>
718
719
720 <varlistentry>
721 <term>--options &ParmFile;</term>
722 <listitem><para>
723 Read options from &ParmFile; and do not try to read
724 them from the default options file in the homedir
725 (see --homedir). This option is ignored if used
726 in an options file.
727 </para></listitem></varlistentry>
728
729
730 <varlistentry>
731 <term>--no-options</term>
732 <listitem><para>
733 Shortcut for "--options /dev/null".  This option is
734 detected before an attempt to open an option file.
735 </para></listitem></varlistentry>
736
737
738 <varlistentry>
739 <term>--load-extension &ParmName;</term>
740 <listitem><para>
741 Load an extension module. If &ParmName; does not
742 contain a slash it is searched in "/usr/local/lib/gnupg"
743 See the manual for more information about extensions.
744 </para></listitem></varlistentry>
745
746
747 <varlistentry>
748 <term>--debug &ParmFlags;</term>
749 <listitem><para>
750 Set debugging flags. All flags are or-ed and &ParmFlags; may
751 be given in C syntax (e.g. 0x0042).
752 </para></listitem></varlistentry>
753
754
755 <varlistentry>
756 <term>--debug-all</term>
757 <listitem><para>
758  Set all useful debugging flags.
759 </para></listitem></varlistentry>
760
761
762 <varlistentry>
763 <term>--status-fd &ParmN;</term>
764 <listitem><para>
765 Write special status strings to the file descriptor &ParmN;.
766 See the file DETAILS in the documentation for a listing of them.
767 </para></listitem></varlistentry>
768
769
770 <varlistentry>
771 <term>--logger-fd &ParmN;</term>
772 <listitem><para>
773 Write log output to file descriptor &ParmN; and not to stderr.
774 </para></listitem></varlistentry>
775
776
777 <varlistentry>
778 <term>--no-comment</term>
779 <listitem><para>
780 Do not write comment packets.  This option affects only
781 the generation of secret keys.  Output of option packets
782 is disabled since version 0.4.2.
783 </para></listitem></varlistentry>
784
785
786 <varlistentry>
787 <term>--comment &ParmString;</term>
788 <listitem><para>
789 Use &ParmString; as comment string in clear text signatures.
790 </para></listitem></varlistentry>
791
792
793 <varlistentry>
794 <term>--default-comment</term>
795 <listitem><para>
796 Force to write the standard comment string in clear
797 text signatures.  Use this to overwrite a --comment
798 from a config file.
799 </para></listitem></varlistentry>
800
801
802 <varlistentry>
803 <term>--no-version</term>
804 <listitem><para>
805 Omit the version string in clear text signatures.
806 </para></listitem></varlistentry>
807
808
809 <varlistentry>
810 <term>--emit-version</term>
811 <listitem><para>
812 Force to write the version string in clear text
813 signatures.  Use this to overwrite a previous
814 --no-version from a config file.
815 </para></listitem></varlistentry>
816
817
818 <varlistentry>
819 <term>-N, --notation-data &ParmNameValue;</term>
820 <listitem><para>
821 Put the name value pair into the signature as notation data.
822 &ParmName; must consists only of alphanumeric characters, digits
823 or the underscore; the first character must not be a digit.
824 &ParmValue; may be any printable string; it will encoded in UTF8,
825 so sou should have check that your --charset is set right.
826 If you prefix &ParmName; with an exclamation mark, the notation
827 data will be flagged as critical (rfc2440:5.2.3.15).
828 </para></listitem></varlistentry>
829
830
831 <varlistentry>
832 <term>--set-policy-url &ParmString;</term>
833 <listitem><para>
834 Use &ParmString; as Policy URL for signatures (rfc2440:5.2.3.19).
835 If you prefix it with an exclamation mark, the policy URL
836 packet will be flagged as critical.
837 </para></listitem></varlistentry>
838
839
840 <varlistentry>
841 <term>--set-filename &ParmString;</term>
842 <listitem><para>
843 Use &ParmString; as the name of file which is stored in
844 messages.
845 </para></listitem></varlistentry>
846
847
848 <varlistentry>
849 <term>--completes-needed &ParmN;</term>
850 <listitem><para>
851 Number of completely trusted users to introduce a new
852 key signer (defaults to 1).
853 </para></listitem></varlistentry>
854
855
856 <varlistentry>
857 <term>--marginals-needed &ParmN;</term>
858 <listitem><para>
859 Number of marginally trusted users to introduce a new
860 key signer (defaults to 3)
861 </para></listitem></varlistentry>
862
863
864 <varlistentry>
865 <term>--max-cert-depth &ParmN;</term>
866 <listitem><para>
867 Maximum depth of a certification chain (default is 5).
868 </para></listitem></varlistentry>
869
870
871 <varlistentry>
872 <term>--cipher-algo &ParmName;</term>
873 <listitem><para>
874 Use  &ParmName; as cipher algorithm. Running the program
875 with the command --version yields a list of supported
876 algorithms. If this is not used the cipher algorithm is
877 selected from the preferences stored with the key.
878 </para></listitem></varlistentry>
879
880
881 <varlistentry>
882 <term>--digest-algo &ParmName;</term>
883 <listitem><para>
884 Use  &ParmName; as message digest algorithm. Running the
885 program with the command --version yields a list of
886 supported algorithms.  Please note that using this
887 option may violate the OpenPGP requirement, that a
888 160 bit hash is to be used for DSA.
889 </para></listitem></varlistentry>
890
891
892 <varlistentry>
893 <term>--s2k-cipher-algo &ParmName;</term>
894 <listitem><para>
895 Use  &ParmName; as the cipher algorithm used to protect secret
896 keys.  The default cipher is BLOWFISH.  This cipher is
897 also used for conventional encryption if --cipher-algo
898 is not given.
899 </para></listitem></varlistentry>
900
901
902 <varlistentry>
903 <term>--s2k-digest-algo &ParmName;</term>
904 <listitem><para>
905 Use  &ParmName; as the digest algorithm used to mangle the
906 passphrases.  The default algorithm is RIPE-MD-160.
907 This digest algorithm is also used for conventional
908 encryption if --digest-algo is not given.
909 </para></listitem></varlistentry>
910
911
912 <varlistentry>
913 <term>--s2k-mode &ParmN;</term>
914 <listitem><para>
915 Selects how passphrases are mangled. If &ParmN; is 0
916 a plain passphrase (which is not recommended) will be used,
917 a 1 (default) adds a salt to the passphrase and
918 a 3 iterates the whole process a couple of times.
919 Unless --rfc1991 is used, this mode is also used
920 for conventional encryption.
921 </para></listitem></varlistentry>
922
923
924 <varlistentry>
925 <term>--compress-algo &ParmN;</term>
926 <listitem><para>
927 Use compress algorithm  &ParmN;. Default is 2 which is
928 RFC1950 compression. You may use 1 to use the old zlib
929 version which is used by PGP. The default algorithm may
930 give better results because the window size is not limited
931 to 8K. If this is not used the OpenPGP behavior is used,
932 i.e. the compression algorithm is selected from the
933 preferences; note, that this can't be done if you do
934 not encrypt the data.
935 </para></listitem></varlistentry>
936
937
938 <varlistentry>
939 <term>--throw-keyid</term>
940 <listitem><para>
941 Do not put the keyid into encrypted packets.  This option
942 hides the receiver of the message and is a countermeasure
943 against traffic analysis.  It may slow down the decryption
944 process because all available secret keys are tried.
945 </para></listitem></varlistentry>
946
947
948 <varlistentry>
949 <term>--not-dash-escaped</term>
950 <listitem><para>
951 This option changes the behavior of cleartext signatures
952 so that they can be used for patch files. You should not
953 send such an armored file via email because all spaces
954 and line endings are hashed too.  You can not use this
955 option for data which has 5 dashes at the beginning of a
956 line, patch files don't have this. A special armor header
957 line tells GnuPG about this cleartext signature option.
958 </para></listitem></varlistentry>
959
960
961 <varlistentry>
962 <term>--escape-from-lines</term>
963 <listitem><para>
964 Because some mailers change lines starting with "From "
965 to "&#60;From " it is good to handle such lines in a special
966 way when creating cleartext signatures. All other PGP
967 versions do it this way too. This option is not enabled
968 by default because it would violate rfc2440.
969 </para></listitem></varlistentry>
970
971
972 <varlistentry>
973 <term>--passphrase-fd &ParmN;</term>
974 <listitem><para>
975 Read the passphrase from file descriptor &ParmN;. If you use
976 0 for &ParmN;, the passphrase will be read from stdin.  This
977 can only be used if only one passphrase is supplied.
978 <!--fixme: make this print strong-->
979 Don't use this option if you can avoid it.
980 </para></listitem></varlistentry>
981
982
983 <varlistentry>
984 <term>--rfc1991</term>
985 <listitem><para>
986 Try to be more RFC1991 (PGP 2.x) compliant.
987 </para></listitem></varlistentry>
988
989
990 <varlistentry>
991 <term>--openpgp</term>
992 <listitem><para>
993 Reset all packet, cipher and digest options to OpenPGP
994 behavior. Use this option to reset all previous
995 options like --rfc1991, --force-v3-sigs, --s2k-*,
996 --cipher-algo, --digest-algo and --compress-algo to
997 OpenPGP compliant values.
998 </para></listitem></varlistentry>
999
1000
1001 <varlistentry>
1002 <term>--force-v3-sigs</term>
1003 <listitem><para>
1004 OpenPGP states that an implementation should generate
1005 v4 signatures but PGP 5.x recognizes v4 signatures only
1006 on key material.  This options forces v3 signatures for
1007 signatures on data.
1008 </para></listitem></varlistentry>
1009
1010
1011 <varlistentry>
1012 <term>--force-mdc</term>
1013 <listitem><para>
1014 Force the use of encryption with appended manipulation
1015 code.  This is always used with the newer cipher (those
1016 with a blocksize greater than 64 bit).
1017 </para></listitem></varlistentry>
1018
1019
1020 <varlistentry>
1021 <term>--lock-once</term>
1022 <listitem><para>
1023 Lock the databases the first time a lock is requested
1024 and do not release the lock until the process
1025 terminates.
1026 </para></listitem></varlistentry>
1027
1028
1029 <varlistentry>
1030 <term>--lock-multiple</term>
1031 <listitem><para>
1032 Release the locks every time a lock is no longer
1033 needed. Use this to override a previous --lock-once
1034 from a config file.
1035 </para></listitem></varlistentry>
1036
1037
1038 <varlistentry>
1039 <term>--no-verbose</term>
1040 <listitem><para>
1041 Reset verbose level to 0.
1042 </para></listitem></varlistentry>
1043
1044
1045 <varlistentry>
1046 <term>--no-greeting</term>
1047 <listitem><para>
1048 Suppress the initial copyright message but do not
1049 enter batch mode.
1050 </para></listitem></varlistentry>
1051
1052
1053 <varlistentry>
1054 <term>--no-armor</term>
1055 <listitem><para>
1056 Assume the input data is not in ASCII armored format.
1057 </para></listitem></varlistentry>
1058
1059
1060 <varlistentry>
1061 <term>--no-default-keyring</term>
1062 <listitem><para>
1063 Do not add the default keyrings to the list of
1064 keyrings.
1065 </para></listitem></varlistentry>
1066
1067
1068 <varlistentry>
1069 <term>--skip-verify</term>
1070 <listitem><para>
1071 Skip the signature verification step.  This may be
1072 used to make the encryption faster if the signature
1073 verification is not needed.
1074 </para></listitem></varlistentry>
1075
1076
1077 <varlistentry>
1078 <term>--with-colons</term>
1079 <listitem><para>
1080 Print key listings delimited by colons.
1081 </para></listitem></varlistentry>
1082
1083
1084 <varlistentry>
1085 <term>--with-key-data</term>
1086 <listitem><para>
1087 Print key listings delimited by colons and print the public key data.
1088 </para></listitem></varlistentry>
1089
1090 <varlistentry>
1091 <term>--with-fingerprint</term>
1092 <listitem><para>
1093 Same as the command --fingerprint but changes only the format of the output
1094 and may be used together with another command.
1095 </para></listitem></varlistentry>
1096
1097
1098 </variablelist>
1099 </refsect1>
1100
1101 <refsect1>
1102     <title>RETURN VALUE</title>
1103     <para>
1104 The program returns 0 if everything was fine, 1 if at least
1105 a signature was bad, and other error codes for fatal errors.
1106     </para>
1107 </refsect1>
1108
1109 <refsect1>
1110     <title>EXAMPLES</title>
1111     <variablelist>
1112
1113 <varlistentry>
1114 <term>gpg -se -r <parameter/Bob/ &ParmFile;</term>
1115 <listitem><para>sign and encrypt for user Bob</para></listitem>
1116 </varlistentry>
1117
1118 <varlistentry>
1119 <term>gpg --clearsign &ParmFile;</term>
1120 <listitem><para>make a clear text signature</para></listitem>
1121 </varlistentry>
1122
1123 <varlistentry>
1124 <term>gpg -sb  &ParmFile;</term>
1125 <listitem><para>make a detached signature</para></listitem>
1126 </varlistentry>
1127
1128 <varlistentry>
1129 <term>gpg --list-keys  <parameter/user_ID/</term>
1130 <listitem><para>show keys</para></listitem>
1131 </varlistentry>
1132
1133 <varlistentry>
1134 <term>gpg --fingerprint  <parameter/user_ID/</term>
1135 <listitem><para>show fingerprint</para></listitem>
1136 </varlistentry>
1137
1138     </variablelist>
1139 </refsect1>
1140
1141
1142 <refsect1>
1143     <title>ENVIRONMENT</title>
1144
1145     <variablelist>
1146 <varlistentry>
1147 <term>HOME</term>
1148 <listitem><para>Used to locate the default home directory.</para></listitem>
1149 </varlistentry>
1150 <varlistentry>
1151 <term>GNUPGHOME</term>
1152 <listitem><para>If set directory used instead of "~/.gnupg".</para></listitem>
1153 </varlistentry>
1154     </variablelist>
1155
1156 </refsect1>
1157
1158 <refsect1>
1159     <title>FILES</title>
1160     <variablelist>
1161
1162 <varlistentry>
1163 <term>~/.gnupg/secring.gpg</term>
1164 <listitem><para>The secret keyring</para></listitem>
1165 </varlistentry>
1166
1167 <varlistentry>
1168 <term>~/.gnupg/secring.gpg.lock</term>
1169 <listitem><para>and the lock file</para></listitem>
1170 </varlistentry>
1171
1172 <varlistentry>
1173 <term>~/.gnupg/pubring.gpg</term>
1174 <listitem><para>The public keyring</para></listitem>
1175 </varlistentry>
1176
1177 <varlistentry>
1178 <term>~/.gnupg/pubring.gpg.lock</term>
1179 <listitem><para>and the lock file</para></listitem>
1180 </varlistentry>
1181
1182 <varlistentry>
1183 <term>~/.gnupg/trustdb.gpg</term>
1184 <listitem><para>The trust database</para></listitem>
1185 </varlistentry>
1186
1187 <varlistentry>
1188 <term>~/.gnupg/trustdb.gpg.lock</term>
1189 <listitem><para>and the lock file</para></listitem>
1190 </varlistentry>
1191
1192 <varlistentry>
1193 <term>~/.gnupg/options</term>
1194 <listitem><para>May contain options</para></listitem>
1195 </varlistentry>
1196
1197 <varlistentry>
1198 <term>/usr[/local]/share/gnupg/options.skel</term>
1199 <listitem><para>Skeleton options file</para></listitem>
1200 </varlistentry>
1201
1202 <varlistentry>
1203 <term>/usr[/local]/lib/gnupg/</term>
1204 <listitem><para>Default location for extensions</para></listitem>
1205 </varlistentry>
1206
1207     </variablelist>
1208 </refsect1>
1209
1210 <!-- SEE ALSO  not yet needed-->
1211
1212 <refsect1>
1213     <title>WARNINGS</title>
1214     <para>
1215 Use a *good* password for your user account and a *good* passphrase
1216 to protect your secret key.  This passphrase is the weakest part of the
1217 whole system.  Programs to do dictionary attacks on your secret keyring
1218 are very easy to write and so you should protect your "~/.gnupg/"
1219 directory very well.
1220 </para>
1221 <para>
1222 Keep in mind that, if this program is used over a network (telnet), it
1223 is *very* easy to spy out your passphrase!
1224 </para>
1225 </refsect1>
1226
1227
1228 <refsect1>
1229     <title>BUGS</title>
1230     <para>
1231 On many systems this program should be installed as setuid(root). This
1232 is necessary to lock memory pages. Locking memory pages prevents the
1233 operating system from writing memory pages to disk. If you get no
1234 warning message about insecure memory your operating system supports
1235 locking without being root. The program drops root privileges as soon
1236 as locked memory is allocated.
1237 </para>
1238 </refsect1>
1239
1240 </refentry>
1241