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