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