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