a172b39ecc8ffafbbb7bb0823fdbd5d293e4e7e0
[gnupg-doc.git] / web / documentation / manpage.org
1 #+TITLE: GnuPG - gpg man page
2 #+STARTUP: showall
3 #+SETUPFILE: "../share/setup.inc"
4 #+OPTIONS: -:nil
5
6 * gpg
7
8 ** Name
9
10 gpg -- encryption and signing tool
11
12 ** Synopsis
13
14 #+BEGIN_EXAMPLE
15     gpg
16      [--homedir name]
17      [--options file]
18      [options]
19      command
20      [args]
21
22 #+END_EXAMPLE
23
24 ** DESCRIPTION
25
26 *gpg* is the main program for the GnuPG system.
27
28 This man page does only list the commands and options available. For a
29 more verbose documentation get the GNU Privacy Handbook (GPH), which is
30 available at https://www.gnupg.org/gph/ . You will find a list of HOWTO
31 documents at https://www.gnupg.org/docs.html .
32
33 ** COMMANDS
34
35 *gpg* recognizes these commands:
36
37 -  -s, --sign :: Make a signature. This command may be combined with
38    --encrypt.
39
40 -  --clearsign :: Make a clear text signature.
41
42 -  -b, --detach-sign :: Make a detached signature.
43
44 -  -e, --encrypt :: Encrypt data. This option may be combined with
45    --sign.
46
47 -  -c, --symmetric :: Encrypt with symmetric cipher only This command
48    asks for a passphrase.
49
50 -  --store :: Store only (make a simple RFC1991 packet).
51
52 -  --decrypt [=file=] :: Decrypt =file= (or stdin if no file is
53    specified) and write it to stdout (or the file specified with
54    --output). If the decrypted file is signed, the signature is also
55    verified. This command differs from the default operation, as it
56    never writes to the filename which is included in the file and it
57    rejects files which don't begin with an encrypted message.
58
59 -  --verify [[=sigfile=] [=signed-files=]] :: Assume that =sigfile= is a
60    signature and verify it without generating any output. With no
61    arguments, the signature packet is read from stdin (it may be a
62    detached signature when not used in batch mode). If only a sigfile is
63    given, it may be a complete signature or a detached signature, in
64    which case the signed stuff is expected in a file without the ".sig"
65    or ".asc" extension (if such a file does not exist it is expected at
66    stdin; use a single dash ("-") as filename to force a read from
67    stdin). With more than 1 argument, the first should be a detached
68    signature and the remaining files are the signed stuff.
69
70 -  --verify-files [=files=] :: This is a special version of the --verify
71    command which does not work with detached signatures. The command
72    expects the files to bee verified either on the commandline or reads
73    the filenames from stdin; each anem muts be on separate line. The
74    command is intended for quick checking of many files.
75
76 -  --list-keys [=names=], --list-public-keys [=names=] :: List all keys
77    from the public keyrings, or just the ones given on the command line.
78
79 -  --list-secret-keys [=names=] :: List all keys from the secret
80    keyrings, or just the ones given on the command line.
81
82 -  --list-sigs [=names=] :: Same as --list-keys, but the signatures are
83    listed too.
84
85 -  --check-sigs [=names=] :: Same as --list-sigs, but the signatures are
86    verified.
87
88 -  --fingerprint [=names=] :: List all keys with their fingerprints.
89    This is the same output as --list-keys but with the additional output
90    of a line with the fingerprint. May also be combined with --list-sigs
91    or --check-sigs. If this command is given twice, the fingerprints of
92    all secondary keys are listed too.
93
94 -  --list-packets :: List only the sequence of packets. This is mainly
95    useful for debugging.
96
97 -  --gen-key :: Generate a new key pair. This command is normally only
98    used interactive.
99
100    There is an experimental feature which allows to create keys in batch
101    mode. See the file =doc/DETAILS= in the source distribution on how to
102    use this.
103
104 -  --edit-key =name= :: Present a menu which enables you to do all key
105    related tasks:
106
107    -  sign :: Make a signature on key of user =name= If the key is not
108       yet signed by the default user (or the users given with -u), the
109       program displays the information of the key again, together with
110       its fingerprint and asks whether it should be signed. This
111       question is repeated for all users specified with -u.
112
113    -  lsign :: Same as --sign but the signature is marked as
114       non-exportable and will therefore never be used by others. This
115       may be used to make keys valid only in the local environment.
116
117    -  revsig :: Revoke a signature. GnuPG asks for every signature which
118       has been done by one of the secret keys, whether a revocation
119       certificate should be generated.
120
121    -  trust :: Change the owner trust value. This updates the trust-db
122       immediately and no save is required.
123
124    -  disable, enable :: Disable or enable an entire key. A disabled key
125       can normally not be used for encryption.
126
127    -  adduid :: Create an alternate user id.
128
129    -  deluid :: Delete an user id.
130
131    -  addkey :: Add a subkey to this key.
132
133    -  delkey :: Remove a subkey.
134
135    -  revkey :: Revoke a subkey.
136
137    -  expire :: Change the key expiration time. If a key is selected,
138       the time of this key will be changed. With no selection the key
139       expiration of the primary key is changed.
140
141    -  passwd :: Change the passphrase of the secret key.
142
143    -  uid =n= :: Toggle selection of user id with index =n=. Use 0 to
144       deselect all.
145
146    -  key =n= :: Toggle selection of subkey with index =n=. Use 0 to
147       deselect all.
148
149    -  check :: Check all selected user ids.
150
151    -  pref :: List preferences.
152
153    -  toggle :: Toggle between public and secret key listing.
154
155    -  save :: Save all changes to the key rings and quit.
156
157    -  quit :: Quit the program without updating the key rings.
158
159    The listing shows you the key with its secondary keys and all user
160    ids. Selected keys or user ids are indicated by an asterisk. The
161    trust value is displayed with the primary key: the first is the
162    assigned owner trust and the second is the calculated trust value.
163    Letters are used for the values:
164
165    -  - :: No ownertrust assigned / not yet calculated.
166
167    -  e :: Trust calculation has failed.
168
169    -  q :: Not enough information for calculation.
170
171    -  n :: Never trust this key.
172
173    -  m :: Marginally trusted.
174
175    -  f :: Fully trusted.
176
177    -  u :: Ultimately trusted.
178
179 -  --sign-key =name= :: Sign a public key with you secret key. This is a
180    shortcut version of the subcommand "sign" from --edit.
181
182 -  --lsign-key =name= :: Sign a public key with you secret key but mark
183    it as non-exportable. This is a shortcut version of the subcommand
184    "lsign" from --edit.
185
186 -  --trusted-key =long key ID= :: Assume that the specified key (which
187    must be given as a full 8 byte key ID) is as trustworthy as one of
188    your own secret keys. This option is useful if you don't want to keep
189    your secret keys (or one of them) online but still be able to check
190    the validity of a given recipient's or signator's key.
191
192 -  --delete-key =name= :: Remove key from the public keyring
193
194 -  --delete-secret-key =name= :: Remove key from the secret and public
195    keyring
196
197 -  --gen-revoke :: Generate a revocation certificate for the complete
198    key. To revoke a subkey or a signature, use the --edit command.
199
200 -  --export [=names=] :: Either export all keys from all keyrings
201    (default keyrings and those registered via option --keyring), or if
202    at least one name is given, those of the given name. The new keyring
203    is written to stdout or to the file given with option "output". Use
204    together with --armor to mail those keys.
205
206 -  --send-keys [=names=] :: Same as --export but sends the keys to a
207    keyserver. Option --keyserver must be used to give the name of this
208    keyserver. Don't send your complete keyring to a keyserver - select
209    only those keys which are new or changed by you.
210
211 -  --export-all [=names=] :: Same as --export, but does also export keys
212    which are not compatible to OpenPGP.
213
214 -  --export-secret-keys [=names=], --export-secret-subkeys
215    [=names=] :: Same as --export, but does export the secret keys. This
216    is normally not very useful and a security risk. the second form of
217    the command has the special property to render the secret part of the
218    primary key useless; this is a GNU extension to OpenPGP and other
219    implementations can not be expected to successful import such a key.
220
221 -  --import [=files=], --fast-import [=files=] :: Import/merge keys.
222    This adds the given keys to the keyring. The fast version does not
223    build the trustdb; this can be done at any time with the command
224    --update-trustdb.
225
226    There are a few other options which control how this command works.
227    Most notable here is the --merge-only options which does not insert
228    new keys but does only the merging of new signatures, user-IDs and
229    subkeys.
230
231 -  --recv-keys =key IDs= :: Import the keys with the given key IDs from
232    a HKP keyserver. Option --keyserver must be used to give the name of
233    this keyserver.
234
235 -  --export-ownertrust :: List the assigned ownertrust values in ASCII
236    format for backup purposes
237
238 -  --import-ownertrust [=files=] :: Update the trustdb with the
239    ownertrust values stored in =files= (or stdin if not given); existing
240    values will be overwritten.
241
242 -  --print-md =algo= [=files=] :: Print message digest of algorithm ALGO
243    for all given files of stdin. If "*" is used for the algorithm,
244    digests for all available algorithms are printed.
245
246 -  --gen-random =0|1|2= [=count=] :: Emit COUNT random bytes of the
247    given quality level. If count is not given or zero, an endless
248    sequence of random bytes will be emitted. PLEASE, don't use this
249    command unless you know what you are doing, it may remove precious
250    entropy from the system!
251
252 -  --gen-prime =mode= =bits= [=qbits=] :: Use the source, Luke :-). The
253    output format is still subject to change.
254
255 -  --version :: Print version information along with a list of supported
256    algorithms.
257
258 -  --warranty :: Print warranty information.
259
260 -  -h, --help :: Print usage information. This is a really long list
261    even it does list not all options.
262
263 ** OPTIONS
264
265 Long options can be put in an options file (default "~/.gnupg/options").
266 Do not write the 2 dashes, but simply the name of the option and any
267 required arguments. Lines with a hash as the first non-white-space
268 character are ignored. Commands may be put in this file too, but that
269 does not make sense.
270
271 *gpg* recognizes these options:
272
273 -  -a, --armor :: Create ASCII armored output.
274
275 -  -o, --output =file= :: Write output to =file=.
276
277 -  -u, --local-user =name= :: Use =name= as the user ID to sign. This
278    option is silently ignored for the list commands, so that it can be
279    used in an options file.
280
281 -  --default-key =name= :: Use =name= as default user ID for signatures.
282    If this is not used the default user ID is the first user ID found in
283    the secret keyring.
284
285 -  -r, --recipient =name=,  :: Encrypt for user id =name=. If this
286    option is not specified, GnuPG asks for the user-id unless
287    --default-recipient is given
288
289 -  --default-recipient =name= :: Use =name= as default recipient if
290    option --recipient is not used and don't ask if this is a valid one.
291    =name= must be a non empty.
292
293 -  --default-recipient-self :: Use the default key as default recipient
294    if option --recipient is not used and don't ask if this is a valid
295    one. The default key is the first one from the secret keyring or the
296    one set with --default-key.
297
298 -  --no-default-recipient :: Reset --default-recipient and
299    --default-recipient-self.
300
301 -  --encrypt-to =name= :: Same as --recipient but this one is intended
302    for in the options file and may be used together with an own user-id
303    as an "encrypt-to-self". These keys are only used when there are
304    other recipients given either by use of --recipient or by the asked
305    user id. No trust checking is performed for these user ids and even
306    disabled keys can be used.
307
308 -  --no-encrypt-to :: Disable the use of all --encrypt-to keys.
309
310 -  -v, --verbose :: Give more information during processing. If used
311    twice, the input data is listed in detail.
312
313 -  -q, --quiet :: Try to be as quiet as possible.
314
315 -  -z =n= :: Set compression level to =n=. A value of 0 for =n= disables
316    compression. Default is to use the default compression level of zlib
317    (normally 6).
318
319 -  -t, --textmode :: Use canonical text mode. If -t (but not --textmode)
320    is used together with armoring and signing, this enables clearsigned
321    messages. This kludge is needed for PGP compatibility; normally you
322    would use --sign or --clearsign to selected the type of the
323    signature.
324
325 -  -n, --dry-run :: Don't make any changes (this is not completely
326    implemented).
327
328 -  -i, --interactive :: Prompt before overwriting any files.
329
330 -  --batch :: Use batch mode. Never ask, do not allow interactive
331    commands.
332
333 -  --no-tty :: Make sure that the TTY (terminal) is never used for any
334    output. This option is needed in some cases because GnuPG sometimes
335    prints warnings to the TTY if if --batch is used.
336
337 -  --no-batch :: Disable batch mode. This may be of use if --batch is
338    enabled from an options file.
339
340 -  --yes :: Assume "yes" on most questions.
341
342 -  --no :: Assume "no" on most questions.
343
344 -  --always-trust :: Skip key validation and assume that used keys are
345    always fully trusted. You won't use this unless you have installed
346    some external validation scheme.
347
348 -  --keyserver =name= :: Use =name= to lookup keys which are not yet in
349    your keyring. This is only done while verifying messages with
350    signatures. The option is also required for the command --send-keys
351    to specify the keyserver to where the keys should be send. All
352    keyservers synchronize with each other - so there is no need to send
353    keys to more than one server. Using the command "host -l pgp.net |
354    grep wwwkeys" gives you a list of keyservers. Because there is load
355    balancing using round-robin DNS you may notice that you get different
356    key servers.
357
358 -  --no-auto-key-retrieve :: This option disables the automatic
359    retrieving of keys from a keyserver while verifying signatures. This
360    option allows to keep a keyserver in the options file or the
361    --send-keys and --recv-keys commands.
362
363 -  --honor-http-proxy :: Try to access the keyserver over the proxy set
364    with the variable "http\_proxy".
365
366 -  --keyring =file= :: Add =file= to the list of keyrings. If =file=
367    begins with a tilde and a slash, these are replaced by the HOME
368    directory. If the filename does not contain a slash, it is assumed to
369    be in the home-directory ("~/.gnupg" if --homedir is not used). The
370    filename may be prefixed with a scheme:
371
372    "gnupg-ring:" is the default one.
373
374    "gnupg-gdbm:" may be used for a GDBM ring. Note that GDBM is
375    experimental and likely to be removed in future versions.
376
377    It might make sense to use it together with --no-default-keyring.
378
379 -  --secret-keyring =file= :: Same as --keyring but for the secret
380    keyrings.
381
382 -  --homedir =directory= :: Set the name of the home directory to
383    =directory= If this option is not used it defaults to "~/.gnupg". It
384    does not make sense to use this in a options file. This also
385    overrides the environment variable "GNUPGHOME".
386
387 -  --charset =name= :: Set the name of the native character set. This is
388    used to convert some strings to proper UTF-8 encoding. Valid values
389    for =name= are:
390
391    -  iso-8859-1 :: This is the default Latin 1 set.
392
393    -  iso-8859-2 :: The Latin 2 set.
394
395    -  koi8-r :: The usual Russian set (rfc1489).
396
397 -  --utf8-strings, --no-utf8-strings :: Assume that the arguments are
398    already given as UTF8 strings. The default (--no-utf8-strings) is to
399    assume that arguments are encoded in the character set as specified
400    by --charset. These options effects all following arguments. Both
401    options may used multiple times.
402
403 -  --options =file= :: Read options from =file= and do not try to read
404    them from the default options file in the homedir (see --homedir).
405    This option is ignored if used in an options file.
406
407 -  --no-options :: Shortcut for "--options /dev/null". This option is
408    detected before an attempt to open an option file.
409
410 -  --load-extension =name= :: Load an extension module. If =name= does
411    not contain a slash it is searched in "/usr/local/lib/gnupg" See the
412    manual for more information about extensions.
413
414 -  --debug =flags= :: Set debugging flags. All flags are or-ed and
415    =flags= may be given in C syntax (e.g. 0x0042).
416
417 -  --debug-all :: Set all useful debugging flags.
418
419 -  --status-fd =n= :: Write special status strings to the file
420    descriptor =n=. See the file DETAILS in the documentation for a
421    listing of them.
422
423 -  --logger-fd =n= :: Write log output to file descriptor =n= and not to
424    stderr.
425
426 -  --no-comment :: Do not write comment packets. This option affects
427    only the generation of secret keys. Please note, that this has
428    nothing to do with the comments in clear text signatures.
429
430 -  --comment =string= :: Use =string= as comment string in clear text
431    signatures. To suppress those comment strings entirely, use an empty
432    string here.
433
434 -  --default-comment :: Force to write the standard comment string in
435    clear text signatures. Use this to overwrite a --comment from a
436    config file.
437
438 -  --no-version :: Omit the version string in clear text signatures.
439
440 -  --emit-version :: Force to write the version string in clear text
441    signatures. Use this to overwrite a previous --no-version from a
442    config file.
443
444 -  -N, --notation-data =name=value= :: Put the name value pair into the
445    signature as notation data. =name= must consists only of alphanumeric
446    characters, digits or the underscore; the first character must not be
447    a digit. =value= may be any printable string; it will encoded in
448    UTF8, so sou should have check that your --charset is set right. If
449    you prefix =name= with an exclamation mark, the notation data will be
450    flagged as critical (rfc2440:5.2.3.15).
451
452 -  --set-policy-url =string= :: Use =string= as Policy URL for
453    signatures (rfc2440:5.2.3.19). If you prefix it with an exclamation
454    mark, the policy URL packet will be flagged as critical.
455
456 -  --set-filename =string= :: Use =string= as the name of file which is
457    stored in messages.
458
459 -  --use-embedded-filename :: Try to create a file with a name as
460    embedded in the data. This can be a dangerous option as it allows to
461    overwrite files.
462
463 -  --completes-needed =n= :: Number of completely trusted users to
464    introduce a new key signer (defaults to 1).
465
466 -  --marginals-needed =n= :: Number of marginally trusted users to
467    introduce a new key signer (defaults to 3)
468
469 -  --max-cert-depth =n= :: Maximum depth of a certification chain
470    (default is 5).
471
472 -  --cipher-algo =name= :: Use =name= as cipher algorithm. Running the
473    program with the command --version yields a list of supported
474    algorithms. If this is not used the cipher algorithm is selected from
475    the preferences stored with the key.
476
477 -  --digest-algo =name= :: Use =name= as message digest algorithm.
478    Running the program with the command --version yields a list of
479    supported algorithms. Please note that using this option may violate
480    the OpenPGP requirement, that a 160 bit hash is to be used for DSA.
481
482 -  --s2k-cipher-algo =name= :: Use =name= as the cipher algorithm used
483    to protect secret keys. The default cipher is BLOWFISH. This cipher
484    is also used for conventional encryption if --cipher-algo is not
485    given.
486
487 -  --s2k-digest-algo =name= :: Use =name= as the digest algorithm used
488    to mangle the passphrases. The default algorithm is RIPE-MD-160. This
489    digest algorithm is also used for conventional encryption if
490    --digest-algo is not given.
491
492 -  --s2k-mode =n= :: Selects how passphrases are mangled. If =n= is 0 a
493    plain passphrase (which is not recommended) will be used, a 1
494    (default) adds a salt to the passphrase and a 3 iterates the whole
495    process a couple of times. Unless --rfc1991 is used, this mode is
496    also used for conventional encryption.
497
498 -  --compress-algo =n= :: Use compress algorithm =n=. Default is 2 which
499    is RFC1950 compression. You may use 1 to use the old zlib version
500    (RFC1951) which is used by PGP. The default algorithm may give better
501    results because the window size is not limited to 8K. If this is not
502    used the OpenPGP behavior is used, i.e. the compression algorithm is
503    selected from the preferences; note, that this can't be done if you
504    do not encrypt the data.
505
506 -  --disable-cipher-algo =name= :: Never allow the use of =name= as
507    cipher algorithm. The given name will not be checked so that a later
508    loaded algorithm will still get disabled.
509
510 -  --disable-pubkey-algo =name= :: Never allow the use of =name= as
511    public key algorithm. The given name will not be checked so that a
512    later loaded algorithm will still get disabled.
513
514 -  --throw-keyid :: Do not put the keyid into encrypted packets. This
515    option hides the receiver of the message and is a countermeasure
516    against traffic analysis. It may slow down the decryption process
517    because all available secret keys are tried.
518
519 -  --not-dash-escaped :: This option changes the behavior of cleartext
520    signatures so that they can be used for patch files. You should not
521    send such an armored file via email because all spaces and line
522    endings are hashed too. You can not use this option for data which
523    has 5 dashes at the beginning of a line, patch files don't have this.
524    A special armor header line tells GnuPG about this cleartext
525    signature option.
526
527 -  --escape-from-lines :: Because some mailers change lines starting
528    with "From " to "<From " it is good to handle such lines in a special
529    way when creating cleartext signatures. All other PGP versions do it
530    this way too. This option is not enabled by default because it would
531    violate rfc2440.
532
533 -  --passphrase-fd =n= :: Read the passphrase from file descriptor =n=.
534    If you use 0 for =n=, the passphrase will be read from stdin. This
535    can only be used if only one passphrase is supplied. Don't use this
536    option if you can avoid it.
537
538 -  --command-fd =n= :: This is a replacement for the depreciated
539    shared-memory IPC mode. If this option is enabled, user input on
540    questions is not expected from the TTY but from the given file
541    descriptor. It should be used together with --status-fd. See the file
542    doc/DETAILS in the source distribution for details on how to use it.
543
544 -  --rfc1991 :: Try to be more RFC1991 (PGP 2.x) compliant.
545
546 -  --openpgp :: Reset all packet, cipher and digest options to OpenPGP
547    behavior. Use this option to reset all previous options like
548    --rfc1991, --force-v3-sigs, --s2k-*, --cipher-algo, --digest-algo and
549    --compress-algo to OpenPGP compliant values. All PGP workarounds are
550    also disabled.
551
552 -  --force-v3-sigs :: OpenPGP states that an implementation should
553    generate v4 signatures but PGP 5.x recognizes v4 signatures only on
554    key material. This options forces v3 signatures for signatures on
555    data.
556
557 -  --force-mdc :: Force the use of encryption with appended manipulation
558    code. This is always used with the newer cipher (those with a
559    blocksize greater than 64 bit). This option might not be implemented
560    yet.
561
562 -  --allow-non-selfsigned-uid :: Allow the import of keys with user IDs
563    which are not self-signed. This is only allows the import - key
564    validation will fail and you have to check the validity of the key my
565    other means. This hack is needed for some German keys generated with
566    pgp 2.6.3in. You should really avoid using it, because OpenPGP has
567    better mechanics to do separate signing and encryption keys.
568
569 -  --allow-freeform-uid :: Disable all checks on the form of the user ID
570    while generating a new one. This option should only be used in very
571    special environments as it does not ensure the de-facto standard
572    format of user IDs.
573
574 -  --ignore-time-conflict :: GnuPG normally checks that the timestamps
575    associated with keys and signatures have plausible values. However,
576    sometimes a signature seems to be older than the key due to clock
577    problems. This option makes these checks just a warning.
578
579 -  --lock-once :: Lock the databases the first time a lock is requested
580    and do not release the lock until the process terminates.
581
582 -  --lock-multiple :: Release the locks every time a lock is no longer
583    needed. Use this to override a previous --lock-once from a config
584    file.
585
586 -  --lock-never :: Disable locking entirely. This option should be used
587    only in very special environments, where it can be assured that only
588    one process is accessing those files. A bootable floppy with a
589    standalone encryption system will probably use this. Improper usage
590    of this option may lead to data and key corruption.
591
592 -  --no-random-seed-file :: GnuPG uses a file to store it's internal
593    random pool over invocations. This makes random generation faster;
594    however sometimes write operations are not desired. This option can
595    be used to achive that with the cost of slower random generation.
596
597 -  --no-verbose :: Reset verbose level to 0.
598
599 -  --no-greeting :: Suppress the initial copyright message but do not
600    enter batch mode.
601
602 -  --no-secmem-warning :: Suppress the warning about "using insecure
603    memory".
604
605 -  --no-armor :: Assume the input data is not in ASCII armored format.
606
607 -  --no-default-keyring :: Do not add the default keyrings to the list
608    of keyrings.
609
610 -  --skip-verify :: Skip the signature verification step. This may be
611    used to make the decryption faster if the signature verification is
612    not needed.
613
614 -  --with-colons :: Print key listings delimited by colons.
615
616 -  --with-key-data :: Print key listings delimited by colons and print
617    the public key data.
618
619 -  --with-fingerprint :: Same as the command --fingerprint but changes
620    only the format of the output and may be used together with another
621    command.
622
623 -  --fast-list-mode :: Changes the output of the list commands to work
624    faster; this is achieved by leaving some parts empty. Some
625    applications don't need the user ID and the trust information given
626    in the listings. By using this options they can get a faster listing.
627    The excact behaviour of this option may change in future versions.
628
629 -  --list-only :: Changes the behaviour of some commands. This is like
630    --dry-run but different in some cases. The semantic of this command
631    may be extended in the future. Currently it does only skip the actual
632    decryption pass and therefore enables a fast listing of the
633    encryption keys.
634
635 -  --no-literal :: This is not for normal use. Use the source to see for
636    what it might be useful.
637
638 -  --set-filesize :: This is not for normal use. Use the source to see
639    for what it might be useful.
640
641 -  --emulate-md-encode-bug :: GnuPG versions prior to 1.0.2 had a bug in
642    the way a signature was encode. This options enables a workaround by
643    checking faulty signatures again with the encoding used in old
644    versions. This may only happen for ElGamal signatures which are not
645    widely used.
646
647 -  --show-session-key :: Display the session key used for one message.
648    See --override-session-key for the counterpart of this option.
649
650    We think that Key-Escrow is a Bad Thing; however the user should have
651    the freedom to decide whether to go to prison or to reveal the
652    content of one specific message without compromising all messages
653    ever encrypted for one secret key. DON'T USE IT UNLESS YOU ARE REALLY
654    FORCED TO DO SO.
655
656 -  --override-session-key =string= :: Don't use the public key but the
657    session key =string=. The format of this string is the same as the
658    one printed by --show-session-key. This option is normally not used
659    but comes handy in case someone forces you to reveal the content of
660    an encrypted message; using this option you can do this without
661    handing out the secret key.
662
663 -  --merge-only :: Don't insert new keys into the keyrings while doing
664    an import.
665
666 -  --try-all-secrets :: Don't look at the key ID as stored in the
667    message but try all secret keys in turn to find the right decryption
668    key. This option forces the behaviour as used by anonymous recipients
669    (created by using --throw-keyid) and might come handy in case where
670    an encrypted message contains a bogus key ID.
671
672 ** How to specify a user ID
673
674 There are different ways on how to specify a user ID to GnuPG; here are
675 some examples:
676
677 -   :: Used to locate the default home directory.
678
679 -  234567C4, 0F34E556E, 01347A56A, 0xAB123456 :: Here the key ID is
680    given in the usual short form.
681
682 -  234AABBCC34567C4, 0F323456784E56EAB, 01AB3FED1347A5612,
683    0x234AABBCC34567C4 :: Here the key ID is given in the long form as
684    used by OpenPGP.
685
686 -  1234343434343434C434343434343434,
687    123434343434343C3434343434343734349A3434,
688    0E12343434343434343434EAB3484343434343434,
689    0xE12343434343434343434EAB3484343434343434 :: The best way to specify
690    a key ID is by using the fingerprint of the key. This avoids any
691    ambiguities in case that there are duplicated key IDs (which are
692    really rare for the long key IDs).
693
694 -  =Heinrich Heine <heinrichh@uni-duesseldorf.de> :: Using an exact to
695    match string. The equal sign indicates this.
696
697 -  <heinrichh@uni-duesseldorf.de> :: Using the email address part which
698    must match exactly. The left angle bracket indicates this email
699    address mode.
700
701 -  +Heinrich Heine duesseldorf :: All words must match exactly (not case
702    sensitive) but can appear in any order in the user ID. Words are any
703    sequences of letters, digits, the underscore and all characters with
704    bit 7 set.
705
706 -  #34 :: Using the Local ID. This is a very low level method and should
707    only be used by applications which really need it. The hash character
708    indicates this method. An application should not assume that this is
709    only a number.
710
711 -  Heine, *Heine :: By case insensitive substring matching. This is the
712    default mode but applications may want to explicitely indicate this
713    by putting the asterisk in front.
714
715 ** RETURN VALUE
716
717 The program returns 0 if everything was fine, 1 if at least a signature
718 was bad, and other error codes for fatal errors.
719
720 ** EXAMPLES
721
722 -  gpg -se -r =Bob= =file= :: sign and encrypt for user Bob
723
724 -  gpg --clearsign =file= :: make a clear text signature
725
726 -  gpg -sb =file= :: make a detached signature
727
728 -  gpg --list-keys =user_ID= :: show keys
729
730 -  gpg --fingerprint =user_ID= :: show fingerprint
731
732 -  gpg --verify =pgpfile=, gpg --verify =sigfile= [=files=] :: Verify
733    the signature of the file but do not output the data. The second form
734    is used for detached signatures, where =sigfile= is the detached
735    signature (either ASCII armored of binary) and [=files=] are the
736    signed data; if this is not given the name of the file holding the
737    signed data is constructed by cutting off the extension (".asc" or
738    ".sig") of =sigfile= or by asking the user for the filename.
739
740 ** ENVIRONMENT
741
742 -  HOME :: Used to locate the default home directory.
743
744 -  GNUPGHOME :: If set directory used instead of "~/.gnupg".
745
746 -  http\_proxy :: Only honored when the option --honor-http-proxy is
747    set.
748
749 ** FILES
750
751 -  ~/.gnupg/secring.gpg :: The secret keyring
752
753 -  ~/.gnupg/secring.gpg.lock :: and the lock file
754
755 -  ~/.gnupg/pubring.gpg :: The public keyring
756
757 -  ~/.gnupg/pubring.gpg.lock :: and the lock file
758
759 -  ~/.gnupg/trustdb.gpg :: The trust database
760
761 -  ~/.gnupg/trustdb.gpg.lock :: and the lock file
762
763 -  ~/.gnupg/random\_seed :: used to preserve the internal random pool
764
765 -  ~/.gnupg/options :: May contain options
766
767 -  /usr[/local]/share/gnupg/options.skel :: Skeleton options file
768
769 -  /usr[/local]/lib/gnupg/ :: Default location for extensions
770
771 ** WARNINGS
772
773 Use a *good* password for your user account and a *good* passphrase to
774 protect your secret key. This passphrase is the weakest part of the
775 whole system. Programs to do dictionary attacks on your secret keyring
776 are very easy to write and so you should protect your "~/.gnupg/"
777 directory very well.
778
779 Keep in mind that, if this program is used over a network (telnet), it
780 is *very* easy to spy out your passphrase!
781
782 ** BUGS
783
784 On many systems this program should be installed as setuid(root). This
785 is necessary to lock memory pages. Locking memory pages prevents the
786 operating system from writing memory pages to disk. If you get no
787 warning message about insecure memory 3our operating system supports
788 locking without being root. The program drops root privileges as soon as
789 locked memory is allocated.