* gpg.sgml: Note web bug behavior of auto-key-retrieve. Note that big
[gnupg.git] / doc / gpg.sgml
1 <!-- gpg.sgml - the man page for GnuPG
2     Copyright (C) 1998, 1999, 2000, 2001, 2002,
3                   2003 Free Software Foundation, Inc.
4
5     This file is part of GnuPG.
6
7     GnuPG is free software; you can redistribute it and/or modify
8     it under the terms of the GNU General Public License as published by
9     the Free Software Foundation; either version 2 of the License, or
10     (at your option) any later version.
11
12     GnuPG is distributed in the hope that it will be useful,
13     but WITHOUT ANY WARRANTY; without even the implied warranty of
14     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15     GNU General Public License for more details.
16
17     You should have received a copy of the GNU General Public License
18     along with this program; if not, write to the Free Software
19     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
20 -->
21 <!-- This file should be processed by docbook-to-man to
22      create a manual page.  This program has currently the bug
23      not to remove leading white space. So this source file does
24      not look very pretty
25
26     FIXME: generated a file with entity (e.g. pathnames) from the
27     configure scripts and include it here
28 -->
29
30
31 <!DOCTYPE refentry PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
32 <!entity ParmDir "<parameter>directory</parameter>">
33 <!entity ParmFile "<parameter>file</parameter>">
34 <!entity OptParmFile "<optional>&ParmFile;</optional>">
35 <!entity ParmFiles "<parameter>files</parameter>">
36 <!entity OptParmFiles "<optional>&ParmFiles;</optional>">
37 <!entity ParmNames "<parameter>names</parameter>">
38 <!entity OptParmNames "<optional>&ParmNames;</optional>">
39 <!entity ParmName  "<parameter>name</parameter>">
40 <!entity OptParmName  "<optional>&ParmName;</optional>">
41 <!entity ParmKeyIDs "<parameter>key IDs</parameter>">
42 <!entity ParmN      "<parameter>n</parameter>">
43 <!entity ParmFlags  "<parameter>flags</parameter>">
44 <!entity ParmString "<parameter>string</parameter>">
45 <!entity ParmValue  "<parameter>value</parameter>">
46 <!entity ParmNameValue  "<parameter>name=value</parameter>">
47 <!entity ParmNameValues "<parameter>name=value1 <optional>value2 value3 ...</optional></parameter>">
48 ]>
49
50 <refentry id="gpg">
51 <refmeta>
52   <refentrytitle>gpg</refentrytitle>
53   <manvolnum>1</manvolnum>
54   <refmiscinfo class="gnu">GNU Tools</refmiscinfo>
55 </refmeta>
56 <refnamediv>
57   <refname/gpg/
58   <refpurpose>encryption and signing tool</>
59 </refnamediv>
60 <refsynopsisdiv>
61   <synopsis>
62 <command>gpg</command>
63  <optional>--homedir <parameter/name/</optional>
64  <optional>--options <parameter/file/</optional>
65  <optional><parameter/options/</optional>
66  <parameter>command</parameter>
67  <optional><parameter/args/</optional>
68   </synopsis>
69 </refsynopsisdiv>
70
71 <refsect1>
72     <title>DESCRIPTION</title>
73     <para>
74 <command/gpg/ is the main program for the GnuPG system.
75     </para>
76     <para>
77 This man page only lists the commands and options available.
78 For more verbose documentation get the GNU Privacy Handbook (GPH) or
79 one of the other documents at http://www.gnupg.org/docs.html .
80 </para>
81 <para>
82 Please remember that option parsing stops as soon as a non option is
83 encountered, you can explicitly stop option parsing by using the
84 special option "--".
85 </para>
86 </refsect1>
87
88 <refsect1>
89 <title>COMMANDS</title>
90 <para>
91 <command/gpg/ recognizes these commands:
92 </para>
93
94 <variablelist>
95
96 <varlistentry>
97 <term>-s, --sign</term>
98 <listitem><para>
99 Make a signature. This command may be combined
100 with --encrypt.
101 </para></listitem></varlistentry>
102
103
104 <varlistentry>
105 <term>--clearsign</term>
106 <listitem><para>
107 Make a clear text signature.
108 </para></listitem></varlistentry>
109
110
111 <varlistentry>
112 <term>-b, --detach-sign</term>
113 <listitem><para>
114 Make a detached signature.
115 </para></listitem></varlistentry>
116
117
118 <varlistentry>
119 <term>-e, --encrypt</term>
120 <listitem><para>
121 Encrypt data. This option may be combined with --sign.
122 </para></listitem></varlistentry>
123
124
125 <varlistentry>
126 <term>-c, --symmetric</term>
127 <listitem><para>
128 Encrypt with a symmetric cipher using a passphrase.  The default
129 symmetric cipher used is CAST5, but may be chosen with the
130 --cipher-algo option.
131 </para></listitem></varlistentry>
132
133
134 <varlistentry>
135 <term>--store</term>
136 <listitem><para>
137 Store only (make a simple RFC1991 packet).
138 </para></listitem></varlistentry>
139
140
141 <varlistentry>
142 <term>--decrypt &OptParmFile;</term>
143 <listitem><para>
144 Decrypt &ParmFile; (or stdin if no file is specified) and
145 write it to stdout (or the file specified with
146 --output). If the decrypted file is signed, the
147 signature is also verified. This command differs
148 from the default operation, as it never writes to the
149 filename which is included in the file and it
150 rejects files which don't begin with an encrypted
151 message.
152 </para></listitem></varlistentry>
153
154
155 <varlistentry>
156 <term>--verify <optional><optional><parameter/sigfile/</optional>
157  <optional><parameter/signed-files/</optional></optional></term>
158 <listitem><para>
159 Assume that <parameter/sigfile/ is a signature and verify it
160 without generating any output.  With no arguments,
161 the signature packet is read from stdin.  If
162 only a sigfile is given, it may be a complete
163 signature or a detached signature, in which case
164 the signed stuff is expected in a file without the
165 ".sig" or ".asc" extension. 
166 With more than
167 1 argument, the first should be a detached signature
168 and the remaining files are the signed stuff.  To read the signed
169 stuff from stdin, use <literal>-</literal> as the second filename.
170 For security reasons a detached signature cannot read the signed
171 material from stdin without denoting it in the above way.
172 </para></listitem></varlistentry>
173
174 <varlistentry>
175 <term>--verify-files <optional><parameter/files/</optional></term>
176 <listitem><para>
177 This is a special version of the --verify command which does not work with
178 detached signatures.  The command expects the files to be verified either
179 on the command line or reads the filenames from stdin;  each name must be on
180 separate line. The command is intended for quick checking of many files.
181 </para></listitem></varlistentry>
182
183 <varlistentry>
184 <term>--encrypt-files <optional><parameter/files/</optional></term>
185 <listitem><para>
186 This is a special version of the --encrypt command. The command expects
187 the files to be encrypted either on the command line or reads the filenames
188 from stdin; each name must be on separate line. The command is intended
189 for a quick encryption of multiple files.
190 </para></listitem></varlistentry>
191
192 <varlistentry>
193 <term>--decrypt-files <optional><parameter/files/</optional></term>
194 <listitem><para>
195 The same as --encrypt-files with the difference that files will be
196 decrypted. The syntax or the filenames is the same.
197 </para></listitem></varlistentry>
198
199 <!--
200 B<-k> [I<username>] [I<keyring>]
201     Kludge to be somewhat compatible with PGP.
202     Without arguments, all public keyrings are listed.
203     With one argument, only I<keyring> is listed.
204     Special combinations are also allowed, but they may
205     give strange results when combined with more options.
206     B<-kv>    Same as B<-k>
207     B<-kvv>   List the signatures with every key.
208     B<-kvvv>  Additionally check all signatures.
209     B<-kvc>   List fingerprints
210     B<-kvvc>  List fingerprints and signatures
211
212     B<This command may be removed in the future!>
213 -->
214
215 <varlistentry>
216 <term>--list-keys &OptParmNames;</term>
217 <term>--list-public-keys &OptParmNames;</term>
218 <listitem><para>
219 List all keys from the public keyrings, or just the ones given on the
220 command line.
221 </para><para>
222 Avoid using the output of this command in scripts or other programs as
223 it is likely to change as GnuPG changes.  See --with-colons for a
224 machine-parseable key listing command that is appropriate for use in
225 scripts and other programs.
226 </para></listitem></varlistentry>
227
228
229 <varlistentry>
230 <term>--list-secret-keys &OptParmNames;</term>
231 <listitem><para>
232 List all keys from the secret keyrings, or just the ones given on the
233 command line.  A '#' after the letters 'sec' means that the secret key
234 is not usable (for example, if it was created via
235 --export-secret-subkeys).
236 </para></listitem></varlistentry>
237
238
239 <varlistentry>
240 <term>--list-sigs &OptParmNames;</term>
241 <listitem><para>
242 Same as --list-keys, but the signatures are listed too.
243 </para><para>
244 For each signature listed, there are several flags in between the
245 "sig" tag and keyid.  These flags give additional information about
246 each signature.  From left to right, they are the numbers 1-3 for
247 certificate check level (see --default-cert-check-level), "L" for a
248 local or non-exportable signature (see --lsign-key), "R" for a
249 nonRevocable signature (see --nrsign-key), "P" for a signature that
250 contains a policy URL (see --cert-policy-url), "N" for a signature
251 that contains a notation (see --cert-notation), "X" for an eXpired
252 signature (see --ask-cert-expire), and the numbers 1-9 or "T" for 10
253 and above to indicate trust signature levels (see the --edit-key
254 command "tsign").
255 </para></listitem></varlistentry>
256
257
258 <varlistentry>
259 <term>--check-sigs &OptParmNames;</term>
260 <listitem><para>
261 Same as --list-sigs, but the signatures are verified.
262 </para></listitem></varlistentry>
263
264 <varlistentry>
265 <term>--fingerprint &OptParmNames;</term>
266 <listitem><para>
267 List all keys with their fingerprints. This is the
268 same output as --list-keys but with the additional output
269 of a line with the fingerprint. May also be combined
270 with --list-sigs or --check-sigs.
271 If this command is given twice, the fingerprints of all
272 secondary keys are listed too.
273 </para></listitem></varlistentry>
274
275
276 <varlistentry>
277 <term>--list-packets</term>
278 <listitem><para>
279 List only the sequence of packets. This is mainly
280 useful for debugging.
281 </para></listitem></varlistentry>
282
283
284 <varlistentry>
285 <term>--gen-key</term>
286 <listitem><para>
287 Generate a new key pair. This command is normally only used
288 interactively.
289 </para>
290 <para>
291 There is an experimental feature which allows you to create keys
292 in batch mode. See the file <filename>doc/DETAILS</filename>
293 in the source distribution on how to use this.
294 </para></listitem></varlistentry>
295
296
297 <varlistentry>
298 <term>--edit-key &ParmName;</term>
299 <listitem><para>
300 Present a menu which enables you to do all key
301 related tasks:</para>
302     <variablelist>
303
304     <varlistentry>
305     <term>sign</term>
306     <listitem><para>
307 Make a signature on key of user &ParmName;
308 If the key is not yet signed by the default
309 user (or the users given with -u), the
310 program displays the information of the key
311 again, together with its fingerprint and
312 asks whether it should be signed. This
313 question is repeated for all users specified
314 with -u.</para></listitem></varlistentry>
315     <varlistentry>
316     <term>lsign</term>
317     <listitem><para>
318 Same as --sign but the signature is marked as
319 non-exportable and will therefore never be used
320 by others.  This may be used to make keys valid
321 only in the local environment.</para></listitem></varlistentry>
322     <varlistentry>
323     <term>nrsign</term>
324     <listitem><para>
325 Same as --sign but the signature is marked as non-revocable and can
326 therefore never be revoked.</para></listitem></varlistentry>
327     <varlistentry>
328     <term>nrlsign</term>
329     <listitem><para>
330 Combines the functionality of nrsign and lsign to make a signature
331 that is both non-revocable and
332 non-exportable.</para></listitem></varlistentry>
333     <varlistentry>
334     <term>tsign</term>
335     <listitem><para>
336 Make a trust signature.  This is a signature that combines the notions
337 of certification (like a regular signature), and trust (like the
338 "trust" command).  It is generally only useful in distinct communities
339 or groups.
340 </para></listitem></varlistentry>
341     <varlistentry>
342     <term>revsig</term>
343     <listitem><para>
344 Revoke a signature.  For every signature which has been generated by
345 one of the secret keys, GnuPG asks whether a revocation certificate
346 should be generated.
347 </para></listitem></varlistentry>
348     <varlistentry>
349     <term>trust</term>
350     <listitem><para>
351 Change the owner trust value. This updates the
352 trust-db immediately and no save is required.</para></listitem></varlistentry>
353     <varlistentry>
354     <term>disable</term>
355     <term>enable</term>
356     <listitem><para>
357 Disable or enable an entire key. A disabled key can not normally be
358 used for encryption.</para></listitem></varlistentry>
359     <varlistentry>
360     <term>adduid</term>
361     <listitem><para>
362 Create an alternate user id.</para></listitem></varlistentry>
363     <varlistentry>
364     <term>addphoto</term>
365     <listitem><para>
366 Create a photographic user id.  This will prompt for a JPEG file that
367 will be embedded into the user ID.  A very large JPEG will make for a
368 very large key.
369 </para></listitem></varlistentry>
370     <varlistentry>
371     <term>deluid</term>
372     <listitem><para>
373 Delete a user id.</para></listitem></varlistentry>
374     <varlistentry>
375     <term>revuid</term>
376     <listitem><para>
377 Revoke a user id.</para></listitem></varlistentry>
378     <varlistentry>
379     <term>addkey</term>
380     <listitem><para>
381 Add a subkey to this key.</para></listitem></varlistentry>
382     <varlistentry>
383     <term>delkey</term>
384     <listitem><para>
385 Remove a subkey.</para></listitem></varlistentry>
386     <varlistentry>
387     <term>addrevoker</term>
388     <listitem><para>
389 Add a designated revoker.  This takes one optional argument:
390 "sensitive".  If a designated revoker is marked as sensitive, it will
391 not be exported by default (see
392 export-options).</para></listitem></varlistentry>
393     <varlistentry>
394     <term>revkey</term>
395     <listitem><para>
396 Revoke a subkey.</para></listitem></varlistentry>
397     <varlistentry>
398     <term>expire</term>
399     <listitem><para>
400 Change the key expiration time.  If a subkey is selected, the
401 expiration time of this subkey will be changed.  With no selection,
402 the key expiration of the primary key is changed.
403 </para></listitem></varlistentry>
404     <varlistentry>
405     <term>passwd</term>
406     <listitem><para>
407 Change the passphrase of the secret key.</para></listitem></varlistentry>
408     <varlistentry>
409     <term>primary</term>
410     <listitem><para>
411 Flag the current user id as the primary one, removes the primary user
412 id flag from all other user ids and sets the timestamp of all affected
413 self-signatures one second ahead.  Note that setting a photo user ID
414 as primary makes it primary over other photo user IDs, and setting a
415 regular user ID as primary makes it primary over other regular user
416 IDs.
417 </para></listitem></varlistentry>
418     <varlistentry>
419     <term>uid &ParmN;</term>
420     <listitem><para>
421 Toggle selection of user id with index &ParmN;.
422 Use 0 to deselect all.</para></listitem></varlistentry>
423     <varlistentry>
424     <term>key &ParmN;</term>
425     <listitem><para>
426 Toggle selection of subkey with index &ParmN;.
427 Use 0 to deselect all.</para></listitem></varlistentry>
428     <varlistentry>
429     <term>check</term>
430     <listitem><para>
431 Check all selected user ids.</para></listitem></varlistentry>
432     <varlistentry>
433     <term>showphoto</term>
434     <listitem><para>
435 Display the selected photographic user
436 id.</para></listitem></varlistentry>
437     <varlistentry>
438     <term>pref</term>
439     <listitem><para>
440 List preferences from the selected user ID.  This shows the actual
441 preferences, without including any implied preferences.
442 </para></listitem></varlistentry>
443     <varlistentry>
444     <term>showpref</term>
445     <listitem><para>
446 More verbose preferences listing for the selected user ID.  This shows
447 the preferences in effect by including the implied preferences of
448 3DES (cipher), SHA-1 (digest), and Uncompressed (compression) if they
449 are not already included in the preference list.
450 </para></listitem></varlistentry>
451     <varlistentry>
452     <term>setpref &ParmString;</term>
453     <listitem><para>
454 Set the list of user ID preferences to &ParmString;, this should be a
455 string similar to the one printed by "pref".  Using an empty string
456 will set the default preference string, using "none" will set the
457 preferences to nil.  Use "gpg --version" to get a list of available
458 algorithms.  This command just initializes an internal list and does
459 not change anything unless another command (such as "updpref") which
460 changes the self-signatures is used.
461 </para></listitem></varlistentry>
462     <varlistentry>
463     <term>updpref</term>
464     <listitem><para>
465 Change the preferences of all user IDs (or just of the selected ones
466 to the current list of preferences.  The timestamp of all affected
467 self-signatures will be advanced by one second.  Note that while you
468 can change the preferences on an attribute user ID (aka "photo ID"),
469 GnuPG does not select keys via attribute user IDs so these preferences
470 will not be used by GnuPG.
471 </para></listitem></varlistentry>
472     <varlistentry>
473     <term>toggle</term>
474     <listitem><para>
475 Toggle between public and secret key listing.</para></listitem></varlistentry>
476     <varlistentry>
477     <term>save</term>
478     <listitem><para>
479 Save all changes to the key rings and quit.</para></listitem></varlistentry>
480     <varlistentry>
481     <term>quit</term>
482     <listitem><para>
483 Quit the program without updating the
484 key rings.</para></listitem></varlistentry>
485     </variablelist>
486     <para>
487 The listing shows you the key with its secondary
488 keys and all user ids. Selected keys or user ids
489 are indicated by an asterisk. The trust value is
490 displayed with the primary key: the first is the
491 assigned owner trust and the second is the calculated
492 trust value.  Letters are used for the values:</para>
493     <variablelist>
494       <varlistentry><term>-</term><listitem><para>No ownertrust assigned / not yet calculated.</para></listitem></varlistentry>
495       <varlistentry><term>e</term><listitem><para>Trust
496 calculation has failed; probably due to an expired key.</para></listitem></varlistentry>
497       <varlistentry><term>q</term><listitem><para>Not enough information for calculation.</para></listitem></varlistentry>
498       <varlistentry><term>n</term><listitem><para>Never trust this key.</para></listitem></varlistentry>
499       <varlistentry><term>m</term><listitem><para>Marginally trusted.</para></listitem></varlistentry>
500       <varlistentry><term>f</term><listitem><para>Fully trusted.</para></listitem></varlistentry>
501       <varlistentry><term>u</term><listitem><para>Ultimately trusted.</para></listitem></varlistentry>
502     </variablelist>
503 </listitem></varlistentry>
504
505 <varlistentry>
506 <term>--sign-key &ParmName;</term>
507 <listitem><para>
508 Signs a public key with your secret key. This is a shortcut version of
509 the subcommand "sign" from --edit.
510 </para></listitem></varlistentry>
511
512 <varlistentry>
513 <term>--lsign-key &ParmName;</term>
514 <listitem><para>
515 Signs a public key with your secret key but marks it as
516 non-exportable.  This is a shortcut version of the subcommand "lsign"
517 from --edit.
518 </para></listitem></varlistentry>
519
520 <varlistentry>
521 <term>--nrsign-key &ParmName;</term>
522 <listitem><para>
523 Signs a public key with your secret key but marks it as non-revocable.
524 This is a shortcut version of the subcommand "nrsign" from --edit.
525 </para></listitem></varlistentry>
526
527 <varlistentry>
528 <term>--delete-key &ParmName;</term>
529 <listitem><para>
530 Remove key from the public keyring.  In batch mode either --yes is
531 required or the key must be specified by fingerprint.  This is a
532 safeguard against accidental deletion of multiple keys.
533 </para></listitem></varlistentry>
534
535 <varlistentry>
536 <term>--delete-secret-key  &ParmName;</term>
537 <listitem><para>
538 Remove key from the secret and public keyring. In batch mode the key
539 must be specified by fingerprint.
540 </para></listitem></varlistentry>
541
542 <varlistentry>
543 <term>--delete-secret-and-public-key  &ParmName;</term>
544 <listitem><para>
545 Same as --delete-key, but if a secret key exists, it will be removed 
546 first. In batch mode the key must be specified by fingerprint.
547 </para></listitem></varlistentry>
548
549 <varlistentry>
550 <term>--gen-revoke</term>
551 <listitem><para>
552 Generate a revocation certificate for the complete key. To revoke
553 a subkey or a signature, use the --edit command.
554 </para></listitem></varlistentry>
555
556 <varlistentry>
557 <term>--desig-revoke</term>
558 <listitem><para>
559 Generate a designated revocation certificate for a key.  This allows a
560 user (with the permission of the keyholder) to revoke someone else's
561 key.
562 </para></listitem></varlistentry>
563
564 <varlistentry>
565 <term>--export &OptParmNames;</term>
566 <listitem><para>
567 Either export all keys from all keyrings (default
568 keyrings and those registered via option --keyring),
569 or if at least one name is given, those of the given
570 name. The new keyring is written to stdout or to
571 the file given with option "output".  Use together
572 with --armor to mail those keys.
573 </para></listitem></varlistentry>
574
575
576 <varlistentry>
577 <term>--send-keys &OptParmNames;</term>
578 <listitem><para>
579 Same as --export but sends the keys to a keyserver.
580 Option --keyserver must be used to give the name
581 of this keyserver. Don't send your complete keyring
582 to a keyserver - select only those keys which are new
583 or changed by you.
584 </para></listitem></varlistentry>
585
586
587 <varlistentry>
588 <term>--export-all &OptParmNames;</term>
589 <listitem><para>
590 Same as --export, but also exports keys which
591 are not compatible with OpenPGP.
592 </para></listitem></varlistentry>
593
594
595 <varlistentry>
596 <term>--export-secret-keys &OptParmNames;</term>
597 <term>--export-secret-subkeys &OptParmNames;</term>
598 <listitem><para>
599 Same as --export, but exports the secret keys instead.
600 This is normally not very useful and a security risk.
601 The second form of the command has the special property to
602 render the secret part of the primary key useless; this is
603 a GNU extension to OpenPGP and other implementations can
604 not be expected to successfully import such a key.
605
606 See the option --simple-sk-checksum if you want to import such an
607 exported key with an older OpenPGP implementation.
608 </para></listitem></varlistentry>
609
610
611 <varlistentry>
612 <term>--import &OptParmFiles;</term>
613 <term>--fast-import &OptParmFiles;</term>
614 <listitem><para>
615 Import/merge keys. This adds the given keys to the
616 keyring.  The fast version is currently just a synonym.
617 </para>
618 <para>
619 There are a few other options which control how this command works.
620 Most notable here is the --merge-only option which does not insert new keys
621 but does only the merging of new signatures, user-IDs and subkeys.
622 </para></listitem></varlistentry>
623
624
625 <varlistentry>
626 <term>--recv-keys &ParmKeyIDs;</term>
627 <listitem><para>
628 Import the keys with the given key IDs from a keyserver. Option
629 --keyserver must be used to give the name of this keyserver.
630 </para></listitem></varlistentry>
631
632 <varlistentry>
633 <term>--refresh-keys &ParmKeyIDs;</term>
634 <listitem><para>
635 Request updates from a keyserver for keys that already exist on the
636 local keyring.  This is useful for updating a key with the latest
637 signatures, user IDs, etc.  Option --keyserver must be used to give
638 the name of this keyserver.
639 </para></listitem></varlistentry>
640
641 <varlistentry>
642 <term>--search-keys &OptParmNames;</term>
643 <listitem><para>
644 Search the keyserver for the given names.  Multiple names given here
645 will be joined together to create the search string for the keyserver.
646 Option --keyserver must be used to give the name of this keyserver.
647 </para></listitem></varlistentry>
648
649 <varlistentry>
650 <term>--update-trustdb</term>
651 <listitem><para>
652 Do trust database maintenance.  This command iterates over all keys
653 and builds the Web-of-Trust. This is an interactive command because it
654 may have to ask for the "ownertrust" values for keys.  The user has to
655 give an estimation of how far she trusts the owner of the displayed
656 key to correctly certify (sign) other keys.  GnuPG only asks for the
657 ownertrust value if it has not yet been assigned to a key.  Using the
658 --edit-key menu, the assigned value can be changed at any time.
659 </para></listitem></varlistentry>
660
661 <varlistentry>
662 <term>--check-trustdb</term>
663 <listitem><para>
664 Do trust database maintenance without user interaction.  From time to
665 time the trust database must be updated so that expired keys or
666 signatures and the resulting changes in the Web-of-Trust can be
667 tracked.  Normally, GnuPG will calculate when this is required and do
668 it automatically unless --no-auto-check-trustdb is set.  This command
669 can be used to force a trust database check at any time.  The
670 processing is identical to that of --update-trustdb but it skips keys
671 with a not yet defined "ownertrust".
672 </para>
673 <para>
674 For use with cron jobs, this command can be used together with --batch
675 in which case the trust database check is done only if a check is
676 needed.  To force a run even in batch mode add the option --yes.
677 </para></listitem></varlistentry>
678
679
680 <varlistentry>
681 <term>--export-ownertrust</term>
682 <listitem><para>
683 Send the ownertrust values to stdout.  This is useful for backup
684 purposes as these values are the only ones which can't be re-created
685 from a corrupted trust DB.
686 </para></listitem></varlistentry>
687
688 <varlistentry>
689 <term>--import-ownertrust &OptParmFiles;</term>
690 <listitem><para>
691 Update the trustdb with the ownertrust values stored
692 in &ParmFiles; (or stdin if not given); existing
693 values will be overwritten.
694 </para></listitem></varlistentry>
695
696 <varlistentry>
697 <term>--rebuild-keydb-caches</term>
698 <listitem><para>
699 When updating from version 1.0.6 to 1.0.7 this command should be used
700 to create signature caches in the keyring.  It might be handy in other
701 situations too.
702 </para></listitem></varlistentry>
703
704 <varlistentry>
705 <term>--print-md <parameter>algo</parameter> &OptParmFiles;</term>
706 <term>--print-mds &OptParmFiles;</term>
707 <listitem><para>
708 Print message digest of algorithm ALGO for all given files or stdin.
709 With the second form (or a deprecated "*" as algo) digests for all
710 available algorithms are printed.
711 </para></listitem></varlistentry>
712
713
714 <varlistentry>
715 <term>--gen-random <parameter>0|1|2</parameter>
716                    <optional><parameter>count</parameter></optional></term>
717 <listitem><para>
718 Emit COUNT random bytes of the given quality level. If count is not given
719 or zero, an endless sequence of random bytes will be emitted.
720 PLEASE, don't use this command unless you know what you are doing; it may
721 remove precious entropy from the system!
722 </para></listitem></varlistentry>
723
724 <varlistentry>
725 <term>--gen-prime <parameter>mode</parameter>
726                   <parameter>bits</parameter>
727                    <optional><parameter>qbits</parameter></optional></term>
728 <listitem><para>
729 Use the source, Luke :-). The output format is still subject to change.
730 </para></listitem></varlistentry>
731
732
733 <varlistentry>
734 <term>--version</term>
735 <listitem><para>
736 Print version information along with a list
737 of supported algorithms.
738 </para></listitem></varlistentry>
739
740
741 <varlistentry>
742 <term>--warranty</term>
743 <listitem><para>
744 Print warranty information.
745 </para></listitem></varlistentry>
746
747
748 <varlistentry>
749 <term>-h, --help</term>
750 <listitem><para>
751 Print usage information.  This is a really long list even though it
752 doesn't list all options.  For every option, consult this manual.
753 </para></listitem></varlistentry>
754
755 </variablelist>
756 </refsect1>
757
758 <refsect1>
759 <title>OPTIONS</title>
760 <para>
761 Long options can be put in an options file (default
762 "~/.gnupg/gpg.conf").  Short option names will not work - for example,
763 "armor" is a valid option for the options file, while "a" is not.  Do
764 not write the 2 dashes, but simply the name of the option and any
765 required arguments.  Lines with a hash ('#') as the first
766 non-white-space character are ignored.  Commands may be put in this
767 file too, but that is not generally useful as the command will execute
768 automatically with every execution of gpg.
769 </para>
770 <para>
771 <command/gpg/ recognizes these options:
772 </para>
773
774 <variablelist>
775
776
777 <varlistentry>
778 <term>-a, --armor</term>
779 <listitem><para>
780 Create ASCII armored output.
781 </para></listitem></varlistentry>
782
783
784 <varlistentry>
785 <term>-o, --output &ParmFile;</term>
786 <listitem><para>
787 Write output to &ParmFile;.
788 </para></listitem></varlistentry>
789
790
791 <varlistentry>
792 <term>--mangle-dos-filenames</term>
793 <term>--no-mangle-dos-filenames</term>
794 <listitem><para>
795 Older version of Windows cannot handle filenames with more than one
796 dot.  --mangle-dos-filenames causes GnuPG to replace (rather than add
797 to) the extension of an output filename to avoid this problem.  This
798 option is off by default and has no effect on non-Windows platforms.
799 </para></listitem></varlistentry>
800
801
802 <varlistentry>
803 <term>-u, --local-user &ParmName;</term>
804 <listitem><para>
805 Use &ParmName as the user ID to sign.
806 This option is silently ignored for the list commands,
807 so that it can be used in an options file.
808 </para></listitem></varlistentry>
809
810
811 <varlistentry>
812 <term>--default-key &ParmName;</term>
813 <listitem><para>
814 Use &ParmName; as default user ID for signatures.  If this
815 is not used the default user ID is the first user ID
816 found in the secret keyring.
817 </para></listitem></varlistentry>
818
819
820 <varlistentry>
821 <term>-r, --recipient &ParmName;</term>
822 <term></term>
823 <listitem><para>
824 Encrypt for user id &ParmName;. If this option or --hidden-recipient
825 is not specified, GnuPG asks for the user-id unless
826 --default-recipient is given.
827 </para></listitem></varlistentry>
828
829 <varlistentry>
830 <term>-R, --hidden-recipient &ParmName;</term>
831 <term></term>
832 <listitem><para>
833 Encrypt for user id &ParmName;, but hide the keyid of the key.  This
834 option hides the receiver of the message and is a countermeasure
835 against traffic analysis.  If this option or --recipient is not
836 specified, GnuPG asks for the user-id unless --default-recipient is
837 given.
838 </para></listitem></varlistentry>
839
840 <varlistentry>
841 <term>--default-recipient &ParmName;</term>
842 <listitem><para>
843 Use &ParmName; as default recipient if option --recipient is not used and
844 don't ask if this is a valid one. &ParmName; must be non-empty.
845 </para></listitem></varlistentry>
846
847 <varlistentry>
848 <term>--default-recipient-self</term>
849 <listitem><para>
850 Use the default key as default recipient if option --recipient is not used and
851 don't ask if this is a valid one. The default key is the first one from the
852 secret keyring or the one set with --default-key.
853 </para></listitem></varlistentry>
854
855
856 <varlistentry>
857 <term>--no-default-recipient</term>
858 <listitem><para>
859 Reset --default-recipient and --default-recipient-self.
860 </para></listitem></varlistentry>
861
862 <varlistentry>
863 <term>--encrypt-to &ParmName;</term>
864 <listitem><para>
865 Same as --recipient but this one is intended for use
866 in the options file and may be used with
867 your own user-id as an "encrypt-to-self".  These keys
868 are only used when there are other recipients given
869 either by use of --recipient or by the asked user id.
870 No trust checking is performed for these user ids and
871 even disabled keys can be used.
872 </para></listitem></varlistentry>
873
874 <varlistentry>
875 <term>--hidden-encrypt-to &ParmName;</term>
876 <listitem><para>
877 Same as --hidden-recipient but this one is intended for use in the
878 options file and may be used with your own user-id as a hidden
879 "encrypt-to-self".  These keys are only used when there are other
880 recipients given either by use of --recipient or by the asked user id.
881 No trust checking is performed for these user ids and even disabled
882 keys can be used.
883 </para></listitem></varlistentry>
884
885 <varlistentry>
886 <term>--no-encrypt-to</term>
887 <listitem><para>
888 Disable the use of all --encrypt-to and --hidden-encrypt-to keys.
889 </para></listitem></varlistentry>
890
891
892 <varlistentry>
893 <term>-v, --verbose</term>
894 <listitem><para>
895 Give more information during processing. If used
896 twice, the input data is listed in detail.
897 </para></listitem></varlistentry>
898
899
900 <varlistentry>
901 <term>-q, --quiet</term>
902 <listitem><para>
903 Try to be as quiet as possible.
904 </para></listitem></varlistentry>
905
906
907 <varlistentry>
908 <term>-z &ParmN;, --compress &ParmN;</term>
909 <listitem><para>
910 Set compression level to &ParmN;. A value of 0 for &ParmN;
911 disables compression. Default is to use the default
912 compression level of zlib (normally 6).
913 </para></listitem></varlistentry>
914
915
916 <varlistentry>
917 <term>-t, --textmode</term>
918 <term>--no-textmode</term>
919 <listitem><para>
920 Use canonical text mode.  --no-textmode disables this option.  If -t
921 (but not --textmode) is used together with armoring and signing, this
922 enables clearsigned messages.  This kludge is needed for command-line
923 compatibility with command-line versions of PGP; normally you would
924 use --sign or --clearsign to select the type of the signature.
925 </para></listitem></varlistentry>
926
927
928 <varlistentry>
929 <term>-n, --dry-run</term>
930 <listitem><para>
931 Don't make any changes (this is not completely implemented).
932 </para></listitem></varlistentry>
933
934
935 <varlistentry>
936 <term>-i, --interactive</term>
937 <listitem><para>
938 Prompt before overwriting any files.
939 </para></listitem></varlistentry>
940
941
942 <varlistentry>
943 <term>--batch</term>
944 <term>--no-batch</term>
945 <listitem><para>
946 Use batch mode.  Never ask, do not allow interactive commands.
947 --no-batch disables this option.
948 </para></listitem></varlistentry>
949
950
951 <varlistentry>
952 <term>--no-tty</term>
953 <listitem><para>
954 Make sure that the TTY (terminal) is never used for any output.
955 This option is needed in some cases because GnuPG sometimes prints
956 warnings to the TTY if --batch is used.
957 </para></listitem></varlistentry>
958
959
960 <varlistentry>
961 <term>--yes</term>
962 <listitem><para>
963 Assume "yes" on most questions.
964 </para></listitem></varlistentry>
965
966
967 <varlistentry>
968 <term>--no</term>
969 <listitem><para>
970  Assume "no" on most questions.
971 </para></listitem></varlistentry>
972
973 <varlistentry>
974 <term>--default-cert-check-level &ParmN;</term>
975 <listitem><para>
976 The default to use for the check level when signing a key.
977 </para><para>
978 0 means you make no particular claim as to how carefully you verified
979 the key.
980 </para><para>
981 1 means you believe the key is owned by the person who claims to own
982 it but you could not, or did not verify the key at all.  This is
983 useful for a "persona" verification, where you sign the key of a
984 pseudonymous user.
985 </para><para>
986 2 means you did casual verification of the key.  For example, this
987 could mean that you verified that the key fingerprint and checked the
988 user ID on the key against a photo ID.
989 </para><para>
990 3 means you did extensive verification of the key.  For example, this
991 could mean that you verified the key fingerprint with the owner of the
992 key in person, and that you checked, by means of a hard to forge
993 document with a photo ID (such as a passport) that the name of the key
994 owner matches the name in the user ID on the key, and finally that you
995 verified (by exchange of email) that the email address on the key
996 belongs to the key owner.
997 </para><para>
998 Note that the examples given above for levels 2 and 3 are just that:
999 examples.  In the end, it is up to you to decide just what "casual"
1000 and "extensive" mean to you.
1001 </para><para>
1002 This option defaults to 0.
1003 </para></listitem></varlistentry>
1004
1005
1006
1007 <varlistentry>
1008 <term>--trusted-key <parameter>long key ID</parameter></term>
1009 <listitem><para>
1010 Assume that the specified key (which must be given
1011 as a  full 8 byte key ID) is as trustworthy as one of
1012 your own secret keys. This option is useful if you
1013 don't want to keep your secret keys (or one of them)
1014 online but still want to be able to check the validity of a given
1015 recipient's or signator's key. 
1016 </para></listitem></varlistentry>
1017
1018 <varlistentry>
1019 <term>--trust-model <parameter>pgp|classic|always</parameter></term>
1020 <listitem><para>
1021
1022 Set what trust model GnuPG should follow.  The models are:
1023
1024 <variablelist>
1025
1026 <varlistentry><term>pgp</term><listitem><para>
1027 This is the web-of-trust combined with trust signatures as used in PGP
1028 5.x and later.  This is the default trust model.
1029 </para></listitem></varlistentry>
1030
1031 <varlistentry><term>classic</term><listitem><para>
1032 This is the standard web-of-trust as used in PGP 2.x and earlier.
1033 </para></listitem></varlistentry>
1034
1035 <varlistentry><term>always</term><listitem><para>
1036 Skip key validation and assume that used keys are always fully
1037 trusted.  You won't use this unless you have installed some external
1038 validation scheme.  This option also suppresses the "[uncertain]" tag
1039 printed with signature checks when there is no evidence that the user
1040 ID is bound to the key.
1041 </para></listitem></varlistentry>
1042
1043 </variablelist></para></listitem></varlistentry>
1044
1045 <varlistentry>
1046 <term>--always-trust</term>
1047 <listitem><para>
1048 Identical to `--trust-model always'
1049 </para></listitem></varlistentry>
1050
1051
1052 <varlistentry>
1053 <term>--keyserver &ParmName;</term>
1054 <listitem><para>
1055 Use &ParmName as your keyserver.  This is the server that --recv-keys,
1056 --send-keys, and --search-keys will communicate with to receive keys
1057 from, send keys to, and search for keys on.  The format of the
1058 &ParmName is a URI: `scheme:[//]keyservername[:port]' The scheme is
1059 the type of keyserver: "hkp" for the Horowitz (or compatible)
1060 keyservers, "ldap" for the NAI LDAP keyserver, or "mailto" for the
1061 Horowitz email keyserver.  Note that your particular installation of
1062 GnuPG may have other keyserver types available as well.  Keyserver
1063 schemes are case-insensitive.
1064 </para><para>
1065 Most keyservers synchronize with each other, so there is generally no
1066 need to send keys to more than one server.  Using the command "host -l
1067 pgp.net | grep wwwkeys" gives you a list of HKP keyservers.  When
1068 using one of the wwwkeys servers, due to load balancing using
1069 round-robin DNS you may notice that you get a different key server
1070 each time.
1071 </para></listitem></varlistentry>
1072
1073 <varlistentry>
1074 <term>--keyserver-options <parameter>parameters</parameter></term>
1075 <listitem><para>
1076 This is a space or comma delimited string that gives options for the
1077 keyserver.  Options can be prepended with a `no-' to give the opposite
1078 meaning.  Valid import-options or export-options may be used here as
1079 well to apply to importing (--recv-key) or exporting (--send-key) a
1080 key from a keyserver.  While not all options are available for all
1081 keyserver types, some common options are:
1082 <variablelist>
1083
1084 <varlistentry>
1085 <term>include-revoked</term>
1086 <listitem><para>
1087 When searching for a key with --search-keys, include keys that are
1088 marked on the keyserver as revoked.  Note that this option is always
1089 set when using the NAI HKP keyserver, as this keyserver does not
1090 differentiate between revoked and unrevoked keys.
1091 </para></listitem></varlistentry>
1092
1093 <varlistentry>
1094 <term>include-disabled</term>
1095 <listitem><para>
1096 When searching for a key with --search-keys, include keys that are
1097 marked on the keyserver as disabled.  Note that this option is not
1098 used with HKP keyservers.
1099 </para></listitem></varlistentry>
1100
1101 <varlistentry>
1102 <term>include-subkeys</term>
1103 <listitem><para>
1104 When receiving a key, include subkeys as potential targets.  Note that
1105 this option is not used with HKP keyservers, as they do not support
1106 retrieving keys by subkey id.
1107 </para></listitem></varlistentry>
1108
1109 <varlistentry>
1110 <term>use-temp-files</term>
1111 <listitem><para>
1112 On most Unix-like platforms, GnuPG communicates with the keyserver
1113 helper program via pipes, which is the most efficient method.  This
1114 option forces GnuPG to use temporary files to communicate.  On some
1115 platforms (such as Win32 and RISC OS), this option is always enabled.
1116 </para></listitem></varlistentry>
1117
1118 <varlistentry>
1119 <term>keep-temp-files</term>
1120 <listitem><para>
1121 If using `use-temp-files', do not delete the temp files after using
1122 them.  This option is useful to learn the keyserver communication
1123 protocol by reading the temporary files.
1124 </para></listitem></varlistentry>
1125
1126 <varlistentry>
1127 <term>verbose</term>
1128 <listitem><para>
1129 Tell the keyserver helper program to be more verbose.  This option can
1130 be repeated multiple times to increase the verbosity level.
1131 </para></listitem></varlistentry>
1132
1133 <varlistentry>
1134 <term>honor-http-proxy</term>
1135 <listitem><para>
1136 For keyserver schemes that use HTTP (such as HKP), try to access the
1137 keyserver over the proxy set with the environment variable
1138 "http_proxy".
1139 </para></listitem></varlistentry>
1140
1141 <varlistentry>
1142 <term>auto-key-retrieve</term>
1143 <listitem><para>
1144 This option enables the automatic retrieving of keys from a keyserver
1145 when verifying signatures made by keys that are not on the local
1146 keyring.
1147 </para><para>
1148 Note that this option makes a "web bug" like behavior possible.
1149 Keyserver operators can see which keys you request, so by sending you
1150 a message signed by a brand new key (which you naturally will not have
1151 on your local keyring), the operator can tell both your IP address and
1152 the time when you verified the signature.
1153 </para></listitem></varlistentry>
1154
1155 </variablelist>
1156 </para></listitem></varlistentry>
1157
1158 <varlistentry>
1159 <term>--import-options <parameter>parameters</parameter></term>
1160 <listitem><para>
1161 This is a space or comma delimited string that gives options for
1162 importing keys.  Options can be prepended with a `no-' to give the
1163 opposite meaning.  The options are:
1164 <variablelist>
1165
1166 <varlistentry>
1167 <term>allow-local-sigs</term>
1168 <listitem><para>
1169 Allow importing key signatures marked as "local".  This is not
1170 generally useful unless a shared keyring scheme is being used.
1171 Defaults to no.
1172 </para></listitem></varlistentry>
1173
1174 <varlistentry>
1175 <term>repair-pks-subkey-bug</term>
1176 <listitem><para>
1177 During import, attempt to repair the damage caused by the PKS
1178 keyserver bug (pre version 0.9.6) that mangles keys with multiple
1179 subkeys.  Note that this cannot completely repair the damaged key as
1180 some crucial data is removed by the keyserver, but it does at least
1181 give you back one subkey.  Defaults to no for regular --import and to
1182 yes for keyserver --recv-keys.
1183 </para></listitem></varlistentry>
1184
1185 </variablelist>
1186 </para></listitem></varlistentry>
1187
1188 <varlistentry>
1189 <term>--export-options <parameter>parameters</parameter></term>
1190 <listitem><para>
1191 This is a space or comma delimited string that gives options for
1192 exporting keys.  Options can be prepended with a `no-' to give the
1193 opposite meaning.  The options are:
1194 <variablelist>
1195
1196 <varlistentry>
1197 <term>include-non-rfc</term>
1198 <listitem><para>
1199 Include non-RFC compliant keys in the export.  Defaults to yes.
1200 </para></listitem></varlistentry>
1201
1202 <varlistentry>
1203 <term>include-local-sigs</term>
1204 <listitem><para>
1205 Allow exporting key signatures marked as "local".  This is not
1206 generally useful unless a shared keyring scheme is being used.
1207 Defaults to no.
1208 </para></listitem></varlistentry>
1209
1210 <varlistentry>
1211 <term>include-attributes</term>
1212 <listitem><para>
1213 Include attribute user IDs (photo IDs) while exporting.  This is
1214 useful to export keys if they are going to be used by an OpenPGP
1215 program that does not accept attribute user IDs.  Defaults to yes.
1216 </para></listitem></varlistentry>
1217
1218 <varlistentry>
1219 <term>include-sensitive-revkeys</term>
1220 <listitem><para>
1221 Include designated revoker information that was marked as
1222 "sensitive".  Defaults to no.
1223 </para></listitem></varlistentry>
1224
1225 </variablelist>
1226 </para></listitem></varlistentry>
1227
1228 <varlistentry>
1229 <term>--list-options <parameter>parameters</parameter></term>
1230 <listitem><para>
1231 This is a space or comma delimited string that gives options used when
1232 listing keys and signatures (that is, --list-keys, --list-sigs,
1233 --list-public-keys, --list-secret-keys, and the --edit-key functions).
1234 Options can be prepended with a `no-' to give the opposite meaning.
1235 The options are:
1236 <variablelist>
1237
1238 <varlistentry>
1239 <term>show-photos</term>
1240 <listitem><para>
1241 Causes --list-keys, --list-sigs, --list-public-keys, and
1242 --list-secret-keys to display any photo IDs attached to the key.
1243 Defaults to no.  See also --photo-viewer.
1244 </para></listitem></varlistentry>
1245
1246 <varlistentry>
1247 <term>show-policy-url</term>
1248 <listitem><para>
1249 Show policy URLs in the --list-sigs or --check-sigs listings.
1250 Defaults to no.
1251 </para></listitem></varlistentry>
1252
1253 <varlistentry>
1254 <term>show-notation</term>
1255 <listitem><para>
1256 Show signature notations in the --list-sigs or --check-sigs listings.
1257 Defaults to no.
1258 </para></listitem></varlistentry>
1259
1260 <varlistentry>
1261 <term>show-keyserver-url</term>
1262 <listitem><para>
1263 Show any preferred keyserver URL in the --list-sigs or --check-sigs
1264 listings.  Defaults to no.
1265 </para></listitem></varlistentry>
1266
1267 <varlistentry>
1268 <term>show-validity</term>
1269 <listitem><para>
1270 Display the calculated validity of keys and user IDs during key
1271 listings.  Defaults to no.
1272 </para></listitem></varlistentry>
1273
1274 <varlistentry>
1275 <term>show-long-keyid</term>
1276 <listitem><para>
1277 Display all 64 bits (16 digits) of key IDs during key listings, rather
1278 than the more common 32 bit (8 digit) IDs.  Defaults to no.
1279 </para></listitem></varlistentry>
1280
1281 <varlistentry>
1282 <term>show-unusable-uids</term>
1283 <listitem><para>
1284 Show revoked and expired user IDs in key listings.  Defaults to no.
1285 </para></listitem></varlistentry>
1286
1287 <varlistentry>
1288 <term>show-keyring</term>
1289 <listitem><para>
1290 Display the keyring name at the head of key listings to show which
1291 keyring a given key resides on.  Defaults to no.
1292 </para></listitem></varlistentry>
1293
1294 <varlistentry>
1295 <term>show-sig-expire</term>
1296 <listitem><para>
1297 Show signature expiration dates (if any) during --list-sigs or
1298 --check-sigs listings.  Defaults to no.
1299 </para></listitem></varlistentry>
1300
1301 </variablelist>
1302 </para></listitem></varlistentry>
1303
1304 <varlistentry>
1305 <term>--verify-options <parameter>parameters</parameter></term>
1306 <listitem><para>
1307 This is a space or comma delimited string that gives options used when
1308 verifying signatures.  Options can be prepended with a `no-' to give
1309 the opposite meaning.  The options are:
1310 <variablelist>
1311
1312 <varlistentry>
1313 <term>show-photos</term>
1314 <listitem><para>
1315 Display any photo IDs present on the key that issued the signature.
1316 Defaults to no.  See also --photo-viewer.
1317 </para></listitem></varlistentry>
1318
1319 <varlistentry>
1320 <term>show-policy-url</term>
1321 <listitem><para>
1322 Show policy URLs in the signature being verified.  Defaults to no.
1323 </para></listitem></varlistentry>
1324
1325 <varlistentry>
1326 <term>show-notation</term>
1327 <listitem><para>
1328 Show signature notations in the signature being verified.  Defaults to
1329 no.
1330 </para></listitem></varlistentry>
1331
1332 <varlistentry>
1333 <term>show-keyserver-url</term>
1334 <listitem><para>
1335 Show any preferred keyserver URL in the signature being verified.
1336 Defaults to no.
1337 </para></listitem></varlistentry>
1338
1339 <varlistentry>
1340 <term>show-validity</term>
1341 <listitem><para>
1342 Display the calculated validity of the user IDs on the key that issued
1343 the signature.  Defaults to no.
1344 </para></listitem></varlistentry>
1345
1346 <varlistentry>
1347 <term>show-long-keyid</term>
1348 <listitem><para>
1349 Display all 64 bits (16 digits) of key IDs during signature
1350 verification, rather than the more common 32 bit (8 digit) IDs.
1351 Defaults to no.
1352 </para></listitem></varlistentry>
1353
1354 <varlistentry>
1355 <term>show-unusable-uids</term>
1356 <listitem><para>
1357 Show revoked and expired user IDs during signature verification.
1358 Defaults to no.
1359 </para></listitem></varlistentry>
1360
1361 </variablelist>
1362 </para></listitem></varlistentry>
1363
1364 <varlistentry>
1365 <term>--show-photos</term>
1366 <term>--no-show-photos</term>
1367 <listitem><para>
1368 Causes --list-keys, --list-sigs, --list-public-keys,
1369 --list-secret-keys, and verifying a signature to also display the
1370 photo ID attached to the key, if any.  See also --photo-viewer.  These
1371 options are deprecated.  Use `--list-options [no-]show-photos' and/or
1372 `--verify-options [no-]show-photos' instead.
1373 </para></listitem></varlistentry>
1374
1375 <varlistentry>
1376 <term>--photo-viewer &ParmString;</term>
1377 <listitem><para>
1378 This is the command line that should be run to view a photo ID.  "%i"
1379 will be expanded to a filename containing the photo.  "%I" does the
1380 same, except the file will not be deleted once the viewer exits.
1381 Other flags are "%k" for the key ID, "%K" for the long key ID, "%f"
1382 for the key fingerprint, "%t" for the extension of the image type
1383 (e.g. "jpg"), "%T" for the MIME type of the image (e.g. "image/jpeg"),
1384 and "%%" for an actual percent sign.  If neither %i or %I are present,
1385 then the photo will be supplied to the viewer on standard input.
1386 </para><para>
1387 The default viewer is "xloadimage -fork -quiet -title 'KeyID 0x%k'
1388 stdin".  Note that if your image viewer program is not secure, then
1389 executing it from GnuPG does not make it secure.
1390 </para></listitem></varlistentry>
1391
1392 <varlistentry>
1393 <term>--exec-path &ParmString;</term>
1394 <listitem><para>
1395 Sets a list of directories to search for photo viewers and keyserver
1396 helpers.  If not provided, keyserver helpers use the compiled-in
1397 default directory, and photo viewers use the $PATH environment
1398 variable.
1399 </para></listitem></varlistentry>
1400
1401 <varlistentry>
1402 <term>--show-keyring</term>
1403 <listitem><para>
1404 Display the keyring name at the head of key listings to show which
1405 keyring a given key resides on.  This option is deprecated: use
1406 `--list-options [no-]show-keyring' instead.
1407 </para></listitem></varlistentry>
1408
1409 <varlistentry>
1410 <term>--keyring &ParmFile;</term>
1411 <listitem><para>
1412 Add &ParmFile; to the list of keyrings.  If &ParmFile; begins with a
1413 tilde and a slash, these are replaced by the HOME directory. If the
1414 filename does not contain a slash, it is assumed to be in the GnuPG
1415 home directory ("~/.gnupg" if --homedir is not used).  The filename
1416 may be prefixed with a scheme:</para>
1417 <para>"gnupg-ring:" is the default one.</para>
1418 <para>It might make sense to use it together with --no-default-keyring.
1419 </para></listitem></varlistentry>
1420
1421
1422 <varlistentry>
1423 <term>--secret-keyring &ParmFile;</term>
1424 <listitem><para>
1425 Same as --keyring but for the secret keyrings.
1426 </para></listitem></varlistentry>
1427
1428 <varlistentry>
1429 <term>--primary-keyring &ParmFile;</term>
1430 <listitem><para>
1431 Designate &ParmFile; as the primary public keyring.  This means that
1432 newly imported keys (via --import or keyserver --recv-from) will go to
1433 this keyring.
1434 </para></listitem></varlistentry>
1435
1436 <varlistentry>
1437 <term>--trustdb-name &ParmFile;</term>
1438 <listitem><para>
1439
1440 Use &ParmFile; instead of the default trustdb.  If &ParmFile; begins
1441 with a tilde and a slash, these are replaced by the HOME directory. If
1442 the filename does not contain a slash, it is assumed to be in the
1443 GnuPG home directory ("~/.gnupg" if --homedir is not used).
1444
1445 </para></listitem></varlistentry>
1446
1447
1448 <varlistentry>
1449 <term>--homedir &ParmDir;</term>
1450 <listitem><para>
1451 Set the name of the home directory to &ParmDir; If this
1452 option is not used it defaults to "~/.gnupg". It does
1453 not make sense to use this in a options file. This
1454 also overrides the environment variable "GNUPGHOME".
1455 </para></listitem></varlistentry>
1456
1457
1458 <varlistentry>
1459 <term>--charset &ParmName;</term>
1460 <listitem><para>
1461 Set the name of the native character set.  This is used
1462 to convert some strings to proper UTF-8 encoding. If this option is not used, the default character set is determined
1463 from the current locale.  A verbosity level of 3 shows the used one.
1464 Valid values for &ParmName; are:</para>
1465 <variablelist>
1466 <varlistentry>
1467 <term>iso-8859-1</term><listitem><para>This is the Latin 1 set.</para></listitem>
1468 </varlistentry>
1469 <varlistentry>
1470 <term>iso-8859-2</term><listitem><para>The Latin 2 set.</para></listitem>
1471 </varlistentry>
1472 <varlistentry>
1473 <term>iso-8859-15</term><listitem><para>This is currently an alias for
1474 the Latin 1 set.</para></listitem>
1475 </varlistentry>
1476 <varlistentry>
1477 <term>koi8-r</term><listitem><para>The usual Russian set (rfc1489).</para></listitem>
1478 </varlistentry>
1479 <varlistentry>
1480 <term>utf-8</term><listitem><para>Bypass all translations and assume
1481 that the OS uses native UTF-8 encoding.</para></listitem>
1482 </varlistentry>
1483 </variablelist>
1484 </listitem></varlistentry>
1485
1486
1487 <varlistentry>
1488 <term>--utf8-strings</term>
1489 <term>--no-utf8-strings</term>
1490 <listitem><para>
1491 Assume that the arguments are already given as UTF8 strings.  The default
1492 (--no-utf8-strings)
1493 is to assume that arguments are encoded in the character set as specified
1494 by --charset. These options affect all following arguments.  Both options may
1495 be used multiple times.
1496 </para></listitem></varlistentry>
1497
1498
1499 <varlistentry>
1500 <term>--options &ParmFile;</term>
1501 <listitem><para>
1502 Read options from &ParmFile; and do not try to read
1503 them from the default options file in the homedir
1504 (see --homedir). This option is ignored if used
1505 in an options file.
1506 </para></listitem></varlistentry>
1507
1508
1509 <varlistentry>
1510 <term>--no-options</term>
1511 <listitem><para>
1512 Shortcut for "--options /dev/null".  This option is
1513 detected before an attempt to open an option file.
1514 Using this option will also prevent the creation of a 
1515 "~./gnupg" homedir.
1516 </para></listitem></varlistentry>
1517
1518
1519 <varlistentry>
1520 <term>--load-extension &ParmName;</term>
1521 <listitem><para>
1522 Load an extension module. If &ParmName; does not contain a slash it is
1523 searched for in the directory configured when GnuPG was built
1524 (generally "/usr/local/lib/gnupg").  Extensions are not generally
1525 useful anymore, and the use of this option is deprecated.
1526 </para></listitem></varlistentry>
1527
1528
1529 <varlistentry>
1530 <term>--debug &ParmFlags;</term>
1531 <listitem><para>
1532 Set debugging flags. All flags are or-ed and &ParmFlags; may
1533 be given in C syntax (e.g. 0x0042).
1534 </para></listitem></varlistentry>
1535
1536
1537 <varlistentry>
1538 <term>--debug-all</term>
1539 <listitem><para>
1540  Set all useful debugging flags.
1541 </para></listitem></varlistentry>
1542
1543
1544 <varlistentry>
1545 <term>--enable-progress-filter</term>
1546 <listitem><para>
1547 Enable certain PROGRESS status outputs.  This option allows frontends
1548 to display a progress indicator while gpg is processing larger files.
1549 There is a slight performance overhead using it.
1550 </para></listitem></varlistentry>
1551
1552
1553 <varlistentry>
1554 <term>--status-fd &ParmN;</term>
1555 <listitem><para>
1556 Write special status strings to the file descriptor &ParmN;.
1557 See the file DETAILS in the documentation for a listing of them.
1558 </para></listitem></varlistentry>
1559
1560
1561 <varlistentry>
1562 <term>--logger-fd &ParmN;</term>
1563 <listitem><para>
1564 Write log output to file descriptor &ParmN; and not to stderr.
1565 </para></listitem></varlistentry>
1566
1567
1568 <varlistentry>
1569 <term>--attribute-fd &ParmN;</term>
1570 <listitem><para>
1571 Write attribute subpackets to the file descriptor &ParmN;.  This is
1572 most useful for use with --status-fd, since the status messages are
1573 needed to separate out the various subpackets from the stream
1574 delivered to the file descriptor.
1575 </para></listitem></varlistentry>
1576
1577
1578 <varlistentry>
1579 <term>--sk-comments</term>
1580 <term>--no-sk-comments</term>
1581 <listitem><para>
1582 Include secret key comment packets when exporting secret keys.  This
1583 is a GnuPG extension to the OpenPGP standard, and is off by default.
1584 Please note that this has nothing to do with the comments in clear
1585 text signatures or armor headers.  --no-sk-comments disables this
1586 option.
1587 </para></listitem></varlistentry>
1588
1589
1590 <varlistentry>
1591 <term>--comment &ParmString;</term>
1592 <term>--no-comments</term>
1593 <listitem><para>
1594 Use &ParmString; as a comment string in clear text signatures and
1595 ASCII armored messages or keys (see --armor).  The default behavior is
1596 not to use a comment string.  --comment may be repeated multiple times
1597 to get multiple comment strings.  --no-comments removes all comments.
1598 </para></listitem></varlistentry>
1599
1600
1601 <varlistentry>
1602 <term>--emit-version</term>
1603 <term>--no-emit-version</term>
1604 <listitem><para>
1605 Force inclusion of the version string in ASCII armored output.
1606 --no-emit-version disables this option.
1607 </para></listitem></varlistentry>
1608
1609
1610 <varlistentry>
1611 <term>--sig-notation &ParmNameValue;</term>
1612 <term>--cert-notation &ParmNameValue;</term>
1613 <term>-N, --set-notation &ParmNameValue;</term>
1614 <listitem><para>
1615 Put the name value pair into the signature as notation data.
1616 &ParmName; must consist only of printable characters or spaces, and
1617 must contain a '@' character.  This is to help prevent pollution of
1618 the IETF reserved notation namespace.  The --expert flag overrides the
1619 '@' check.  &ParmValue; may be any printable string; it will be
1620 encoded in UTF8, so you should check that your --charset is set
1621 correctly.  If you prefix &ParmName; with an exclamation mark, the
1622 notation data will be flagged as critical (rfc2440:5.2.3.15).
1623 --sig-notation sets a notation for data signatures.  --cert-notation
1624 sets a notation for key signatures (certifications).  --set-notation
1625 sets both.
1626 </para>
1627
1628 <para>
1629 There are special codes that may be used in notation names.  "%k" will
1630 be expanded into the key ID of the key being signed, "%K" into the
1631 long key ID of the key being signed, "%f" into the fingerprint of the
1632 key being signed, "%s" into the key ID of the key making the
1633 signature, "%S" into the long key ID of the key making the signature,
1634 "%g" into the fingerprint of the key making the signature (which might
1635 be a subkey), "%p" into the fingerprint of the primary key of the key
1636 making the signature, and "%%" results in a single "%".  %k, %K, and
1637 %f are only meaningful when making a key signature (certification).
1638 </para>
1639
1640 </listitem></varlistentry>
1641
1642 <varlistentry>
1643 <term>--show-notation</term>
1644 <term>--no-show-notation</term>
1645 <listitem><para>
1646 Show signature notations in the --list-sigs or --check-sigs listings
1647 as well as when verifying a signature with a notation in it.  These
1648 options are deprecated.  Use `--list-options [no-]show-notation'
1649 and/or `--verify-options [no-]show-notation' instead.
1650 </para></listitem></varlistentry>
1651
1652
1653 <varlistentry>
1654 <term>--sig-policy-url &ParmString;</term>
1655 <term>--cert-policy-url &ParmString;</term>
1656 <term>--set-policy-url &ParmString;</term>
1657 <listitem><para>
1658 Use &ParmString; as a Policy URL for signatures (rfc2440:5.2.3.19).
1659 If you prefix it with an exclamation mark, the policy URL packet will
1660 be flagged as critical.  --sig-policy-url sets a a policy url for data
1661 signatures.  --cert-policy-url sets a policy url for key signatures
1662 (certifications).  --set-policy-url sets both.
1663 </para><para>
1664 The same %-expandos used for notation data are available here as well.
1665 </para></listitem></varlistentry>
1666
1667 <varlistentry>
1668 <term>--show-policy-url</term>
1669 <term>--no-show-policy-url</term>
1670 <listitem><para>
1671 Show policy URLs in the --list-sigs or --check-sigs listings as well
1672 as when verifying a signature with a policy URL in it.  These options
1673 are deprecated.  Use `--list-options [no-]show-policy-url' and/or
1674 `--verify-options [no-]show-policy-url' instead.
1675 </para></listitem></varlistentry>
1676
1677
1678 <varlistentry>
1679 <term>--sig-keyserver-url &ParmString;</term>
1680 <listitem><para>
1681 Use &ParmString; as a preferred keyserver URL for data signatures.  If
1682 you prefix it with an exclamation mark, the keyserver URL packet will
1683 be flagged as critical.  </para><para>
1684 The same %-expandos used for notation data are available here as well.
1685 </para></listitem></varlistentry>
1686
1687
1688 <varlistentry>
1689 <term>--set-filename &ParmString;</term>
1690 <listitem><para>
1691 Use &ParmString; as the filename which is stored inside messages.
1692 This overrides the default, which is to use the actual filename of the
1693 file being encrypted.
1694 </para></listitem></varlistentry>
1695
1696 <varlistentry>
1697 <term>--for-your-eyes-only</term>
1698 <term>--no-for-your-eyes-only</term>
1699 <listitem><para>
1700 Set the `for your eyes only' flag in the message.  This causes GnuPG
1701 to refuse to save the file unless the --output option is given, and
1702 PGP to use the "secure viewer" with a Tempest-resistant font to
1703 display the message.  This option overrides --set-filename.
1704 --no-for-your-eyes-only disables this option.
1705 </para></listitem></varlistentry>
1706
1707 <varlistentry>
1708 <term>--use-embedded-filename</term>
1709 <listitem><para>
1710 Try to create a file with a name as embedded in the data.
1711 This can be a dangerous option as it allows to overwrite files.
1712 </para></listitem></varlistentry>
1713
1714
1715 <varlistentry>
1716 <term>--completes-needed &ParmN;</term>
1717 <listitem><para>
1718 Number of completely trusted users to introduce a new
1719 key signer (defaults to 1).
1720 </para></listitem></varlistentry>
1721
1722
1723 <varlistentry>
1724 <term>--marginals-needed &ParmN;</term>
1725 <listitem><para>
1726 Number of marginally trusted users to introduce a new
1727 key signer (defaults to 3)
1728 </para></listitem></varlistentry>
1729
1730
1731 <varlistentry>
1732 <term>--max-cert-depth &ParmN;</term>
1733 <listitem><para>
1734 Maximum depth of a certification chain (default is 5).
1735 </para></listitem></varlistentry>
1736
1737
1738 <varlistentry>
1739 <term>--cipher-algo &ParmName;</term>
1740 <listitem><para>
1741 Use  &ParmName; as cipher algorithm. Running the program
1742 with the command --version yields a list of supported
1743 algorithms. If this is not used the cipher algorithm is
1744 selected from the preferences stored with the key.
1745 </para></listitem></varlistentry>
1746
1747
1748 <varlistentry>
1749 <term>--digest-algo &ParmName;</term>
1750 <listitem><para>
1751 Use &ParmName; as the message digest algorithm. Running the program
1752 with the command --version yields a list of supported algorithms.
1753 </para></listitem></varlistentry>
1754
1755
1756 <varlistentry>
1757 <term>--compress-algo &ParmName;</term>
1758 <listitem><para>
1759 Use compression algorithm &ParmName;.  "zlib" is RFC1950 ZLIB
1760 compression.  "zip" is RFC-1951 ZIP compression which is used by PGP.
1761 "uncompressed" or "none" disables compression.  If this option is not
1762 used, the default behavior is to examine the recipient key preferences
1763 to see which algorithms the recipient supports.  If all else fails,
1764 ZIP is used for maximum compatibility.  Note, however, that ZLIB may
1765 give better compression results if that is more important, as the
1766 compression window size is not limited to 8k.
1767 </para></listitem></varlistentry>
1768
1769
1770 <varlistentry>
1771 <term>--cert-digest-algo &ParmName;</term>
1772 <listitem><para>
1773 Use &ParmName; as the message digest algorithm used when signing a
1774 key.  Running the program with the command --version yields a list of
1775 supported algorithms.  Be aware that if you choose an algorithm that
1776 GnuPG supports but other OpenPGP implementations do not, then some
1777 users will not be able to use the key signatures you make, or quite
1778 possibly your entire key.
1779 </para></listitem></varlistentry>
1780
1781
1782 <varlistentry>
1783 <term>--s2k-cipher-algo &ParmName;</term>
1784 <listitem><para>
1785 Use &ParmName; as the cipher algorithm used to protect secret keys.
1786 The default cipher is CAST5.  This cipher is also used for
1787 conventional encryption if --personal-cipher-preferences and
1788 --cipher-algo is not given.
1789 </para></listitem></varlistentry>
1790
1791
1792 <varlistentry>
1793 <term>--s2k-digest-algo &ParmName;</term>
1794 <listitem><para>
1795 Use &ParmName; as the digest algorithm used to mangle the passphrases.
1796 The default algorithm is SHA-1.
1797 </para></listitem></varlistentry>
1798
1799
1800 <varlistentry>
1801 <term>--s2k-mode &ParmN;</term>
1802 <listitem><para>
1803 Selects how passphrases are mangled. If &ParmN; is 0 a plain
1804 passphrase (which is not recommended) will be used, a 1 adds a salt to
1805 the passphrase and a 3 (the default) iterates the whole process a
1806 couple of times.  Unless --rfc1991 is used, this mode is also used for
1807 conventional encryption.
1808 </para></listitem></varlistentry>
1809
1810
1811 <varlistentry>
1812 <term>--simple-sk-checksum</term>
1813 <listitem><para>
1814 Secret keys are integrity protected by using a SHA-1 checksum.  This
1815 method will be part of an enhanced OpenPGP specification but GnuPG
1816 already uses it as a countermeasure against certain attacks.  Old
1817 applications don't understand this new format, so this option may be
1818 used to switch back to the old behaviour.  Using this this option
1819 bears a security risk.  Note that using this option only takes effect
1820 when the secret key is encrypted - the simplest way to make this
1821 happen is to change the passphrase on the key (even changing it to the
1822 same value is acceptable).
1823 </para></listitem></varlistentry>
1824
1825
1826 <varlistentry>
1827 <term>--disable-cipher-algo &ParmName;</term>
1828 <listitem><para>
1829 Never allow the use of &ParmName; as cipher algorithm.
1830 The given name will not be checked so that a later loaded algorithm
1831 will still get disabled.
1832 </para></listitem></varlistentry>
1833
1834 <varlistentry>
1835 <term>--disable-pubkey-algo &ParmName;</term>
1836 <listitem><para>
1837 Never allow the use of &ParmName; as public key algorithm.
1838 The given name will not be checked so that a later loaded algorithm
1839 will still get disabled.
1840 </para></listitem></varlistentry>
1841
1842 <varlistentry>
1843 <term>--no-sig-cache</term>
1844 <listitem><para>
1845 Do not cache the verification status of key signatures.
1846 Caching gives a much better performance in key listings.  However, if
1847 you suspect that your public keyring is not save against write
1848 modifications, you can use this option to disable the caching.  It
1849 probably does not make sense to disable it because all kind of damage
1850 can be done if someone else has write access to your public keyring.
1851 </para></listitem></varlistentry>
1852
1853 <varlistentry>
1854 <term>--no-sig-create-check</term>
1855 <listitem><para>
1856 GnuPG normally verifies each signature right after creation to protect
1857 against bugs and hardware malfunctions which could leak out bits from
1858 the secret key.  This extra verification needs some time (about 115%
1859 for DSA keys), and so this option can be used to disable it.
1860 However, due to the fact that the signature creation needs manual
1861 interaction, this performance penalty does not matter in most settings.
1862 </para></listitem></varlistentry>
1863
1864 <varlistentry>
1865 <term>--auto-check-trustdb</term>
1866 <term>--no-auto-check-trustdb</term>
1867 <listitem><para>
1868 If GnuPG feels that its information about the Web-of-Trust has to be
1869 updated, it automatically runs the --check-trustdb command internally.
1870 This may be a time consuming process.  --no-auto-check-trustdb
1871 disables this option.
1872 </para></listitem></varlistentry>
1873
1874 <varlistentry>
1875 <term>--throw-keyid</term>
1876 <listitem><para>
1877 Do not put the keyids into encrypted packets.  This option hides the
1878 receiver of the message and is a countermeasure against traffic
1879 analysis.  It may slow down the decryption process because all
1880 available secret keys are tried.
1881 </para></listitem></varlistentry>
1882
1883 <varlistentry>
1884 <term>--no-throw-keyid</term>
1885 <listitem><para>
1886 Resets the --throw-keyid option.
1887 </para></listitem></varlistentry>
1888
1889 <varlistentry>
1890 <term>--not-dash-escaped</term>
1891 <listitem><para>
1892 This option changes the behavior of cleartext signatures
1893 so that they can be used for patch files. You should not
1894 send such an armored file via email because all spaces
1895 and line endings are hashed too.  You can not use this
1896 option for data which has 5 dashes at the beginning of a
1897 line, patch files don't have this. A special armor header
1898 line tells GnuPG about this cleartext signature option.
1899 </para></listitem></varlistentry>
1900
1901
1902 <varlistentry>
1903 <term>--escape-from-lines</term>
1904 <term>--no-escape-from-lines</term>
1905 <listitem><para>
1906 Because some mailers change lines starting with "From " to "&#62;From
1907 " it is good to handle such lines in a special way when creating
1908 cleartext signatures to prevent the mail system from breaking the
1909 signature.  Note that all other PGP versions do it this way too.
1910 Enabled by default.  --no-escape-from-lines disables this option.
1911 </para></listitem></varlistentry>
1912
1913
1914 <varlistentry>
1915 <term>--passphrase-fd &ParmN;</term>
1916 <listitem><para>
1917 Read the passphrase from file descriptor &ParmN;. If you use
1918 0 for &ParmN;, the passphrase will be read from stdin.  This
1919 can only be used if only one passphrase is supplied.
1920 <!--fixme: make this print strong-->
1921 Don't use this option if you can avoid it.
1922 </para></listitem></varlistentry>
1923
1924 <varlistentry>
1925 <term>--command-fd &ParmN;</term>
1926 <listitem><para>
1927 This is a replacement for the deprecated shared-memory IPC mode.
1928 If this option is enabled, user input on questions is not expected
1929 from the TTY but from the given file descriptor.  It should be used
1930 together with --status-fd. See the file doc/DETAILS in the source
1931 distribution for details on how to use it.
1932 </para></listitem></varlistentry>
1933
1934 <varlistentry>
1935 <term>--use-agent</term>
1936 <term>--no-use-agent</term>
1937 <listitem><para>
1938 Try to use the GnuPG-Agent. Please note that this agent is still under
1939 development.  With this option, GnuPG first tries to connect to the
1940 agent before it asks for a passphrase.  --no-use-agent disables this
1941 option.
1942 </para></listitem></varlistentry>
1943
1944 <varlistentry>
1945 <term>--gpg-agent-info</term>
1946 <listitem><para>
1947 Override the value of the environment variable
1948 <literal>GPG_AGENT_INFO</literal>.  This is only used when --use-agent has been given
1949 </para></listitem></varlistentry>
1950
1951 <varlistentry>
1952 <term>Compliance options</term>
1953 <listitem><para>
1954 These options control what GnuPG is compliant to.  Only one of these
1955 options may be active at a time.  Note that the default setting of
1956 this is nearly always the correct one.  See the INTEROPERABILITY WITH
1957 OTHER OPENPGP PROGRAMS section below before using one of these
1958 options.
1959 <variablelist>
1960
1961 <varlistentry>
1962 <term>--gnupg</term>
1963 <listitem><para>
1964 Use standard GnuPG behavior.  This is essentially OpenPGP behavior
1965 (see --openpgp), but with some additional workarounds for common
1966 compatibility problems in different versions of PGP.  This is the
1967 default option, so it is not generally needed, but it may be useful to
1968 override a different compliance option in the gpg.conf file.
1969 </para></listitem></varlistentry>
1970
1971 <varlistentry>
1972 <term>--openpgp</term>
1973 <listitem><para>
1974 Reset all packet, cipher and digest options to strict OpenPGP
1975 behavior.  Use this option to reset all previous options like
1976 --rfc1991, --force-v3-sigs, --s2k-*, --cipher-algo, --digest-algo and
1977 --compress-algo to OpenPGP compliant values.  All PGP workarounds are
1978 disabled.
1979 </para></listitem></varlistentry>
1980
1981 <varlistentry>
1982 <term>--rfc2440</term>
1983 <listitem><para>
1984 Reset all packet, cipher and digest options to strict RFC-2440
1985 behavior.  Note that this is currently the same thing as --openpgp.
1986 </para></listitem></varlistentry>
1987
1988 <varlistentry>
1989 <term>--rfc1991</term>
1990 <listitem><para>
1991 Try to be more RFC-1991 (PGP 2.x) compliant.
1992 </para></listitem></varlistentry>
1993
1994 <varlistentry>
1995 <term>--pgp2</term>
1996 <listitem><para>
1997 Set up all options to be as PGP 2.x compliant as possible, and warn if
1998 an action is taken (e.g. encrypting to a non-RSA key) that will create
1999 a message that PGP 2.x will not be able to handle.  Note that `PGP
2000 2.x' here means `MIT PGP 2.6.2'.  There are other versions of PGP 2.x
2001 available, but the MIT release is a good common baseline.
2002 </para><para>
2003 This option implies `--rfc1991 --disable-mdc --no-force-v4-certs
2004 --no-sk-comment --escape-from-lines --force-v3-sigs
2005 --no-ask-sig-expire --no-ask-cert-expire --cipher-algo IDEA
2006 --digest-algo MD5 --compress-algo 1'.  It also disables --textmode
2007 when encrypting.
2008 </para></listitem></varlistentry>
2009
2010 <varlistentry>
2011 <term>--pgp6</term>
2012 <listitem><para>
2013 Set up all options to be as PGP 6 compliant as possible.  This
2014 restricts you to the ciphers IDEA (if the IDEA plugin is installed),
2015 3DES, and CAST5, the hashes MD5, SHA1 and RIPEMD160, and the
2016 compression algorithms none and ZIP.  This also disables
2017 --throw-keyid, and making signatures with signing subkeys as PGP 6
2018 does not understand signatures made by signing subkeys.
2019 </para><para>
2020 This option implies `--disable-mdc --no-sk-comment --escape-from-lines
2021 --force-v3-sigs --no-ask-sig-expire'
2022 </para></listitem></varlistentry>
2023
2024 <varlistentry>
2025 <term>--pgp7</term>
2026 <listitem><para>
2027 Set up all options to be as PGP 7 compliant as possible.  This is
2028 identical to --pgp6 except that MDCs are not disabled, and the list of
2029 allowable ciphers is expanded to add AES128, AES192, AES256, and
2030 TWOFISH.
2031 </para></listitem></varlistentry>
2032
2033 <varlistentry>
2034 <term>--pgp8</term>
2035 <listitem><para>
2036 Set up all options to be as PGP 8 compliant as possible.  PGP 8 is a
2037 lot closer to the OpenPGP standard than previous versions of PGP, so
2038 all this does is disable --throw-keyid and set --escape-from-lines.
2039 The allowed algorithms list is the same as --pgp7 with the addition of
2040 the SHA-256 digest algorithm.
2041 </para></listitem></varlistentry>
2042
2043 </variablelist></para></listitem></varlistentry>
2044
2045 <varlistentry>
2046 <term>--force-v3-sigs</term>
2047 <term>--no-force-v3-sigs</term>
2048 <listitem><para>
2049 OpenPGP states that an implementation should generate v4 signatures
2050 but PGP versions 5 and higher only recognize v4 signatures on key
2051 material.  This option forces v3 signatures for signatures on data.
2052 Note that this option overrides --ask-sig-expire, as v3 signatures
2053 cannot have expiration dates.  --no-force-v3-sigs disables this
2054 option.
2055 </para></listitem></varlistentry>
2056
2057 <varlistentry>
2058 <term>--force-v4-certs</term>
2059 <term>--no-force-v4-certs</term>
2060 <listitem><para>
2061 Always use v4 key signatures even on v3 keys.  This option also
2062 changes the default hash algorithm for v3 RSA keys from MD5 to SHA-1.
2063 --no-force-v4-certs disables this option.
2064 </para></listitem></varlistentry>
2065
2066 <varlistentry>
2067 <term>--force-mdc</term>
2068 <listitem><para>
2069 Force the use of encryption with a modification detection code.  This
2070 is always used with the newer ciphers (those with a blocksize greater
2071 than 64 bits), or if all of the recipient keys indicate MDC support in
2072 their feature flags.
2073 </para></listitem></varlistentry>
2074
2075 <varlistentry>
2076 <term>--disable-mdc</term>
2077 <listitem><para>
2078 Disable the use of the modification detection code.  Note that by
2079 using this option, the encrypted message becomes vulnerable to a
2080 message modification attack.
2081 </para></listitem></varlistentry>
2082
2083 <varlistentry>
2084 <term>--allow-non-selfsigned-uid</term>
2085 <term>--no-allow-non-selfsigned-uid</term>
2086 <listitem><para>
2087 Allow the import and use of keys with user IDs which are not
2088 self-signed.  This is not recommended, as a non self-signed user ID is
2089 trivial to forge.  --no-allow-non-selfsigned-uid disables.
2090 </para></listitem></varlistentry>
2091
2092 <varlistentry>
2093 <term>--allow-freeform-uid</term>
2094 <listitem><para>
2095 Disable all checks on the form of the user ID while generating a new
2096 one.  This option should only be used in very special environments as
2097 it does not ensure the de-facto standard format of user IDs.
2098 </para></listitem></varlistentry>
2099
2100 <varlistentry>
2101 <term>--ignore-time-conflict</term>
2102 <listitem><para>
2103 GnuPG normally checks that the timestamps associated with keys and
2104 signatures have plausible values.  However, sometimes a signature
2105 seems to be older than the key due to clock problems.  This option
2106 makes these checks just a warning.  See also --ignore-valid-from for
2107 timestamp issues on subkeys.
2108 </para></listitem></varlistentry>
2109
2110 <varlistentry>
2111 <term>--ignore-valid-from</term>
2112 <listitem><para>
2113 GnuPG normally does not select and use subkeys created in the future.
2114 This option allows the use of such keys and thus exhibits the
2115 pre-1.0.7 behaviour.  You should not use this option unless you there
2116 is some clock problem.  See also --ignore-time-conflict for timestamp
2117 issues with signatures.
2118 </para></listitem></varlistentry>
2119
2120 <varlistentry>
2121 <term>--ignore-crc-error</term>
2122 <listitem><para>
2123 The ASCII armor used by OpenPGP is protected by a CRC checksum against
2124 transmission errors.  Sometimes it happens that the CRC gets mangled
2125 somewhere on the transmission channel but the actual content (which is
2126 protected by the OpenPGP protocol anyway) is still okay.  This option
2127 will let gpg ignore CRC errors.
2128 </para></listitem></varlistentry>
2129
2130 <varlistentry>
2131 <term>--ignore-mdc-error</term>
2132 <listitem><para>
2133 This option changes a MDC integrity protection failure into a warning.
2134 This can be useful if a message is partially corrupt, but it is
2135 necessary to get as much data as possible out of the corrupt message.
2136 However, be aware that a MDC protection failure may also mean that the
2137 message was tampered with intentionally by an attacker.
2138 </para></listitem></varlistentry>
2139
2140 <varlistentry>
2141 <term>--lock-once</term>
2142 <listitem><para>
2143 Lock the databases the first time a lock is requested
2144 and do not release the lock until the process
2145 terminates.
2146 </para></listitem></varlistentry>
2147
2148 <varlistentry>
2149 <term>--lock-multiple</term>
2150 <listitem><para>
2151 Release the locks every time a lock is no longer
2152 needed. Use this to override a previous --lock-once
2153 from a config file.
2154 </para></listitem></varlistentry>
2155
2156 <varlistentry>
2157 <term>--lock-never</term>
2158 <listitem><para>
2159 Disable locking entirely.  This option should be used only in very
2160 special environments, where it can be assured that only one process
2161 is accessing those files.  A bootable floppy with a stand-alone
2162 encryption system will probably use this.  Improper usage of this
2163 option may lead to data and key corruption.
2164 </para></listitem></varlistentry>
2165
2166 <varlistentry>
2167 <term>--no-random-seed-file</term>
2168 <listitem><para>
2169 GnuPG uses a file to store its internal random pool over invocations.
2170 This makes random generation faster; however sometimes write operations
2171 are not desired.  This option can be used to achieve that with the cost of
2172 slower random generation.
2173 </para></listitem></varlistentry>
2174
2175 <varlistentry>
2176 <term>--no-verbose</term>
2177 <listitem><para>
2178 Reset verbose level to 0.
2179 </para></listitem></varlistentry>
2180
2181 <varlistentry>
2182 <term>--no-greeting</term>
2183 <listitem><para>
2184 Suppress the initial copyright message.
2185 </para></listitem></varlistentry>
2186
2187 <varlistentry>
2188 <term>--no-secmem-warning</term>
2189 <listitem><para>
2190 Suppress the warning about "using insecure memory".
2191 </para></listitem></varlistentry>
2192
2193 <varlistentry>
2194 <term>--no-permission-warning</term>
2195 <listitem><para>
2196
2197 Suppress the warning about unsafe file and home directory (--homedir)
2198 permissions.  Note that the permission checks that GnuPG performs are
2199 not intended to be authoritative, but rather they simply warn about
2200 certain common permission problems.  Do not assume that the lack of a
2201 warning means that your system is secure.
2202 </para><para>
2203 Note that the warning for unsafe --homedir permissions cannot be
2204 supressed in the gpg.conf file, as this would allow an attacker to
2205 place an unsafe gpg.conf file in place, and use this file to supress
2206 warnings about itself.  The --homedir permissions warning may only be
2207 supressed on the command line.
2208 </para></listitem></varlistentry>
2209
2210 <varlistentry>
2211 <term>--no-mdc-warning</term>
2212 <listitem><para>
2213 Suppress the warning about missing MDC integrity protection.
2214 </para></listitem></varlistentry>
2215
2216
2217 <varlistentry>
2218 <term>--no-armor</term>
2219 <listitem><para>
2220 Assume the input data is not in ASCII armored format.
2221 </para></listitem></varlistentry>
2222
2223
2224 <varlistentry>
2225 <term>--no-default-keyring</term>
2226 <listitem><para>
2227 Do not add the default keyrings to the list of
2228 keyrings.
2229 </para></listitem></varlistentry>
2230
2231
2232 <varlistentry>
2233 <term>--skip-verify</term>
2234 <listitem><para>
2235 Skip the signature verification step.  This may be
2236 used to make the decryption faster if the signature
2237 verification is not needed.
2238 </para></listitem></varlistentry>
2239
2240
2241 <varlistentry>
2242 <term>--with-colons</term>
2243 <listitem><para>
2244 Print key listings delimited by colons.  Note that the output will be
2245 encoded in UTF-8 regardless of any --charset setting.  This format is
2246 useful when GnuPG is called from scripts and other programs as it is
2247 easily machine parsed.  The details of this format are documented in
2248 the file doc/DETAILS, which is included in the GnuPG source
2249 distribution.
2250 </para></listitem></varlistentry>
2251
2252
2253 <varlistentry>
2254 <term>--with-key-data</term>
2255 <listitem><para>
2256 Print key listings delimited by colons (like --with-colons) and print the public key data.
2257 </para></listitem></varlistentry>
2258
2259 <varlistentry>
2260 <term>--with-fingerprint</term>
2261 <listitem><para>
2262 Same as the command --fingerprint but changes only the format of the output
2263 and may be used together with another command.
2264 </para></listitem></varlistentry>
2265
2266 <varlistentry>
2267 <term>--fast-list-mode</term>
2268 <listitem><para>
2269 Changes the output of the list commands to work faster; this is achieved
2270 by leaving some parts empty.  Some applications don't need the user ID and
2271 the trust information given in the listings.  By using this options they
2272 can get a faster listing.  The exact behaviour of this option may change
2273 in future versions.
2274 </para></listitem></varlistentry>
2275
2276 <varlistentry>
2277 <term>--fixed-list-mode</term>
2278 <listitem><para>
2279 Do not merge primary user ID and primary key in --with-colon listing
2280 mode and print all timestamps as seconds since 1970-01-01.
2281 </para></listitem></varlistentry>
2282
2283 <varlistentry>
2284 <term>--list-only</term>
2285 <listitem><para>
2286 Changes the behaviour of some commands.  This is like --dry-run but
2287 different in some cases.  The semantic of this command may be extended in
2288 the future.  Currently it only skips the actual decryption pass and
2289 therefore enables a fast listing of the encryption keys.
2290 </para></listitem></varlistentry>
2291
2292 <varlistentry>
2293 <term>--no-literal</term>
2294 <listitem><para>
2295 This is not for normal use.  Use the source to see for what it might be useful.
2296 </para></listitem></varlistentry>
2297
2298 <varlistentry>
2299 <term>--set-filesize</term>
2300 <listitem><para>
2301 This is not for normal use.  Use the source to see for what it might be useful.
2302 </para></listitem></varlistentry>
2303
2304 <varlistentry>
2305 <term>--emulate-md-encode-bug</term>
2306 <listitem><para>
2307 GnuPG versions prior to 1.0.2 had a bug in the way a signature was encoded.
2308 This options enables a workaround by checking faulty signatures again with
2309 the encoding used in old versions.  This may only happen for ElGamal signatures
2310 which are not widely used.
2311 </para></listitem></varlistentry>
2312
2313 <varlistentry>
2314 <term>--show-session-key</term>
2315 <listitem><para>
2316 Display the session key used for one message. See --override-session-key
2317 for the counterpart of this option.
2318 </para>
2319 <para>
2320 We think that Key-Escrow is a Bad Thing; however the user should
2321 have the freedom to decide whether to go to prison or to reveal the content of
2322 one specific message without compromising all messages ever encrypted for one
2323 secret key. DON'T USE IT UNLESS YOU ARE REALLY FORCED TO DO SO.
2324 </para></listitem></varlistentry>
2325
2326 <varlistentry>
2327 <term>--override-session-key &ParmString; </term>
2328 <listitem><para>
2329 Don't use the public key but the session key &ParmString;.  The format of this
2330 string is the same as the one printed by --show-session-key.  This option
2331 is normally not used but comes handy in case someone forces you to reveal the
2332 content of an encrypted message; using this option you can do this without
2333 handing out the secret key.
2334 </para></listitem></varlistentry>
2335
2336 <varlistentry>
2337 <term>--ask-sig-expire</term>
2338 <term>--no-ask-sig-expire</term>
2339 <listitem><para>
2340 When making a data signature, prompt for an expiration time.  If this
2341 option is not specified, the expiration time is "never".
2342 --no-ask-sig-expire disables this option.
2343 </para></listitem></varlistentry>
2344
2345 <varlistentry>
2346 <term>--ask-cert-expire</term>
2347 <term>--no-ask-cert-expire</term>
2348 <listitem><para>
2349 When making a key signature, prompt for an expiration time.  If this
2350 option is not specified, the expiration time is "never".
2351 --no-ask-cert-expire disables this option.
2352 </para></listitem></varlistentry>
2353
2354 <varlistentry>
2355 <term>--expert</term>
2356 <term>--no-expert</term>
2357 <listitem><para>
2358 Allow the user to do certain nonsensical or "silly" things like
2359 signing an expired or revoked key, or certain potentially incompatible
2360 things like generating deprecated key types.  This also disables
2361 certain warning messages about potentially incompatible actions.  As
2362 the name implies, this option is for experts only.  If you don't fully
2363 understand the implications of what it allows you to do, leave this
2364 off.  --no-expert disables this option.
2365 </para></listitem></varlistentry>
2366
2367 <varlistentry>
2368 <term>--merge-only</term>
2369 <listitem><para>
2370 Don't insert new keys into the keyrings while doing an import.
2371 </para></listitem></varlistentry>
2372
2373 <varlistentry>
2374 <term>--allow-secret-key-import</term>
2375 <listitem><para>
2376 This is an obsolete option and is not used anywhere.
2377 </para></listitem></varlistentry>
2378
2379 <varlistentry>
2380 <term>--try-all-secrets</term>
2381 <listitem><para>
2382 Don't look at the key ID as stored in the message but try all secret keys in
2383 turn to find the right decryption key.  This option forces the behaviour as
2384 used by anonymous recipients (created by using --throw-keyid) and might come
2385 handy in case where an encrypted message contains a bogus key ID.
2386 </para></listitem></varlistentry>
2387
2388 <varlistentry>
2389 <term>--enable-special-filenames</term>
2390 <listitem><para>
2391 This options enables a mode in which filenames of the form
2392 <filename>-&#38;n</filename>, where n is a non-negative decimal number,
2393 refer to the file descriptor n and not to a file with that name.
2394 </para></listitem></varlistentry>
2395
2396 <varlistentry>
2397 <term>--no-expensive-trust-checks</term>
2398 <listitem><para>
2399 Experimental use only.
2400 </para></listitem></varlistentry>
2401
2402 <varlistentry>
2403 <term>--group &ParmNameValues;</term>
2404 <listitem><para>
2405 Sets up a named group, which is similar to aliases in email programs.
2406 Any time the group name is a recipient (-r or --recipient), it will
2407 be expanded to the values specified.
2408 </para><para>
2409 The values are &ParmKeyIDs; or fingerprints, but any key description
2410 is accepted.  Note that a value with spaces in it will be treated as
2411 two different values.  Note also there is only one level of expansion
2412 - you cannot make an group that points to another group.  When used
2413 from the command line, it may be necessary to quote the argument to
2414 this option to prevent the shell from treating it as multiple
2415 arguments.
2416 </para></listitem></varlistentry>
2417
2418 <varlistentry>
2419 <term>--preserve-permissions</term>
2420 <listitem><para>
2421 Don't change the permissions of a secret keyring back to user
2422 read/write only.  Use this option only if you really know what you are doing.
2423 </para></listitem></varlistentry>
2424
2425 <varlistentry>
2426 <term>--personal-cipher-preferences &ParmString;</term>
2427 <listitem><para>
2428 Set the list of personal cipher preferences to &ParmString;, this list
2429 should be a string similar to the one printed by the command "pref" in
2430 the edit menu.  This allows the user to factor in their own preferred
2431 algorithms when algorithms are chosen via recipient key preferences.
2432 The most highly ranked cipher in this list is also used for the
2433 --symmetric encryption command.
2434 </para></listitem></varlistentry>
2435
2436 <varlistentry>
2437 <term>--personal-digest-preferences &ParmString;</term>
2438 <listitem><para>
2439 Set the list of personal digest preferences to &ParmString;, this list
2440 should be a string similar to the one printed by the command "pref" in
2441 the edit menu.  This allows the user to factor in their own preferred
2442 algorithms when algorithms are chosen via recipient key preferences.
2443 The most highly ranked digest algorithm in this list is algo used when
2444 signing without encryption (e.g. --clearsign or --sign).  The default
2445 value is SHA-1.
2446 </para></listitem></varlistentry>
2447
2448 <varlistentry>
2449 <term>--personal-compress-preferences &ParmString;</term>
2450 <listitem><para>
2451 Set the list of personal compression preferences to &ParmString;, this
2452 list should be a string similar to the one printed by the command
2453 "pref" in the edit menu.  This allows the user to factor in their own
2454 preferred algorithms when algorithms are chosen via recipient key
2455 preferences.  The most highly ranked algorithm in this list is also
2456 used when there are no recipient keys to consider (e.g. --symmetric).
2457 </para></listitem></varlistentry>
2458
2459 <varlistentry>
2460 <term>--default-preference-list &ParmString;</term>
2461 <listitem><para>
2462 Set the list of default preferences to &ParmString;, this list should
2463 be a string similar to the one printed by the command "pref" in the
2464 edit menu.  This affects both key generation and "updpref" in the edit
2465 menu.
2466 </para></listitem></varlistentry>
2467
2468
2469 </variablelist>
2470 </refsect1>
2471
2472
2473 <refsect1>
2474     <title>How to specify a user ID</title>
2475     <para>
2476 There are different ways to specify a user ID to GnuPG; here are some
2477 examples:
2478     </para>
2479
2480     <variablelist>
2481 <varlistentry>
2482 <term></term>
2483 <listitem><para></para></listitem>
2484 </varlistentry>
2485
2486 <varlistentry>
2487 <term>234567C4</term>
2488 <term>0F34E556E</term>
2489 <term>01347A56A</term>
2490 <term>0xAB123456</term>
2491 <listitem><para>
2492 Here the key ID is given in the usual short form.
2493 </para></listitem>
2494 </varlistentry>
2495
2496 <varlistentry>
2497 <term>234AABBCC34567C4</term>
2498 <term>0F323456784E56EAB</term>
2499 <term>01AB3FED1347A5612</term>
2500 <term>0x234AABBCC34567C4</term>
2501 <listitem><para>
2502 Here the key ID is given in the long form as used by OpenPGP
2503 (you can get the long key ID using the option --with-colons).
2504 </para></listitem>
2505 </varlistentry>
2506
2507 <varlistentry>
2508 <term>1234343434343434C434343434343434</term>
2509 <term>123434343434343C3434343434343734349A3434</term>
2510 <term>0E12343434343434343434EAB3484343434343434</term>
2511 <term>0xE12343434343434343434EAB3484343434343434</term>
2512 <listitem><para>
2513 The best way to specify a key ID is by using the fingerprint of
2514 the key.  This avoids any ambiguities in case that there are duplicated
2515 key IDs (which are really rare for the long key IDs).
2516 </para></listitem>
2517 </varlistentry>
2518
2519 <varlistentry>
2520 <term>=Heinrich Heine &#60;heinrichh@uni-duesseldorf.de&#62;</term>
2521 <listitem><para>
2522 Using an exact to match string.  The equal sign indicates this.
2523 </para></listitem>
2524 </varlistentry>
2525
2526 <varlistentry>
2527 <term>&#60;heinrichh@uni-duesseldorf.de&#62;</term>
2528 <listitem><para>
2529 Using the email address part which must match exactly.  The left angle bracket
2530 indicates this email address mode.
2531 </para></listitem>
2532 </varlistentry>
2533
2534 <varlistentry>
2535 <term>+Heinrich Heine duesseldorf</term>
2536 <listitem><para>
2537 All words must match exactly (not case sensitive) but can appear in
2538 any order in the user ID.  Words are any sequences of letters,
2539 digits, the underscore and all characters with bit 7 set.
2540 </para></listitem>
2541 </varlistentry>
2542
2543 <varlistentry>
2544 <term>Heine</term>
2545 <term>*Heine</term>
2546 <listitem><para>
2547 By case insensitive substring matching.  This is the default mode but
2548 applications may want to explicitly indicate this by putting the asterisk
2549 in front.
2550 </para></listitem>
2551 </varlistentry>
2552
2553     </variablelist>
2554
2555     <para>
2556 Note that you can append an exclamation mark to key IDs or
2557 fingerprints.  This flag tells GnuPG to use exactly the given primary
2558 or secondary key and not to try to figure out which secondary or
2559 primary key to use.
2560     </para>
2561
2562 </refsect1>
2563
2564
2565 <refsect1>
2566     <title>RETURN VALUE</title>
2567     <para>
2568 The program returns 0 if everything was fine, 1 if at least
2569 a signature was bad, and other error codes for fatal errors.
2570     </para>
2571 </refsect1>
2572
2573 <refsect1>
2574     <title>EXAMPLES</title>
2575     <variablelist>
2576
2577 <varlistentry>
2578 <term>gpg -se -r <parameter/Bob/ &ParmFile;</term>
2579 <listitem><para>sign and encrypt for user Bob</para></listitem>
2580 </varlistentry>
2581
2582 <varlistentry>
2583 <term>gpg --clearsign &ParmFile;</term>
2584 <listitem><para>make a clear text signature</para></listitem>
2585 </varlistentry>
2586
2587 <varlistentry>
2588 <term>gpg -sb  &ParmFile;</term>
2589 <listitem><para>make a detached signature</para></listitem>
2590 </varlistentry>
2591
2592 <varlistentry>
2593 <term>gpg --list-keys  <parameter/user_ID/</term>
2594 <listitem><para>show keys</para></listitem>
2595 </varlistentry>
2596
2597 <varlistentry>
2598 <term>gpg --fingerprint  <parameter/user_ID/</term>
2599 <listitem><para>show fingerprint</para></listitem>
2600 </varlistentry>
2601
2602 <varlistentry>
2603 <term>gpg --verify  <parameter/pgpfile/</term>
2604 <term>gpg --verify  <parameter/sigfile/ &OptParmFiles;</term>
2605 <listitem><para>
2606 Verify the signature of the file but do not output the data. The second form
2607 is used for detached signatures, where <parameter/sigfile/ is the detached
2608 signature (either ASCII armored of binary) and &OptParmFiles are the signed
2609 data; if this is not given the name of the file holding the signed data is
2610 constructed by cutting off the extension (".asc" or ".sig") of
2611 <parameter/sigfile/ or by asking the user for the filename.
2612 </para></listitem></varlistentry>
2613
2614     </variablelist>
2615 </refsect1>
2616
2617
2618 <refsect1>
2619     <title>ENVIRONMENT</title>
2620
2621     <variablelist>
2622 <varlistentry>
2623 <term>HOME</term>
2624 <listitem><para>Used to locate the default home directory.</para></listitem>
2625 </varlistentry>
2626 <varlistentry>
2627 <term>GNUPGHOME</term>
2628 <listitem><para>If set directory used instead of "~/.gnupg".</para></listitem>
2629 </varlistentry>
2630 <varlistentry>
2631 <term>GPG_AGENT_INFO</term>
2632 <listitem><para>Used to locate the gpg-agent; only honored when
2633 --use-agent is set.  The value consists of 3 colon delimited fields: 
2634 The first is the path to the Unix Domain Socket, the second the PID of
2635 the gpg-agent and the protocol version which should be set to 1.  When
2636 starting the gpg-agent as described in its documentation, this
2637 variable is set to the correct value.  The option --gpg-agent-info can
2638 be used to override it.</para></listitem>
2639 </varlistentry>
2640 <varlistentry>
2641 <term>http_proxy</term>
2642 <listitem><para>Only honored when the keyserver-option
2643 honor-http-proxy is set.</para></listitem>
2644 </varlistentry>
2645     </variablelist>
2646
2647 </refsect1>
2648
2649 <refsect1>
2650     <title>FILES</title>
2651     <variablelist>
2652
2653 <varlistentry>
2654 <term>~/.gnupg/secring.gpg</term>
2655 <listitem><para>The secret keyring</para></listitem>
2656 </varlistentry>
2657
2658 <varlistentry>
2659 <term>~/.gnupg/secring.gpg.lock</term>
2660 <listitem><para>and the lock file</para></listitem>
2661 </varlistentry>
2662
2663 <varlistentry>
2664 <term>~/.gnupg/pubring.gpg</term>
2665 <listitem><para>The public keyring</para></listitem>
2666 </varlistentry>
2667
2668 <varlistentry>
2669 <term>~/.gnupg/pubring.gpg.lock</term>
2670 <listitem><para>and the lock file</para></listitem>
2671 </varlistentry>
2672
2673 <varlistentry>
2674 <term>~/.gnupg/trustdb.gpg</term>
2675 <listitem><para>The trust database</para></listitem>
2676 </varlistentry>
2677
2678 <varlistentry>
2679 <term>~/.gnupg/trustdb.gpg.lock</term>
2680 <listitem><para>and the lock file</para></listitem>
2681 </varlistentry>
2682
2683 <varlistentry>
2684 <term>~/.gnupg/random_seed</term>
2685 <listitem><para>used to preserve the internal random pool</para></listitem>
2686 </varlistentry>
2687
2688 <varlistentry>
2689 <term>~/.gnupg/gpg.conf</term>
2690 <listitem><para>Default configuration file</para></listitem>
2691 </varlistentry>
2692
2693 <varlistentry>
2694 <term>~/.gnupg/options</term>
2695 <listitem><para>Old style configuration file; only used when gpg.conf
2696 is not found</para></listitem>
2697 </varlistentry>
2698
2699 <varlistentry>
2700 <term>/usr[/local]/share/gnupg/options.skel</term>
2701 <listitem><para>Skeleton options file</para></listitem>
2702 </varlistentry>
2703
2704 <varlistentry>
2705 <term>/usr[/local]/lib/gnupg/</term>
2706 <listitem><para>Default location for extensions</para></listitem>
2707 </varlistentry>
2708
2709     </variablelist>
2710 </refsect1>
2711
2712 <!-- SEE ALSO  not yet needed-->
2713
2714 <refsect1>
2715     <title>WARNINGS</title>
2716     <para>
2717 Use a *good* password for your user account and a *good* passphrase
2718 to protect your secret key.  This passphrase is the weakest part of the
2719 whole system.  Programs to do dictionary attacks on your secret keyring
2720 are very easy to write and so you should protect your "~/.gnupg/"
2721 directory very well.
2722 </para>
2723 <para>
2724 Keep in mind that, if this program is used over a network (telnet), it
2725 is *very* easy to spy out your passphrase!
2726 </para>
2727 <para>
2728 If you are going to verify detached signatures, make sure that the
2729 program knows about it; either be giving both filenames on the
2730 command line or using <literal>-</literal> to specify stdin.
2731 </para>
2732 </refsect1>
2733
2734 <refsect1>
2735     <title>INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS</title>
2736 <para>
2737 GnuPG tries to be a very flexible implementation of the OpenPGP
2738 standard.  In particular, GnuPG implements many of the "optional"
2739 parts of the standard, such as the RIPEMD/160 hash, and the ZLIB
2740 compression algorithms.  It is important to be aware that not all
2741 OpenPGP programs implement these optional algorithms and that by
2742 forcing their use via the --cipher-algo, --digest-algo,
2743 --cert-digest-algo, or --compress-algo options in GnuPG, it is
2744 possible to create a perfectly valid OpenPGP message, but one that
2745 cannot be read by the intended recipient.
2746 </para>
2747
2748 <para>
2749 For example, as of this writing, no version of official PGP supports
2750 the BLOWFISH cipher algorithm.  If you use it, no PGP user will be
2751 able to decrypt your message.  The same thing applies to the ZLIB
2752 compression algorithm.  By default, GnuPG uses the OpenPGP preferences
2753 system that will always do the right thing and create messages that
2754 are usable by all recipients, regardless of which OpenPGP program they
2755 use.  Only override this safe default if you know what you are doing.
2756 </para>
2757
2758 <para>
2759 If you absolutely must override the safe default, or if the
2760 preferences on a given key are invalid for some reason, you are far
2761 better off using the --pgp2, --pgp6, --pgp7, or --pgp8 options.  These
2762 options are safe as they do not force any particular algorithms in
2763 violation of OpenPGP, but rather reduce the available algorithms to a
2764 "PGP-safe" list.
2765 </para>
2766
2767 </refsect1>
2768
2769
2770 <refsect1>
2771     <title>BUGS</title>
2772     <para>
2773 On many systems this program should be installed as setuid(root). This
2774 is necessary to lock memory pages. Locking memory pages prevents the
2775 operating system from writing memory pages to disk. If you get no
2776 warning message about insecure memory your operating system supports
2777 locking without being root. The program drops root privileges as soon
2778 as locked memory is allocated.
2779 </para>
2780 </refsect1>
2781
2782 </refentry>