See ChangeLog: Wed Aug 4 10:34:46 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 <varlistentry>
359 <term>--sign-key &ParmName;</term>
360 <listitem><para>
361 Sign a public key with you secret key.  This is a shortcut version
362 of the subcommand "sign" from --edit.
363 </para></listitem></varlistentry>
364
365 <varlistentry>
366 <term>--lsign-key &ParmName;</term>
367 <listitem><para>
368 Sign a public key with you secret key but mark it as non-exportable.
369 This is a shortcut version of the subcommand "lsign" from --edit.
370 </para></listitem></varlistentry>
371
372 <varlistentry>
373 <term>--delete-key &ParmName;</term>
374 <listitem><para>
375 Remove key from the public keyring
376 </para></listitem></varlistentry>
377
378 <varlistentry>
379 <term>--delete-secret-key  &ParmName;</term>
380 <listitem><para>
381 Remove key from the secret and public keyring
382 </para></listitem></varlistentry>
383
384 <varlistentry>
385 <term>--gen-revoke</term>
386 <listitem><para>
387 Generate a revocation certificate for the complete key. To revoke
388 a subkey or a signature, use the --edit command.
389 </para></listitem></varlistentry>
390
391
392 <varlistentry>
393 <term>--export &OptParmNames;</term>
394 <listitem><para>
395 Either export all keys from all keyrings (default
396 keyrings and those registered via option --keyring),
397 or if at least one name is given, those of the given
398 name. The new keyring is written to stdout or to
399 the file given with option "output".  Use together
400 with --armor to mail those keys.
401 </para></listitem></varlistentry>
402
403
404 <varlistentry>
405 <term>--send-keys &OptParmNames;</term>
406 <listitem><para>
407 Same as --export but sends the keys to a keyserver.
408 Option --keyserver must be used to give the name
409 of this keyserver. Don't send your complete keyring
410 to a keyserver - select only those keys which are new
411 or changed by you.
412 </para></listitem></varlistentry>
413
414
415 <varlistentry>
416 <term>--export-all &OptParmNames;</term>
417 <listitem><para>
418 Same as --export, but does also export keys which
419 are not compatible to OpenPGP.
420 </para></listitem></varlistentry>
421
422
423 <varlistentry>
424 <term>--export-secret-keys &OptParmNames;</term>
425 <listitem><para>
426 Same as --export, but does export the secret keys.
427 This is normally not very useful and a security risk.
428 </para></listitem></varlistentry>
429
430
431 <varlistentry>
432 <term>--import &OptParmFiles;</term>
433 <term>--fast-import &OptParmFiles;</term>
434 <listitem><para>
435 Import/merge keys. This adds the given keys to the
436 keyring.
437 The fast version does not build
438 the trustdb; this can be done at any time with the
439 command --update-trustdb.
440 </para></listitem></varlistentry>
441
442
443 <varlistentry>
444 <term>--recv-keys &ParmKeyIDs;</term>
445 <listitem><para>
446 Import the keys with the given key IDs from a HKP
447 keyserver. Option --keyserver must be used to
448 give the name of this keyserver.
449 </para></listitem></varlistentry>
450
451
452 <varlistentry>
453 <term>--export-ownertrust</term>
454 <listitem><para>
455 List the assigned ownertrust values in ASCII format
456 for backup purposes
457 </para></listitem></varlistentry>
458
459
460 <varlistentry>
461 <term>--import-ownertrust &OptParmFiles;</term>
462 <listitem><para>
463 Update the trustdb with the ownertrust values stored
464 in &ParmFiles; (or stdin if not given); existing
465 values will be overwritten.
466 </para></listitem></varlistentry>
467
468
469 <varlistentry>
470 <term>--print-md <parameter>algo</parameter> &OptParmFiles;</term>
471 <listitem><para>
472 Print message digest og algorithm ALGO for all given files of stdin.
473 If "*" is used for the algorithm, digests for all available algorithms
474 are printed.
475 </para></listitem></varlistentry>
476
477
478 <varlistentry>
479 <term>--gen-random <parameter>0|1|2</parameter>
480                    <optional><parameter>count</parameter></optional></term>
481 <listitem><para>
482 Emit COUNT random bytes of the given quality level. If count is not given
483 or zero, an endless sequenece of random bytes will be emitted.
484 PLEASE, don't use this command unless you know waht you are doing, it may
485 remove precious entropy from the system!
486 </para></listitem></varlistentry>
487
488 <varlistentry>
489 <term>--gen-prime <parameter>mode</parameter>
490                   <parameter>bits</parameter>
491                    <optional><parameter>qbits</parameter></optional></term>
492 <listitem><para>
493 Use the source, Luke :-). The output format is still subject to change.
494 </para></listitem></varlistentry>
495
496
497 <varlistentry>
498 <term>--version</term>
499 <listitem><para>
500 Print version information along with a list
501 of supported algorithms.
502 </para></listitem></varlistentry>
503
504
505 <varlistentry>
506 <term>--warranty</term>
507 <listitem><para>
508 Print warranty information.
509 </para></listitem></varlistentry>
510
511
512 <varlistentry>
513 <term>-h, --help</term>
514 <listitem><para>
515 Print usage information.  This is a really long list even it does list
516 not all options.
517 </para></listitem></varlistentry>
518
519
520
521 </variablelist>
522 </refsect1>
523
524 <refsect1>
525 <title>OPTIONS</title>
526 <para>
527 Long options can be put in an options file (default "~/.gnupg/options").
528 Do not write the 2 dashes, but simply the name of the option and any
529 required arguments. Lines with a hash as the first non-white-space
530 character are ignored. Commands may be put in this file too, but that
531 does not make sense.
532 </para>
533 <para>
534 <command/gpg/ recognizes these options:
535 </para>
536
537 <variablelist>
538
539
540 <varlistentry>
541 <term>-a, --armor</term>
542 <listitem><para>
543 Create ASCII armored output.
544 </para></listitem></varlistentry>
545
546
547 <varlistentry>
548 <term>-o, --output &ParmFile;</term>
549 <listitem><para>
550 Write output to &ParmFile;.
551 </para></listitem></varlistentry>
552
553
554 <varlistentry>
555 <term>-u, --local-user &ParmName;</term>
556 <listitem><para>
557 Use &ParmName as the user ID to sign.
558 This option is silently ignored for the list commands,
559 so that it can be used in an options file.
560 </para></listitem></varlistentry>
561
562
563 <varlistentry>
564 <term>--default-key &ParmName;</term>
565 <listitem><para>
566 Use &ParmName; as default user ID for signatures.  If this
567 is not used the default user ID is the first user ID
568 found in the secret keyring.
569 </para></listitem></varlistentry>
570
571
572 <varlistentry>
573 <term>-r, --recipient &ParmName;</term>
574 <term></term>
575 <listitem><para>
576 Encrypt for user id &ParmName;. If this option is not
577 specified, GnuPG asks for the user-id unless --default-recipient is given
578 </para></listitem></varlistentry>
579
580 <varlistentry>
581 <term>--default-recipient &ParmName;</term>
582 <listitem><para>
583 Use &ParmName; as default recipient if option --recipient is not used and
584 don't ask if this is a valid one. &ParmName; must be a non empty.
585 </para></listitem></varlistentry>
586
587 <varlistentry>
588 <term>--default-recipient-self</term>
589 <listitem><para>
590 Use the default key as default recipient if option --recipient is not used and
591 don't ask if this is a valid one. The default key is the first one from the
592 secret keyring or the one set with --default-key.
593 </para></listitem></varlistentry>
594
595
596 <varlistentry>
597 <term>--no-default-recipient</term>
598 <listitem><para>
599 Reset --default-recipient and --default-recipient-self.
600 </para></listitem></varlistentry>
601
602 <varlistentry>
603 <term>--encrypt-to &ParmName;</term>
604 <listitem><para>
605 Same as --recipient but this one is intended for
606 in the options file and may be used together with
607 an own user-id as an "encrypt-to-self".  These keys
608 are only used when there are other recipients given
609 either by use of --recipient or by the asked user id.
610 No trust checking is performed for these user ids and
611 even disabled keys can be used.
612 </para></listitem></varlistentry>
613
614
615 <varlistentry>
616 <term>--no-encrypt-to</term>
617 <listitem><para>
618 Disable the use of all --encrypt-to keys.
619 </para></listitem></varlistentry>
620
621
622 <varlistentry>
623 <term>-v, --verbose</term>
624 <listitem><para>
625 Give more information during processing. If used
626 twice, the input data is listed in detail.
627 </para></listitem></varlistentry>
628
629
630 <varlistentry>
631 <term>-q, --quiet</term>
632 <listitem><para>
633 Try to be as quiet as possible.
634 </para></listitem></varlistentry>
635
636
637 <varlistentry>
638 <term>-z &ParmN;</term>
639 <listitem><para>
640 Set compression level to &ParmN;. A value of 0 for &ParmN;
641 disables compression. Default is to use the default
642 compression level of zlib (normally 6).
643 </para></listitem></varlistentry>
644
645
646 <varlistentry>
647 <term>-t, --textmode</term>
648 <listitem><para>
649 Use canonical text mode.  If -t (but not
650 --textmode) is used together with armoring
651 and signing, this enables clearsigned messages.
652 This kludge is needed for PGP compatibility;
653 normally you would use --sign or --clearsign
654 to selected the type of the signature.
655 </para></listitem></varlistentry>
656
657
658 <varlistentry>
659 <term>-n, --dry-run</term>
660 <listitem><para>
661 Don't make any changes (this is not completely implemented).
662 </para></listitem></varlistentry>
663
664
665 <varlistentry>
666 <term>-i, --interactive</term>
667 <listitem><para>
668 Prompt before overwriting any files.
669 </para></listitem></varlistentry>
670
671
672 <varlistentry>
673 <term>--batch</term>
674 <listitem><para>
675 Use batch mode.  Never ask, do not allow interactive
676 commands.
677 </para></listitem></varlistentry>
678
679
680 <varlistentry>
681 <term>--no-batch</term>
682 <listitem><para>
683 Disable batch mode.  This may be of use if --batch
684 is enabled from an options file.
685 </para></listitem></varlistentry>
686
687
688 <varlistentry>
689 <term>--yes</term>
690 <listitem><para>
691 Assume "yes" on most questions.
692 </para></listitem></varlistentry>
693
694
695 <varlistentry>
696 <term>--no</term>
697 <listitem><para>
698  Assume "no" on most questions.
699 </para></listitem></varlistentry>
700
701 <varlistentry>
702 <term>--always-trust</term>
703 <listitem><para>
704 Skip key validation and assume that used keys are always fully trusted.
705 You won't use this unless you have installed some external validation scheme.
706 </para></listitem></varlistentry>
707
708
709 <varlistentry>
710 <term>--keyserver &ParmName;</term>
711 <listitem><para>
712 Use &ParmName to lookup keys which are not yet in
713 your keyring.  This is only done while verifying
714 messages with signatures.  The option is also
715 required for the command --send-keys to
716 specify the keyserver to where the keys should
717 be send.  All keyservers synchronize with each
718 other - so there is no need to send keys to more
719 than one server.  Using the command
720 "host -l pgp.net | grep wwwkeys" gives you a
721 list of keyservers.  Because there is load
722 balancing using round-robin DNS you may notice
723 that you get different key servers.
724 </para></listitem></varlistentry>
725
726
727 <varlistentry>
728 <term>--keyring &ParmFile;</term>
729 <listitem><para>
730 Add &ParmFile to the list of keyrings.
731 If &ParmFile begins with a tilde and a slash, these
732 are replaced by the HOME directory. If the filename
733 does not contain a slash, it is assumed to be in the
734 home-directory ("~/.gnupg" if --homedir is not used).
735 The filename may be prefixed with a scheme:</para>
736 <para>"gnupg-ring:" is the default one.</para>
737 <para>"gnupg-gdbm:" may be used for a GDBM ring.</para>
738 <para>It might make sense to use it together with --no-default-keyring.
739 </para></listitem></varlistentry>
740
741
742 <varlistentry>
743 <term>--secret-keyring &ParmFile;</term>
744 <listitem><para>
745 Same as --keyring but for the secret keyrings.
746 </para></listitem></varlistentry>
747
748
749 <varlistentry>
750 <term>--homedir &ParmDir;</term>
751 <listitem><para>
752 Set the name of the home directory to &ParmDir; If this
753 option is not used it defaults to "~/.gnupg". It does
754 not make sense to use this in a options file. This
755 also overrides the environment variable "GNUPGHOME".
756 </para></listitem></varlistentry>
757
758
759 <varlistentry>
760 <term>--charset &ParmName;</term>
761 <listitem><para>
762 Set the name of the native character set.  This is used
763 to convert some strings to proper UTF-8 encoding.
764 Valid values for &ParmName; are:</para>
765 <variablelist>
766 <varlistentry>
767 <term>iso-8859-1</term><listitem><para>This is the default Latin 1 set.</para></listitem>
768 </varlistentry>
769 <varlistentry>
770 <term>iso-8859-2</term><listitem><para>The Latin 2 set.</para></listitem>
771 </varlistentry>
772 <varlistentry>
773 <term>koi8-r</term><listitem><para>The usual Russian set (rfc1489).</para></listitem>
774 </varlistentry>
775 </variablelist>
776 </listitem></varlistentry>
777
778
779 <varlistentry>
780 <term>--utf8-strings</term>
781 <term>--no-utf8-strings</term>
782 <listitem><para>
783 Assume that the arguments are already given as UTF8 strings.  The default
784 (--no-utf8-strings)
785 is to assume that arguments are encoded in the character set as specified
786 by --charset. These options effects all following arguments.  Both options may
787 used multiple times.
788 </para></listitem></varlistentry>
789
790
791 <varlistentry>
792 <term>--options &ParmFile;</term>
793 <listitem><para>
794 Read options from &ParmFile; and do not try to read
795 them from the default options file in the homedir
796 (see --homedir). This option is ignored if used
797 in an options file.
798 </para></listitem></varlistentry>
799
800
801 <varlistentry>
802 <term>--no-options</term>
803 <listitem><para>
804 Shortcut for "--options /dev/null".  This option is
805 detected before an attempt to open an option file.
806 </para></listitem></varlistentry>
807
808
809 <varlistentry>
810 <term>--load-extension &ParmName;</term>
811 <listitem><para>
812 Load an extension module. If &ParmName; does not
813 contain a slash it is searched in "/usr/local/lib/gnupg"
814 See the manual for more information about extensions.
815 </para></listitem></varlistentry>
816
817
818 <varlistentry>
819 <term>--debug &ParmFlags;</term>
820 <listitem><para>
821 Set debugging flags. All flags are or-ed and &ParmFlags; may
822 be given in C syntax (e.g. 0x0042).
823 </para></listitem></varlistentry>
824
825
826 <varlistentry>
827 <term>--debug-all</term>
828 <listitem><para>
829  Set all useful debugging flags.
830 </para></listitem></varlistentry>
831
832
833 <varlistentry>
834 <term>--status-fd &ParmN;</term>
835 <listitem><para>
836 Write special status strings to the file descriptor &ParmN;.
837 See the file DETAILS in the documentation for a listing of them.
838 </para></listitem></varlistentry>
839
840
841 <varlistentry>
842 <term>--logger-fd &ParmN;</term>
843 <listitem><para>
844 Write log output to file descriptor &ParmN; and not to stderr.
845 </para></listitem></varlistentry>
846
847
848 <varlistentry>
849 <term>--no-comment</term>
850 <listitem><para>
851 Do not write comment packets.  This option affects only
852 the generation of secret keys.  Output of option packets
853 is disabled since version 0.4.2.
854 </para></listitem></varlistentry>
855
856
857 <varlistentry>
858 <term>--comment &ParmString;</term>
859 <listitem><para>
860 Use &ParmString; as comment string in clear text signatures.
861 </para></listitem></varlistentry>
862
863
864 <varlistentry>
865 <term>--default-comment</term>
866 <listitem><para>
867 Force to write the standard comment string in clear
868 text signatures.  Use this to overwrite a --comment
869 from a config file.
870 </para></listitem></varlistentry>
871
872
873 <varlistentry>
874 <term>--no-version</term>
875 <listitem><para>
876 Omit the version string in clear text signatures.
877 </para></listitem></varlistentry>
878
879
880 <varlistentry>
881 <term>--emit-version</term>
882 <listitem><para>
883 Force to write the version string in clear text
884 signatures.  Use this to overwrite a previous
885 --no-version from a config file.
886 </para></listitem></varlistentry>
887
888
889 <varlistentry>
890 <term>-N, --notation-data &ParmNameValue;</term>
891 <listitem><para>
892 Put the name value pair into the signature as notation data.
893 &ParmName; must consists only of alphanumeric characters, digits
894 or the underscore; the first character must not be a digit.
895 &ParmValue; may be any printable string; it will encoded in UTF8,
896 so sou should have check that your --charset is set right.
897 If you prefix &ParmName; with an exclamation mark, the notation
898 data will be flagged as critical (rfc2440:5.2.3.15).
899 </para></listitem></varlistentry>
900
901
902 <varlistentry>
903 <term>--set-policy-url &ParmString;</term>
904 <listitem><para>
905 Use &ParmString; as Policy URL for signatures (rfc2440:5.2.3.19).
906 If you prefix it with an exclamation mark, the policy URL
907 packet will be flagged as critical.
908 </para></listitem></varlistentry>
909
910
911 <varlistentry>
912 <term>--set-filename &ParmString;</term>
913 <listitem><para>
914 Use &ParmString; as the name of file which is stored in
915 messages.
916 </para></listitem></varlistentry>
917
918
919 <varlistentry>
920 <term>--completes-needed &ParmN;</term>
921 <listitem><para>
922 Number of completely trusted users to introduce a new
923 key signer (defaults to 1).
924 </para></listitem></varlistentry>
925
926
927 <varlistentry>
928 <term>--marginals-needed &ParmN;</term>
929 <listitem><para>
930 Number of marginally trusted users to introduce a new
931 key signer (defaults to 3)
932 </para></listitem></varlistentry>
933
934
935 <varlistentry>
936 <term>--max-cert-depth &ParmN;</term>
937 <listitem><para>
938 Maximum depth of a certification chain (default is 5).
939 </para></listitem></varlistentry>
940
941
942 <varlistentry>
943 <term>--cipher-algo &ParmName;</term>
944 <listitem><para>
945 Use  &ParmName; as cipher algorithm. Running the program
946 with the command --version yields a list of supported
947 algorithms. If this is not used the cipher algorithm is
948 selected from the preferences stored with the key.
949 </para></listitem></varlistentry>
950
951
952
953 <varlistentry>
954 <term>--digest-algo &ParmName;</term>
955 <listitem><para>
956 Use  &ParmName; as message digest algorithm. Running the
957 program with the command --version yields a list of
958 supported algorithms.  Please note that using this
959 option may violate the OpenPGP requirement, that a
960 160 bit hash is to be used for DSA.
961 </para></listitem></varlistentry>
962
963
964 <varlistentry>
965 <term>--s2k-cipher-algo &ParmName;</term>
966 <listitem><para>
967 Use  &ParmName; as the cipher algorithm used to protect secret
968 keys.  The default cipher is BLOWFISH.  This cipher is
969 also used for conventional encryption if --cipher-algo
970 is not given.
971 </para></listitem></varlistentry>
972
973
974 <varlistentry>
975 <term>--s2k-digest-algo &ParmName;</term>
976 <listitem><para>
977 Use  &ParmName; as the digest algorithm used to mangle the
978 passphrases.  The default algorithm is RIPE-MD-160.
979 This digest algorithm is also used for conventional
980 encryption if --digest-algo is not given.
981 </para></listitem></varlistentry>
982
983
984 <varlistentry>
985 <term>--s2k-mode &ParmN;</term>
986 <listitem><para>
987 Selects how passphrases are mangled. If &ParmN; is 0
988 a plain passphrase (which is not recommended) will be used,
989 a 1 (default) adds a salt to the passphrase and
990 a 3 iterates the whole process a couple of times.
991 Unless --rfc1991 is used, this mode is also used
992 for conventional encryption.
993 </para></listitem></varlistentry>
994
995
996 <varlistentry>
997 <term>--compress-algo &ParmN;</term>
998 <listitem><para>
999 Use compress algorithm  &ParmN;. Default is 2 which is
1000 RFC1950 compression. You may use 1 to use the old zlib
1001 version which is used by PGP. The default algorithm may
1002 give better results because the window size is not limited
1003 to 8K. If this is not used the OpenPGP behavior is used,
1004 i.e. the compression algorithm is selected from the
1005 preferences; note, that this can't be done if you do
1006 not encrypt the data.
1007 </para></listitem></varlistentry>
1008
1009
1010 <varlistentry>
1011 <term>--disable-cipher-algo &ParmName;</term>
1012 <listitem><para>
1013 Never allow the use of &ParmName; as cipher algorithm.
1014 The given name will not be checked so that a later loaded algorithm
1015 will still get disabled.
1016 </para></listitem></varlistentry>
1017
1018 <varlistentry>
1019 <term>--disable-pubkey-algo &ParmName;</term>
1020 <listitem><para>
1021 Never allow the use of &ParmName; as public key algorithm.
1022 The given name will not be checked so that a later loaded algorithm
1023 will still get disabled.
1024 </para></listitem></varlistentry>
1025
1026 <varlistentry>
1027 <term>--throw-keyid</term>
1028 <listitem><para>
1029 Do not put the keyid into encrypted packets.  This option
1030 hides the receiver of the message and is a countermeasure
1031 against traffic analysis.  It may slow down the decryption
1032 process because all available secret keys are tried.
1033 </para></listitem></varlistentry>
1034
1035
1036 <varlistentry>
1037 <term>--not-dash-escaped</term>
1038 <listitem><para>
1039 This option changes the behavior of cleartext signatures
1040 so that they can be used for patch files. You should not
1041 send such an armored file via email because all spaces
1042 and line endings are hashed too.  You can not use this
1043 option for data which has 5 dashes at the beginning of a
1044 line, patch files don't have this. A special armor header
1045 line tells GnuPG about this cleartext signature option.
1046 </para></listitem></varlistentry>
1047
1048
1049 <varlistentry>
1050 <term>--escape-from-lines</term>
1051 <listitem><para>
1052 Because some mailers change lines starting with "From "
1053 to "&#60;From " it is good to handle such lines in a special
1054 way when creating cleartext signatures. All other PGP
1055 versions do it this way too. This option is not enabled
1056 by default because it would violate rfc2440.
1057 </para></listitem></varlistentry>
1058
1059
1060 <varlistentry>
1061 <term>--passphrase-fd &ParmN;</term>
1062 <listitem><para>
1063 Read the passphrase from file descriptor &ParmN;. If you use
1064 0 for &ParmN;, the passphrase will be read from stdin.  This
1065 can only be used if only one passphrase is supplied.
1066 <!--fixme: make this print strong-->
1067 Don't use this option if you can avoid it.
1068 </para></listitem></varlistentry>
1069
1070
1071 <varlistentry>
1072 <term>--rfc1991</term>
1073 <listitem><para>
1074 Try to be more RFC1991 (PGP 2.x) compliant.
1075 </para></listitem></varlistentry>
1076
1077
1078 <varlistentry>
1079 <term>--openpgp</term>
1080 <listitem><para>
1081 Reset all packet, cipher and digest options to OpenPGP
1082 behavior. Use this option to reset all previous
1083 options like --rfc1991, --force-v3-sigs, --s2k-*,
1084 --cipher-algo, --digest-algo and --compress-algo to
1085 OpenPGP compliant values.
1086 </para></listitem></varlistentry>
1087
1088
1089 <varlistentry>
1090 <term>--force-v3-sigs</term>
1091 <listitem><para>
1092 OpenPGP states that an implementation should generate
1093 v4 signatures but PGP 5.x recognizes v4 signatures only
1094 on key material.  This options forces v3 signatures for
1095 signatures on data.
1096 </para></listitem></varlistentry>
1097
1098
1099 <varlistentry>
1100 <term>--force-mdc</term>
1101 <listitem><para>
1102 Force the use of encryption with appended manipulation
1103 code.  This is always used with the newer cipher (those
1104 with a blocksize greater than 64 bit).
1105 This option might not be implemented yet.
1106 </para></listitem></varlistentry>
1107
1108 <varlistentry>
1109 <term>--allow-non-selfsigned-uid</term>
1110 <listitem><para>
1111 Allow the import of keys with user IDs which are not self-signed.
1112 This is only allows the import - key validation will fail und you
1113 have to check the validity of the key my other means.  This hack is
1114 needed for some German keys generated with pgp 2.6.3in. You should really
1115 avoid using it, because OpenPGP has better mechanics to do separate signing
1116 and encryption keys.
1117 </para></listitem></varlistentry>
1118
1119
1120 <varlistentry>
1121 <term>--lock-once</term>
1122 <listitem><para>
1123 Lock the databases the first time a lock is requested
1124 and do not release the lock until the process
1125 terminates.
1126 </para></listitem></varlistentry>
1127
1128
1129 <varlistentry>
1130 <term>--lock-multiple</term>
1131 <listitem><para>
1132 Release the locks every time a lock is no longer
1133 needed. Use this to override a previous --lock-once
1134 from a config file.
1135 </para></listitem></varlistentry>
1136
1137
1138 <varlistentry>
1139 <term>--no-verbose</term>
1140 <listitem><para>
1141 Reset verbose level to 0.
1142 </para></listitem></varlistentry>
1143
1144
1145 <varlistentry>
1146 <term>--no-greeting</term>
1147 <listitem><para>
1148 Suppress the initial copyright message but do not
1149 enter batch mode.
1150 </para></listitem></varlistentry>
1151
1152 <varlistentry>
1153 <term>--no-secmem-warning</term>
1154 <listitem><para>
1155 Suppress the warning about "using insecure memory".
1156 </para></listitem></varlistentry>
1157
1158
1159 <varlistentry>
1160 <term>--no-armor</term>
1161 <listitem><para>
1162 Assume the input data is not in ASCII armored format.
1163 </para></listitem></varlistentry>
1164
1165
1166 <varlistentry>
1167 <term>--no-default-keyring</term>
1168 <listitem><para>
1169 Do not add the default keyrings to the list of
1170 keyrings.
1171 </para></listitem></varlistentry>
1172
1173
1174 <varlistentry>
1175 <term>--skip-verify</term>
1176 <listitem><para>
1177 Skip the signature verification step.  This may be
1178 used to make the decryption faster if the signature
1179 verification is not needed.
1180 </para></listitem></varlistentry>
1181
1182
1183 <varlistentry>
1184 <term>--with-colons</term>
1185 <listitem><para>
1186 Print key listings delimited by colons.
1187 </para></listitem></varlistentry>
1188
1189
1190 <varlistentry>
1191 <term>--with-key-data</term>
1192 <listitem><para>
1193 Print key listings delimited by colons and print the public key data.
1194 </para></listitem></varlistentry>
1195
1196 <varlistentry>
1197 <term>--with-fingerprint</term>
1198 <listitem><para>
1199 Same as the command --fingerprint but changes only the format of the output
1200 and may be used together with another command.
1201 </para></listitem></varlistentry>
1202
1203 <varlistentry>
1204 <term>--no-literal</term>
1205 <listitem><para>
1206 This is not for normal use.  Use the source to see for what it might be useful.
1207 </para></listitem></varlistentry>
1208
1209 <varlistentry>
1210 <term>--set-filesize</term>
1211 <listitem><para>
1212 This is not for normal use.  Use the source to see for what it might be useful.
1213 </para></listitem></varlistentry>
1214
1215
1216 </variablelist>
1217 </refsect1>
1218
1219 <refsect1>
1220     <title>RETURN VALUE</title>
1221     <para>
1222 The program returns 0 if everything was fine, 1 if at least
1223 a signature was bad, and other error codes for fatal errors.
1224     </para>
1225 </refsect1>
1226
1227 <refsect1>
1228     <title>EXAMPLES</title>
1229     <variablelist>
1230
1231 <varlistentry>
1232 <term>gpg -se -r <parameter/Bob/ &ParmFile;</term>
1233 <listitem><para>sign and encrypt for user Bob</para></listitem>
1234 </varlistentry>
1235
1236 <varlistentry>
1237 <term>gpg --clearsign &ParmFile;</term>
1238 <listitem><para>make a clear text signature</para></listitem>
1239 </varlistentry>
1240
1241 <varlistentry>
1242 <term>gpg -sb  &ParmFile;</term>
1243 <listitem><para>make a detached signature</para></listitem>
1244 </varlistentry>
1245
1246 <varlistentry>
1247 <term>gpg --list-keys  <parameter/user_ID/</term>
1248 <listitem><para>show keys</para></listitem>
1249 </varlistentry>
1250
1251 <varlistentry>
1252 <term>gpg --fingerprint  <parameter/user_ID/</term>
1253 <listitem><para>show fingerprint</para></listitem>
1254 </varlistentry>
1255
1256 <varlistentry>
1257 <term>gpg --verify  <parameter/pgpfile/</term>
1258 <term>gpg --verify  <parameter/sigfile/ &OptParmFiles;</term>
1259 <listitem><para>
1260 Verify the signature of the file but do not output the data. The second form
1261 is used for detached signatures, where <parameter/sigfile/ is the detached
1262 signature (either ASCII armored of binary) and &OptParmFiles are the signed
1263 data; if this is not given the name of the file holding the signed data is
1264 constructed by cutting off the extension (".asc" or ".sig") of
1265 <parameter/sigfile/ or by asking the user for the filename.
1266 </para></listitem></varlistentry>
1267
1268     </variablelist>
1269 </refsect1>
1270
1271
1272 <refsect1>
1273     <title>ENVIRONMENT</title>
1274
1275     <variablelist>
1276 <varlistentry>
1277 <term>HOME</term>
1278 <listitem><para>Used to locate the default home directory.</para></listitem>
1279 </varlistentry>
1280 <varlistentry>
1281 <term>GNUPGHOME</term>
1282 <listitem><para>If set directory used instead of "~/.gnupg".</para></listitem>
1283 </varlistentry>
1284     </variablelist>
1285
1286 </refsect1>
1287
1288 <refsect1>
1289     <title>FILES</title>
1290     <variablelist>
1291
1292 <varlistentry>
1293 <term>~/.gnupg/secring.gpg</term>
1294 <listitem><para>The secret keyring</para></listitem>
1295 </varlistentry>
1296
1297 <varlistentry>
1298 <term>~/.gnupg/secring.gpg.lock</term>
1299 <listitem><para>and the lock file</para></listitem>
1300 </varlistentry>
1301
1302 <varlistentry>
1303 <term>~/.gnupg/pubring.gpg</term>
1304 <listitem><para>The public keyring</para></listitem>
1305 </varlistentry>
1306
1307 <varlistentry>
1308 <term>~/.gnupg/pubring.gpg.lock</term>
1309 <listitem><para>and the lock file</para></listitem>
1310 </varlistentry>
1311
1312 <varlistentry>
1313 <term>~/.gnupg/trustdb.gpg</term>
1314 <listitem><para>The trust database</para></listitem>
1315 </varlistentry>
1316
1317 <varlistentry>
1318 <term>~/.gnupg/trustdb.gpg.lock</term>
1319 <listitem><para>and the lock file</para></listitem>
1320 </varlistentry>
1321
1322 <varlistentry>
1323 <term>~/.gnupg/options</term>
1324 <listitem><para>May contain options</para></listitem>
1325 </varlistentry>
1326
1327 <varlistentry>
1328 <term>/usr[/local]/share/gnupg/options.skel</term>
1329 <listitem><para>Skeleton options file</para></listitem>
1330 </varlistentry>
1331
1332 <varlistentry>
1333 <term>/usr[/local]/lib/gnupg/</term>
1334 <listitem><para>Default location for extensions</para></listitem>
1335 </varlistentry>
1336
1337     </variablelist>
1338 </refsect1>
1339
1340 <!-- SEE ALSO  not yet needed-->
1341
1342 <refsect1>
1343     <title>WARNINGS</title>
1344     <para>
1345 Use a *good* password for your user account and a *good* passphrase
1346 to protect your secret key.  This passphrase is the weakest part of the
1347 whole system.  Programs to do dictionary attacks on your secret keyring
1348 are very easy to write and so you should protect your "~/.gnupg/"
1349 directory very well.
1350 </para>
1351 <para>
1352 Keep in mind that, if this program is used over a network (telnet), it
1353 is *very* easy to spy out your passphrase!
1354 </para>
1355 </refsect1>
1356
1357
1358 <refsect1>
1359     <title>BUGS</title>
1360     <para>
1361 On many systems this program should be installed as setuid(root). This
1362 is necessary to lock memory pages. Locking memory pages prevents the
1363 operating system from writing memory pages to disk. If you get no
1364 warning message about insecure memory your operating system supports
1365 locking without being root. The program drops root privileges as soon
1366 as locked memory is allocated.
1367 </para>
1368 </refsect1>
1369
1370 </refentry>
1371