* DETAILS: Document the --attribute-fd data.
[gnupg.git] / doc / gpg.texi
1 \input texinfo
2 @c This Texinfo document has been automatically generated by
3 @c docbook2texi from a DocBook documentation.  The tool used
4 @c can be found at:
5 @c <URL:http://shell.ipoline.com/~elmert/hacks/docbook2X/>
6 @c Please send any bug reports, improvements, comments, 
7 @c patches, etc. to Steve Cheng <steve@ggi-project.org>.
8
9 @setfilename gpg.info
10 @dircategory GnuPG
11 @direntry
12 * gpg: (gpg).                         GnuPG encryption and signing tool.
13 @end direntry
14
15 @node top
16 @top gpg
17 @menu
18 @end menu
19
20 @majorheading Name
21 gpg ---- encryption and signing tool</>
22
23 @majorheading Synopsis
24
25 @majorheading DESCRIPTION
26 @code{gpg} is the main program for the GnuPG system.
27
28 This man page only lists the commands and options available.
29 For more verbose documentation get the GNU Privacy Handbook (GPH) or
30 one of the other documents at http://www.gnupg.org/docs.html .
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
36 @majorheading COMMANDS
37 @code{gpg} recognizes these commands:
38
39 @table @asis
40 @item -s, ---sign
41 Make a signature. This command may be combined
42 with ---encrypt.
43
44 @item ---clearsign
45 Make a clear text signature.
46
47 @item -b, ---detach-sign
48 Make a detached signature.
49
50 @item -e, ---encrypt
51 Encrypt data. This option may be combined with ---sign.
52
53 @item -c, ---symmetric
54 Encrypt with a symmetric cipher using a passphrase. The default
55 symmetric cipher used is CAST5, but may be chosen with the
56 ---cipher-algo option.
57
58 @item ---store
59 Store only (make a simple RFC1991 packet).
60
61 @item ---decrypt @code{file}
62 Decrypt @code{file} (or stdin if no file is specified) and
63 write it to stdout (or the file specified with
64 ---output). If the decrypted file is signed, the
65 signature is also verified. This command differs
66 from the default operation, as it never writes to the
67 filename which is included in the file and it
68 rejects files which don't begin with an encrypted
69 message.
70
71 @item ---verify @code{sigfile} @code{signed-files}
72 Assume that @code{sigfile} is a signature and verify it
73 without generating any output. With no arguments,
74 the signature packet is read from stdin. If
75 only a sigfile is given, it may be a complete
76 signature or a detached signature, in which case
77 the signed stuff is expected in a file without the
78 ".sig" or ".asc" extension. 
79 With more than
80 1 argument, the first should be a detached signature
81 and the remaining files are the signed stuff. To read the signed
82 stuff from stdin, use @samp{-} as the second filename.
83 For security reasons a detached signature cannot read the signed
84 material from stdin without denoting it in the above way.
85
86 @item ---verify-files @code{files}
87 This is a special version of the ---verify command which does not work with
88 detached signatures. The command expects the files to be verified either
89 on the command line or reads the filenames from stdin; each name must be on
90 separate line. The command is intended for quick checking of many files.
91
92 @item ---encrypt-files @code{files}
93 This is a special version of the ---encrypt command. The command expects
94 the files to be encrypted either on the command line or reads the filenames
95 from stdin; each name must be on separate line. The command is intended
96 for a quick encryption of multiple files.
97
98 @item ---decrypt-files @code{files}
99 The same as ---encrypt-files with the difference that files will be
100 decrypted. The syntax or the filenames is the same.
101
102 @item ---list-keys @code{names}
103 @itemx ---list-public-keys @code{names}
104 List all keys from the public keyrings, or just the
105 ones given on the command line.
106
107 @item ---list-secret-keys @code{names}
108 List all keys from the secret keyrings, or just the ones given on the
109 command line. A '#' after the letters 'sec' means that the secret key
110 is not usable (for example, if it was created via
111 ---export-secret-subkeys).
112
113 @item ---list-sigs @code{names}
114 Same as ---list-keys, but the signatures are listed too.
115
116 @item ---check-sigs @code{names}
117 Same as ---list-sigs, but the signatures are verified.
118
119 @item ---fingerprint @code{names}
120 List all keys with their fingerprints. This is the
121 same output as ---list-keys but with the additional output
122 of a line with the fingerprint. May also be combined
123 with ---list-sigs or --check-sigs.
124 If this command is given twice, the fingerprints of all
125 secondary keys are listed too.
126
127 @item ---list-packets
128 List only the sequence of packets. This is mainly
129 useful for debugging.
130
131 @item ---gen-key
132 Generate a new key pair. This command is normally only used
133 interactively.
134
135 There is an experimental feature which allows you to create keys
136 in batch mode. See the file @file{doc/DETAILS}
137 in the source distribution on how to use this.
138
139 @item ---edit-key @code{name}
140 Present a menu which enables you to do all key
141 related tasks:
142
143 @table @asis
144 @item sign
145 Make a signature on key of user @code{name}
146 If the key is not yet signed by the default
147 user (or the users given with -u), the
148 program displays the information of the key
149 again, together with its fingerprint and
150 asks whether it should be signed. This
151 question is repeated for all users specified
152 with -u.
153
154 @item lsign
155 Same as ---sign but the signature is marked as
156 non-exportable and will therefore never be used
157 by others. This may be used to make keys valid
158 only in the local environment.
159
160 @item nrsign
161 Same as ---sign but the signature is marked as non-revocable and can
162 therefore never be revoked.
163
164 @item nrlsign
165 Combines the functionality of nrsign and lsign to make a signature
166 that is both non-revocable and
167 non-exportable.
168
169 @item tsign
170 Make a trust signature. This is a signature that combines the notions
171 of certification (like a regular signature), and trust (like the
172 "trust" command). It is generally only useful in distinct communities
173 or groups.
174
175 @item revsig
176 Revoke a signature. For every signature which has been generated by
177 one of the secret keys, GnuPG asks whether a revocation certificate
178 should be generated.
179
180 @item trust
181 Change the owner trust value. This updates the
182 trust-db immediately and no save is required.
183
184 @item disable
185 @itemx enable
186 Disable or enable an entire key. A disabled key can not normally be
187 used for encryption.
188
189 @item adduid
190 Create an alternate user id.
191
192 @item addphoto
193 Create a photographic user id. This will prompt for a JPEG file that
194 will be embedded into the user ID.
195
196 @item deluid
197 Delete a user id.
198
199 @item revuid
200 Revoke a user id.
201
202 @item addkey
203 Add a subkey to this key.
204
205 @item delkey
206 Remove a subkey.
207
208 @item addrevoker
209 Add a designated revoker. This takes one optional argument:
210 "sensitive". If a designated revoker is marked as sensitive, it will
211 not be exported by default (see
212 export-options).
213
214 @item revkey
215 Revoke a subkey.
216
217 @item expire
218 Change the key expiration time. If a subkey is selected, the
219 expiration time of this subkey will be changed. With no selection,
220 the key expiration of the primary key is changed.
221
222 @item passwd
223 Change the passphrase of the secret key.
224
225 @item primary
226 Flag the current user id as the primary one, removes the primary user
227 id flag from all other user ids and sets the timestamp of all affected
228 self-signatures one second ahead. Note that setting a photo user ID
229 as primary makes it primary over other photo user IDs, and setting a
230 regular user ID as primary makes it primary over other regular user
231 IDs.
232
233 @item uid @code{n}
234 Toggle selection of user id with index @code{n}.
235 Use 0 to deselect all.
236
237 @item key @code{n}
238 Toggle selection of subkey with index @code{n}.
239 Use 0 to deselect all.
240
241 @item check
242 Check all selected user ids.
243
244 @item showphoto
245 Display the selected photographic user
246 id.
247
248 @item pref
249 List preferences from the selected user ID. This shows the actual
250 preferences, without including any implied preferences.
251
252 @item showpref
253 More verbose preferences listing for the selected user ID. This shows
254 the preferences in effect by including the implied preferences of
255 3DES (cipher), SHA-1 (digest), and Uncompressed (compression) if they
256 are not already included in the preference list.
257
258 @item setpref @code{string}
259 Set the list of user ID preferences to @code{string}, this should be a
260 string similar to the one printed by "pref". Using an empty string
261 will set the default preference string, using "none" will set the
262 preferences to nil. Use "gpg ---version" to get a list of available
263 algorithms. This command just initializes an internal list and does
264 not change anything unless another command (such as "updpref") which
265 changes the self-signatures is used.
266
267 @item updpref
268 Change the preferences of all user IDs (or just of the selected ones
269 to the current list of preferences. The timestamp of all affected
270 self-signatures will be advanced by one second. Note that while you
271 can change the preferences on an attribute user ID (aka "photo ID"),
272 GnuPG does not select keys via attribute user IDs so these preferences
273 will not be used by GnuPG.
274
275 @item toggle
276 Toggle between public and secret key listing.
277
278 @item save
279 Save all changes to the key rings and quit.
280
281 @item quit
282 Quit the program without updating the
283 key rings.
284
285 @end table
286
287 The listing shows you the key with its secondary
288 keys and all user ids. Selected keys or user ids
289 are indicated by an asterisk. The trust value is
290 displayed with the primary key: the first is the
291 assigned owner trust and the second is the calculated
292 trust value. Letters are used for the values:
293
294 @table @asis
295 @item -
296 No ownertrust assigned / not yet calculated.
297
298 @item e
299 Trust
300 calculation has failed; probably due to an expired key.
301
302 @item q
303 Not enough information for calculation.
304
305 @item n
306 Never trust this key.
307
308 @item m
309 Marginally trusted.
310
311 @item f
312 Fully trusted.
313
314 @item u
315 Ultimately trusted.
316
317 @end table
318
319 @item ---sign-key @code{name}
320 Signs a public key with your secret key. This is a shortcut version of
321 the subcommand "sign" from ---edit.
322
323 @item ---lsign-key @code{name}
324 Signs a public key with your secret key but marks it as
325 non-exportable. This is a shortcut version of the subcommand "lsign"
326 from ---edit.
327
328 @item ---nrsign-key @code{name}
329 Signs a public key with your secret key but marks it as non-revocable.
330 This is a shortcut version of the subcommand "nrsign" from ---edit.
331
332 @item ---delete-key @code{name}
333 Remove key from the public keyring. In batch mode either ---yes is
334 required or the key must be specified by fingerprint. This is a
335 safeguard against accidental deletion of multiple keys.
336
337 @item ---delete-secret-key @code{name}
338 Remove key from the secret and public keyring. In batch mode the key
339 must be specified by fingerprint.
340
341 @item ---delete-secret-and-public-key @code{name}
342 Same as ---delete-key, but if a secret key exists, it will be removed 
343 first. In batch mode the key must be specified by fingerprint.
344
345 @item ---gen-revoke
346 Generate a revocation certificate for the complete key. To revoke
347 a subkey or a signature, use the ---edit command.
348
349 @item ---desig-revoke
350 Generate a designated revocation certificate for a key. This allows a
351 user (with the permission of the keyholder) to revoke someone else's
352 key.
353
354 @item ---export @code{names}
355 Either export all keys from all keyrings (default
356 keyrings and those registered via option ---keyring),
357 or if at least one name is given, those of the given
358 name. The new keyring is written to stdout or to
359 the file given with option "output". Use together
360 with ---armor to mail those keys.
361
362 @item ---send-keys @code{names}
363 Same as ---export but sends the keys to a keyserver.
364 Option ---keyserver must be used to give the name
365 of this keyserver. Don't send your complete keyring
366 to a keyserver - select only those keys which are new
367 or changed by you.
368
369 @item ---export-all @code{names}
370 Same as ---export, but also exports keys which
371 are not compatible with OpenPGP.
372
373 @item ---export-secret-keys @code{names}
374 @itemx ---export-secret-subkeys @code{names}
375 Same as ---export, but exports the secret keys instead.
376 This is normally not very useful and a security risk.
377 The second form of the command has the special property to
378 render the secret part of the primary key useless; this is
379 a GNU extension to OpenPGP and other implementations can
380 not be expected to successfully import such a key.
381 See the option ---simple-sk-checksum if you want to import such an
382 exported key with an older OpenPGP implementation.
383
384 @item ---import @code{files}
385 @itemx ---fast-import @code{files}
386 Import/merge keys. This adds the given keys to the
387 keyring. The fast version is currently just a synonym.
388
389 There are a few other options which control how this command works.
390 Most notable here is the ---merge-only option which does not insert new keys
391 but does only the merging of new signatures, user-IDs and subkeys.
392
393 @item ---recv-keys @code{key IDs}
394 Import the keys with the given key IDs from a keyserver. Option
395 ---keyserver must be used to give the name of this keyserver.
396
397 @item ---refresh-keys @code{key IDs}
398 Request updates from a keyserver for keys that already exist on the
399 local keyring. This is useful for updating a key with the latest
400 signatures, user IDs, etc. Option ---keyserver must be used to give
401 the name of this keyserver.
402
403 @item ---search-keys @code{names}
404 Search the keyserver for the given names. Multiple names given here
405 will be joined together to create the search string for the keyserver.
406 Option ---keyserver must be used to give the name of this keyserver.
407
408 @item ---update-trustdb
409 Do trust database maintenance. This command iterates over all keys
410 and builds the Web-of-Trust. This is an interactive command because it
411 may have to ask for the "ownertrust" values for keys. The user has to
412 give an estimation of how far she trusts the owner of the displayed
413 key to correctly certify (sign) other keys. GnuPG only asks for the
414 ownertrust value if it has not yet been assigned to a key. Using the
415 ---edit-key menu, the assigned value can be changed at any time.
416
417 @item ---check-trustdb
418 Do trust database maintenance without user interaction. From time to
419 time the trust database must be updated so that expired keys or
420 signatures and the resulting changes in the Web-of-Trust can be
421 tracked. Normally, GnuPG will calculate when this is required and do
422 it automatically unless ---no-auto-check-trustdb is set. This command
423 can be used to force a trust database check at any time. The
424 processing is identical to that of ---update-trustdb but it skips keys
425 with a not yet defined "ownertrust".
426
427 For use with cron jobs, this command can be used together with ---batch
428 in which case the trust database check is done only if a check is
429 needed. To force a run even in batch mode add the option ---yes.
430
431 @item ---export-ownertrust
432 Send the ownertrust values to stdout. This is useful for backup
433 purposes as these values are the only ones which can't be re-created
434 from a corrupted trust DB.
435
436 @item ---import-ownertrust @code{files}
437 Update the trustdb with the ownertrust values stored
438 in @code{files} (or stdin if not given); existing
439 values will be overwritten.
440
441 @item ---rebuild-keydb-caches
442 When updating from version 1.0.6 to 1.0.7 this command should be used
443 to create signature caches in the keyring. It might be handy in other
444 situations too.
445
446 @item ---print-md @code{algo} @code{files}
447 @itemx ---print-mds @code{files}
448 Print message digest of algorithm ALGO for all given files or stdin.
449 With the second form (or a deprecated "*" as algo) digests for all
450 available algorithms are printed.
451
452 @item ---gen-random @code{0|1|2} @code{count}
453 Emit COUNT random bytes of the given quality level. If count is not given
454 or zero, an endless sequence of random bytes will be emitted.
455 PLEASE, don't use this command unless you know what you are doing; it may
456 remove precious entropy from the system!
457
458 @item ---gen-prime @code{mode} @code{bits} @code{qbits}
459 Use the source, Luke :-). The output format is still subject to change.
460
461 @item ---version
462 Print version information along with a list
463 of supported algorithms.
464
465 @item ---warranty
466 Print warranty information.
467
468 @item -h, ---help
469 Print usage information. This is a really long list even though it
470 doesn't list all options. For every option, consult this manual.
471
472 @end table
473
474 @majorheading OPTIONS
475 Long options can be put in an options file (default
476 "~/.gnupg/gpg.conf"). Short option names will not work - for example,
477 "armor" is a valid option for the options file, while "a" is not. Do
478 not write the 2 dashes, but simply the name of the option and any
479 required arguments. Lines with a hash ('#') as the first
480 non-white-space character are ignored. Commands may be put in this
481 file too, but that is not generally useful as the command will execute
482 automatically with every execution of gpg.
483
484 @code{gpg} recognizes these options:
485
486 @table @asis
487 @item -a, ---armor
488 Create ASCII armored output.
489
490 @item -o, ---output @code{file}
491 Write output to @code{file}.
492
493 @item ---mangle-dos-filenames
494 @itemx ---no-mangle-dos-filenames
495 The Windows version of GnuPG replaces the extension of an output
496 filename to avoid problems with filenames containing more than one
497 dot. This is not necessary for newer Windows versions and so
498 ---no-mangle-dos-filenames can be used to switch this feature off and
499 have GnuPG append the new extension. This option has no effect on
500 non-Windows platforms.
501
502 @item -u, ---local-user @code{name}
503 Use @code{name} as the user ID to sign.
504 This option is silently ignored for the list commands,
505 so that it can be used in an options file.
506
507 @item ---default-key @code{name}
508 Use @code{name} as default user ID for signatures. If this
509 is not used the default user ID is the first user ID
510 found in the secret keyring.
511
512 @item -r, ---recipient @code{name}
513 @itemx 
514 Encrypt for user id @code{name}. If this option or ---hidden-recipient
515 is not specified, GnuPG asks for the user-id unless
516 ---default-recipient is given.
517
518 @item -R, ---hidden-recipient @code{name}
519 @itemx 
520 Encrypt for user id @code{name}, but hide the keyid of the key. This
521 option hides the receiver of the message and is a countermeasure
522 against traffic analysis. If this option or ---recipient is not
523 specified, GnuPG asks for the user-id unless ---default-recipient is
524 given.
525
526 @item ---default-recipient @code{name}
527 Use @code{name} as default recipient if option ---recipient is not used and
528 don't ask if this is a valid one. @code{name} must be non-empty.
529
530 @item ---default-recipient-self
531 Use the default key as default recipient if option ---recipient is not used and
532 don't ask if this is a valid one. The default key is the first one from the
533 secret keyring or the one set with ---default-key.
534
535 @item ---no-default-recipient
536 Reset ---default-recipient and --default-recipient-self.
537
538 @item ---encrypt-to @code{name}
539 Same as ---recipient but this one is intended for use
540 in the options file and may be used with
541 your own user-id as an "encrypt-to-self". These keys
542 are only used when there are other recipients given
543 either by use of ---recipient or by the asked user id.
544 No trust checking is performed for these user ids and
545 even disabled keys can be used.
546
547 @item ---hidden-encrypt-to @code{name}
548 Same as ---hidden-recipient but this one is intended for use in the
549 options file and may be used with your own user-id as a hidden
550 "encrypt-to-self". These keys are only used when there are other
551 recipients given either by use of ---recipient or by the asked user id.
552 No trust checking is performed for these user ids and even disabled
553 keys can be used.
554
555 @item ---no-encrypt-to
556 Disable the use of all ---encrypt-to and --hidden-encrypt-to keys.
557
558 @item -v, ---verbose
559 Give more information during processing. If used
560 twice, the input data is listed in detail.
561
562 @item -q, ---quiet
563 Try to be as quiet as possible.
564
565 @item -z @code{n}, ---compress @code{n}
566 Set compression level to @code{n}. A value of 0 for @code{n}
567 disables compression. Default is to use the default
568 compression level of zlib (normally 6).
569
570 @item -t, ---textmode
571 @itemx ---no-textmode
572 Use canonical text mode. ---no-textmode disables this option. If -t
573 (but not ---textmode) is used together with armoring and signing, this
574 enables clearsigned messages. This kludge is needed for command-line
575 compatibility with command-line versions of PGP; normally you would
576 use ---sign or --clearsign to select the type of the signature.
577
578 @item -n, ---dry-run
579 Don't make any changes (this is not completely implemented).
580
581 @item -i, ---interactive
582 Prompt before overwriting any files.
583
584 @item ---batch
585 @itemx ---no-batch
586 Use batch mode. Never ask, do not allow interactive commands.
587 ---no-batch disables this option.
588
589 @item ---no-tty
590 Make sure that the TTY (terminal) is never used for any output.
591 This option is needed in some cases because GnuPG sometimes prints
592 warnings to the TTY if ---batch is used.
593
594 @item ---yes
595 Assume "yes" on most questions.
596
597 @item ---no
598 Assume "no" on most questions.
599
600 @item ---default-cert-check-level @code{n}
601 The default to use for the check level when signing a key.
602
603 0 means you make no particular claim as to how carefully you verified
604 the key.
605
606 1 means you believe the key is owned by the person who claims to own
607 it but you could not, or did not verify the key at all. This is
608 useful for a "persona" verification, where you sign the key of a
609 pseudonymous user.
610
611 2 means you did casual verification of the key. For example, this
612 could mean that you verified that the key fingerprint and checked the
613 user ID on the key against a photo ID.
614
615 3 means you did extensive verification of the key. For example, this
616 could mean that you verified the key fingerprint with the owner of the
617 key in person, and that you checked, by means of a hard to forge
618 document with a photo ID (such as a passport) that the name of the key
619 owner matches the name in the user ID on the key, and finally that you
620 verified (by exchange of email) that the email address on the key
621 belongs to the key owner.
622
623 Note that the examples given above for levels 2 and 3 are just that:
624 examples. In the end, it is up to you to decide just what "casual"
625 and "extensive" mean to you.
626
627 This option defaults to 0.
628
629 @item ---trusted-key @code{long key ID}
630 Assume that the specified key (which must be given
631 as a full 8 byte key ID) is as trustworthy as one of
632 your own secret keys. This option is useful if you
633 don't want to keep your secret keys (or one of them)
634 online but still want to be able to check the validity of a given
635 recipient's or signator's key. 
636
637 @item ---trust-model @code{pgp|classic|always}
638 Set what trust model GnuPG should follow. The models are:
639
640 @table @asis
641 @item pgp
642 This is the web-of-trust combined with trust signatures as used in PGP
643 5.x and later. This is the default trust model.
644
645 @item classic
646 This is the standard web-of-trust as used in PGP 2.x and earlier.
647
648 @item always
649 Skip key validation and assume that used keys are always fully
650 trusted. You won't use this unless you have installed some external
651 validation scheme. This option also suppresses the "[uncertain]" tag
652 printed with signature checks when there is no evidence that the user
653 ID is bound to the key.
654
655 @end table
656
657 @item ---always-trust
658 Identical to `---trust-model always'
659
660 @item ---keyserver @code{name}
661 Use @code{name} as your keyserver. This is the server that ---recv-keys,
662 ---send-keys, and --search-keys will communicate with to receive keys
663 from, send keys to, and search for keys on. The format of the
664 @code{name} is a URI: `scheme:[//]keyservername[:port]' The scheme is
665 the type of keyserver: "hkp" for the Horowitz (or compatible)
666 keyservers, "ldap" for the NAI LDAP keyserver, or "mailto" for the
667 Horowitz email keyserver. Note that your particular installation of
668 GnuPG may have other keyserver types available as well. Keyserver
669 schemes are case-insensitive.
670
671 Most keyservers synchronize with each other, so there is generally no
672 need to send keys to more than one server. Using the command "host -l
673 pgp.net | grep wwwkeys" gives you a list of HKP keyservers. When
674 using one of the wwwkeys servers, due to load balancing using
675 round-robin DNS you may notice that you get a different key server
676 each time.
677
678 @item ---keyserver-options @code{parameters}
679 This is a space or comma delimited string that gives options for the
680 keyserver. Options can be prepended with a `no-' to give the opposite
681 meaning. Valid import-options or export-options may be used here as
682 well to apply to importing (---recv-key) or exporting (--send-key) a
683 key from a keyserver. While not all options are available for all
684 keyserver types, some common options are:
685
686 @table @asis
687 @item include-revoked
688 When searching for a key with ---search-keys, include keys that are
689 marked on the keyserver as revoked. Note that this option is always
690 set when using the NAI HKP keyserver, as this keyserver does not
691 differentiate between revoked and unrevoked keys.
692
693 @item include-disabled
694 When searching for a key with ---search-keys, include keys that are
695 marked on the keyserver as disabled. Note that this option is not
696 used with HKP keyservers.
697
698 @item include-subkeys
699 When receiving a key, include subkeys as potential targets. Note that
700 this option is not used with HKP keyservers, as they do not support
701 retrieving keys by subkey id.
702
703 @item use-temp-files
704 On most Unix-like platforms, GnuPG communicates with the keyserver
705 helper program via pipes, which is the most efficient method. This
706 option forces GnuPG to use temporary files to communicate. On some
707 platforms (such as Win32 and RISC OS), this option is always enabled.
708
709 @item keep-temp-files
710 If using `use-temp-files', do not delete the temp files after using
711 them. This option is useful to learn the keyserver communication
712 protocol by reading the temporary files.
713
714 @item verbose
715 Tell the keyserver helper program to be more verbose. This option can
716 be repeated multiple times to increase the verbosity level.
717
718 @item honor-http-proxy
719 For keyserver schemes that use HTTP (such as HKP), try to access the
720 keyserver over the proxy set with the environment variable
721 "http_proxy".
722
723 @item auto-key-retrieve
724 This option enables the automatic retrieving of keys from a keyserver
725 when verifying signatures made by keys that are not on the local
726 keyring.
727
728 @end table
729
730 @item ---import-options @code{parameters}
731 This is a space or comma delimited string that gives options for
732 importing keys. Options can be prepended with a `no-' to give the
733 opposite meaning. The options are:
734
735 @table @asis
736 @item allow-local-sigs
737 Allow importing key signatures marked as "local". This is not
738 generally useful unless a shared keyring scheme is being used.
739 Defaults to no.
740
741 @item repair-pks-subkey-bug
742 During import, attempt to repair the damage caused by the PKS
743 keyserver bug (pre version 0.9.6) that mangles keys with multiple
744 subkeys. Note that this cannot completely repair the damaged key as
745 some crucial data is removed by the keyserver, but it does at least
746 give you back one subkey. Defaults to no for regular ---import and to
747 yes for keyserver ---recv-keys.
748
749 @end table
750
751 @item ---export-options @code{parameters}
752 This is a space or comma delimited string that gives options for
753 exporting keys. Options can be prepended with a `no-' to give the
754 opposite meaning. The options are:
755
756 @table @asis
757 @item include-non-rfc
758 Include non-RFC compliant keys in the export. Defaults to yes.
759
760 @item include-local-sigs
761 Allow exporting key signatures marked as "local". This is not
762 generally useful unless a shared keyring scheme is being used.
763 Defaults to no.
764
765 @item include-attributes
766 Include attribute user IDs (photo IDs) while exporting. This is
767 useful to export keys if they are going to be used by an OpenPGP
768 program that does not accept attribute user IDs. Defaults to yes.
769
770 @item include-sensitive-revkeys
771 Include designated revoker information that was marked as
772 "sensitive". Defaults to no.
773
774 @end table
775
776 @item ---show-photos
777 @itemx ---no-show-photos
778 Causes ---list-keys, --list-sigs, --list-public-keys,
779 ---list-secret-keys, and verifying a signature to also display the
780 photo ID attached to the key, if any. See also ---photo-viewer.
781 ---no-show-photos disables this option.
782
783 @item ---photo-viewer @code{string}
784 This is the command line that should be run to view a photo ID. "%i"
785 will be expanded to a filename containing the photo. "%I" does the
786 same, except the file will not be deleted once the viewer exits.
787 Other flags are "%k" for the key ID, "%K" for the long key ID, "%f"
788 for the key fingerprint, "%t" for the extension of the image type
789 (e.g. "jpg"), "%T" for the MIME type of the image (e.g. "image/jpeg"),
790 and "%%" for an actual percent sign. If neither %i or %I are present,
791 then the photo will be supplied to the viewer on standard input.
792
793 The default viewer is "xloadimage -fork -quiet -title 'KeyID 0x%k'
794 stdin"
795
796 @item ---exec-path @code{string}
797 Sets a list of directories to search for photo viewers and keyserver
798 helpers. If not provided, keyserver helpers use the compiled-in
799 default directory, and photo viewers use the $PATH environment
800 variable.
801
802 @item ---show-keyring
803 Causes ---list-keys, --list-public-keys, and --list-secret-keys to
804 display the name of the keyring a given key resides on. This is only
805 useful when you're listing a specific key or set of keys. It has no
806 effect when listing all keys.
807
808 @item ---keyring @code{file}
809 Add @code{file} to the list of keyrings. If @code{file} begins with a
810 tilde and a slash, these are replaced by the HOME directory. If the
811 filename does not contain a slash, it is assumed to be in the GnuPG
812 home directory ("~/.gnupg" if ---homedir is not used). The filename
813 may be prefixed with a scheme:
814
815 "gnupg-ring:" is the default one.
816
817 It might make sense to use it together with ---no-default-keyring.
818
819 @item ---secret-keyring @code{file}
820 Same as ---keyring but for the secret keyrings.
821
822 @item ---primary-keyring @code{file}
823 Designate @code{file} as the primary public keyring. This means that
824 newly imported keys (via ---import or keyserver --recv-from) will go to
825 this keyring.
826
827 @item ---trustdb-name @code{file}
828 Use @code{file} instead of the default trustdb. If @code{file} begins
829 with a tilde and a slash, these are replaced by the HOME directory. If
830 the filename does not contain a slash, it is assumed to be in the
831 GnuPG home directory ("~/.gnupg" if ---homedir is not used).
832
833 @item ---homedir @code{directory}
834 Set the name of the home directory to @code{directory} If this
835 option is not used it defaults to "~/.gnupg". It does
836 not make sense to use this in a options file. This
837 also overrides the environment variable "GNUPGHOME".
838
839 @item ---charset @code{name}
840 Set the name of the native character set. This is used
841 to convert some strings to proper UTF-8 encoding. If this option is not used, the default character set is determined
842 from the current locale. A verbosity level of 3 shows the used one.
843 Valid values for @code{name} are:
844
845 @table @asis
846 @item iso-8859-1
847 This is the Latin 1 set.
848
849 @item iso-8859-2
850 The Latin 2 set.
851
852 @item iso-8859-15
853 This is currently an alias for
854 the Latin 1 set.
855
856 @item koi8-r
857 The usual Russian set (rfc1489).
858
859 @item utf-8
860 Bypass all translations and assume
861 that the OS uses native UTF-8 encoding.
862
863 @end table
864
865 @item ---utf8-strings
866 @itemx ---no-utf8-strings
867 Assume that the arguments are already given as UTF8 strings. The default
868 (---no-utf8-strings)
869 is to assume that arguments are encoded in the character set as specified
870 by ---charset. These options affect all following arguments. Both options may
871 be used multiple times.
872
873 @item ---options @code{file}
874 Read options from @code{file} and do not try to read
875 them from the default options file in the homedir
876 (see ---homedir). This option is ignored if used
877 in an options file.
878
879 @item ---no-options
880 Shortcut for "---options /dev/null". This option is
881 detected before an attempt to open an option file.
882 Using this option will also prevent the creation of a 
883 "~./gnupg" homedir.
884
885 @item ---load-extension @code{name}
886 Load an extension module. If @code{name} does not contain a slash it is
887 searched for in the directory configured when GnuPG was built
888 (generally "/usr/local/lib/gnupg"). Extensions are not generally
889 useful anymore, and the use of this option is deprecated.
890
891 @item ---debug @code{flags}
892 Set debugging flags. All flags are or-ed and @code{flags} may
893 be given in C syntax (e.g. 0x0042).
894
895 @item ---debug-all
896 Set all useful debugging flags.
897
898 @item ---enable-progress-filter
899 Enable certain PROGRESS status outputs. This option allows frontends
900 to display a progress indicator while gpg is processing larger files.
901 There is a slight performance overhead using it.
902
903 @item ---status-fd @code{n}
904 Write special status strings to the file descriptor @code{n}.
905 See the file DETAILS in the documentation for a listing of them.
906
907 @item ---logger-fd @code{n}
908 Write log output to file descriptor @code{n} and not to stderr.
909
910 @item ---attribute-fd @code{n}
911 Write attribute subpackets to the file descriptor @code{n}. This is
912 most useful for use with ---status-fd, since the status messages are
913 needed to separate out the various subpackets from the stream
914 delivered to the file descriptor.
915
916 @item ---sk-comments
917 @itemx ---no-sk-comments
918 Include secret key comment packets when exporting secret keys. This
919 is a GnuPG extension to the OpenPGP standard, and is off by default.
920 Please note that this has nothing to do with the comments in clear
921 text signatures or armor headers. ---no-sk-comments disables this
922 option.
923
924 @item ---no-comment
925 See ---no-sk-comments. This option is deprecated and may be removed
926 soon.
927
928 @item ---comment @code{string}
929 Use @code{string} as the comment string in clear text signatures. The
930 default behavior is not to use a comment string.
931
932 @item ---default-comment
933 Force to write the standard comment string in clear
934 text signatures. Use this to overwrite a ---comment
935 from a config file. This option is now obsolete because there is no
936 default comment string anymore.
937
938 @item ---emit-version
939 @itemx ---no-emit-version
940 Force inclusion of the version string in ASCII armored output.
941 ---no-emit-version disables this option.
942
943 @item ---sig-notation @code{name=value}
944 @itemx ---cert-notation @code{name=value}
945 @itemx -N, ---notation-data @code{name=value}
946 Put the name value pair into the signature as notation data.
947 @code{name} must consist only of printable characters or spaces, and
948 must contain a '@@' character. This is to help prevent pollution of
949 the IETF reserved notation namespace. The ---expert flag overrides the
950 '@@' check. @code{value} may be any printable string; it will be
951 encoded in UTF8, so you should check that your ---charset is set
952 correctly. If you prefix @code{name} with an exclamation mark, the
953 notation data will be flagged as critical (rfc2440:5.2.3.15).
954 ---sig-notation sets a notation for data signatures. --cert-notation
955 sets a notation for key signatures (certifications). ---notation-data
956 sets both.
957
958 There are special codes that may be used in notation names. "%k" will
959 be expanded into the key ID of the key being signed, "%K" for the long
960 key ID of the key being signed, "%f" for the key fingerprint of the
961 key being signed, "%s" for the key ID of the key making the signature,
962 "%S" for the long key ID of the key making the signature, and "%%"
963 results in a single "%". %k, %K, and %f are only meaningful when
964 making a key signature (certification).
965
966 @item ---show-notation
967 @itemx ---no-show-notation
968 Show signature notations in the ---list-sigs or --check-sigs listings
969 as well as when verifying a signature with a notation in it.
970 ---no-show-notation disables this option.
971
972 @item ---sig-policy-url @code{string}
973 @itemx ---cert-policy-url @code{string}
974 @itemx ---set-policy-url @code{string}
975 Use @code{string} as Policy URL for signatures (rfc2440:5.2.3.19). If
976 you prefix it with an exclamation mark, the policy URL packet will be
977 flagged as critical. ---sig-policy-url sets a a policy url for data
978 signatures. ---cert-policy-url sets a policy url for key signatures
979 (certifications). ---set-policy-url sets both.
980
981 The same %-expandos used for notation data are available here as well.
982
983 @item ---show-policy-url
984 @itemx ---no-show-policy-url
985 Show policy URLs in the ---list-sigs or --check-sigs listings as well
986 as when verifying a signature with a policy URL in it.
987 ---no-show-policy-url disables this option.
988
989 @item ---set-filename @code{string}
990 Use @code{string} as the filename which is stored inside messages.
991 This overrides the default, which is to use the actual filename of the
992 file being encrypted.
993
994 @item ---for-your-eyes-only
995 @itemx ---no-for-your-eyes-only
996 Set the `for your eyes only' flag in the message. This causes GnuPG
997 to refuse to save the file unless the ---output option is given, and
998 PGP to use the "secure viewer" with a Tempest-resistant font to
999 display the message. This option overrides ---set-filename.
1000 ---no-for-your-eyes-only disables this option.
1001
1002 @item ---use-embedded-filename
1003 Try to create a file with a name as embedded in the data.
1004 This can be a dangerous option as it allows to overwrite files.
1005
1006 @item ---completes-needed @code{n}
1007 Number of completely trusted users to introduce a new
1008 key signer (defaults to 1).
1009
1010 @item ---marginals-needed @code{n}
1011 Number of marginally trusted users to introduce a new
1012 key signer (defaults to 3)
1013
1014 @item ---max-cert-depth @code{n}
1015 Maximum depth of a certification chain (default is 5).
1016
1017 @item ---cipher-algo @code{name}
1018 Use @code{name} as cipher algorithm. Running the program
1019 with the command ---version yields a list of supported
1020 algorithms. If this is not used the cipher algorithm is
1021 selected from the preferences stored with the key.
1022
1023 @item ---digest-algo @code{name}
1024 Use @code{name} as the message digest algorithm. Running the program
1025 with the command ---version yields a list of supported algorithms.
1026
1027 @item ---compress-algo @code{name}
1028 Use compression algorithm @code{name}. "zlib" is RFC1950 ZLIB
1029 compression. "zip" is RFC-1951 ZIP compression which is used by PGP.
1030 "uncompressed" or "none" disables compression. If this option is not
1031 used, the default behavior is to examine the recipient key preferences
1032 to see which algorithms the recipient supports. If all else fails,
1033 ZIP is used for maximum compatibility. Note, however, that ZLIB may
1034 give better compression results if that is more important, as the
1035 compression window size is not limited to 8k.
1036
1037 @item ---cert-digest-algo @code{name}
1038 Use @code{name} as the message digest algorithm used when signing a
1039 key. Running the program with the command ---version yields a list of
1040 supported algorithms. Be aware that if you choose an algorithm that
1041 GnuPG supports but other OpenPGP implementations do not, then some
1042 users will not be able to use the key signatures you make, or quite
1043 possibly your entire key.
1044
1045 @item ---s2k-cipher-algo @code{name}
1046 Use @code{name} as the cipher algorithm used to protect secret keys.
1047 The default cipher is CAST5. This cipher is also used for
1048 conventional encryption if ---personal-cipher-preferences and
1049 ---cipher-algo is not given.
1050
1051 @item ---s2k-digest-algo @code{name}
1052 Use @code{name} as the digest algorithm used to mangle the passphrases.
1053 The default algorithm is SHA-1.
1054
1055 @item ---s2k-mode @code{n}
1056 Selects how passphrases are mangled. If @code{n} is 0 a plain
1057 passphrase (which is not recommended) will be used, a 1 adds a salt to
1058 the passphrase and a 3 (the default) iterates the whole process a
1059 couple of times. Unless ---rfc1991 is used, this mode is also used for
1060 conventional encryption.
1061
1062 @item ---simple-sk-checksum
1063 Secret keys are integrity protected by using a SHA-1 checksum. This
1064 method will be part of an enhanced OpenPGP specification but GnuPG
1065 already uses it as a countermeasure against certain attacks. Old
1066 applications don't understand this new format, so this option may be
1067 used to switch back to the old behaviour. Using this this option
1068 bears a security risk. Note that using this option only takes effect
1069 when the secret key is encrypted - the simplest way to make this
1070 happen is to change the passphrase on the key (even changing it to the
1071 same value is acceptable).
1072
1073 @item ---disable-cipher-algo @code{name}
1074 Never allow the use of @code{name} as cipher algorithm.
1075 The given name will not be checked so that a later loaded algorithm
1076 will still get disabled.
1077
1078 @item ---disable-pubkey-algo @code{name}
1079 Never allow the use of @code{name} as public key algorithm.
1080 The given name will not be checked so that a later loaded algorithm
1081 will still get disabled.
1082
1083 @item ---no-sig-cache
1084 Do not cache the verification status of key signatures.
1085 Caching gives a much better performance in key listings. However, if
1086 you suspect that your public keyring is not save against write
1087 modifications, you can use this option to disable the caching. It
1088 probably does not make sense to disable it because all kind of damage
1089 can be done if someone else has write access to your public keyring.
1090
1091 @item ---no-sig-create-check
1092 GnuPG normally verifies each signature right after creation to protect
1093 against bugs and hardware malfunctions which could leak out bits from
1094 the secret key. This extra verification needs some time (about 115%
1095 for DSA keys), and so this option can be used to disable it.
1096 However, due to the fact that the signature creation needs manual
1097 interaction, this performance penalty does not matter in most settings.
1098
1099 @item ---auto-check-trustdb
1100 @itemx ---no-auto-check-trustdb
1101 If GnuPG feels that its information about the Web-of-Trust has to be
1102 updated, it automatically runs the ---check-trustdb command internally.
1103 This may be a time consuming process. ---no-auto-check-trustdb
1104 disables this option.
1105
1106 @item ---throw-keyid
1107 Do not put the keyids into encrypted packets. This option hides the
1108 receiver of the message and is a countermeasure against traffic
1109 analysis. It may slow down the decryption process because all
1110 available secret keys are tried.
1111
1112 @item ---no-throw-keyid
1113 Resets the ---throw-keyid option.
1114
1115 @item ---not-dash-escaped
1116 This option changes the behavior of cleartext signatures
1117 so that they can be used for patch files. You should not
1118 send such an armored file via email because all spaces
1119 and line endings are hashed too. You can not use this
1120 option for data which has 5 dashes at the beginning of a
1121 line, patch files don't have this. A special armor header
1122 line tells GnuPG about this cleartext signature option.
1123
1124 @item ---escape-from-lines
1125 @itemx ---no-escape-from-lines
1126 Because some mailers change lines starting with "From " to ">From
1127 " it is good to handle such lines in a special way when creating
1128 cleartext signatures to prevent the mail system from breaking the
1129 signature. Note that all other PGP versions do it this way too.
1130 Enabled by default. ---no-escape-from-lines disables this option.
1131
1132 @item ---passphrase-fd @code{n}
1133 Read the passphrase from file descriptor @code{n}. If you use
1134 0 for @code{n}, the passphrase will be read from stdin. This
1135 can only be used if only one passphrase is supplied.
1136 Don't use this option if you can avoid it.
1137
1138 @item ---command-fd @code{n}
1139 This is a replacement for the deprecated shared-memory IPC mode.
1140 If this option is enabled, user input on questions is not expected
1141 from the TTY but from the given file descriptor. It should be used
1142 together with ---status-fd. See the file doc/DETAILS in the source
1143 distribution for details on how to use it.
1144
1145 @item ---use-agent
1146 @itemx ---no-use-agent
1147 Try to use the GnuPG-Agent. Please note that this agent is still under
1148 development. With this option, GnuPG first tries to connect to the
1149 agent before it asks for a passphrase. ---no-use-agent disables this
1150 option.
1151
1152 @item ---gpg-agent-info
1153 Override the value of the environment variable
1154 @samp{GPG_AGENT_INFO}. This is only used when ---use-agent has been given
1155
1156 @item Compliance options
1157 These options control what GnuPG is compliant to. Only one of these
1158 options may be active at a time. Note that the default setting of
1159 this is nearly always the correct one. See the INTEROPERABILITY WITH
1160 OTHER OPENPGP PROGRAMS section below before using one of these
1161 options.
1162
1163 @table @asis
1164 @item ---gnupg
1165 Use standard GnuPG behavior. This is essentially OpenPGP behavior
1166 (see ---openpgp), but with some additional workarounds for common
1167 compatibility problems in different versions of PGP. This is the
1168 default option, so it is not generally needed, but it may be useful to
1169 override a different compliance option in the gpg.conf file.
1170
1171 @item ---openpgp
1172 Reset all packet, cipher and digest options to strict OpenPGP
1173 behavior. Use this option to reset all previous options like
1174 ---rfc1991, --force-v3-sigs, --s2k-*, --cipher-algo, --digest-algo and
1175 ---compress-algo to OpenPGP compliant values. All PGP workarounds are
1176 disabled.
1177
1178 @item ---rfc1991
1179 Try to be more RFC-1991 (PGP 2.x) compliant.
1180
1181 @item ---pgp2
1182 Set up all options to be as PGP 2.x compliant as possible, and warn if
1183 an action is taken (e.g. encrypting to a non-RSA key) that will create
1184 a message that PGP 2.x will not be able to handle. Note that `PGP
1185 2.x' here means `MIT PGP 2.6.2'. There are other versions of PGP 2.x
1186 available, but the MIT release is a good common baseline.
1187
1188 This option implies `---rfc1991 --disable-mdc --no-force-v4-certs
1189 ---no-sk-comment --escape-from-lines --force-v3-sigs
1190 ---no-ask-sig-expire --no-ask-cert-expire --cipher-algo IDEA
1191 ---digest-algo MD5 --compress-algo 1'. It also disables --textmode
1192 when encrypting.
1193
1194 @item ---pgp6
1195 Set up all options to be as PGP 6 compliant as possible. This
1196 restricts you to the ciphers IDEA (if the IDEA plugin is installed),
1197 3DES, and CAST5, the hashes MD5, SHA1 and RIPEMD160, and the
1198 compression algorithms none and ZIP. This also disables
1199 ---throw-keyid, and making signatures with signing subkeys as PGP 6
1200 does not understand signatures made by signing subkeys.
1201
1202 This option implies `---disable-mdc --no-sk-comment --escape-from-lines
1203 ---force-v3-sigs --no-ask-sig-expire'
1204
1205 @item ---pgp7
1206 Set up all options to be as PGP 7 compliant as possible. This is
1207 identical to ---pgp6 except that MDCs are not disabled, and the list of
1208 allowable ciphers is expanded to add AES128, AES192, AES256, and
1209 TWOFISH.
1210
1211 @item ---pgp8
1212 Set up all options to be as PGP 8 compliant as possible. PGP 8 is a
1213 lot closer to the OpenPGP standard than previous versions of PGP, so
1214 all this does is disable ---throw-keyid and set --escape-from-lines.
1215 The allowed algorithms list is the same as ---pgp7 with the addition of
1216 the SHA-256 digest algorithm.
1217
1218 @end table
1219
1220 @item ---force-v3-sigs
1221 @itemx ---no-force-v3-sigs
1222 OpenPGP states that an implementation should generate v4 signatures
1223 but PGP versions 5 and higher only recognize v4 signatures on key
1224 material. This option forces v3 signatures for signatures on data.
1225 Note that this option overrides ---ask-sig-expire, as v3 signatures
1226 cannot have expiration dates. ---no-force-v3-sigs disables this
1227 option.
1228
1229 @item ---force-v4-certs
1230 @itemx ---no-force-v4-certs
1231 Always use v4 key signatures even on v3 keys. This option also
1232 changes the default hash algorithm for v3 RSA keys from MD5 to SHA-1.
1233 ---no-force-v4-certs disables this option.
1234
1235 @item ---force-mdc
1236 Force the use of encryption with a modification detection code. This
1237 is always used with the newer ciphers (those with a blocksize greater
1238 than 64 bits), or if all of the recipient keys indicate MDC support in
1239 their feature flags.
1240
1241 @item ---disable-mdc
1242 Disable the use of the modification detection code. Note that by
1243 using this option, the encrypted message becomes vulnerable to a
1244 message modification attack.
1245
1246 @item ---allow-non-selfsigned-uid
1247 @itemx ---no-allow-non-selfsigned-uid
1248 Allow the import and use of keys with user IDs which are not
1249 self-signed. This is not recommended, as a non self-signed user ID is
1250 trivial to forge. ---no-allow-non-selfsigned-uid disables.
1251
1252 @item ---allow-freeform-uid
1253 Disable all checks on the form of the user ID while generating a new
1254 one. This option should only be used in very special environments as
1255 it does not ensure the de-facto standard format of user IDs.
1256
1257 @item ---ignore-time-conflict
1258 GnuPG normally checks that the timestamps associated with keys and
1259 signatures have plausible values. However, sometimes a signature seems to
1260 be older than the key due to clock problems. This option makes these
1261 checks just a warning.
1262
1263 @item ---ignore-valid-from
1264 GnuPG normally does not select and use subkeys created in the future. This
1265 option allows the use of such keys and thus exhibits the pre-1.0.7
1266 behaviour. You should not use this option unless you there is some
1267 clock problem.
1268
1269 @item ---ignore-crc-error
1270 The ASCII armor used by OpenPGP is protected by a CRC checksum against
1271 transmission errors. Sometimes it happens that the CRC gets mangled
1272 somewhere on the transmission channel but the actual content (which is
1273 protected by the OpenPGP protocol anyway) is still okay. This option
1274 will let gpg ignore CRC errors.
1275
1276 @item ---ignore-mdc-error
1277 This option changes a MDC integrity protection failure into a warning.
1278 This can be useful if a message is partially corrupt, but it is
1279 necessary to get as much data as possible out of the corrupt message.
1280 However, be aware that a MDC protection failure may also mean that the
1281 message was tampered with intentionally by an attacker.
1282
1283 @item ---lock-once
1284 Lock the databases the first time a lock is requested
1285 and do not release the lock until the process
1286 terminates.
1287
1288 @item ---lock-multiple
1289 Release the locks every time a lock is no longer
1290 needed. Use this to override a previous ---lock-once
1291 from a config file.
1292
1293 @item ---lock-never
1294 Disable locking entirely. This option should be used only in very
1295 special environments, where it can be assured that only one process
1296 is accessing those files. A bootable floppy with a stand-alone
1297 encryption system will probably use this. Improper usage of this
1298 option may lead to data and key corruption.
1299
1300 @item ---no-random-seed-file
1301 GnuPG uses a file to store its internal random pool over invocations.
1302 This makes random generation faster; however sometimes write operations
1303 are not desired. This option can be used to achieve that with the cost of
1304 slower random generation.
1305
1306 @item ---no-verbose
1307 Reset verbose level to 0.
1308
1309 @item ---no-greeting
1310 Suppress the initial copyright message.
1311
1312 @item ---no-secmem-warning
1313 Suppress the warning about "using insecure memory".
1314
1315 @item ---no-permission-warning
1316 Suppress the warning about unsafe file permissions. Note that the
1317 file permission checks that GnuPG performs are not intended to be
1318 authoritative, rather they simply warn about certain common permission
1319 problems. Do not assume that the lack of a warning means that your
1320 system is secure.
1321
1322 @item ---no-mdc-warning
1323 Suppress the warning about missing MDC integrity protection.
1324
1325 @item ---no-armor
1326 Assume the input data is not in ASCII armored format.
1327
1328 @item ---no-default-keyring
1329 Do not add the default keyrings to the list of
1330 keyrings.
1331
1332 @item ---skip-verify
1333 Skip the signature verification step. This may be
1334 used to make the decryption faster if the signature
1335 verification is not needed.
1336
1337 @item ---with-colons
1338 Print key listings delimited by colons. Note, that the output will be
1339 encoded in UTF-8 regardless of any ---charset setting.
1340
1341 @item ---with-key-data
1342 Print key listings delimited by colons (like ---with-colons) and print the public key data.
1343
1344 @item ---with-fingerprint
1345 Same as the command ---fingerprint but changes only the format of the output
1346 and may be used together with another command.
1347
1348 @item ---fast-list-mode
1349 Changes the output of the list commands to work faster; this is achieved
1350 by leaving some parts empty. Some applications don't need the user ID and
1351 the trust information given in the listings. By using this options they
1352 can get a faster listing. The exact behaviour of this option may change
1353 in future versions.
1354
1355 @item ---fixed-list-mode
1356 Do not merge primary user ID and primary key in ---with-colon listing
1357 mode and print all timestamps as seconds since 1970-01-01.
1358
1359 @item ---list-only
1360 Changes the behaviour of some commands. This is like ---dry-run but
1361 different in some cases. The semantic of this command may be extended in
1362 the future. Currently it only skips the actual decryption pass and
1363 therefore enables a fast listing of the encryption keys.
1364
1365 @item ---no-literal
1366 This is not for normal use. Use the source to see for what it might be useful.
1367
1368 @item ---set-filesize
1369 This is not for normal use. Use the source to see for what it might be useful.
1370
1371 @item ---emulate-md-encode-bug
1372 GnuPG versions prior to 1.0.2 had a bug in the way a signature was encoded.
1373 This options enables a workaround by checking faulty signatures again with
1374 the encoding used in old versions. This may only happen for ElGamal signatures
1375 which are not widely used.
1376
1377 @item ---show-session-key
1378 Display the session key used for one message. See ---override-session-key
1379 for the counterpart of this option.
1380
1381 We think that Key-Escrow is a Bad Thing; however the user should
1382 have the freedom to decide whether to go to prison or to reveal the content of
1383 one specific message without compromising all messages ever encrypted for one
1384 secret key. DON'T USE IT UNLESS YOU ARE REALLY FORCED TO DO SO.
1385
1386 @item ---override-session-key @code{string} 
1387 Don't use the public key but the session key @code{string}. The format of this
1388 string is the same as the one printed by ---show-session-key. This option
1389 is normally not used but comes handy in case someone forces you to reveal the
1390 content of an encrypted message; using this option you can do this without
1391 handing out the secret key.
1392
1393 @item ---ask-sig-expire
1394 @itemx ---no-ask-sig-expire
1395 When making a data signature, prompt for an expiration time. If this
1396 option is not specified, the expiration time is "never".
1397 ---no-ask-sig-expire disables this option.
1398
1399 @item ---ask-cert-expire
1400 @itemx ---no-ask-cert-expire
1401 When making a key signature, prompt for an expiration time. If this
1402 option is not specified, the expiration time is "never".
1403 ---no-ask-cert-expire disables this option.
1404
1405 @item ---expert
1406 @itemx ---no-expert
1407 Allow the user to do certain nonsensical or "silly" things like
1408 signing an expired or revoked key, or certain potentially incompatible
1409 things like generating deprecated key types. This also disables
1410 certain warning messages about potentially incompatible actions. As
1411 the name implies, this option is for experts only. If you don't fully
1412 understand the implications of what it allows you to do, leave this
1413 off. ---no-expert disables this option.
1414
1415 @item ---merge-only
1416 Don't insert new keys into the keyrings while doing an import.
1417
1418 @item ---allow-secret-key-import
1419 This is an obsolete option and is not used anywhere.
1420
1421 @item ---try-all-secrets
1422 Don't look at the key ID as stored in the message but try all secret keys in
1423 turn to find the right decryption key. This option forces the behaviour as
1424 used by anonymous recipients (created by using ---throw-keyid) and might come
1425 handy in case where an encrypted message contains a bogus key ID.
1426
1427 @item ---enable-special-filenames
1428 This options enables a mode in which filenames of the form
1429 @file{-&n}, where n is a non-negative decimal number,
1430 refer to the file descriptor n and not to a file with that name.
1431
1432 @item ---no-expensive-trust-checks
1433 Experimental use only.
1434
1435 @item ---group @code{name=value1 value2 value3 ...}
1436 Sets up a named group, which is similar to aliases in email programs.
1437 Any time the group name is a recipient (-r or ---recipient), it will
1438 be expanded to the values specified.
1439
1440 The values are @code{key IDs} or fingerprints, but any key description
1441 is accepted. Note that a value with spaces in it will be treated as
1442 two different values. Note also there is only one level of expansion
1443 - you cannot make an group that points to another group. When used
1444 from the command line, it may be necessary to quote the argument to
1445 this option to prevent the shell from treating it as multiple
1446 arguments.
1447
1448 @item ---preserve-permissions
1449 Don't change the permissions of a secret keyring back to user
1450 read/write only. Use this option only if you really know what you are doing.
1451
1452 @item ---personal-cipher-preferences @code{string}
1453 Set the list of personal cipher preferences to @code{string}, this list
1454 should be a string similar to the one printed by the command "pref" in
1455 the edit menu. This allows the user to factor in their own preferred
1456 algorithms when algorithms are chosen via recipient key preferences.
1457 The most highly ranked cipher in this list is also used for the
1458 ---symmetric encryption command.
1459
1460 @item ---personal-digest-preferences @code{string}
1461 Set the list of personal digest preferences to @code{string}, this list
1462 should be a string similar to the one printed by the command "pref" in
1463 the edit menu. This allows the user to factor in their own preferred
1464 algorithms when algorithms are chosen via recipient key preferences.
1465 The most highly ranked digest algorithm in this list is algo used when
1466 signing without encryption (e.g. ---clearsign or --sign).
1467
1468 @item ---personal-compress-preferences @code{string}
1469 Set the list of personal compression preferences to @code{string}, this
1470 list should be a string similar to the one printed by the command
1471 "pref" in the edit menu. This allows the user to factor in their own
1472 preferred algorithms when algorithms are chosen via recipient key
1473 preferences. The most highly ranked algorithm in this list is also
1474 used when there are no recipient keys to consider (e.g. ---symmetric).
1475
1476 @item ---default-preference-list @code{string}
1477 Set the list of default preferences to @code{string}, this list should
1478 be a string similar to the one printed by the command "pref" in the
1479 edit menu. This affects both key generation and "updpref" in the edit
1480 menu.
1481
1482 @end table
1483
1484 @majorheading How to specify a user ID
1485 There are different ways to specify a user ID to GnuPG; here are some
1486 examples:
1487
1488 @table @asis
1489 @item 
1490 @item 234567C4
1491 @itemx 0F34E556E
1492 @itemx 01347A56A
1493 @itemx 0xAB123456
1494 Here the key ID is given in the usual short form.
1495
1496 @item 234AABBCC34567C4
1497 @itemx 0F323456784E56EAB
1498 @itemx 01AB3FED1347A5612
1499 @itemx 0x234AABBCC34567C4
1500 Here the key ID is given in the long form as used by OpenPGP
1501 (you can get the long key ID using the option ---with-colons).
1502
1503 @item 1234343434343434C434343434343434
1504 @itemx 123434343434343C3434343434343734349A3434
1505 @itemx 0E12343434343434343434EAB3484343434343434
1506 @itemx 0xE12343434343434343434EAB3484343434343434
1507 The best way to specify a key ID is by using the fingerprint of
1508 the key. This avoids any ambiguities in case that there are duplicated
1509 key IDs (which are really rare for the long key IDs).
1510
1511 @item =Heinrich Heine <heinrichh@@uni-duesseldorf.de>
1512 Using an exact to match string. The equal sign indicates this.
1513
1514 @item <heinrichh@@uni-duesseldorf.de>
1515 Using the email address part which must match exactly. The left angle bracket
1516 indicates this email address mode.
1517
1518 @item +Heinrich Heine duesseldorf
1519 All words must match exactly (not case sensitive) but can appear in
1520 any order in the user ID. Words are any sequences of letters,
1521 digits, the underscore and all characters with bit 7 set.
1522
1523 @item Heine
1524 @itemx *Heine
1525 By case insensitive substring matching. This is the default mode but
1526 applications may want to explicitly indicate this by putting the asterisk
1527 in front.
1528
1529 @end table
1530
1531 Note that you can append an exclamation mark to key IDs or
1532 fingerprints. This flag tells GnuPG to use exactly the given primary
1533 or secondary key and not to try to figure out which secondary or
1534 primary key to use.
1535
1536 @majorheading RETURN VALUE
1537 The program returns 0 if everything was fine, 1 if at least
1538 a signature was bad, and other error codes for fatal errors.
1539
1540 @majorheading EXAMPLES
1541 @table @asis
1542 @item gpg -se -r @code{Bob} @code{file}
1543 sign and encrypt for user Bob
1544
1545 @item gpg ---clearsign @code{file}
1546 make a clear text signature
1547
1548 @item gpg -sb @code{file}
1549 make a detached signature
1550
1551 @item gpg ---list-keys @code{user_ID}
1552 show keys
1553
1554 @item gpg ---fingerprint @code{user_ID}
1555 show fingerprint
1556
1557 @item gpg ---verify @code{pgpfile}
1558 @itemx gpg ---verify @code{sigfile} @code{files}
1559 Verify the signature of the file but do not output the data. The second form
1560 is used for detached signatures, where @code{sigfile} is the detached
1561 signature (either ASCII armored of binary) and @code{files} are the signed
1562 data; if this is not given the name of the file holding the signed data is
1563 constructed by cutting off the extension (".asc" or ".sig") of
1564 @code{sigfile} or by asking the user for the filename.
1565
1566 @end table
1567
1568 @majorheading ENVIRONMENT
1569 @table @asis
1570 @item HOME
1571 Used to locate the default home directory.
1572
1573 @item GNUPGHOME
1574 If set directory used instead of "~/.gnupg".
1575
1576 @item GPG_AGENT_INFO
1577 Used to locate the gpg-agent; only honored when
1578 ---use-agent is set. The value consists of 3 colon delimited fields: 
1579 The first is the path to the Unix Domain Socket, the second the PID of
1580 the gpg-agent and the protocol version which should be set to 1. When
1581 starting the gpg-agent as described in its documentation, this
1582 variable is set to the correct value. The option ---gpg-agent-info can
1583 be used to override it.
1584
1585 @item http_proxy
1586 Only honored when the keyserver-option
1587 honor-http-proxy is set.
1588
1589 @end table
1590
1591 @majorheading FILES
1592 @table @asis
1593 @item ~/.gnupg/secring.gpg
1594 The secret keyring
1595
1596 @item ~/.gnupg/secring.gpg.lock
1597 and the lock file
1598
1599 @item ~/.gnupg/pubring.gpg
1600 The public keyring
1601
1602 @item ~/.gnupg/pubring.gpg.lock
1603 and the lock file
1604
1605 @item ~/.gnupg/trustdb.gpg
1606 The trust database
1607
1608 @item ~/.gnupg/trustdb.gpg.lock
1609 and the lock file
1610
1611 @item ~/.gnupg/random_seed
1612 used to preserve the internal random pool
1613
1614 @item ~/.gnupg/gpg.conf
1615 Default configuration file
1616
1617 @item ~/.gnupg/options
1618 Old style configuration file; only used when gpg.conf
1619 is not found
1620
1621 @item /usr[/local]/share/gnupg/options.skel
1622 Skeleton options file
1623
1624 @item /usr[/local]/lib/gnupg/
1625 Default location for extensions
1626
1627 @end table
1628
1629 @majorheading WARNINGS
1630 Use a *good* password for your user account and a *good* passphrase
1631 to protect your secret key. This passphrase is the weakest part of the
1632 whole system. Programs to do dictionary attacks on your secret keyring
1633 are very easy to write and so you should protect your "~/.gnupg/"
1634 directory very well.
1635
1636 Keep in mind that, if this program is used over a network (telnet), it
1637 is *very* easy to spy out your passphrase!
1638
1639 If you are going to verify detached signatures, make sure that the
1640 program knows about it; either be giving both filenames on the
1641 command line or using @samp{-} to specify stdin.
1642
1643 @majorheading INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS
1644 GnuPG tries to be a very flexible implementation of the OpenPGP
1645 standard. In particular, GnuPG implements many of the "optional"
1646 parts of the standard, such as the RIPEMD/160 hash, and the ZLIB
1647 compression algorithms. It is important to be aware that not all
1648 OpenPGP programs implement these optional algorithms and that by
1649 forcing their use via the ---cipher-algo, --digest-algo,
1650 ---cert-digest-algo, or --compress-algo options in GnuPG, it is
1651 possible to create a perfectly valid OpenPGP message, but one that
1652 cannot be read by the intended recipient.
1653
1654 For example, as of this writing, no version of official PGP supports
1655 the BLOWFISH cipher algorithm. If you use it, no PGP user will be
1656 able to decrypt your message. The same thing applies to the ZLIB
1657 compression algorithm. By default, GnuPG uses the OpenPGP preferences
1658 system that will always do the right thing and create messages that
1659 are usable by all recipients, regardless of which OpenPGP program they
1660 use. Only override this safe default if you know what you are doing.
1661
1662 If you absolutely must override the safe default, or if the
1663 preferences on a given key are invalid for some reason, you are far
1664 better off using the ---pgp2, --pgp6, --pgp7, or --pgp8 options. These
1665 options are safe as they do not force any particular algorithms in
1666 violation of OpenPGP, but rather reduce the available algorithms to a
1667 "PGP-safe" list.
1668
1669 @majorheading BUGS
1670 On many systems this program should be installed as setuid(root). This
1671 is necessary to lock memory pages. Locking memory pages prevents the
1672 operating system from writing memory pages to disk. If you get no
1673 warning message about insecure memory your operating system supports
1674 locking without being root. The program drops root privileges as soon
1675 as locked memory is allocated.
1676
1677 @bye