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