e02c5c183f62b6c2909bfe4eb12be054b19a4093
[gnupg.git] / doc / gpg.texi
1 @c Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
2 @c               2008, 2009, 2010 Free Software Foundation, Inc.
3 @c This is part of the GnuPG manual.
4 @c For copying conditions, see the file gnupg.texi.
5
6 @include defs.inc
7
8 @node Invoking GPG
9 @chapter Invoking GPG
10 @cindex GPG command options
11 @cindex command options
12 @cindex options, GPG command
13
14
15 @c Begin standard stuff
16 @ifclear gpgtwohack
17 @manpage gpg.1
18 @ifset manverb
19 .B gpg
20 \- OpenPGP encryption and signing tool
21 @end ifset
22
23 @mansect synopsis
24 @ifset manverb
25 .B  gpg
26 .RB [ \-\-homedir
27 .IR dir ]
28 .RB [ \-\-options
29 .IR file ]
30 .RI [ options ]
31 .I command
32 .RI [ args ]
33 @end ifset
34 @end ifclear
35 @c End standard stuff
36
37 @c Begin gpg2 hack stuff
38 @ifset gpgtwohack
39 @manpage gpg2.1
40 @ifset manverb
41 .B gpg2
42 \- OpenPGP encryption and signing tool
43 @end ifset
44
45 @mansect synopsis
46 @ifset manverb
47 .B  gpg2
48 .RB [ \-\-homedir
49 .IR dir ]
50 .RB [ \-\-options
51 .IR file ]
52 .RI [ options ]
53 .I command
54 .RI [ args ]
55 @end ifset
56 @end ifset
57 @c End gpg2 hack stuff
58
59
60 @mansect description
61 @command{@gpgname} is the OpenPGP part of the GNU Privacy Guard (GnuPG). It
62 is a tool to provide digital encryption and signing services using the
63 OpenPGP standard. @command{@gpgname} features complete key management and
64 all the bells and whistles you would expect from a full OpenPGP
65 implementation.
66
67 There are two main versions of GnuPG: GnuPG 1.x and GnuPG 2.x.  GnuPG
68 2.x supports modern encryption algorithms and thus should be preferred
69 over GnuPG 1.x.  You only need to use GnuPG 1.x if your platform
70 doesn't support GnuPG 2.x, or you need support for some features that
71 GnuPG 2.x has deprecated, e.g., decrypting data created with PGP-2
72 keys.
73
74 @ifclear gpgtwohack
75 If you are looking for version 1 of GnuPG, you may find that version
76 installed under the name @command{gpg1}.
77 @end ifclear
78 @ifset gpgtwohack
79 In contrast to the standalone command @command{gpg} from GnuPG 1.x,
80 the 2.x version is commonly installed under the name
81 @command{@gpgname}.
82 @end ifset
83
84 @manpause
85
86 @xref{Option Index}, for an index to @command{@gpgname}'s commands and options.
87 @mancont
88
89 @menu
90 * GPG Commands::            List of all commands.
91 * GPG Options::             List of all options.
92 * GPG Configuration::       Configuration files.
93 * GPG Examples::            Some usage examples.
94
95 Developer information:
96 * Unattended Usage of GPG:: Using @command{gpg} from other programs.
97 @end menu
98
99 @c * GPG Protocol::        The protocol the server mode uses.
100
101
102 @c *******************************************
103 @c ***************            ****************
104 @c ***************  COMMANDS  ****************
105 @c ***************            ****************
106 @c *******************************************
107 @mansect commands
108 @node GPG Commands
109 @section Commands
110
111 Commands are not distinguished from options except for the fact that
112 only one command is allowed.  Generally speaking, irrelevant options
113 are silently ignored, and may not be checked for correctness.
114
115 @command{@gpgname} may be run with no commands. In this case it will
116 perform a reasonable action depending on the type of file it is given
117 as input (an encrypted message is decrypted, a signature is verified,
118 a file containing keys is listed, etc.).
119
120
121 @menu
122 * General GPG Commands::        Commands not specific to the functionality.
123 * Operational GPG Commands::    Commands to select the type of operation.
124 * OpenPGP Key Management::      How to manage your keys.
125 @end menu
126
127
128 @c *******************************************
129 @c **********  GENERAL COMMANDS  *************
130 @c *******************************************
131 @node General GPG Commands
132 @subsection Commands not specific to the function
133
134 @table @gnupgtabopt
135 @item --version
136 @opindex version
137 Print the program version and licensing information.  Note that you
138 cannot abbreviate this command.
139
140 @item --help
141 @itemx -h
142 @opindex help
143 Print a usage message summarizing the most useful command-line options.
144 Note that you cannot abbreviate this command.
145
146 @item --warranty
147 @opindex warranty
148 Print warranty information.
149
150 @item --dump-options
151 @opindex dump-options
152 Print a list of all available options and commands.  Note that you cannot
153 abbreviate this command.
154 @end table
155
156
157 @c *******************************************
158 @c ********  OPERATIONAL COMMANDS  ***********
159 @c *******************************************
160 @node Operational GPG Commands
161 @subsection Commands to select the type of operation
162
163
164 @table @gnupgtabopt
165
166 @item --sign
167 @itemx -s
168 @opindex sign
169 Sign a message. This command may be combined with @option{--encrypt}
170 (to sign and encrypt a message), @option{--symmetric} (to sign and
171 symmetrically encrypt a message), or both @option{--encrypt} and
172 @option{--symmetric} (to sign and encrypt a message that can be
173 decrypted using a secret key or a passphrase).  The signing key is
174 chosen by default or can be set explicitly using the
175 @option{--local-user} and @option{--default-key} options.
176
177 @item --clear-sign
178 @opindex clear-sign
179 @itemx --clearsign
180 @opindex clearsign
181 Make a cleartext signature.  The content in a cleartext signature is
182 readable without any special software. OpenPGP software is only needed
183 to verify the signature.  cleartext signatures may modify end-of-line
184 whitespace for platform independence and are not intended to be
185 reversible.  The signing key is chosen by default or can be set
186 explicitly using the @option{--local-user} and @option{--default-key}
187 options.
188
189
190 @item --detach-sign
191 @itemx -b
192 @opindex detach-sign
193 Make a detached signature.
194
195 @item --encrypt
196 @itemx -e
197 @opindex encrypt
198 Encrypt data. This command may be combined with @option{--sign} (to
199 sign and encrypt a message), @option{--symmetric} (to encrypt a
200 message that can decrypted using a secret key or a passphrase), or
201 @option{--sign} and @option{--symmetric} together (for a signed
202 message that can be decrypted using a secret key or a passphrase).
203
204 @item --symmetric
205 @itemx -c
206 @opindex symmetric
207 Encrypt with a symmetric cipher using a passphrase. The default
208 symmetric cipher used is @value{GPGSYMENCALGO}, but may be chosen with the
209 @option{--cipher-algo} option. This command may be combined with
210 @option{--sign} (for a signed and symmetrically encrypted message),
211 @option{--encrypt} (for a message that may be decrypted via a secret key
212 or a passphrase), or @option{--sign} and @option{--encrypt} together
213 (for a signed message that may be decrypted via a secret key or a
214 passphrase).
215
216 @item --store
217 @opindex store
218 Store only (make a simple literal data packet).
219
220 @item --decrypt
221 @itemx -d
222 @opindex decrypt
223 Decrypt the file given on the command line (or STDIN if no file
224 is specified) and write it to STDOUT (or the file specified with
225 @option{--output}). If the decrypted file is signed, the signature is also
226 verified. This command differs from the default operation, as it never
227 writes to the filename which is included in the file and it rejects
228 files that don't begin with an encrypted message.
229
230 @item --verify
231 @opindex verify
232 Assume that the first argument is a signed file and verify it without
233 generating any output.  With no arguments, the signature packet is
234 read from STDIN.  If only one argument is given, the specified file is
235 expected to include a complete signature.
236
237 With more than one argument, the first argument should specify a file
238 with a detached signature and the remaining files should contain the
239 signed data. To read the signed data from STDIN, use @samp{-} as the
240 second filename.  For security reasons, a detached signature will not
241 read the signed material from STDIN if not explicitly specified.
242
243 Note: If the option @option{--batch} is not used, @command{@gpgname}
244 may assume that a single argument is a file with a detached signature,
245 and it will try to find a matching data file by stripping certain
246 suffixes.  Using this historical feature to verify a detached
247 signature is strongly discouraged; you should always specify the data file
248 explicitly.
249
250 Note: When verifying a cleartext signature, @command{@gpgname} verifies
251 only what makes up the cleartext signed data and not any extra data
252 outside of the cleartext signature or the header lines directly following
253 the dash marker line.  The option @code{--output} may be used to write
254 out the actual signed data, but there are other pitfalls with this
255 format as well.  It is suggested to avoid cleartext signatures in
256 favor of detached signatures.
257
258 @item --multifile
259 @opindex multifile
260 This modifies certain other commands to accept multiple files for
261 processing on the command line or read from STDIN with each filename on
262 a separate line. This allows for many files to be processed at
263 once. @option{--multifile} may currently be used along with
264 @option{--verify}, @option{--encrypt}, and @option{--decrypt}. Note that
265 @option{--multifile --verify} may not be used with detached signatures.
266
267 @item --verify-files
268 @opindex verify-files
269 Identical to @option{--multifile --verify}.
270
271 @item --encrypt-files
272 @opindex encrypt-files
273 Identical to @option{--multifile --encrypt}.
274
275 @item --decrypt-files
276 @opindex decrypt-files
277 Identical to @option{--multifile --decrypt}.
278
279 @item --list-keys
280 @itemx -k
281 @itemx --list-public-keys
282 @opindex list-keys
283 List the specified keys.  If no keys are specified, then all keys from
284 the configured public keyrings are listed.
285
286 Never use the output of this command in scripts or other programs.
287 The output is intended only for humans and its format is likely to
288 change.  The @option{--with-colons} option emits the output in a
289 stable, machine-parseable format, which is intended for use by scripts
290 and other programs.
291
292 @item --list-secret-keys
293 @itemx -K
294 @opindex list-secret-keys
295 List the specified secret keys.  If no keys are specified, then all
296 known secret keys are listed.  A @code{#} after the letters @code{sec}
297 means that the secret key is not usable (for example, if it was
298 exported using @option{--export-secret-subkeys}).  See also
299 @option{--list-keys}.
300
301 @item --list-signatures
302 @opindex list-signatures
303 @itemx --list-sigs
304 @opindex list-sigs
305 Same as @option{--list-keys}, but the signatures are listed too.
306 This command has the same effect as
307 using @option{--list-keys} with @option{--with-sig-list}.
308
309 For each signature listed, there are several flags in between the "sig"
310 tag and keyid. These flags give additional information about each
311 signature. From left to right, they are the numbers 1-3 for certificate
312 check level (see @option{--ask-cert-level}), "L" for a local or
313 non-exportable signature (see @option{--lsign-key}), "R" for a
314 nonRevocable signature (see the @option{--edit-key} command "nrsign"),
315 "P" for a signature that contains a policy URL (see
316 @option{--cert-policy-url}), "N" for a signature that contains a
317 notation (see @option{--cert-notation}), "X" for an eXpired signature
318 (see @option{--ask-cert-expire}), and the numbers 1-9 or "T" for 10 and
319 above to indicate trust signature levels (see the @option{--edit-key}
320 command "tsign").
321
322 @item --check-signatures
323 @opindex check-signatures
324 @itemx --check-sigs
325 @opindex check-sigs
326 Same as @option{--list-signatures}, but the signatures are verified.  Note
327 that for performance reasons the revocation status of a signing key is
328 not shown.
329 This command has the same effect as
330 using @option{--list-keys} with @option{--with-sig-check}.
331
332 The status of the verification is indicated by a flag directly following
333 the "sig" tag (and thus before the flags described above for
334 @option{--list-signatures}).  A "!" indicates that the signature has been
335 successfully verified, a "-" denotes a bad signature and a "%" is used
336 if an error occurred while checking the signature (e.g. a non supported
337 algorithm).
338
339 @item --locate-keys
340 @opindex locate-keys
341 Locate the keys given as arguments.  This command basically uses the
342 same algorithm as used when locating keys for encryption or signing and
343 may thus be used to see what keys @command{@gpgname} might use.  In
344 particular external methods as defined by @option{--auto-key-locate} may
345 be used to locate a key.  Only public keys are listed.
346
347 @item --fingerprint
348 @opindex fingerprint
349 List all keys (or the specified ones) along with their
350 fingerprints. This is the same output as @option{--list-keys} but with
351 the additional output of a line with the fingerprint. May also be
352 combined with @option{--list-signatures} or @option{--check-signatures}.  If this
353 command is given twice, the fingerprints of all secondary keys are
354 listed too.  This command also forces pretty printing of fingerprints
355 if the keyid format has been set to "none".
356
357 @item --list-packets
358 @opindex list-packets
359 List only the sequence of packets.  This command is only useful for
360 debugging.  When used with option @option{--verbose} the actual MPI
361 values are dumped and not only their lengths.  Note that the output of
362 this command may change with new releases.
363
364
365 @item --edit-card
366 @opindex edit-card
367 @itemx --card-edit
368 @opindex card-edit
369 Present a menu to work with a smartcard. The subcommand "help" provides
370 an overview on available commands. For a detailed description, please
371 see the Card HOWTO at
372 https://gnupg.org/documentation/howtos.html#GnuPG-cardHOWTO .
373
374 @item --card-status
375 @opindex card-status
376 Show the content of the smart card.
377
378 @item --change-pin
379 @opindex change-pin
380 Present a menu to allow changing the PIN of a smartcard. This
381 functionality is also available as the subcommand "passwd" with the
382 @option{--edit-card} command.
383
384 @item --delete-keys @code{name}
385 @itemx --delete-keys @code{name}
386 Remove key from the public keyring. In batch mode either @option{--yes} is
387 required or the key must be specified by fingerprint. This is a
388 safeguard against accidental deletion of multiple keys.
389
390 @item --delete-secret-keys @code{name}
391 @opindex delete-secret-keys
392 Remove key from the secret keyring. In batch mode the key must be
393 specified by fingerprint.  The option @option{--yes} can be used to
394 advice gpg-agent not to request a confirmation.  This extra
395 pre-caution is done because @command{@gpgname} can't be sure that the
396 secret key (as controlled by gpg-agent) is only used for the given
397 OpenPGP public key.
398
399
400 @item --delete-secret-and-public-key @code{name}
401 @opindex delete-secret-and-public-key
402 Same as @option{--delete-key}, but if a secret key exists, it will be
403 removed first. In batch mode the key must be specified by fingerprint.
404 The option @option{--yes} can be used to advice gpg-agent not to
405 request a confirmation.
406
407 @item --export
408 @opindex export
409 Either export all keys from all keyrings (default keyrings and those
410 registered via option @option{--keyring}), or if at least one name is given,
411 those of the given name. The exported keys are written to STDOUT or to the
412 file given with option @option{--output}.  Use together with
413 @option{--armor} to mail those keys.
414
415 @item --send-keys @code{key IDs}
416 @opindex send-keys
417 Similar to @option{--export} but sends the keys to a keyserver.
418 Fingerprints may be used instead of key IDs. Option @option{--keyserver}
419 must be used to give the name of this keyserver. Don't send your
420 complete keyring to a keyserver --- select only those keys which are new
421 or changed by you.  If no key IDs are given, @command{@gpgname} does nothing.
422
423 @item --export-secret-keys
424 @itemx --export-secret-subkeys
425 @opindex export-secret-keys
426 @opindex export-secret-subkeys
427 Same as @option{--export}, but exports the secret keys instead.  The
428 exported keys are written to STDOUT or to the file given with option
429 @option{--output}.  This command is often used along with the option
430 @option{--armor} to allow for easy printing of the key for paper backup;
431 however the external tool @command{paperkey} does a better job of
432 creating backups on paper.  Note that exporting a secret key can be a
433 security risk if the exported keys are sent over an insecure channel.
434
435 The second form of the command has the special property to render the
436 secret part of the primary key useless; this is a GNU extension to
437 OpenPGP and other implementations can not be expected to successfully
438 import such a key.  Its intended use is in generating a full key with
439 an additional signing subkey on a dedicated machine.  This command
440 then exports the key without the primary key to the main machine.
441
442 GnuPG may ask you to enter the passphrase for the key.  This is
443 required, because the internal protection method of the secret key is
444 different from the one specified by the OpenPGP protocol.
445
446 @item --export-ssh-key
447 @opindex export-ssh-key
448 This command is used to export a key in the OpenSSH public key format.
449 It requires the specification of one key by the usual means and
450 exports the latest valid subkey which has an authentication capability
451 to STDOUT or to the file given with option @option{--output}.  That
452 output can directly be added to ssh's @file{authorized_key} file.
453
454 By specifying the key to export using a key ID or a fingerprint
455 suffixed with an exclamation mark (!), a specific subkey or the
456 primary key can be exported.  This does not even require that the key
457 has the authentication capability flag set.
458
459 @item --import
460 @itemx --fast-import
461 @opindex import
462 Import/merge keys. This adds the given keys to the
463 keyring. The fast version is currently just a synonym.
464
465 There are a few other options which control how this command works.
466 Most notable here is the @option{--import-options merge-only} option
467 which does not insert new keys but does only the merging of new
468 signatures, user-IDs and subkeys.
469
470 @item --receive-keys @code{key IDs}
471 @opindex receive-keys
472 @itemx --recv-keys @code{key IDs}
473 @opindex recv-keys
474 Import the keys with the given key IDs from a keyserver. Option
475 @option{--keyserver} must be used to give the name of this keyserver.
476
477 @item --refresh-keys
478 @opindex refresh-keys
479 Request updates from a keyserver for keys that already exist on the
480 local keyring. This is useful for updating a key with the latest
481 signatures, user IDs, etc. Calling this with no arguments will refresh
482 the entire keyring. Option @option{--keyserver} must be used to give the
483 name of the keyserver for all keys that do not have preferred keyservers
484 set (see @option{--keyserver-options honor-keyserver-url}).
485
486 @item --search-keys @code{names}
487 @opindex search-keys
488 Search the keyserver for the given names. Multiple names given here will
489 be joined together to create the search string for the keyserver.
490 Option @option{--keyserver} must be used to give the name of this
491 keyserver.  Keyservers that support different search methods allow using
492 the syntax specified in "How to specify a user ID" below. Note that
493 different keyserver types support different search methods. Currently
494 only LDAP supports them all.
495
496 @item --fetch-keys @code{URIs}
497 @opindex fetch-keys
498 Retrieve keys located at the specified URIs. Note that different
499 installations of GnuPG may support different protocols (HTTP, FTP,
500 LDAP, etc.).  When using HTTPS the system provided root certificates
501 are used by this command.
502
503 @item --update-trustdb
504 @opindex update-trustdb
505 Do trust database maintenance. This command iterates over all keys and
506 builds the Web of Trust. This is an interactive command because it may
507 have to ask for the "ownertrust" values for keys. The user has to give
508 an estimation of how far she trusts the owner of the displayed key to
509 correctly certify (sign) other keys. GnuPG only asks for the ownertrust
510 value if it has not yet been assigned to a key. Using the
511 @option{--edit-key} menu, the assigned value can be changed at any time.
512
513 @item --check-trustdb
514 @opindex check-trustdb
515 Do trust database maintenance without user interaction. From time to
516 time the trust database must be updated so that expired keys or
517 signatures and the resulting changes in the Web of Trust can be
518 tracked. Normally, GnuPG will calculate when this is required and do it
519 automatically unless @option{--no-auto-check-trustdb} is set. This
520 command can be used to force a trust database check at any time. The
521 processing is identical to that of @option{--update-trustdb} but it
522 skips keys with a not yet defined "ownertrust".
523
524 For use with cron jobs, this command can be used together with
525 @option{--batch} in which case the trust database check is done only if
526 a check is needed. To force a run even in batch mode add the option
527 @option{--yes}.
528
529 @anchor{option --export-ownertrust}
530 @item --export-ownertrust
531 @opindex export-ownertrust
532 Send the ownertrust values to STDOUT. This is useful for backup purposes
533 as these values are the only ones which can't be re-created from a
534 corrupted trustdb.  Example:
535 @c man:.RS
536 @example
537   @gpgname{} --export-ownertrust > otrust.txt
538 @end example
539 @c man:.RE
540
541
542 @item --import-ownertrust
543 @opindex import-ownertrust
544 Update the trustdb with the ownertrust values stored in @code{files} (or
545 STDIN if not given); existing values will be overwritten.  In case of a
546 severely damaged trustdb and if you have a recent backup of the
547 ownertrust values (e.g. in the file @file{otrust.txt}), you may re-create
548 the trustdb using these commands:
549 @c man:.RS
550 @example
551   cd ~/.gnupg
552   rm trustdb.gpg
553   @gpgname{} --import-ownertrust < otrust.txt
554 @end example
555 @c man:.RE
556
557
558 @item --rebuild-keydb-caches
559 @opindex rebuild-keydb-caches
560 When updating from version 1.0.6 to 1.0.7 this command should be used
561 to create signature caches in the keyring. It might be handy in other
562 situations too.
563
564 @item --print-md @code{algo}
565 @itemx --print-mds
566 @opindex print-md
567 Print message digest of algorithm ALGO for all given files or STDIN.
568 With the second form (or a deprecated "*" as algo) digests for all
569 available algorithms are printed.
570
571 @item --gen-random @code{0|1|2} @code{count}
572 @opindex gen-random
573 Emit @var{count} random bytes of the given quality level 0, 1 or 2. If
574 @var{count} is not given or zero, an endless sequence of random bytes
575 will be emitted.  If used with @option{--armor} the output will be
576 base64 encoded.  PLEASE, don't use this command unless you know what
577 you are doing; it may remove precious entropy from the system!
578
579 @item --gen-prime @code{mode}  @code{bits}
580 @opindex gen-prime
581 Use the source, Luke :-). The output format is still subject to change.
582
583
584 @item --enarmor
585 @itemx --dearmor
586 @opindex enarmor
587 @opindex dearmor
588 Pack or unpack an arbitrary input into/from an OpenPGP ASCII armor.
589 This is a GnuPG extension to OpenPGP and in general not very useful.
590
591 @item --tofu-policy @code{auto|good|unknown|bad|ask}  @code{key...}
592 @opindex tofu-policy
593 Set the TOFU policy for all the bindings associated with the specified
594 keys.  For more information about the meaning of the policies,
595 @pxref{trust-model-tofu}.  The keys may be specified either by their
596 fingerprint (preferred) or their keyid.
597
598 @c @item --server
599 @c @opindex server
600 @c Run gpg in server mode.  This feature is not yet ready for use and
601 @c thus not documented.
602
603 @end table
604
605
606 @c *******************************************
607 @c *******  KEY MANGEMENT COMMANDS  **********
608 @c *******************************************
609 @node OpenPGP Key Management
610 @subsection How to manage your keys
611
612 This section explains the main commands for key management.
613
614 @table @gnupgtabopt
615
616 @item --quick-generate-key @code{user-id} [@code{algo} [@code{usage} [@code{expire}]]]
617 @opindex quick-generate-key
618 This is a simple command to generate a standard key with one user id.
619 In contrast to @option{--generate-key} the key is generated directly
620 without the need to answer a bunch of prompts.  Unless the option
621 @option{--yes} is given, the key creation will be canceled if the
622 given user id already exists in the keyring.
623
624 If invoked directly on the console without any special options an
625 answer to a ``Continue?'' style confirmation prompt is required.  In
626 case the user id already exists in the keyring a second prompt to
627 force the creation of the key will show up.
628
629 If @code{algo} or @code{usage} are given, only the primary key is
630 created and no prompts are shown.  To specify an expiration date but
631 still create a primary and subkey use ``default'' or
632 ``future-default'' for @code{algo} and ``default'' for @code{usage}.
633 For a description of these optional arguments see the command
634 @code{--quick-add-key}.  The @code{usage} accepts also the value
635 ``cert'' which can be used to create a certification only primary key;
636 the default is to a create certification and signing key.
637
638 The @code{expire} argument can be used to specify an expiration date
639 for the key.  Several formats are supported; commonly the ISO
640 YYYY-MM-DD format is used.  The values ``never'', ``none'' can be used
641 for no expiration date.  Not specifying a value, or using ``-''
642 results in a key expiring in a reasonable default interval.
643
644 If this command is used with @option{--batch},
645 @option{--pinentry-mode} has been set to @code{loopback}, and one of
646 the passphrase options (@option{--passphrase},
647 @option{--passphrase-fd}, or @option{passphrase-file}) is used, the
648 supplied passphrase is used for the new key and the agent does not ask
649 for it.  To create a key without any protection @code{--passphrase ''}
650 may be used.
651
652 @item --quick-set-expire @code{fpr} @code{expire}
653 @opindex quick-set-expire
654 Directly set the expiration time of the primary key to @code{expire}.
655 To remove the expiration time @code{0} can be used.
656
657
658 @item --quick-add-key @code{fpr} [@code{algo} [@code{usage} [@code{expire}]]]
659 @opindex quick-add-key
660 Directly add a subkey to the key identified by the fingerprint
661 @code{fpr}.  Without the optional arguments an encryption subkey is
662 added.  If any of the arguments are given a more specific subkey is
663 added.
664
665 @code{algo} may be any of the supported algorithms or curve names
666 given in the format as used by key listings.  To use the default
667 algorithm the string ``default'' or ``-'' can be used.  Supported
668 algorithms are ``rsa'', ``dsa'', ``elg'', ``ed25519'', ``cv25519'',
669 and other ECC curves.  For example the string ``rsa'' adds an RSA key
670 with the default key length; a string ``rsa4096'' requests that the
671 key length is 4096 bits.  The string ``future-default'' is an alias
672 for the algorithm which will likely be used as default algorithm in
673 future versions of gpg.
674
675 Depending on the given @code{algo} the subkey may either be an
676 encryption subkey or a signing subkey.  If an algorithm is capable of
677 signing and encryption and such a subkey is desired, a @code{usage}
678 string must be given.  This string is either ``default'' or ``-'' to
679 keep the default or a comma delimited list of keywords: ``sign'' for a
680 signing subkey, ``auth'' for an authentication subkey, and ``encr''
681 for an encryption subkey (``encrypt'' can be used as alias for
682 ``encr'').  The valid combinations depend on the algorithm.
683
684 The @code{expire} argument can be used to specify an expiration date
685 for the subkey.  Several formats are supported; commonly the ISO
686 YYYY-MM-DD format is used.  The values ``never'', ``none'', or ``-''
687 can be used for no expiration date.
688
689 @item --generate-key
690 @opindex generate-key
691 @itemx --gen-key
692 @opindex gen-key
693 Generate a new key pair using the current default parameters.  This is
694 the standard command to create a new key.  In addition to the key a
695 revocation certificate is created and stored in the
696 @file{openpgp-revocs.d} directory below the GnuPG home directory.
697
698 @item --full-generate-key
699 @opindex full-generate-key
700 @itemx --full-gen-key
701 @opindex full-gen-key
702 Generate a new key pair with dialogs for all options.  This is an
703 extended version of @option{--generate-key}.
704
705 There is also a feature which allows you to create keys in batch
706 mode. See the manual section ``Unattended key generation'' on how
707 to use this.
708
709
710 @item --generate-revocation @code{name}
711 @opindex generate-revocation
712 @itemx --gen-revoke @code{name}
713 @opindex gen-revoke
714 Generate a revocation certificate for the complete key.  To only revoke
715 a subkey or a key signature, use the @option{--edit} command.
716
717 This command merely creates the revocation certificate so that it can
718 be used to revoke the key if that is ever needed.  To actually revoke
719 a key the created revocation certificate needs to be merged with the
720 key to revoke.  This is done by importing the revocation certificate
721 using the @option{--import} command.  Then the revoked key needs to be
722 published, which is best done by sending the key to a keyserver
723 (command @option{--send-key}) and by exporting (@option{--export}) it
724 to a file which is then send to frequent communication partners.
725
726
727 @item --generate-designated-revocation @code{name}
728 @opindex generate-designated-revocation
729 @itemx --desig-revoke @code{name}
730 @opindex desig-revoke
731 Generate a designated revocation certificate for a key. This allows a
732 user (with the permission of the keyholder) to revoke someone else's
733 key.
734
735
736 @item --edit-key
737 @opindex edit-key
738 Present a menu which enables you to do most of the key management
739 related tasks.  It expects the specification of a key on the command
740 line.
741
742 @c ******** Begin Edit-key Options **********
743 @table @asis
744
745   @item uid @code{n}
746   @opindex keyedit:uid
747   Toggle selection of user ID or photographic user ID with index @code{n}.
748   Use @code{*} to select all and @code{0} to deselect all.
749
750   @item key @code{n}
751   @opindex keyedit:key
752   Toggle selection of subkey with index @code{n} or key ID @code{n}.
753   Use @code{*} to select all and @code{0} to deselect all.
754
755   @item sign
756   @opindex keyedit:sign
757   Make a signature on key of user @code{name}. If the key is not yet
758   signed by the default user (or the users given with @option{-u}), the program
759   displays the information of the key again, together with its
760   fingerprint and asks whether it should be signed. This question is
761   repeated for all users specified with
762   @option{-u}.
763
764   @item lsign
765   @opindex keyedit:lsign
766   Same as "sign" but the signature is marked as non-exportable and will
767   therefore never be used by others. This may be used to make keys
768   valid only in the local environment.
769
770   @item nrsign
771   @opindex keyedit:nrsign
772   Same as "sign" but the signature is marked as non-revocable and can
773   therefore never be revoked.
774
775   @item tsign
776   @opindex keyedit:tsign
777   Make a trust signature. This is a signature that combines the notions
778   of certification (like a regular signature), and trust (like the
779   "trust" command). It is generally only useful in distinct communities
780   or groups.  For more information please read the sections
781   ``Trust Signature'' and ``Regular Expression'' in RFC-4880.
782 @end table
783
784 @c man:.RS
785 Note that "l" (for local / non-exportable), "nr" (for non-revocable,
786 and "t" (for trust) may be freely mixed and prefixed to "sign" to
787 create a signature of any type desired.
788 @c man:.RE
789
790 If the option @option{--only-sign-text-ids} is specified, then any
791 non-text based user ids (e.g., photo IDs) will not be selected for
792 signing.
793
794 @table @asis
795
796   @item delsig
797   @opindex keyedit:delsig
798   Delete a signature. Note that it is not possible to retract a signature,
799   once it has been send to the public (i.e. to a keyserver).  In that case
800   you better use @code{revsig}.
801
802   @item revsig
803   @opindex keyedit:revsig
804   Revoke a signature. For every signature which has been generated by
805   one of the secret keys, GnuPG asks whether a revocation certificate
806   should be generated.
807
808   @item check
809   @opindex keyedit:check
810   Check the signatures on all selected user IDs.  With the extra
811   option @code{selfsig} only self-signatures are shown.
812
813   @item adduid
814   @opindex keyedit:adduid
815   Create an additional user ID.
816
817   @item addphoto
818   @opindex keyedit:addphoto
819   Create a photographic user ID. This will prompt for a JPEG file that
820   will be embedded into the user ID. Note that a very large JPEG will make
821   for a very large key. Also note that some programs will display your
822   JPEG unchanged (GnuPG), and some programs will scale it to fit in a
823   dialog box (PGP).
824
825   @item showphoto
826   @opindex keyedit:showphoto
827   Display the selected photographic user ID.
828
829   @item deluid
830   @opindex keyedit:deluid
831   Delete a user ID or photographic user ID.  Note that it is not
832   possible to retract a user id, once it has been send to the public
833   (i.e. to a keyserver).  In that case you better use @code{revuid}.
834
835   @item revuid
836   @opindex keyedit:revuid
837   Revoke a user ID or photographic user ID.
838
839   @item primary
840   @opindex keyedit:primary
841   Flag the current user id as the primary one, removes the primary user
842   id flag from all other user ids and sets the timestamp of all affected
843   self-signatures one second ahead. Note that setting a photo user ID
844   as primary makes it primary over other photo user IDs, and setting a
845   regular user ID as primary makes it primary over other regular user
846   IDs.
847
848   @item keyserver
849   @opindex keyedit:keyserver
850   Set a preferred keyserver for the specified user ID(s). This allows
851   other users to know where you prefer they get your key from. See
852   @option{--keyserver-options honor-keyserver-url} for more on how this
853   works.  Setting a value of "none" removes an existing preferred
854   keyserver.
855
856   @item notation
857   @opindex keyedit:notation
858   Set a name=value notation for the specified user ID(s). See
859   @option{--cert-notation} for more on how this works. Setting a value of
860   "none" removes all notations, setting a notation prefixed with a minus
861   sign (-) removes that notation, and setting a notation name (without the
862   =value) prefixed with a minus sign removes all notations with that name.
863
864   @item pref
865   @opindex keyedit:pref
866   List preferences from the selected user ID. This shows the actual
867   preferences, without including any implied preferences.
868
869   @item showpref
870   @opindex keyedit:showpref
871   More verbose preferences listing for the selected user ID. This shows
872   the preferences in effect by including the implied preferences of 3DES
873   (cipher), SHA-1 (digest), and Uncompressed (compression) if they are
874   not already included in the preference list. In addition, the
875   preferred keyserver and signature notations (if any) are shown.
876
877   @item setpref @code{string}
878   @opindex keyedit:setpref
879   Set the list of user ID preferences to @code{string} for all (or just
880   the selected) user IDs. Calling setpref with no arguments sets the
881   preference list to the default (either built-in or set via
882   @option{--default-preference-list}), and calling setpref with "none"
883   as the argument sets an empty preference list. Use @command{@gpgname
884   --version} to get a list of available algorithms. Note that while you
885   can change the preferences on an attribute user ID (aka "photo ID"),
886   GnuPG does not select keys via attribute user IDs so these preferences
887   will not be used by GnuPG.
888
889   When setting preferences, you should list the algorithms in the order
890   which you'd like to see them used by someone else when encrypting a
891   message to your key.  If you don't include 3DES, it will be
892   automatically added at the end.  Note that there are many factors that
893   go into choosing an algorithm (for example, your key may not be the
894   only recipient), and so the remote OpenPGP application being used to
895   send to you may or may not follow your exact chosen order for a given
896   message.  It will, however, only choose an algorithm that is present
897   on the preference list of every recipient key.  See also the
898   INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS section below.
899
900   @item addkey
901   @opindex keyedit:addkey
902   Add a subkey to this key.
903
904   @item addcardkey
905   @opindex keyedit:addcardkey
906   Generate a subkey on a card and add it to this key.
907
908   @item keytocard
909   @opindex keyedit:keytocard
910   Transfer the selected secret subkey (or the primary key if no subkey
911   has been selected) to a smartcard. The secret key in the keyring will
912   be replaced by a stub if the key could be stored successfully on the
913   card and you use the save command later. Only certain key types may be
914   transferred to the card. A sub menu allows you to select on what card
915   to store the key. Note that it is not possible to get that key back
916   from the card - if the card gets broken your secret key will be lost
917   unless you have a backup somewhere.
918
919   @item bkuptocard @code{file}
920   @opindex keyedit:bkuptocard
921   Restore the given file to a card. This command may be used to restore a
922   backup key (as generated during card initialization) to a new card. In
923   almost all cases this will be the encryption key. You should use this
924   command only with the corresponding public key and make sure that the
925   file given as argument is indeed the backup to restore. You should then
926   select 2 to restore as encryption key.  You will first be asked to enter
927   the passphrase of the backup key and then for the Admin PIN of the card.
928
929   @item delkey
930   @opindex keyedit:delkey
931   Remove a subkey (secondary key). Note that it is not possible to retract
932   a subkey, once it has been send to the public (i.e. to a keyserver).  In
933   that case you better use @code{revkey}.
934
935   @item revkey
936   @opindex keyedit:revkey
937   Revoke a subkey.
938
939   @item expire
940   @opindex keyedit:expire
941   Change the key or subkey expiration time. If a subkey is selected, the
942   expiration time of this subkey will be changed. With no selection, the
943   key expiration of the primary key is changed.
944
945   @item trust
946   @opindex keyedit:trust
947   Change the owner trust value for the key. This updates the trust-db
948   immediately and no save is required.
949
950   @item disable
951   @itemx enable
952   @opindex keyedit:disable
953   @opindex keyedit:enable
954   Disable or enable an entire key. A disabled key can not normally be
955   used for encryption.
956
957   @item addrevoker
958   @opindex keyedit:addrevoker
959   Add a designated revoker to the key. This takes one optional argument:
960   "sensitive". If a designated revoker is marked as sensitive, it will
961   not be exported by default (see export-options).
962
963   @item passwd
964   @opindex keyedit:passwd
965   Change the passphrase of the secret key.
966
967   @item toggle
968   @opindex keyedit:toggle
969   This is dummy command which exists only for backward compatibility.
970
971   @item clean
972   @opindex keyedit:clean
973   Compact (by removing all signatures except the selfsig) any user ID
974   that is no longer usable (e.g. revoked, or expired). Then, remove any
975   signatures that are not usable by the trust calculations.
976   Specifically, this removes any signature that does not validate, any
977   signature that is superseded by a later signature, revoked signatures,
978   and signatures issued by keys that are not present on the keyring.
979
980   @item minimize
981   @opindex keyedit:minimize
982   Make the key as small as possible. This removes all signatures from
983   each user ID except for the most recent self-signature.
984
985   @item cross-certify
986   @opindex keyedit:cross-certify
987   Add cross-certification signatures to signing subkeys that may not
988   currently have them. Cross-certification signatures protect against a
989   subtle attack against signing subkeys. See
990   @option{--require-cross-certification}.  All new keys generated have
991   this signature by default, so this command is only useful to bring
992   older keys up to date.
993
994   @item save
995   @opindex keyedit:save
996   Save all changes to the keyrings and quit.
997
998   @item quit
999   @opindex keyedit:quit
1000   Quit the program without updating the
1001   keyrings.
1002 @end table
1003
1004 @c man:.RS
1005 The listing shows you the key with its secondary keys and all user
1006 ids.  The primary user id is indicated by a dot, and selected keys or
1007 user ids are indicated by an asterisk.  The trust
1008 value is displayed with the primary key: the first is the assigned owner
1009 trust and the second is the calculated trust value. Letters are used for
1010 the values:
1011 @c man:.RE
1012
1013 @table @asis
1014
1015   @item -
1016   No ownertrust assigned / not yet calculated.
1017
1018   @item e
1019   Trust
1020   calculation has failed; probably due to an expired key.
1021
1022   @item q
1023   Not enough information for calculation.
1024
1025   @item n
1026   Never trust this key.
1027
1028   @item m
1029   Marginally trusted.
1030
1031   @item f
1032   Fully trusted.
1033
1034   @item u
1035   Ultimately trusted.
1036
1037 @end table
1038 @c ******** End Edit-key Options **********
1039
1040 @item --sign-key @code{name}
1041 @opindex sign-key
1042 Signs a public key with your secret key. This is a shortcut version of
1043 the subcommand "sign" from @option{--edit}.
1044
1045 @item --lsign-key @code{name}
1046 @opindex lsign-key
1047 Signs a public key with your secret key but marks it as
1048 non-exportable. This is a shortcut version of the subcommand "lsign"
1049 from @option{--edit-key}.
1050
1051 @item --quick-sign-key @code{fpr} [@code{names}]
1052 @itemx --quick-lsign-key @code{fpr} [@code{names}]
1053 @opindex quick-sign-key
1054 @opindex quick-lsign-key
1055 Directly sign a key from the passphrase without any further user
1056 interaction.  The @code{fpr} must be the verified primary fingerprint
1057 of a key in the local keyring. If no @code{names} are given, all
1058 useful user ids are signed; with given [@code{names}] only useful user
1059 ids matching one of theses names are signed.  By default, or if a name
1060 is prefixed with a '*', a case insensitive substring match is used.
1061 If a name is prefixed with a '=' a case sensitive exact match is done.
1062
1063 The command @option{--quick-lsign-key} marks the signatures as
1064 non-exportable.  If such a non-exportable signature already exists the
1065 @option{--quick-sign-key} turns it into a exportable signature.
1066
1067 This command uses reasonable defaults and thus does not provide the
1068 full flexibility of the "sign" subcommand from @option{--edit-key}.
1069 Its intended use is to help unattended key signing by utilizing a list
1070 of verified fingerprints.
1071
1072 @item --quick-add-uid  @var{user-id} @var{new-user-id}
1073 @opindex quick-add-uid
1074 This command adds a new user id to an existing key.  In contrast to
1075 the interactive sub-command @code{adduid} of @option{--edit-key} the
1076 @var{new-user-id} is added verbatim with only leading and trailing
1077 white space removed, it is expected to be UTF-8 encoded, and no checks
1078 on its form are applied.
1079
1080 @item --quick-revoke-uid  @var{user-id} @var{user-id-to-revoke}
1081 @opindex quick-revoke-uid
1082 This command revokes a User ID on an existing key.  It cannot be used
1083 to revoke the last User ID on key (some non-revoked User ID must
1084 remain), with revocation reason ``User ID is no longer valid''.  If
1085 you want to specify a different revocation reason, or to supply
1086 supplementary revocation text, you should use the interactive
1087 sub-command @code{revuid} of @option{--edit-key}.
1088
1089 @item --change-passphrase @var{user_id}
1090 @opindex change-passphrase
1091 @itemx --passwd @var{user_id}
1092 @opindex passwd
1093 Change the passphrase of the secret key belonging to the certificate
1094 specified as @var{user_id}.  This is a shortcut for the sub-command
1095 @code{passwd} of the edit key menu.
1096
1097 @end table
1098
1099
1100 @c *******************************************
1101 @c ***************            ****************
1102 @c ***************  OPTIONS   ****************
1103 @c ***************            ****************
1104 @c *******************************************
1105 @mansect options
1106 @node GPG Options
1107 @section Option Summary
1108
1109 @command{@gpgname} features a bunch of options to control the exact
1110 behaviour and to change the default configuration.
1111
1112 @menu
1113 * GPG Configuration Options::   How to change the configuration.
1114 * GPG Key related Options::     Key related options.
1115 * GPG Input and Output::        Input and Output.
1116 * OpenPGP Options::             OpenPGP protocol specific options.
1117 * Compliance Options::          Compliance options.
1118 * GPG Esoteric Options::        Doing things one usually doesn't want to do.
1119 * Deprecated Options::          Deprecated options.
1120 @end menu
1121
1122 Long options can be put in an options file (default
1123 "~/.gnupg/gpg.conf"). Short option names will not work - for example,
1124 "armor" is a valid option for the options file, while "a" is not. Do not
1125 write the 2 dashes, but simply the name of the option and any required
1126 arguments. Lines with a hash ('#') as the first non-white-space
1127 character are ignored. Commands may be put in this file too, but that is
1128 not generally useful as the command will execute automatically with
1129 every execution of gpg.
1130
1131 Please remember that option parsing stops as soon as a non-option is
1132 encountered, you can explicitly stop parsing by using the special option
1133 @option{--}.
1134
1135 @c *******************************************
1136 @c ********  CONFIGURATION OPTIONS  **********
1137 @c *******************************************
1138 @node GPG Configuration Options
1139 @subsection How to change the configuration
1140
1141 These options are used to change the configuration and are usually found
1142 in the option file.
1143
1144 @table @gnupgtabopt
1145
1146 @item --default-key @var{name}
1147 @opindex default-key
1148 Use @var{name} as the default key to sign with. If this option is not
1149 used, the default key is the first key found in the secret keyring.
1150 Note that @option{-u} or @option{--local-user} overrides this option.
1151 This option may be given multiple times.  In this case, the last key
1152 for which a secret key is available is used.  If there is no secret
1153 key available for any of the specified values, GnuPG will not emit an
1154 error message but continue as if this option wasn't given.
1155
1156 @item --default-recipient @var{name}
1157 @opindex default-recipient
1158 Use @var{name} as default recipient if option @option{--recipient} is
1159 not used and don't ask if this is a valid one. @var{name} must be
1160 non-empty.
1161
1162 @item --default-recipient-self
1163 @opindex default-recipient-self
1164 Use the default key as default recipient if option @option{--recipient} is not
1165 used and don't ask if this is a valid one. The default key is the first
1166 one from the secret keyring or the one set with @option{--default-key}.
1167
1168 @item --no-default-recipient
1169 @opindex no-default-recipient
1170 Reset @option{--default-recipient} and @option{--default-recipient-self}.
1171
1172 @item -v, --verbose
1173 @opindex verbose
1174 Give more information during processing. If used
1175 twice, the input data is listed in detail.
1176
1177 @item --no-verbose
1178 @opindex no-verbose
1179 Reset verbose level to 0.
1180
1181 @item -q, --quiet
1182 @opindex quiet
1183 Try to be as quiet as possible.
1184
1185 @item --batch
1186 @itemx --no-batch
1187 @opindex batch
1188 @opindex no-batch
1189 Use batch mode.  Never ask, do not allow interactive commands.
1190 @option{--no-batch} disables this option.  Note that even with a
1191 filename given on the command line, gpg might still need to read from
1192 STDIN (in particular if gpg figures that the input is a
1193 detached signature and no data file has been specified).  Thus if you
1194 do not want to feed data via STDIN, you should connect STDIN to
1195 g@file{/dev/null}.
1196
1197 It is highly recommended to use this option along with the options
1198 @option{--status-fd} and @option{--with-colons} for any unattended of
1199 @command{gpg}.
1200
1201 @item --no-tty
1202 @opindex no-tty
1203 Make sure that the TTY (terminal) is never used for any output.
1204 This option is needed in some cases because GnuPG sometimes prints
1205 warnings to the TTY even if @option{--batch} is used.
1206
1207 @item --yes
1208 @opindex yes
1209 Assume "yes" on most questions.
1210
1211 @item --no
1212 @opindex no
1213 Assume "no" on most questions.
1214
1215
1216 @item --list-options @code{parameters}
1217 @opindex list-options
1218 This is a space or comma delimited string that gives options used when
1219 listing keys and signatures (that is, @option{--list-keys},
1220 @option{--list-signatures}, @option{--list-public-keys},
1221 @option{--list-secret-keys}, and the @option{--edit-key} functions).
1222 Options can be prepended with a @option{no-} (after the two dashes) to
1223 give the opposite meaning.  The options are:
1224
1225 @table @asis
1226
1227   @item show-photos
1228   @opindex list-options:show-photos
1229   Causes @option{--list-keys}, @option{--list-signatures},
1230   @option{--list-public-keys}, and @option{--list-secret-keys} to
1231   display any photo IDs attached to the key.  Defaults to no. See also
1232   @option{--photo-viewer}.  Does not work with @option{--with-colons}:
1233   see @option{--attribute-fd} for the appropriate way to get photo data
1234   for scripts and other frontends.
1235
1236   @item show-usage
1237   @opindex list-options:show-usage
1238   Show usage information for keys and subkeys in the standard key
1239   listing.  This is a list of letters indicating the allowed usage for a
1240   key (@code{E}=encryption, @code{S}=signing, @code{C}=certification,
1241   @code{A}=authentication).  Defaults to yes.
1242
1243   @item show-policy-urls
1244   @opindex list-options:show-policy-urls
1245   Show policy URLs in the @option{--list-signatures} or @option{--check-signatures}
1246   listings.  Defaults to no.
1247
1248   @item show-notations
1249   @itemx show-std-notations
1250   @itemx show-user-notations
1251   @opindex list-options:show-notations
1252   @opindex list-options:show-std-notations
1253   @opindex list-options:show-user-notations
1254   Show all, IETF standard, or user-defined signature notations in the
1255   @option{--list-signatures} or @option{--check-signatures} listings. Defaults to no.
1256
1257   @item show-keyserver-urls
1258   @opindex list-options:show-keyserver-urls
1259   Show any preferred keyserver URL in the @option{--list-signatures} or
1260   @option{--check-signatures} listings. Defaults to no.
1261
1262   @item show-uid-validity
1263   @opindex list-options:show-uid-validity
1264   Display the calculated validity of user IDs during key listings.
1265   Defaults to yes.
1266
1267   @item show-unusable-uids
1268   @opindex list-options:show-unusable-uids
1269   Show revoked and expired user IDs in key listings. Defaults to no.
1270
1271   @item show-unusable-subkeys
1272   @opindex list-options:show-unusable-subkeys
1273   Show revoked and expired subkeys in key listings. Defaults to no.
1274
1275   @item show-keyring
1276   @opindex list-options:show-keyring
1277   Display the keyring name at the head of key listings to show which
1278   keyring a given key resides on. Defaults to no.
1279
1280   @item show-sig-expire
1281   @opindex list-options:show-sig-expire
1282   Show signature expiration dates (if any) during @option{--list-signatures} or
1283   @option{--check-signatures} listings. Defaults to no.
1284
1285   @item show-sig-subpackets
1286   @opindex list-options:show-sig-subpackets
1287   Include signature subpackets in the key listing. This option can take an
1288   optional argument list of the subpackets to list. If no argument is
1289   passed, list all subpackets. Defaults to no. This option is only
1290   meaningful when using @option{--with-colons} along with
1291   @option{--list-signatures} or @option{--check-signatures}.
1292
1293 @end table
1294
1295 @item --verify-options @code{parameters}
1296 @opindex verify-options
1297 This is a space or comma delimited string that gives options used when
1298 verifying signatures. Options can be prepended with a `no-' to give
1299 the opposite meaning. The options are:
1300
1301 @table @asis
1302
1303   @item show-photos
1304   @opindex verify-options:show-photos
1305   Display any photo IDs present on the key that issued the signature.
1306   Defaults to no. See also @option{--photo-viewer}.
1307
1308   @item show-policy-urls
1309   @opindex verify-options:show-policy-urls
1310   Show policy URLs in the signature being verified. Defaults to yes.
1311
1312   @item show-notations
1313   @itemx show-std-notations
1314   @itemx show-user-notations
1315   @opindex verify-options:show-notations
1316   @opindex verify-options:show-std-notations
1317   @opindex verify-options:show-user-notations
1318   Show all, IETF standard, or user-defined signature notations in the
1319   signature being verified. Defaults to IETF standard.
1320
1321   @item show-keyserver-urls
1322   @opindex verify-options:show-keyserver-urls
1323   Show any preferred keyserver URL in the signature being verified.
1324   Defaults to yes.
1325
1326   @item show-uid-validity
1327   @opindex verify-options:show-uid-validity
1328   Display the calculated validity of the user IDs on the key that issued
1329   the signature. Defaults to yes.
1330
1331   @item show-unusable-uids
1332   @opindex verify-options:show-unusable-uids
1333   Show revoked and expired user IDs during signature verification.
1334   Defaults to no.
1335
1336   @item show-primary-uid-only
1337   @opindex verify-options:show-primary-uid-only
1338   Show only the primary user ID during signature verification.  That is
1339   all the AKA lines as well as photo Ids are not shown with the signature
1340   verification status.
1341
1342   @item pka-lookups
1343   @opindex verify-options:pka-lookups
1344   Enable PKA lookups to verify sender addresses. Note that PKA is based
1345   on DNS, and so enabling this option may disclose information on when
1346   and what signatures are verified or to whom data is encrypted. This
1347   is similar to the "web bug" described for the @option{--auto-key-retrieve}
1348   option.
1349
1350   @item pka-trust-increase
1351   @opindex verify-options:pka-trust-increase
1352   Raise the trust in a signature to full if the signature passes PKA
1353   validation. This option is only meaningful if pka-lookups is set.
1354 @end table
1355
1356 @item --enable-large-rsa
1357 @itemx --disable-large-rsa
1358 @opindex enable-large-rsa
1359 @opindex disable-large-rsa
1360 With --generate-key and --batch, enable the creation of RSA secret keys as
1361 large as 8192 bit.  Note: 8192 bit is more than is generally
1362 recommended.  These large keys don't significantly improve security,
1363 but they are more expensive to use, and their signatures and
1364 certifications are larger.  This option is only available if the
1365 binary was build with large-secmem support.
1366
1367 @item --enable-dsa2
1368 @itemx --disable-dsa2
1369 @opindex enable-dsa2
1370 @opindex disable-dsa2
1371 Enable hash truncation for all DSA keys even for old DSA Keys up to
1372 1024 bit.  This is also the default with @option{--openpgp}.  Note
1373 that older versions of GnuPG also required this flag to allow the
1374 generation of DSA larger than 1024 bit.
1375
1376 @item --photo-viewer @code{string}
1377 @opindex photo-viewer
1378 This is the command line that should be run to view a photo ID. "%i"
1379 will be expanded to a filename containing the photo. "%I" does the
1380 same, except the file will not be deleted once the viewer exits.
1381 Other flags are "%k" for the key ID, "%K" for the long key ID, "%f"
1382 for the key fingerprint, "%t" for the extension of the image type
1383 (e.g. "jpg"), "%T" for the MIME type of the image (e.g. "image/jpeg"),
1384 "%v" for the single-character calculated validity of the image being
1385 viewed (e.g. "f"), "%V" for the calculated validity as a string (e.g.
1386 "full"), "%U" for a base32 encoded hash of the user ID,
1387 and "%%" for an actual percent sign. If neither %i or %I are present,
1388 then the photo will be supplied to the viewer on standard input.
1389
1390 The default viewer is "xloadimage -fork -quiet -title 'KeyID 0x%k'
1391 STDIN". Note that if your image viewer program is not secure, then
1392 executing it from GnuPG does not make it secure.
1393
1394 @item --exec-path @code{string}
1395 @opindex exec-path
1396 @efindex PATH
1397 Sets a list of directories to search for photo viewers and keyserver
1398 helpers. If not provided, keyserver helpers use the compiled-in
1399 default directory, and photo viewers use the @code{PATH} environment
1400 variable.
1401 Note, that on W32 system this value is ignored when searching for
1402 keyserver helpers.
1403
1404 @item --keyring @code{file}
1405 @opindex keyring
1406 Add @code{file} to the current list of keyrings. If @code{file} begins
1407 with a tilde and a slash, these are replaced by the $HOME directory. If
1408 the filename does not contain a slash, it is assumed to be in the GnuPG
1409 home directory ("~/.gnupg" if @option{--homedir} or $GNUPGHOME is not
1410 used).
1411
1412 Note that this adds a keyring to the current list. If the intent is to
1413 use the specified keyring alone, use @option{--keyring} along with
1414 @option{--no-default-keyring}.
1415
1416 If the the option @option{--no-keyring} has been used no keyrings will
1417 be used at all.
1418
1419
1420 @item --secret-keyring @code{file}
1421 @opindex secret-keyring
1422 This is an obsolete option and ignored.  All secret keys are stored in
1423 the @file{private-keys-v1.d} directory below the GnuPG home directory.
1424
1425 @item --primary-keyring @code{file}
1426 @opindex primary-keyring
1427 Designate @code{file} as the primary public keyring. This means that
1428 newly imported keys (via @option{--import} or keyserver
1429 @option{--recv-from}) will go to this keyring.
1430
1431 @item --trustdb-name @code{file}
1432 @opindex trustdb-name
1433 Use @code{file} instead of the default trustdb. If @code{file} begins
1434 with a tilde and a slash, these are replaced by the $HOME directory. If
1435 the filename does not contain a slash, it is assumed to be in the GnuPG
1436 home directory (@file{~/.gnupg} if @option{--homedir} or $GNUPGHOME is
1437 not used).
1438
1439 @include opt-homedir.texi
1440
1441
1442 @item --display-charset @code{name}
1443 @opindex display-charset
1444 Set the name of the native character set. This is used to convert
1445 some informational strings like user IDs to the proper UTF-8 encoding.
1446 Note that this has nothing to do with the character set of data to be
1447 encrypted or signed; GnuPG does not recode user-supplied data. If
1448 this option is not used, the default character set is determined from
1449 the current locale. A verbosity level of 3 shows the chosen set.
1450 Valid values for @code{name} are:
1451
1452 @table @asis
1453
1454   @item iso-8859-1
1455   @opindex display-charset:iso-8859-1
1456   This is the Latin 1 set.
1457
1458   @item iso-8859-2
1459   @opindex display-charset:iso-8859-2
1460   The Latin 2 set.
1461
1462   @item iso-8859-15
1463   @opindex display-charset:iso-8859-15
1464   This is currently an alias for
1465   the Latin 1 set.
1466
1467   @item koi8-r
1468   @opindex display-charset:koi8-r
1469   The usual Russian set (RFC-1489).
1470
1471   @item utf-8
1472   @opindex display-charset:utf-8
1473   Bypass all translations and assume
1474   that the OS uses native UTF-8 encoding.
1475 @end table
1476
1477 @item --utf8-strings
1478 @itemx --no-utf8-strings
1479 @opindex utf8-strings
1480 Assume that command line arguments are given as UTF-8 strings. The
1481 default (@option{--no-utf8-strings}) is to assume that arguments are
1482 encoded in the character set as specified by
1483 @option{--display-charset}. These options affect all following
1484 arguments. Both options may be used multiple times.
1485
1486 @anchor{gpg-option --options}
1487 @item --options @code{file}
1488 @opindex options
1489 Read options from @code{file} and do not try to read them from the
1490 default options file in the homedir (see @option{--homedir}). This
1491 option is ignored if used in an options file.
1492
1493 @item --no-options
1494 @opindex no-options
1495 Shortcut for @option{--options /dev/null}. This option is detected
1496 before an attempt to open an option file.  Using this option will also
1497 prevent the creation of a @file{~/.gnupg} homedir.
1498
1499 @item -z @code{n}
1500 @itemx --compress-level @code{n}
1501 @itemx --bzip2-compress-level @code{n}
1502 @opindex compress-level
1503 @opindex bzip2-compress-level
1504 Set compression level to @code{n} for the ZIP and ZLIB compression
1505 algorithms. The default is to use the default compression level of zlib
1506 (normally 6). @option{--bzip2-compress-level} sets the compression level
1507 for the BZIP2 compression algorithm (defaulting to 6 as well). This is a
1508 different option from @option{--compress-level} since BZIP2 uses a
1509 significant amount of memory for each additional compression level.
1510 @option{-z} sets both. A value of 0 for @code{n} disables compression.
1511
1512 @item --bzip2-decompress-lowmem
1513 @opindex bzip2-decompress-lowmem
1514 Use a different decompression method for BZIP2 compressed files. This
1515 alternate method uses a bit more than half the memory, but also runs
1516 at half the speed. This is useful under extreme low memory
1517 circumstances when the file was originally compressed at a high
1518 @option{--bzip2-compress-level}.
1519
1520
1521 @item --mangle-dos-filenames
1522 @itemx --no-mangle-dos-filenames
1523 @opindex mangle-dos-filenames
1524 @opindex no-mangle-dos-filenames
1525 Older version of Windows cannot handle filenames with more than one
1526 dot. @option{--mangle-dos-filenames} causes GnuPG to replace (rather
1527 than add to) the extension of an output filename to avoid this
1528 problem. This option is off by default and has no effect on non-Windows
1529 platforms.
1530
1531 @item --ask-cert-level
1532 @itemx --no-ask-cert-level
1533 @opindex ask-cert-level
1534 When making a key signature, prompt for a certification level. If this
1535 option is not specified, the certification level used is set via
1536 @option{--default-cert-level}. See @option{--default-cert-level} for
1537 information on the specific levels and how they are
1538 used. @option{--no-ask-cert-level} disables this option. This option
1539 defaults to no.
1540
1541 @item --default-cert-level @code{n}
1542 @opindex default-cert-level
1543 The default to use for the check level when signing a key.
1544
1545 0 means you make no particular claim as to how carefully you verified
1546 the key.
1547
1548 1 means you believe the key is owned by the person who claims to own
1549 it but you could not, or did not verify the key at all. This is
1550 useful for a "persona" verification, where you sign the key of a
1551 pseudonymous user.
1552
1553 2 means you did casual verification of the key. For example, this
1554 could mean that you verified the key fingerprint and checked the
1555 user ID on the key against a photo ID.
1556
1557 3 means you did extensive verification of the key. For example, this
1558 could mean that you verified the key fingerprint with the owner of the
1559 key in person, and that you checked, by means of a hard to forge
1560 document with a photo ID (such as a passport) that the name of the key
1561 owner matches the name in the user ID on the key, and finally that you
1562 verified (by exchange of email) that the email address on the key
1563 belongs to the key owner.
1564
1565 Note that the examples given above for levels 2 and 3 are just that:
1566 examples. In the end, it is up to you to decide just what "casual"
1567 and "extensive" mean to you.
1568
1569 This option defaults to 0 (no particular claim).
1570
1571 @item --min-cert-level
1572 @opindex min-cert-level
1573 When building the trust database, treat any signatures with a
1574 certification level below this as invalid. Defaults to 2, which
1575 disregards level 1 signatures. Note that level 0 "no particular
1576 claim" signatures are always accepted.
1577
1578 @item --trusted-key @code{long key ID}
1579 @opindex trusted-key
1580 Assume that the specified key (which must be given
1581 as a full 8 byte key ID) is as trustworthy as one of
1582 your own secret keys. This option is useful if you
1583 don't want to keep your secret keys (or one of them)
1584 online but still want to be able to check the validity of a given
1585 recipient's or signator's key.
1586
1587 @item --trust-model @code{pgp|classic|tofu|tofu+pgp|direct|always|auto}
1588 @opindex trust-model
1589 Set what trust model GnuPG should follow. The models are:
1590
1591 @table @asis
1592
1593   @item pgp
1594   @opindex trust-mode:pgp
1595   This is the Web of Trust combined with trust signatures as used in PGP
1596   5.x and later. This is the default trust model when creating a new
1597   trust database.
1598
1599   @item classic
1600   @opindex trust-mode:classic
1601   This is the standard Web of Trust as introduced by PGP 2.
1602
1603   @item tofu
1604   @opindex trust-mode:tofu
1605   @anchor{trust-model-tofu}
1606   TOFU stands for Trust On First Use.  In this trust model, the first
1607   time a key is seen, it is memorized.  If later another key is seen
1608   with a user id with the same email address, a warning is displayed
1609   indicating that there is a conflict and that the key might be a
1610   forgery and an attempt at a man-in-the-middle attack.
1611
1612   Because a potential attacker is able to control the email address
1613   and thereby circumvent the conflict detection algorithm by using an
1614   email address that is similar in appearance to a trusted email
1615   address, whenever a message is verified, statistics about the number
1616   of messages signed with the key are shown.  In this way, a user can
1617   easily identify attacks using fake keys for regular correspondents.
1618
1619   When compared with the Web of Trust, TOFU offers significantly
1620   weaker security guarantees.  In particular, TOFU only helps ensure
1621   consistency (that is, that the binding between a key and email
1622   address doesn't change).  A major advantage of TOFU is that it
1623   requires little maintenance to use correctly.  To use the web of
1624   trust properly, you need to actively sign keys and mark users as
1625   trusted introducers.  This is a time-consuming process and anecdotal
1626   evidence suggests that even security-conscious users rarely take the
1627   time to do this thoroughly and instead rely on an ad-hoc TOFU
1628   process.
1629
1630   In the TOFU model, policies are associated with bindings between
1631   keys and email addresses (which are extracted from user ids and
1632   normalized).  There are five policies, which can be set manually
1633   using the @option{--tofu-policy} option.  The default policy can be
1634   set using the @option{--tofu-default-policy} option.
1635
1636   The TOFU policies are: @code{auto}, @code{good}, @code{unknown},
1637   @code{bad} and @code{ask}.  The @code{auto} policy is used by
1638   default (unless overridden by @option{--tofu-default-policy}) and
1639   marks a binding as marginally trusted.  The @code{good},
1640   @code{unknown} and @code{bad} policies mark a binding as fully
1641   trusted, as having unknown trust or as having trust never,
1642   respectively.  The @code{unknown} policy is useful for just using
1643   TOFU to detect conflicts, but to never assign positive trust to a
1644   binding.  The final policy, @code{ask} prompts the user to indicate
1645   the binding's trust.  If batch mode is enabled (or input is
1646   inappropriate in the context), then the user is not prompted and the
1647   @code{undefined} trust level is returned.
1648
1649   @item tofu+pgp
1650   @opindex trust-mode:tofu+pgp
1651   This trust model combines TOFU with the Web of Trust.  This is done
1652   by computing the trust level for each model and then taking the
1653   maximum trust level where the trust levels are ordered as follows:
1654   @code{unknown < undefined < marginal < fully < ultimate < expired <
1655   never}.
1656
1657   By setting @option{--tofu-default-policy=unknown}, this model can be
1658   used to implement the web of trust with TOFU's conflict detection
1659   algorithm, but without its assignment of positive trust values,
1660   which some security-conscious users don't like.
1661
1662   @item direct
1663   @opindex trust-mode:direct
1664   Key validity is set directly by the user and not calculated via the
1665   Web of Trust.
1666
1667   @item always
1668   @opindex trust-mode:always
1669   Skip key validation and assume that used keys are always fully
1670   valid. You generally won't use this unless you are using some
1671   external validation scheme. This option also suppresses the
1672   "[uncertain]" tag printed with signature checks when there is no
1673   evidence that the user ID is bound to the key.  Note that this
1674   trust model still does not allow the use of expired, revoked, or
1675   disabled keys.
1676
1677   @item auto
1678   @opindex trust-mode:auto
1679   Select the trust model depending on whatever the internal trust
1680   database says. This is the default model if such a database already
1681   exists.
1682 @end table
1683
1684 @item --auto-key-locate @code{parameters}
1685 @itemx --no-auto-key-locate
1686 @opindex auto-key-locate
1687 GnuPG can automatically locate and retrieve keys as needed using this
1688 option. This happens when encrypting to an email address (in the
1689 "user@@example.com" form), and there are no user@@example.com keys on
1690 the local keyring.  This option takes any number of the following
1691 mechanisms, in the order they are to be tried:
1692
1693 @table @asis
1694
1695   @item cert
1696   Locate a key using DNS CERT, as specified in RFC-4398.
1697
1698   @item pka
1699   Locate a key using DNS PKA.
1700
1701   @item dane
1702   Locate a key using DANE, as specified
1703   in draft-ietf-dane-openpgpkey-05.txt.
1704
1705   @item wkd
1706   Locate a key using the Web Key Directory protocol.
1707   This is an experimental method and semantics may change.
1708
1709   @item ldap
1710   Using DNS Service Discovery, check the domain in question for any LDAP
1711   keyservers to use.  If this fails, attempt to locate the key using the
1712   PGP Universal method of checking @samp{ldap://keys.(thedomain)}.
1713
1714   @item keyserver
1715   Locate a key using whatever keyserver is defined using the
1716   @option{--keyserver} option.
1717
1718   @item keyserver-URL
1719   In addition, a keyserver URL as used in the @option{--keyserver} option
1720   may be used here to query that particular keyserver.
1721
1722   @item local
1723   Locate the key using the local keyrings.  This mechanism allows the user to
1724   select the order a local key lookup is done.  Thus using
1725   @samp{--auto-key-locate local} is identical to
1726   @option{--no-auto-key-locate}.
1727
1728   @item nodefault
1729   This flag disables the standard local key lookup, done before any of the
1730   mechanisms defined by the @option{--auto-key-locate} are tried.  The
1731   position of this mechanism in the list does not matter.  It is not
1732   required if @code{local} is also used.
1733
1734   @item clear
1735   Clear all defined mechanisms.  This is useful to override
1736   mechanisms given in a config file.
1737
1738 @end table
1739
1740 @item --auto-key-retrieve
1741 @itemx --no-auto-key-retrieve
1742 @opindex auto-key-retrieve
1743 @opindex no-auto-key-retrieve
1744 This option enables the automatic retrieving of keys from a keyserver
1745 when verifying signatures made by keys that are not on the local
1746 keyring.
1747
1748 If the method "wkd" is included in the list of methods given to
1749 @option{auto-key-locate}, the Signer's User ID is part of the
1750 signature, and the option @option{--disable-signer-uid} is not used,
1751 the "wkd" method may also be used to retrieve a key.
1752
1753 Note that this option makes a "web bug" like behavior possible.
1754 Keyserver or Web Key Directory operators can see which keys you
1755 request, so by sending you a message signed by a brand new key (which
1756 you naturally will not have on your local keyring), the operator can
1757 tell both your IP address and the time when you verified the
1758 signature.
1759
1760 @item --keyid-format @code{none|short|0xshort|long|0xlong}
1761 @opindex keyid-format
1762 Select how to display key IDs.  "none" does not show the key ID at all
1763 but shows the fingerprint in a separate line.  "short" is the
1764 traditional 8-character key ID.  "long" is the more accurate (but less
1765 convenient) 16-character key ID.  Add an "0x" to either to include an
1766 "0x" at the beginning of the key ID, as in 0x99242560.  Note that this
1767 option is ignored if the option @option{--with-colons} is used.
1768
1769 @item --keyserver @code{name}
1770 @opindex keyserver
1771 This option is deprecated - please use the @option{--keyserver} in
1772 @file{dirmngr.conf} instead.
1773
1774 Use @code{name} as your keyserver. This is the server that
1775 @option{--receive-keys}, @option{--send-keys}, and @option{--search-keys}
1776 will communicate with to receive keys from, send keys to, and search for
1777 keys on. The format of the @code{name} is a URI:
1778 `scheme:[//]keyservername[:port]' The scheme is the type of keyserver:
1779 "hkp" for the HTTP (or compatible) keyservers, "ldap" for the LDAP
1780 keyservers, or "mailto" for the Graff email keyserver. Note that your
1781 particular installation of GnuPG may have other keyserver types
1782 available as well. Keyserver schemes are case-insensitive. After the
1783 keyserver name, optional keyserver configuration options may be
1784 provided. These are the same as the global @option{--keyserver-options}
1785 from below, but apply only to this particular keyserver.
1786
1787 Most keyservers synchronize with each other, so there is generally no
1788 need to send keys to more than one server. The keyserver
1789 @code{hkp://keys.gnupg.net} uses round robin DNS to give a different
1790 keyserver each time you use it.
1791
1792 @item --keyserver-options @code{name=value}
1793 @opindex keyserver-options
1794 This is a space or comma delimited string that gives options for the
1795 keyserver. Options can be prefixed with a `no-' to give the opposite
1796 meaning. Valid import-options or export-options may be used here as
1797 well to apply to importing (@option{--recv-key}) or exporting
1798 (@option{--send-key}) a key from a keyserver. While not all options
1799 are available for all keyserver types, some common options are:
1800
1801 @table @asis
1802
1803   @item include-revoked
1804   When searching for a key with @option{--search-keys}, include keys that
1805   are marked on the keyserver as revoked. Note that not all keyservers
1806   differentiate between revoked and unrevoked keys, and for such
1807   keyservers this option is meaningless. Note also that most keyservers do
1808   not have cryptographic verification of key revocations, and so turning
1809   this option off may result in skipping keys that are incorrectly marked
1810   as revoked.
1811
1812   @item include-disabled
1813   When searching for a key with @option{--search-keys}, include keys that
1814   are marked on the keyserver as disabled. Note that this option is not
1815   used with HKP keyservers.
1816
1817   @item auto-key-retrieve
1818   This is the same as the option @option{auto-key-retrieve}.
1819
1820   @item honor-keyserver-url
1821   When using @option{--refresh-keys}, if the key in question has a preferred
1822   keyserver URL, then use that preferred keyserver to refresh the key
1823   from. In addition, if auto-key-retrieve is set, and the signature
1824   being verified has a preferred keyserver URL, then use that preferred
1825   keyserver to fetch the key from. Note that this option introduces a
1826   "web bug": The creator of the key can see when the keys is
1827   refreshed.  Thus this option is not enabled by default.
1828
1829   @item honor-pka-record
1830   If @option{--auto-key-retrieve} is used, and the signature being
1831   verified has a PKA record, then use the PKA information to fetch
1832   the key. Defaults to "yes".
1833
1834   @item include-subkeys
1835   When receiving a key, include subkeys as potential targets. Note that
1836   this option is not used with HKP keyservers, as they do not support
1837   retrieving keys by subkey id.
1838
1839   @item timeout
1840   Tell the keyserver helper program how long (in seconds) to try and
1841   perform a keyserver action before giving up. Note that performing
1842   multiple actions at the same time uses this timeout value per action.
1843   For example, when retrieving multiple keys via @option{--receive-keys}, the
1844   timeout applies separately to each key retrieval, and not to the
1845   @option{--receive-keys} command as a whole. Defaults to 30 seconds.
1846
1847   @item http-proxy=@code{value}
1848   This option is deprecated.
1849   Set the proxy to use for HTTP and HKP keyservers.
1850   This overrides any proxy defined in @file{dirmngr.conf}.
1851
1852   @item verbose
1853   This option has no more function since GnuPG 2.1.  Use the
1854   @code{dirmngr} configuration options instead.
1855
1856   @item debug
1857   This option has no more function since GnuPG 2.1.  Use the
1858   @code{dirmngr} configuration options instead.
1859
1860   @item check-cert
1861   This option has no more function since GnuPG 2.1.  Use the
1862   @code{dirmngr} configuration options instead.
1863
1864   @item ca-cert-file
1865   This option has no more function since GnuPG 2.1.  Use the
1866   @code{dirmngr} configuration options instead.
1867
1868 @end table
1869
1870 @item --completes-needed @code{n}
1871 @opindex compliant-needed
1872 Number of completely trusted users to introduce a new
1873 key signer (defaults to 1).
1874
1875 @item --marginals-needed @code{n}
1876 @opindex marginals-needed
1877 Number of marginally trusted users to introduce a new
1878 key signer (defaults to 3)
1879
1880 @item --tofu-default-policy @code{auto|good|unknown|bad|ask}
1881 @opindex tofu-default-policy
1882 The default TOFU policy (defaults to @code{auto}).  For more
1883 information about the meaning of this option, @pxref{trust-model-tofu}.
1884
1885 @item --max-cert-depth @code{n}
1886 @opindex max-cert-depth
1887 Maximum depth of a certification chain (default is 5).
1888
1889 @item --no-sig-cache
1890 @opindex no-sig-cache
1891 Do not cache the verification status of key signatures.
1892 Caching gives a much better performance in key listings. However, if
1893 you suspect that your public keyring is not safe against write
1894 modifications, you can use this option to disable the caching. It
1895 probably does not make sense to disable it because all kind of damage
1896 can be done if someone else has write access to your public keyring.
1897
1898 @item --auto-check-trustdb
1899 @itemx --no-auto-check-trustdb
1900 @opindex auto-check-trustdb
1901 If GnuPG feels that its information about the Web of Trust has to be
1902 updated, it automatically runs the @option{--check-trustdb} command
1903 internally.  This may be a time consuming
1904 process. @option{--no-auto-check-trustdb} disables this option.
1905
1906 @item --use-agent
1907 @itemx --no-use-agent
1908 @opindex use-agent
1909 This is dummy option. @command{@gpgname} always requires the agent.
1910
1911 @item --gpg-agent-info
1912 @opindex gpg-agent-info
1913 This is dummy option. It has no effect when used with @command{@gpgname}.
1914
1915
1916 @item --agent-program @var{file}
1917 @opindex agent-program
1918 Specify an agent program to be used for secret key operations.  The
1919 default value is determined by running @command{gpgconf} with the
1920 option @option{--list-dirs}.  Note that the pipe symbol (@code{|}) is
1921 used for a regression test suite hack and may thus not be used in the
1922 file name.
1923
1924 @item --dirmngr-program @var{file}
1925 @opindex dirmngr-program
1926 Specify a dirmngr program to be used for keyserver access.  The
1927 default value is @file{@value{BINDIR}/dirmngr}.
1928
1929 @item --no-autostart
1930 @opindex no-autostart
1931 Do not start the gpg-agent or the dirmngr if it has not yet been
1932 started and its service is required.  This option is mostly useful on
1933 machines where the connection to gpg-agent has been redirected to
1934 another machines.  If dirmngr is required on the remote machine, it
1935 may be started manually using @command{gpgconf --launch dirmngr}.
1936
1937 @item --lock-once
1938 @opindex lock-once
1939 Lock the databases the first time a lock is requested
1940 and do not release the lock until the process
1941 terminates.
1942
1943 @item --lock-multiple
1944 @opindex lock-multiple
1945 Release the locks every time a lock is no longer
1946 needed. Use this to override a previous @option{--lock-once}
1947 from a config file.
1948
1949 @item --lock-never
1950 @opindex lock-never
1951 Disable locking entirely. This option should be used only in very
1952 special environments, where it can be assured that only one process
1953 is accessing those files. A bootable floppy with a stand-alone
1954 encryption system will probably use this. Improper usage of this
1955 option may lead to data and key corruption.
1956
1957 @item --exit-on-status-write-error
1958 @opindex exit-on-status-write-error
1959 This option will cause write errors on the status FD to immediately
1960 terminate the process. That should in fact be the default but it never
1961 worked this way and thus we need an option to enable this, so that the
1962 change won't break applications which close their end of a status fd
1963 connected pipe too early. Using this option along with
1964 @option{--enable-progress-filter} may be used to cleanly cancel long
1965 running gpg operations.
1966
1967 @item --limit-card-insert-tries @code{n}
1968 @opindex limit-card-insert-tries
1969 With @code{n} greater than 0 the number of prompts asking to insert a
1970 smartcard gets limited to N-1. Thus with a value of 1 gpg won't at
1971 all ask to insert a card if none has been inserted at startup. This
1972 option is useful in the configuration file in case an application does
1973 not know about the smartcard support and waits ad infinitum for an
1974 inserted card.
1975
1976 @item --no-random-seed-file
1977 @opindex no-random-seed-file
1978 GnuPG uses a file to store its internal random pool over invocations.
1979 This makes random generation faster; however sometimes write operations
1980 are not desired. This option can be used to achieve that with the cost of
1981 slower random generation.
1982
1983 @item --no-greeting
1984 @opindex no-greeting
1985 Suppress the initial copyright message.
1986
1987 @item --no-secmem-warning
1988 @opindex no-secmem-warning
1989 Suppress the warning about "using insecure memory".
1990
1991 @item --no-permission-warning
1992 @opindex permission-warning
1993 Suppress the warning about unsafe file and home directory (@option{--homedir})
1994 permissions. Note that the permission checks that GnuPG performs are
1995 not intended to be authoritative, but rather they simply warn about
1996 certain common permission problems. Do not assume that the lack of a
1997 warning means that your system is secure.
1998
1999 Note that the warning for unsafe @option{--homedir} permissions cannot be
2000 suppressed in the gpg.conf file, as this would allow an attacker to
2001 place an unsafe gpg.conf file in place, and use this file to suppress
2002 warnings about itself. The @option{--homedir} permissions warning may only be
2003 suppressed on the command line.
2004
2005 @item --no-mdc-warning
2006 @opindex no-mdc-warning
2007 Suppress the warning about missing MDC integrity protection.
2008
2009 @item --require-secmem
2010 @itemx --no-require-secmem
2011 @opindex require-secmem
2012 Refuse to run if GnuPG cannot get secure memory. Defaults to no
2013 (i.e. run, but give a warning).
2014
2015
2016 @item --require-cross-certification
2017 @itemx --no-require-cross-certification
2018 @opindex require-cross-certification
2019 When verifying a signature made from a subkey, ensure that the cross
2020 certification "back signature" on the subkey is present and valid.  This
2021 protects against a subtle attack against subkeys that can sign.
2022 Defaults to @option{--require-cross-certification} for
2023 @command{@gpgname}.
2024
2025 @item --expert
2026 @itemx --no-expert
2027 @opindex expert
2028 Allow the user to do certain nonsensical or "silly" things like
2029 signing an expired or revoked key, or certain potentially incompatible
2030 things like generating unusual key types. This also disables certain
2031 warning messages about potentially incompatible actions. As the name
2032 implies, this option is for experts only. If you don't fully
2033 understand the implications of what it allows you to do, leave this
2034 off. @option{--no-expert} disables this option.
2035
2036 @end table
2037
2038
2039 @c *******************************************
2040 @c ********  KEY RELATED OPTIONS  ************
2041 @c *******************************************
2042 @node GPG Key related Options
2043 @subsection Key related options
2044
2045 @table @gnupgtabopt
2046
2047 @item --recipient @var{name}
2048 @itemx -r
2049 @opindex recipient
2050 Encrypt for user id @var{name}. If this option or
2051 @option{--hidden-recipient} is not specified, GnuPG asks for the user-id
2052 unless @option{--default-recipient} is given.
2053
2054 @item --hidden-recipient @var{name}
2055 @itemx -R
2056 @opindex hidden-recipient
2057 Encrypt for user ID @var{name}, but hide the key ID of this user's
2058 key. This option helps to hide the receiver of the message and is a
2059 limited countermeasure against traffic analysis. If this option or
2060 @option{--recipient} is not specified, GnuPG asks for the user ID unless
2061 @option{--default-recipient} is given.
2062
2063 @item --recipient-file @var{file}
2064 @itemx -f
2065 @opindex recipient-file
2066 This option is similar to @option{--recipient} except that it
2067 encrypts to a key stored in the given file.  @var{file} must be the
2068 name of a file containing exactly one key.  @command{@gpgname} assumes that
2069 the key in this file is fully valid.
2070
2071 @item --hidden-recipient-file @var{file}
2072 @itemx -F
2073 @opindex hidden-recipient-file
2074 This option is similar to @option{--hidden-recipient} except that it
2075 encrypts to a key stored in the given file.  @var{file} must be the
2076 name of a file containing exactly one key.  @command{@gpgname} assumes that
2077 the key in this file is fully valid.
2078
2079 @item --encrypt-to @code{name}
2080 @opindex encrypt-to
2081 Same as @option{--recipient} but this one is intended for use in the
2082 options file and may be used with your own user-id as an
2083 "encrypt-to-self". These keys are only used when there are other
2084 recipients given either by use of @option{--recipient} or by the asked
2085 user id.  No trust checking is performed for these user ids and even
2086 disabled keys can be used.
2087
2088 @item --hidden-encrypt-to @code{name}
2089 @opindex hidden-encrypt-to
2090 Same as @option{--hidden-recipient} but this one is intended for use in the
2091 options file and may be used with your own user-id as a hidden
2092 "encrypt-to-self". These keys are only used when there are other
2093 recipients given either by use of @option{--recipient} or by the asked user id.
2094 No trust checking is performed for these user ids and even disabled
2095 keys can be used.
2096
2097 @item --no-encrypt-to
2098 @opindex no-encrypt-to
2099 Disable the use of all @option{--encrypt-to} and
2100 @option{--hidden-encrypt-to} keys.
2101
2102 @item --group @code{name=value}
2103 @opindex group
2104 Sets up a named group, which is similar to aliases in email programs.
2105 Any time the group name is a recipient (@option{-r} or
2106 @option{--recipient}), it will be expanded to the values
2107 specified. Multiple groups with the same name are automatically merged
2108 into a single group.
2109
2110 The values are @code{key IDs} or fingerprints, but any key description
2111 is accepted. Note that a value with spaces in it will be treated as
2112 two different values. Note also there is only one level of expansion
2113 --- you cannot make an group that points to another group. When used
2114 from the command line, it may be necessary to quote the argument to
2115 this option to prevent the shell from treating it as multiple
2116 arguments.
2117
2118 @item --ungroup @code{name}
2119 @opindex ungroup
2120 Remove a given entry from the @option{--group} list.
2121
2122 @item --no-groups
2123 @opindex no-groups
2124 Remove all entries from the @option{--group} list.
2125
2126 @item --local-user @var{name}
2127 @itemx -u
2128 @opindex local-user
2129 Use @var{name} as the key to sign with. Note that this option overrides
2130 @option{--default-key}.
2131
2132 @item --sender @var{mbox}
2133 @opindex sender
2134 This option has two purposes.  @var{mbox} must either be a complete
2135 user id with a proper mail address or just a mail address.  When
2136 creating a signature this option tells gpg the user id of a key used
2137 to make a signature if the key was not directly specified by a user
2138 id.  When verifying a signature the @var{mbox} is used to restrict the
2139 information printed by the TOFU code to matching user ids.
2140
2141 @item --try-secret-key @var{name}
2142 @opindex try-secret-key
2143 For hidden recipients GPG needs to know the keys to use for trial
2144 decryption.  The key set with @option{--default-key} is always tried
2145 first, but this is often not sufficient.  This option allows setting more
2146 keys to be used for trial decryption.  Although any valid user-id
2147 specification may be used for @var{name} it makes sense to use at least
2148 the long keyid to avoid ambiguities.  Note that gpg-agent might pop up a
2149 pinentry for a lot keys to do the trial decryption.  If you want to stop
2150 all further trial decryption you may use close-window button instead of
2151 the cancel button.
2152
2153 @item --try-all-secrets
2154 @opindex try-all-secrets
2155 Don't look at the key ID as stored in the message but try all secret
2156 keys in turn to find the right decryption key. This option forces the
2157 behaviour as used by anonymous recipients (created by using
2158 @option{--throw-keyids} or @option{--hidden-recipient}) and might come
2159 handy in case where an encrypted message contains a bogus key ID.
2160
2161 @item --skip-hidden-recipients
2162 @itemx --no-skip-hidden-recipients
2163 @opindex skip-hidden-recipients
2164 @opindex no-skip-hidden-recipients
2165 During decryption skip all anonymous recipients.  This option helps in
2166 the case that people use the hidden recipients feature to hide there
2167 own encrypt-to key from others.  If oneself has many secret keys this
2168 may lead to a major annoyance because all keys are tried in turn to
2169 decrypt something which was not really intended for it.  The drawback
2170 of this option is that it is currently not possible to decrypt a
2171 message which includes real anonymous recipients.
2172
2173
2174 @end table
2175
2176 @c *******************************************
2177 @c ********  INPUT AND OUTPUT  ***************
2178 @c *******************************************
2179 @node GPG Input and Output
2180 @subsection Input and Output
2181
2182 @table @gnupgtabopt
2183
2184 @item --armor
2185 @itemx -a
2186 @opindex armor
2187 Create ASCII armored output.  The default is to create the binary
2188 OpenPGP format.
2189
2190 @item --no-armor
2191 @opindex no-armor
2192 Assume the input data is not in ASCII armored format.
2193
2194 @item --output @var{file}
2195 @itemx -o @var{file}
2196 @opindex output
2197 Write output to @var{file}.  To write to stdout use @code{-} as the
2198 filename.
2199
2200 @item --max-output @code{n}
2201 @opindex max-output
2202 This option sets a limit on the number of bytes that will be generated
2203 when processing a file. Since OpenPGP supports various levels of
2204 compression, it is possible that the plaintext of a given message may be
2205 significantly larger than the original OpenPGP message. While GnuPG
2206 works properly with such messages, there is often a desire to set a
2207 maximum file size that will be generated before processing is forced to
2208 stop by the OS limits. Defaults to 0, which means "no limit".
2209
2210 @item --input-size-hint @var{n}
2211 @opindex input-size-hint
2212 This option can be used to tell GPG the size of the input data in
2213 bytes.  @var{n} must be a positive base-10 number.  This option is
2214 only useful if the input is not taken from a file.  GPG may use this
2215 hint to optimize its buffer allocation strategy.  It is also used by
2216 the @option{--status-fd} line ``PROGRESS'' to provide a value for
2217 ``total'' if that is not available by other means.
2218
2219 @item --import-options @code{parameters}
2220 @opindex import-options
2221 This is a space or comma delimited string that gives options for
2222 importing keys. Options can be prepended with a `no-' to give the
2223 opposite meaning. The options are:
2224
2225 @table @asis
2226
2227   @item import-local-sigs
2228   Allow importing key signatures marked as "local". This is not
2229   generally useful unless a shared keyring scheme is being used.
2230   Defaults to no.
2231
2232   @item keep-ownertrust
2233   Normally possible still existing ownertrust values of a key are
2234   cleared if a key is imported.  This is in general desirable so that
2235   a formerly deleted key does not automatically gain an ownertrust
2236   values merely due to import.  On the other hand it is sometimes
2237   necessary to re-import a trusted set of keys again but keeping
2238   already assigned ownertrust values.  This can be achieved by using
2239   this option.
2240
2241   @item repair-pks-subkey-bug
2242   During import, attempt to repair the damage caused by the PKS keyserver
2243   bug (pre version 0.9.6) that mangles keys with multiple subkeys. Note
2244   that this cannot completely repair the damaged key as some crucial data
2245   is removed by the keyserver, but it does at least give you back one
2246   subkey. Defaults to no for regular @option{--import} and to yes for
2247   keyserver @option{--receive-keys}.
2248
2249   @item import-show
2250   Show a listing of the key as imported right before it is stored.
2251   This can be combined with the option @option{--dry-run} to only look
2252   at keys.
2253
2254   @item import-export
2255   Run the entire import code but instead of storing the key to the
2256   local keyring write it to the output.  The export options
2257   @option{export-pka} and @option{export-dane} affect the output.  This
2258   option can be used to remove all invalid parts from a key without the
2259   need to store it.
2260
2261   @item merge-only
2262   During import, allow key updates to existing keys, but do not allow
2263   any new keys to be imported. Defaults to no.
2264
2265   @item import-clean
2266   After import, compact (remove all signatures except the
2267   self-signature) any user IDs from the new key that are not usable.
2268   Then, remove any signatures from the new key that are not usable.
2269   This includes signatures that were issued by keys that are not present
2270   on the keyring. This option is the same as running the @option{--edit-key}
2271   command "clean" after import. Defaults to no.
2272
2273   @item import-minimal
2274   Import the smallest key possible. This removes all signatures except
2275   the most recent self-signature on each user ID. This option is the
2276   same as running the @option{--edit-key} command "minimize" after import.
2277   Defaults to no.
2278 @end table
2279
2280 @item --import-filter @code{@var{name}=@var{expr}}
2281 @itemx --export-filter @code{@var{name}=@var{expr}}
2282 @opindex import-filter
2283 @opindex export-filter
2284 These options define an import/export filter which are applied to the
2285 imported/exported keyblock right before it will be stored/written.
2286 @var{name} defines the type of filter to use, @var{expr} the
2287 expression to evaluate.  The option can be used several times which
2288 then appends more expression to the same @var{name}.
2289
2290 @noindent
2291 The available filter types are:
2292
2293 @table @asis
2294
2295   @item keep-uid
2296   This filter will keep a user id packet and its dependent packets in
2297   the keyblock if the expression evaluates to true.
2298
2299   @item drop-subkey
2300   This filter drops the selected subkeys.
2301   Currently only implemented for --export-filter.
2302
2303   @item drop-sig
2304   This filter drops the selected key signatures on user ids.
2305   Self-signatures are not considered.
2306   Currently only implemented for --import-filter.
2307
2308 @end table
2309
2310 For the syntax of the expression see the chapter "FILTER EXPRESSIONS".
2311 The property names for the expressions depend on the actual filter
2312 type and are indicated in the following table.
2313
2314 The available properties are:
2315
2316 @table @asis
2317
2318   @item uid
2319   A string with the user id.  (keep-uid)
2320
2321   @item mbox
2322   The addr-spec part of a user id with mailbox or the empty string.
2323   (keep-uid)
2324
2325   @item key_algo
2326   A number with the public key algorithm of a key or subkey packet.
2327   (drop-subkey)
2328
2329   @item key_created
2330   @itemx key_created_d
2331   The first is the timestamp a public key or subkey packet was
2332   created.  The second is the same but given as an ISO string,
2333   e.g. "2016-08-17". (drop-subkey)
2334
2335   @item primary
2336   Boolean indicating whether the user id is the primary one.  (keep-uid)
2337
2338   @item secret
2339   Boolean indicating whether a key or subkey is a secret one.
2340   drop-subkey)
2341
2342   @item sig_created
2343   @itemx sig_created_d
2344   The first is the timestamp a signature packet was created.  The
2345   second is the same but given as an ISO string,
2346   e.g. "2016-08-17". (drop-sig)
2347
2348   @item sig_algo
2349   A number with the public key algorithm of a signature packet. (drop-sig)
2350
2351   @item sig_digest_algo
2352   A number with the digest algorithm of a signature packet. (drop-sig)
2353
2354 @end table
2355
2356 @item --export-options @code{parameters}
2357 @opindex export-options
2358 This is a space or comma delimited string that gives options for
2359 exporting keys. Options can be prepended with a `no-' to give the
2360 opposite meaning. The options are:
2361
2362 @table @asis
2363
2364   @item export-local-sigs
2365   Allow exporting key signatures marked as "local". This is not
2366   generally useful unless a shared keyring scheme is being used.
2367   Defaults to no.
2368
2369   @item export-attributes
2370   Include attribute user IDs (photo IDs) while exporting. This is
2371   useful to export keys if they are going to be used by an OpenPGP
2372   program that does not accept attribute user IDs. Defaults to yes.
2373
2374   @item export-sensitive-revkeys
2375   Include designated revoker information that was marked as
2376   "sensitive". Defaults to no.
2377
2378   @c Since GnuPG 2.1 gpg-agent manages the secret key and thus the
2379   @c export-reset-subkey-passwd hack is not anymore justified.  Such use
2380   @c cases may be implemented using a specialized secret key export
2381   @c tool.
2382   @c @item export-reset-subkey-passwd
2383   @c When using the @option{--export-secret-subkeys} command, this option resets
2384   @c the passphrases for all exported subkeys to empty. This is useful
2385   @c when the exported subkey is to be used on an unattended machine where
2386   @c a passphrase doesn't necessarily make sense. Defaults to no.
2387
2388   @item export-clean
2389   Compact (remove all signatures from) user IDs on the key being
2390   exported if the user IDs are not usable. Also, do not export any
2391   signatures that are not usable. This includes signatures that were
2392   issued by keys that are not present on the keyring. This option is
2393   the same as running the @option{--edit-key} command "clean" before export
2394   except that the local copy of the key is not modified. Defaults to
2395   no.
2396
2397   @item export-minimal
2398   Export the smallest key possible. This removes all signatures except the
2399   most recent self-signature on each user ID. This option is the same as
2400   running the @option{--edit-key} command "minimize" before export except
2401   that the local copy of the key is not modified. Defaults to no.
2402
2403   @item export-pka
2404   Instead of outputting the key material output PKA records suitable
2405   to put into DNS zone files.  An ORIGIN line is printed before each
2406   record to allow diverting the records to the corresponding zone file.
2407
2408   @item export-dane
2409   Instead of outputting the key material output OpenPGP DANE records
2410   suitable to put into DNS zone files.  An ORIGIN line is printed before
2411   each record to allow diverting the records to the corresponding zone
2412   file.
2413
2414 @end table
2415
2416 @item --with-colons
2417 @opindex with-colons
2418 Print key listings delimited by colons. Note that the output will be
2419 encoded in UTF-8 regardless of any @option{--display-charset} setting. This
2420 format is useful when GnuPG is called from scripts and other programs
2421 as it is easily machine parsed. The details of this format are
2422 documented in the file @file{doc/DETAILS}, which is included in the GnuPG
2423 source distribution.
2424
2425 @item --fixed-list-mode
2426 @opindex fixed-list-mode
2427 Do not merge primary user ID and primary key in @option{--with-colon}
2428 listing mode and print all timestamps as seconds since 1970-01-01.
2429 Since GnuPG 2.0.10, this mode is always used and thus this option is
2430 obsolete; it does not harm to use it though.
2431
2432 @item --legacy-list-mode
2433 @opindex legacy-list-mode
2434 Revert to the pre-2.1 public key list mode.  This only affects the
2435 human readable output and not the machine interface
2436 (i.e. @code{--with-colons}).  Note that the legacy format does not
2437 convey suitable information for elliptic curves.
2438
2439 @item --with-fingerprint
2440 @opindex with-fingerprint
2441 Same as the command @option{--fingerprint} but changes only the format
2442 of the output and may be used together with another command.
2443
2444 @item --with-subkey-fingerprint
2445 @opindex with-subkey-fingerprint
2446 If a fingerprint is printed for the primary key, this option forces
2447 printing of the fingerprint for all subkeys.  This could also be
2448 achieved by using the @option{--with-fingerprint} twice but by using
2449 this option along with keyid-format "none" a compact fingerprint is
2450 printed.
2451
2452 @item --with-icao-spelling
2453 @opindex with-icao-spelling
2454 Print the ICAO spelling of the fingerprint in addition to the hex digits.
2455
2456 @item --with-keygrip
2457 @opindex with-keygrip
2458 Include the keygrip in the key listings.  In @code{--with-colons} mode
2459 this is implicitly enable for secret keys.
2460
2461 @item --with-wkd-hash
2462 @opindex with-wkd-hash
2463 Print a Web Key Directory identifier along with each user ID in key
2464 listings.  This is an experimental feature and semantics may change.
2465
2466 @item --with-secret
2467 @opindex with-secret
2468 Include info about the presence of a secret key in public key listings
2469 done with @code{--with-colons}.
2470
2471 @end table
2472
2473 @c *******************************************
2474 @c ********  OPENPGP OPTIONS  ****************
2475 @c *******************************************
2476 @node OpenPGP Options
2477 @subsection OpenPGP protocol specific options
2478
2479 @table @gnupgtabopt
2480
2481 @item -t, --textmode
2482 @itemx --no-textmode
2483 @opindex textmode
2484 Treat input files as text and store them in the OpenPGP canonical text
2485 form with standard "CRLF" line endings. This also sets the necessary
2486 flags to inform the recipient that the encrypted or signed data is text
2487 and may need its line endings converted back to whatever the local
2488 system uses. This option is useful when communicating between two
2489 platforms that have different line ending conventions (UNIX-like to Mac,
2490 Mac to Windows, etc). @option{--no-textmode} disables this option, and
2491 is the default.
2492
2493 @item --force-v3-sigs
2494 @itemx --no-force-v3-sigs
2495 @item --force-v4-certs
2496 @itemx --no-force-v4-certs
2497 These options are obsolete and have no effect since GnuPG 2.1.
2498
2499 @item --force-mdc
2500 @opindex force-mdc
2501 Force the use of encryption with a modification detection code. This
2502 is always used with the newer ciphers (those with a blocksize greater
2503 than 64 bits), or if all of the recipient keys indicate MDC support in
2504 their feature flags.
2505
2506 @item --disable-mdc
2507 @opindex disable-mdc
2508 Disable the use of the modification detection code. Note that by
2509 using this option, the encrypted message becomes vulnerable to a
2510 message modification attack.
2511
2512 @item --disable-signer-uid
2513 @opindex disable-signer-uid
2514 By default the user ID of the signing key is embedded in the data
2515 signature.  As of now this is only done if the signing key has been
2516 specified with @option{local-user} using a mail address.  This
2517 information can be helpful for verifier to locate the key; see
2518 option @option{--auto-key-retrieve}.
2519
2520 @item --personal-cipher-preferences @code{string}
2521 @opindex personal-cipher-preferences
2522 Set the list of personal cipher preferences to @code{string}.  Use
2523 @command{@gpgname --version} to get a list of available algorithms,
2524 and use @code{none} to set no preference at all.  This allows the user
2525 to safely override the algorithm chosen by the recipient key
2526 preferences, as GPG will only select an algorithm that is usable by
2527 all recipients.  The most highly ranked cipher in this list is also
2528 used for the @option{--symmetric} encryption command.
2529
2530 @item --personal-digest-preferences @code{string}
2531 @opindex personal-digest-preferences
2532 Set the list of personal digest preferences to @code{string}.  Use
2533 @command{@gpgname --version} to get a list of available algorithms,
2534 and use @code{none} to set no preference at all.  This allows the user
2535 to safely override the algorithm chosen by the recipient key
2536 preferences, as GPG will only select an algorithm that is usable by
2537 all recipients.  The most highly ranked digest algorithm in this list
2538 is also used when signing without encryption
2539 (e.g. @option{--clear-sign} or @option{--sign}).
2540
2541 @item --personal-compress-preferences @code{string}
2542 @opindex personal-compress-preferences
2543 Set the list of personal compression preferences to @code{string}.
2544 Use @command{@gpgname --version} to get a list of available
2545 algorithms, and use @code{none} to set no preference at all.  This
2546 allows the user to safely override the algorithm chosen by the
2547 recipient key preferences, as GPG will only select an algorithm that
2548 is usable by all recipients.  The most highly ranked compression
2549 algorithm in this list is also used when there are no recipient keys
2550 to consider (e.g. @option{--symmetric}).
2551
2552 @item --s2k-cipher-algo @code{name}
2553 @opindex s2k-cipher-algo
2554 Use @code{name} as the cipher algorithm for symmetric encryption with
2555 a passphrase if @option{--personal-cipher-preferences} and
2556 @option{--cipher-algo} are not given.  The default is @value{GPGSYMENCALGO}.
2557
2558 @item --s2k-digest-algo @code{name}
2559 @opindex s2k-digest-algo
2560 Use @code{name} as the digest algorithm used to mangle the passphrases
2561 for symmetric encryption.  The default is SHA-1.
2562
2563 @item --s2k-mode @code{n}
2564 @opindex s2k-mode
2565 Selects how passphrases for symmetric encryption are mangled. If
2566 @code{n} is 0 a plain passphrase (which is in general not recommended)
2567 will be used, a 1 adds a salt (which should not be used) to the
2568 passphrase and a 3 (the default) iterates the whole process a number
2569 of times (see @option{--s2k-count}).
2570
2571 @item --s2k-count @code{n}
2572 @opindex s2k-count
2573 Specify how many times the passphrases mangling for symmetric
2574 encryption is repeated.  This value may range between 1024 and
2575 65011712 inclusive.  The default is inquired from gpg-agent.  Note
2576 that not all values in the 1024-65011712 range are legal and if an
2577 illegal value is selected, GnuPG will round up to the nearest legal
2578 value.  This option is only meaningful if @option{--s2k-mode} is set
2579 to the default of 3.
2580
2581
2582 @end table
2583
2584 @c ***************************
2585 @c ******* Compliance ********
2586 @c ***************************
2587 @node Compliance Options
2588 @subsection Compliance options
2589
2590 These options control what GnuPG is compliant to. Only one of these
2591 options may be active at a time. Note that the default setting of
2592 this is nearly always the correct one. See the INTEROPERABILITY WITH
2593 OTHER OPENPGP PROGRAMS section below before using one of these
2594 options.
2595
2596 @table @gnupgtabopt
2597
2598 @item --gnupg
2599 @opindex gnupg
2600 Use standard GnuPG behavior. This is essentially OpenPGP behavior
2601 (see @option{--openpgp}), but with some additional workarounds for common
2602 compatibility problems in different versions of PGP. This is the
2603 default option, so it is not generally needed, but it may be useful to
2604 override a different compliance option in the gpg.conf file.
2605
2606 @item --openpgp
2607 @opindex openpgp
2608 Reset all packet, cipher and digest options to strict OpenPGP
2609 behavior. Use this option to reset all previous options like
2610 @option{--s2k-*}, @option{--cipher-algo}, @option{--digest-algo} and
2611 @option{--compress-algo} to OpenPGP compliant values. All PGP
2612 workarounds are disabled.
2613
2614 @item --rfc4880
2615 @opindex rfc4880
2616 Reset all packet, cipher and digest options to strict RFC-4880
2617 behavior. Note that this is currently the same thing as
2618 @option{--openpgp}.
2619
2620 @item --rfc4880bis
2621 @opindex rfc4880bis
2622 Enable experimental features from proposed updates to RFC-4880.  This
2623 option can be used in addition to the other compliance options.
2624 Warning: The behavior may change with any GnuPG release and created
2625 keys or data may not be usable with future GnuPG versions.
2626
2627 @item --rfc2440
2628 @opindex rfc2440
2629 Reset all packet, cipher and digest options to strict RFC-2440
2630 behavior.
2631
2632 @item --pgp6
2633 @opindex pgp6
2634 Set up all options to be as PGP 6 compliant as possible. This
2635 restricts you to the ciphers IDEA (if the IDEA plugin is installed),
2636 3DES, and CAST5, the hashes MD5, SHA1 and RIPEMD160, and the
2637 compression algorithms none and ZIP. This also disables
2638 @option{--throw-keyids}, and making signatures with signing subkeys as PGP 6
2639 does not understand signatures made by signing subkeys.
2640
2641 This option implies @option{--disable-mdc --escape-from-lines}.
2642
2643 @item --pgp7
2644 @opindex pgp7
2645 Set up all options to be as PGP 7 compliant as possible. This is
2646 identical to @option{--pgp6} except that MDCs are not disabled, and the
2647 list of allowable ciphers is expanded to add AES128, AES192, AES256, and
2648 TWOFISH.
2649
2650 @item --pgp8
2651 @opindex pgp8
2652 Set up all options to be as PGP 8 compliant as possible. PGP 8 is a lot
2653 closer to the OpenPGP standard than previous versions of PGP, so all
2654 this does is disable @option{--throw-keyids} and set
2655 @option{--escape-from-lines}.  All algorithms are allowed except for the
2656 SHA224, SHA384, and SHA512 digests.
2657
2658 @item --compliance @var{string}
2659 @opindex compliance
2660 This option can be used instead of one of the options above.  Valid
2661 values for @var{string} are the above option names (without the double
2662 dash) and possibly others as shown when using "help" for @var{value}.
2663
2664 @end table
2665
2666
2667 @c *******************************************
2668 @c ********  ESOTERIC OPTIONS  ***************
2669 @c *******************************************
2670 @node GPG Esoteric Options
2671 @subsection Doing things one usually doesn't want to do
2672
2673 @table @gnupgtabopt
2674
2675 @item -n
2676 @itemx --dry-run
2677 @opindex dry-run
2678 Don't make any changes (this is not completely implemented).
2679
2680 @item --list-only
2681 @opindex list-only
2682 Changes the behaviour of some commands. This is like @option{--dry-run} but
2683 different in some cases. The semantic of this option may be extended in
2684 the future. Currently it only skips the actual decryption pass and
2685 therefore enables a fast listing of the encryption keys.
2686
2687 @item -i
2688 @itemx --interactive
2689 @opindex interactive
2690 Prompt before overwriting any files.
2691
2692 @item --debug-level @var{level}
2693 @opindex debug-level
2694 Select the debug level for investigating problems. @var{level} may be
2695 a numeric value or by a keyword:
2696
2697 @table @code
2698   @item none
2699   No debugging at all.  A value of less than 1 may be used instead of
2700   the keyword.
2701   @item basic
2702   Some basic debug messages.  A value between 1 and 2 may be used
2703   instead of the keyword.
2704   @item advanced
2705   More verbose debug messages.  A value between 3 and 5 may be used
2706   instead of the keyword.
2707   @item expert
2708   Even more detailed messages.  A value between 6 and 8 may be used
2709   instead of the keyword.
2710   @item guru
2711   All of the debug messages you can get. A value greater than 8 may be
2712   used instead of the keyword.  The creation of hash tracing files is
2713   only enabled if the keyword is used.
2714 @end table
2715
2716 How these messages are mapped to the actual debugging flags is not
2717 specified and may change with newer releases of this program. They are
2718 however carefully selected to best aid in debugging.
2719
2720 @item --debug @var{flags}
2721 @opindex debug
2722 Set debugging flags. All flags are or-ed and @var{flags} may be given
2723 in C syntax (e.g. 0x0042) or as a comma separated list of flag names.
2724 To get a list of all supported flags the single word "help" can be
2725 used.
2726
2727 @item --debug-all
2728 @opindex debug-all
2729 Set all useful debugging flags.
2730
2731 @item --debug-iolbf
2732 @opindex debug-iolbf
2733 Set stdout into line buffered mode.  This option is only honored when
2734 given on the command line.
2735
2736 @item --faked-system-time @var{epoch}
2737 @opindex faked-system-time
2738 This option is only useful for testing; it sets the system time back or
2739 forth to @var{epoch} which is the number of seconds elapsed since the year
2740 1970.  Alternatively @var{epoch} may be given as a full ISO time string
2741 (e.g. "20070924T154812").
2742
2743 @item --enable-progress-filter
2744 @opindex enable-progress-filter
2745 Enable certain PROGRESS status outputs. This option allows frontends
2746 to display a progress indicator while gpg is processing larger files.
2747 There is a slight performance overhead using it.
2748
2749 @item --status-fd @code{n}
2750 @opindex status-fd
2751 Write special status strings to the file descriptor @code{n}.
2752 See the file DETAILS in the documentation for a listing of them.
2753
2754 @item --status-file @code{file}
2755 @opindex status-file
2756 Same as @option{--status-fd}, except the status data is written to file
2757 @code{file}.
2758
2759 @item --logger-fd @code{n}
2760 @opindex logger-fd
2761 Write log output to file descriptor @code{n} and not to STDERR.
2762
2763 @item --log-file @code{file}
2764 @itemx --logger-file @code{file}
2765 @opindex log-file
2766 Same as @option{--logger-fd}, except the logger data is written to
2767 file @code{file}.  Use @file{socket://} to log to socket.
2768
2769 @item --attribute-fd @code{n}
2770 @opindex attribute-fd
2771 Write attribute subpackets to the file descriptor @code{n}. This is most
2772 useful for use with @option{--status-fd}, since the status messages are
2773 needed to separate out the various subpackets from the stream delivered
2774 to the file descriptor.
2775
2776 @item --attribute-file @code{file}
2777 @opindex attribute-file
2778 Same as @option{--attribute-fd}, except the attribute data is written to
2779 file @code{file}.
2780
2781 @item --comment @code{string}
2782 @itemx --no-comments
2783 @opindex comment
2784 Use @code{string} as a comment string in cleartext signatures and ASCII
2785 armored messages or keys (see @option{--armor}). The default behavior is
2786 not to use a comment string. @option{--comment} may be repeated multiple
2787 times to get multiple comment strings. @option{--no-comments} removes
2788 all comments.  It is a good idea to keep the length of a single comment
2789 below 60 characters to avoid problems with mail programs wrapping such
2790 lines.  Note that comment lines, like all other header lines, are not
2791 protected by the signature.
2792
2793 @item --emit-version
2794 @itemx --no-emit-version
2795 @opindex emit-version
2796 Force inclusion of the version string in ASCII armored output.  If
2797 given once only the name of the program and the major number is
2798 emitted, given twice the minor is also emitted, given thrice
2799 the micro is added, and given four times an operating system identification
2800 is also emitted.  @option{--no-emit-version} (default) disables the version
2801 line.
2802
2803 @item --sig-notation @code{name=value}
2804 @itemx --cert-notation @code{name=value}
2805 @itemx -N, --set-notation @code{name=value}
2806 @opindex sig-notation
2807 @opindex cert-notation
2808 @opindex set-notation
2809 Put the name value pair into the signature as notation data.
2810 @code{name} must consist only of printable characters or spaces, and
2811 must contain a '@@' character in the form keyname@@domain.example.com
2812 (substituting the appropriate keyname and domain name, of course).  This
2813 is to help prevent pollution of the IETF reserved notation
2814 namespace. The @option{--expert} flag overrides the '@@'
2815 check. @code{value} may be any printable string; it will be encoded in
2816 UTF-8, so you should check that your @option{--display-charset} is set
2817 correctly. If you prefix @code{name} with an exclamation mark (!), the
2818 notation data will be flagged as critical
2819 (rfc4880:5.2.3.16). @option{--sig-notation} sets a notation for data
2820 signatures. @option{--cert-notation} sets a notation for key signatures
2821 (certifications). @option{--set-notation} sets both.
2822
2823 There are special codes that may be used in notation names. "%k" will
2824 be expanded into the key ID of the key being signed, "%K" into the
2825 long key ID of the key being signed, "%f" into the fingerprint of the
2826 key being signed, "%s" into the key ID of the key making the
2827 signature, "%S" into the long key ID of the key making the signature,
2828 "%g" into the fingerprint of the key making the signature (which might
2829 be a subkey), "%p" into the fingerprint of the primary key of the key
2830 making the signature, "%c" into the signature count from the OpenPGP
2831 smartcard, and "%%" results in a single "%". %k, %K, and %f are only
2832 meaningful when making a key signature (certification), and %c is only
2833 meaningful when using the OpenPGP smartcard.
2834
2835 @item --sig-policy-url @code{string}
2836 @itemx --cert-policy-url @code{string}
2837 @itemx --set-policy-url @code{string}
2838 @opindex sig-policy-url
2839 @opindex cert-policy-url
2840 @opindex set-policy-url
2841 Use @code{string} as a Policy URL for signatures (rfc4880:5.2.3.20).  If
2842 you prefix it with an exclamation mark (!), the policy URL packet will
2843 be flagged as critical. @option{--sig-policy-url} sets a policy url for
2844 data signatures. @option{--cert-policy-url} sets a policy url for key
2845 signatures (certifications). @option{--set-policy-url} sets both.
2846
2847 The same %-expandos used for notation data are available here as well.
2848
2849 @item --sig-keyserver-url @code{string}
2850 @opindex sig-keyserver-url
2851 Use @code{string} as a preferred keyserver URL for data signatures. If
2852 you prefix it with an exclamation mark (!), the keyserver URL packet
2853 will be flagged as critical.
2854
2855 The same %-expandos used for notation data are available here as well.
2856
2857 @item --set-filename @code{string}
2858 @opindex set-filename
2859 Use @code{string} as the filename which is stored inside messages.
2860 This overrides the default, which is to use the actual filename of the
2861 file being encrypted.  Using the empty string for @code{string}
2862 effectively removes the filename from the output.
2863
2864 @item --for-your-eyes-only
2865 @itemx --no-for-your-eyes-only
2866 @opindex for-your-eyes-only
2867 Set the `for your eyes only' flag in the message. This causes GnuPG to
2868 refuse to save the file unless the @option{--output} option is given,
2869 and PGP to use a "secure viewer" with a claimed Tempest-resistant font
2870 to display the message. This option overrides @option{--set-filename}.
2871 @option{--no-for-your-eyes-only} disables this option.
2872
2873 @item --use-embedded-filename
2874 @itemx --no-use-embedded-filename
2875 @opindex use-embedded-filename
2876 Try to create a file with a name as embedded in the data. This can be
2877 a dangerous option as it enables overwriting files. Defaults to no.
2878
2879 @item --cipher-algo @code{name}
2880 @opindex cipher-algo
2881 Use @code{name} as cipher algorithm. Running the program with the
2882 command @option{--version} yields a list of supported algorithms. If
2883 this is not used the cipher algorithm is selected from the preferences
2884 stored with the key. In general, you do not want to use this option as
2885 it allows you to violate the OpenPGP standard.
2886 @option{--personal-cipher-preferences} is the safe way to accomplish the
2887 same thing.
2888
2889 @item --digest-algo @code{name}
2890 @opindex digest-algo
2891 Use @code{name} as the message digest algorithm. Running the program
2892 with the command @option{--version} yields a list of supported algorithms. In
2893 general, you do not want to use this option as it allows you to
2894 violate the OpenPGP standard. @option{--personal-digest-preferences} is the
2895 safe way to accomplish the same thing.
2896
2897 @item --compress-algo @code{name}
2898 @opindex compress-algo
2899 Use compression algorithm @code{name}. "zlib" is RFC-1950 ZLIB
2900 compression. "zip" is RFC-1951 ZIP compression which is used by PGP.
2901 "bzip2" is a more modern compression scheme that can compress some
2902 things better than zip or zlib, but at the cost of more memory used
2903 during compression and decompression. "uncompressed" or "none"
2904 disables compression. If this option is not used, the default
2905 behavior is to examine the recipient key preferences to see which
2906 algorithms the recipient supports. If all else fails, ZIP is used for
2907 maximum compatibility.
2908
2909 ZLIB may give better compression results than ZIP, as the compression
2910 window size is not limited to 8k. BZIP2 may give even better
2911 compression results than that, but will use a significantly larger
2912 amount of memory while compressing and decompressing. This may be
2913 significant in low memory situations. Note, however, that PGP (all
2914 versions) only supports ZIP compression. Using any algorithm other
2915 than ZIP or "none" will make the message unreadable with PGP. In
2916 general, you do not want to use this option as it allows you to
2917 violate the OpenPGP standard. @option{--personal-compress-preferences} is the
2918 safe way to accomplish the same thing.
2919
2920 @item --cert-digest-algo @code{name}
2921 @opindex cert-digest-algo
2922 Use @code{name} as the message digest algorithm used when signing a
2923 key. Running the program with the command @option{--version} yields a
2924 list of supported algorithms. Be aware that if you choose an algorithm
2925 that GnuPG supports but other OpenPGP implementations do not, then some
2926 users will not be able to use the key signatures you make, or quite
2927 possibly your entire key.
2928
2929 @item --disable-cipher-algo @code{name}
2930 @opindex disable-cipher-algo
2931 Never allow the use of @code{name} as cipher algorithm.
2932 The given name will not be checked so that a later loaded algorithm
2933 will still get disabled.
2934
2935 @item --disable-pubkey-algo @code{name}
2936 @opindex disable-pubkey-algo
2937 Never allow the use of @code{name} as public key algorithm.
2938 The given name will not be checked so that a later loaded algorithm
2939 will still get disabled.
2940
2941 @item --throw-keyids
2942 @itemx --no-throw-keyids
2943 @opindex throw-keyids
2944 Do not put the recipient key IDs into encrypted messages. This helps to
2945 hide the receivers of the message and is a limited countermeasure
2946 against traffic analysis.@footnote{Using a little social engineering
2947 anyone who is able to decrypt the message can check whether one of the
2948 other recipients is the one he suspects.}  On the receiving side, it may
2949 slow down the decryption process because all available secret keys must
2950 be tried.  @option{--no-throw-keyids} disables this option. This option
2951 is essentially the same as using @option{--hidden-recipient} for all
2952 recipients.
2953
2954 @item --not-dash-escaped
2955 @opindex not-dash-escaped
2956 This option changes the behavior of cleartext signatures
2957 so that they can be used for patch files. You should not
2958 send such an armored file via email because all spaces
2959 and line endings are hashed too. You can not use this
2960 option for data which has 5 dashes at the beginning of a
2961 line, patch files don't have this. A special armor header
2962 line tells GnuPG about this cleartext signature option.
2963
2964 @item --escape-from-lines
2965 @itemx --no-escape-from-lines
2966 @opindex escape-from-lines
2967 Because some mailers change lines starting with "From " to ">From " it
2968 is good to handle such lines in a special way when creating cleartext
2969 signatures to prevent the mail system from breaking the signature. Note
2970 that all other PGP versions do it this way too.  Enabled by
2971 default. @option{--no-escape-from-lines} disables this option.
2972
2973 @item --passphrase-repeat @code{n}
2974 @opindex passphrase-repeat
2975 Specify how many times @command{@gpgname} will request a new
2976 passphrase be repeated.  This is useful for helping memorize a
2977 passphrase.  Defaults to 1 repetition.
2978
2979 @item --passphrase-fd @code{n}
2980 @opindex passphrase-fd
2981 Read the passphrase from file descriptor @code{n}. Only the first line
2982 will be read from file descriptor @code{n}. If you use 0 for @code{n},
2983 the passphrase will be read from STDIN. This can only be used if only
2984 one passphrase is supplied.
2985
2986 Note that this passphrase is only used if the option @option{--batch}
2987 has also been given.  This is different from GnuPG version 1.x.
2988
2989 @item --passphrase-file @code{file}
2990 @opindex passphrase-file
2991 Read the passphrase from file @code{file}. Only the first line will
2992 be read from file @code{file}. This can only be used if only one
2993 passphrase is supplied. Obviously, a passphrase stored in a file is
2994 of questionable security if other users can read this file. Don't use
2995 this option if you can avoid it.
2996 Note that this passphrase is only used if the option @option{--batch}
2997 has also been given.  This is different from GnuPG version 1.x.
2998
2999 @item --passphrase @code{string}
3000 @opindex passphrase
3001 Use @code{string} as the passphrase. This can only be used if only one
3002 passphrase is supplied. Obviously, this is of very questionable
3003 security on a multi-user system. Don't use this option if you can
3004 avoid it.
3005 Note that this passphrase is only used if the option @option{--batch}
3006 has also been given.  This is different from GnuPG version 1.x.
3007
3008 @item --pinentry-mode @code{mode}
3009 @opindex pinentry-mode
3010 Set the pinentry mode to @code{mode}.  Allowed values for @code{mode}
3011 are:
3012 @table @asis
3013   @item default
3014   Use the default of the agent, which is @code{ask}.
3015   @item ask
3016   Force the use of the Pinentry.
3017   @item cancel
3018   Emulate use of Pinentry's cancel button.
3019   @item error
3020   Return a Pinentry error (``No Pinentry'').
3021   @item loopback
3022   Redirect Pinentry queries to the caller.  Note that in contrast to
3023   Pinentry the user is not prompted again if he enters a bad password.
3024 @end table
3025
3026 @item --command-fd @code{n}
3027 @opindex command-fd
3028 This is a replacement for the deprecated shared-memory IPC mode.
3029 If this option is enabled, user input on questions is not expected
3030 from the TTY but from the given file descriptor. It should be used
3031 together with @option{--status-fd}. See the file doc/DETAILS in the source
3032 distribution for details on how to use it.
3033
3034 @item --command-file @code{file}
3035 @opindex command-file
3036 Same as @option{--command-fd}, except the commands are read out of file
3037 @code{file}
3038
3039 @item --allow-non-selfsigned-uid
3040 @itemx --no-allow-non-selfsigned-uid
3041 @opindex allow-non-selfsigned-uid
3042 Allow the import and use of keys with user IDs which are not
3043 self-signed. This is not recommended, as a non self-signed user ID is
3044 trivial to forge. @option{--no-allow-non-selfsigned-uid} disables.
3045
3046 @item --allow-freeform-uid
3047 @opindex allow-freeform-uid
3048 Disable all checks on the form of the user ID while generating a new
3049 one. This option should only be used in very special environments as
3050 it does not ensure the de-facto standard format of user IDs.
3051
3052 @item --ignore-time-conflict
3053 @opindex ignore-time-conflict
3054 GnuPG normally checks that the timestamps associated with keys and
3055 signatures have plausible values. However, sometimes a signature
3056 seems to be older than the key due to clock problems. This option
3057 makes these checks just a warning. See also @option{--ignore-valid-from} for
3058 timestamp issues on subkeys.
3059
3060 @item --ignore-valid-from
3061 @opindex ignore-valid-from
3062 GnuPG normally does not select and use subkeys created in the future.
3063 This option allows the use of such keys and thus exhibits the
3064 pre-1.0.7 behaviour. You should not use this option unless there
3065 is some clock problem. See also @option{--ignore-time-conflict} for timestamp
3066 issues with signatures.
3067
3068 @item --ignore-crc-error
3069 @opindex ignore-crc-error
3070 The ASCII armor used by OpenPGP is protected by a CRC checksum against
3071 transmission errors. Occasionally the CRC gets mangled somewhere on
3072 the transmission channel but the actual content (which is protected by
3073 the OpenPGP protocol anyway) is still okay. This option allows GnuPG
3074 to ignore CRC errors.
3075
3076 @item --ignore-mdc-error
3077 @opindex ignore-mdc-error
3078 This option changes a MDC integrity protection failure into a warning.
3079 This can be useful if a message is partially corrupt, but it is
3080 necessary to get as much data as possible out of the corrupt message.
3081 However, be aware that a MDC protection failure may also mean that the
3082 message was tampered with intentionally by an attacker.
3083
3084 @item --allow-weak-digest-algos
3085 @opindex allow-weak-digest-algos
3086 Signatures made with known-weak digest algorithms are normally
3087 rejected with an ``invalid digest algorithm'' message.  This option
3088 allows the verification of signatures made with such weak algorithms.
3089 MD5 is the only digest algorithm considered weak by default.  See also
3090 @option{--weak-digest} to reject other digest algorithms.
3091
3092 @item --weak-digest @code{name}
3093 @opindex weak-digest
3094 Treat the specified digest algorithm as weak.  Signatures made over
3095 weak digests algorithms are normally rejected. This option can be
3096 supplied multiple times if multiple algorithms should be considered
3097 weak.  See also @option{--allow-weak-digest-algos} to disable
3098 rejection of weak digests.  MD5 is always considered weak, and does
3099 not need to be listed explicitly.
3100
3101 @item --no-default-keyring
3102 @opindex no-default-keyring
3103 Do not add the default keyrings to the list of keyrings. Note that
3104 GnuPG will not operate without any keyrings, so if you use this option
3105 and do not provide alternate keyrings via @option{--keyring} or
3106 @option{--secret-keyring}, then GnuPG will still use the default public or
3107 secret keyrings.
3108
3109 @item --no-keyring
3110 @opindex no-keyring
3111 Do not add use any keyrings even if specified as options.
3112
3113 @item --skip-verify
3114 @opindex skip-verify
3115 Skip the signature verification step. This may be
3116 used to make the decryption faster if the signature
3117 verification is not needed.
3118
3119 @item --with-key-data
3120 @opindex with-key-data
3121 Print key listings delimited by colons (like @option{--with-colons}) and
3122 print the public key data.
3123
3124 @item --fast-list-mode
3125 @opindex fast-list-mode
3126 Changes the output of the list commands to work faster; this is achieved
3127 by leaving some parts empty. Some applications don't need the user ID
3128 and the trust information given in the listings. By using this options
3129 they can get a faster listing. The exact behaviour of this option may
3130 change in future versions.  If you are missing some information, don't
3131 use this option.
3132
3133 @item --no-literal
3134 @opindex no-literal
3135 This is not for normal use. Use the source to see for what it might be useful.
3136
3137 @item --set-filesize
3138 @opindex set-filesize
3139 This is not for normal use. Use the source to see for what it might be useful.
3140
3141 @item --show-session-key
3142 @opindex show-session-key
3143 Display the session key used for one message. See
3144 @option{--override-session-key} for the counterpart of this option.
3145
3146 We think that Key Escrow is a Bad Thing; however the user should have
3147 the freedom to decide whether to go to prison or to reveal the content
3148 of one specific message without compromising all messages ever
3149 encrypted for one secret key.
3150
3151 You can also use this option if you receive an encrypted message which
3152 is abusive or offensive, to prove to the administrators of the
3153 messaging system that the ciphertext transmitted corresponds to an
3154 inappropriate plaintext so they can take action against the offending
3155 user.
3156
3157 @item --override-session-key @code{string}
3158 @itemx --override-session-key-fd @code{fd}
3159 @opindex override-session-key
3160 Don't use the public key but the session key @code{string} respective
3161 the session key taken from the first line read from file descriptor
3162 @code{fd}.  The format of this string is the same as the one printed
3163 by @option{--show-session-key}. This option is normally not used but
3164 comes handy in case someone forces you to reveal the content of an
3165 encrypted message; using this option you can do this without handing
3166 out the secret key.  Note that using @option{--override-session-key}
3167 may reveal the session key to all local users via the global process
3168 table.
3169
3170 @item --ask-sig-expire
3171 @itemx --no-ask-sig-expire
3172 @opindex ask-sig-expire
3173 When making a data signature, prompt for an expiration time. If this
3174 option is not specified, the expiration time set via
3175 @option{--default-sig-expire} is used. @option{--no-ask-sig-expire}
3176 disables this option.
3177
3178 @item --default-sig-expire
3179 @opindex default-sig-expire
3180 The default expiration time to use for signature expiration. Valid
3181 values are "0" for no expiration, a number followed by the letter d
3182 (for days), w (for weeks), m (for months), or y (for years) (for
3183 example "2m" for two months, or "5y" for five years), or an absolute
3184 date in the form YYYY-MM-DD. Defaults to "0".
3185
3186 @item --ask-cert-expire
3187 @itemx --no-ask-cert-expire
3188 @opindex ask-cert-expire
3189 When making a key signature, prompt for an expiration time. If this
3190 option is not specified, the expiration time set via
3191 @option{--default-cert-expire} is used. @option{--no-ask-cert-expire}
3192 disables this option.
3193
3194 @item --default-cert-expire
3195 @opindex default-cert-expire
3196 The default expiration time to use for key signature expiration.
3197 Valid values are "0" for no expiration, a number followed by the
3198 letter d (for days), w (for weeks), m (for months), or y (for years)
3199 (for example "2m" for two months, or "5y" for five years), or an
3200 absolute date in the form YYYY-MM-DD. Defaults to "0".
3201
3202 @item --default-new-key-algo @var{string}
3203 @opindex default-new-key-algo @var{string}
3204 This option can be used to change the default algorithms for key
3205 generation.  Note that the advanced key generation commands can always
3206 be used to specify a key algorithm directly.  Please consult the
3207 source code to learn the syntax of @var{string}.
3208
3209 @item --allow-secret-key-import
3210 @opindex allow-secret-key-import
3211 This is an obsolete option and is not used anywhere.
3212
3213 @item --allow-multiple-messages
3214 @item --no-allow-multiple-messages
3215 @opindex allow-multiple-messages
3216 Allow processing of multiple OpenPGP messages contained in a single file
3217 or stream.  Some programs that call GPG are not prepared to deal with
3218 multiple messages being processed together, so this option defaults to
3219 no.  Note that versions of GPG prior to 1.4.7 always allowed multiple
3220 messages.
3221
3222 Warning: Do not use this option unless you need it as a temporary
3223 workaround!
3224
3225
3226 @item --enable-special-filenames
3227 @opindex enable-special-filenames
3228 This option enables a mode in which filenames of the form
3229 @file{-&n}, where n is a non-negative decimal number,
3230 refer to the file descriptor n and not to a file with that name.
3231
3232 @item --no-expensive-trust-checks
3233 @opindex no-expensive-trust-checks
3234 Experimental use only.
3235
3236 @item --preserve-permissions
3237 @opindex preserve-permissions
3238 Don't change the permissions of a secret keyring back to user
3239 read/write only. Use this option only if you really know what you are doing.
3240
3241 @item --default-preference-list @code{string}
3242 @opindex default-preference-list
3243 Set the list of default preferences to @code{string}. This preference
3244 list is used for new keys and becomes the default for "setpref" in the
3245 edit menu.
3246
3247 @item --default-keyserver-url @code{name}
3248 @opindex default-keyserver-url
3249 Set the default keyserver URL to @code{name}. This keyserver will be
3250 used as the keyserver URL when writing a new self-signature on a key,
3251 which includes key generation and changing preferences.
3252
3253 @item --list-config
3254 @opindex list-config
3255 Display various internal configuration parameters of GnuPG. This option
3256 is intended for external programs that call GnuPG to perform tasks, and
3257 is thus not generally useful. See the file @file{doc/DETAILS} in the
3258 source distribution for the details of which configuration items may be
3259 listed. @option{--list-config} is only usable with
3260 @option{--with-colons} set.
3261
3262 @item --list-gcrypt-config
3263 @opindex list-gcrypt-config
3264 Display various internal configuration parameters of Libgcrypt.
3265
3266 @item --gpgconf-list
3267 @opindex gpgconf-list
3268 This command is similar to @option{--list-config} but in general only
3269 internally used by the @command{gpgconf} tool.
3270
3271 @item --gpgconf-test
3272 @opindex gpgconf-test
3273 This is more or less dummy action.  However it parses the configuration
3274 file and returns with failure if the configuration file would prevent
3275 @command{@gpgname} from startup.  Thus it may be used to run a syntax check
3276 on the configuration file.
3277
3278 @end table
3279
3280 @c *******************************
3281 @c ******* Deprecated ************
3282 @c *******************************
3283 @node Deprecated Options
3284 @subsection Deprecated options
3285
3286 @table @gnupgtabopt
3287
3288 @item --show-photos
3289 @itemx --no-show-photos
3290 @opindex show-photos
3291 Causes @option{--list-keys}, @option{--list-signatures},
3292 @option{--list-public-keys}, @option{--list-secret-keys}, and verifying
3293 a signature to also display the photo ID attached to the key, if
3294 any. See also @option{--photo-viewer}. These options are deprecated. Use
3295 @option{--list-options [no-]show-photos} and/or @option{--verify-options
3296 [no-]show-photos} instead.
3297
3298 @item --show-keyring
3299 @opindex show-keyring
3300 Display the keyring name at the head of key listings to show which
3301 keyring a given key resides on. This option is deprecated: use
3302 @option{--list-options [no-]show-keyring} instead.
3303
3304 @item --always-trust
3305 @opindex always-trust
3306 Identical to @option{--trust-model always}. This option is deprecated.
3307
3308 @item --show-notation
3309 @itemx --no-show-notation
3310 @opindex show-notation
3311 Show signature notations in the @option{--list-signatures} or @option{--check-signatures} listings
3312 as well as when verifying a signature with a notation in it. These
3313 options are deprecated. Use @option{--list-options [no-]show-notation}
3314 and/or @option{--verify-options [no-]show-notation} instead.
3315
3316 @item --show-policy-url
3317 @itemx --no-show-policy-url
3318 @opindex show-policy-url
3319 Show policy URLs in the @option{--list-signatures} or @option{--check-signatures}
3320 listings as well as when verifying a signature with a policy URL in
3321 it. These options are deprecated. Use @option{--list-options
3322 [no-]show-policy-url} and/or @option{--verify-options
3323 [no-]show-policy-url} instead.
3324
3325
3326 @end table
3327
3328
3329 @c *******************************************
3330 @c ***************            ****************
3331 @c ***************   FILES    ****************
3332 @c ***************            ****************
3333 @c *******************************************
3334 @mansect files
3335 @node GPG Configuration
3336 @section Configuration files
3337
3338 There are a few configuration files to control certain aspects of
3339 @command{@gpgname}'s operation. Unless noted, they are expected in the
3340 current home directory (@pxref{option --homedir}).
3341
3342 @table @file
3343
3344   @item gpg.conf
3345   @efindex gpg.conf
3346   This is the standard configuration file read by @command{@gpgname} on
3347   startup.  It may contain any valid long option; the leading two dashes
3348   may not be entered and the option may not be abbreviated.  This default
3349   name may be changed on the command line (@pxref{gpg-option --options}).
3350   You should backup this file.
3351
3352 @end table
3353
3354 Note that on larger installations, it is useful to put predefined files
3355 into the directory @file{@value{SYSCONFSKELDIR}} so that
3356 newly created users start up with a working configuration.
3357 For existing users a small
3358 helper script is provided to create these files (@pxref{addgnupghome}).
3359
3360 For internal purposes @command{@gpgname} creates and maintains a few other
3361 files; They all live in in the current home directory (@pxref{option
3362 --homedir}).  Only the @command{@gpgname} program may modify these files.
3363
3364
3365 @table @file
3366   @item ~/.gnupg
3367   @efindex ~/.gnupg
3368   This is the default home directory which is used if neither the
3369   environment variable @code{GNUPGHOME} nor the option
3370   @option{--homedir} is given.
3371
3372   @item ~/.gnupg/pubring.gpg
3373   @efindex pubring.gpg
3374   The public keyring.  You should backup this file.
3375
3376   @item ~/.gnupg/pubring.gpg.lock
3377   The lock file for the public keyring.
3378
3379   @item ~/.gnupg/pubring.kbx
3380   @efindex pubring.kbx
3381   The public keyring using a different format.  This file is shared
3382   with @command{gpgsm}.  You should backup this file.
3383
3384   @item ~/.gnupg/pubring.kbx.lock
3385   The lock file for @file{pubring.kbx}.
3386
3387   @item ~/.gnupg/secring.gpg
3388   @efindex secring.gpg
3389   A secret keyring as used by GnuPG versions before 2.1.  It is not
3390   used by GnuPG 2.1 and later.
3391
3392   @item ~/.gnupg/secring.gpg.lock
3393   The lock file for the secret keyring.
3394
3395   @item ~/.gnupg/.gpg-v21-migrated
3396   @efindex .gpg-v21-migrated
3397   File indicating that a migration to GnuPG 2.1 has been done.
3398
3399   @item ~/.gnupg/trustdb.gpg
3400   @efindex trustdb.gpg
3401   The trust database.  There is no need to backup this file; it is better
3402   to backup the ownertrust values (@pxref{option --export-ownertrust}).
3403
3404   @item ~/.gnupg/trustdb.gpg.lock
3405   The lock file for the trust database.
3406
3407   @item ~/.gnupg/random_seed
3408   @efindex random_seed
3409   A file used to preserve the state of the internal random pool.
3410
3411   @item ~/.gnupg/openpgp-revocs.d/
3412   @efindex openpgp-revocs.d
3413   This is the directory where gpg stores pre-generated revocation
3414   certificates.  The file name corresponds to the OpenPGP fingerprint of
3415   the respective key.  It is suggested to backup those certificates and
3416   if the primary private key is not stored on the disk to move them to
3417   an external storage device.  Anyone who can access theses files is
3418   able to revoke the corresponding key.  You may want to print them out.
3419   You should backup all files in this directory and take care to keep
3420   this backup closed away.
3421
3422   @item @value{DATADIR}/options.skel
3423   @efindex options.skel
3424   The skeleton options file.
3425
3426 @end table
3427
3428 Operation is further controlled by a few environment variables:
3429
3430 @table @asis
3431
3432   @item HOME
3433   @efindex HOME
3434   Used to locate the default home directory.
3435
3436   @item GNUPGHOME
3437   @efindex GNUPGHOME
3438   If set directory used instead of "~/.gnupg".
3439
3440   @item GPG_AGENT_INFO
3441   This variable is obsolete; it was used by GnuPG versions before 2.1.
3442
3443   @item PINENTRY_USER_DATA
3444   @efindex PINENTRY_USER_DATA
3445   This value is passed via gpg-agent to pinentry.  It is useful to convey
3446   extra information to a custom pinentry.
3447
3448   @item COLUMNS
3449   @itemx LINES
3450   @efindex COLUMNS
3451   @efindex LINES
3452   Used to size some displays to the full size of the screen.
3453
3454   @item LANGUAGE
3455   @efindex LANGUAGE
3456   Apart from its use by GNU, it is used in the W32 version to override the
3457   language selection done through the Registry.  If used and set to a
3458   valid and available language name (@var{langid}), the file with the
3459   translation is loaded from
3460   @code{@var{gpgdir}/gnupg.nls/@var{langid}.mo}.  Here @var{gpgdir} is the
3461   directory out of which the gpg binary has been loaded.  If it can't be
3462   loaded the Registry is tried and as last resort the native Windows
3463   locale system is used.
3464
3465 @end table
3466
3467
3468 @c *******************************************
3469 @c ***************            ****************
3470 @c ***************  EXAMPLES  ****************
3471 @c ***************            ****************
3472 @c *******************************************
3473 @mansect examples
3474 @node GPG Examples
3475 @section Examples
3476
3477 @table @asis
3478
3479 @item gpg -se -r @code{Bob} @code{file}
3480 sign and encrypt for user Bob
3481
3482 @item gpg --clear-sign @code{file}
3483 make a cleartext signature
3484
3485 @item gpg -sb @code{file}
3486 make a detached signature
3487
3488 @item gpg -u 0x12345678 -sb @code{file}
3489 make a detached signature with the key 0x12345678
3490
3491 @item gpg --list-keys @code{user_ID}
3492 show keys
3493
3494 @item gpg --fingerprint @code{user_ID}
3495 show fingerprint
3496
3497 @item gpg --verify @code{pgpfile}
3498 @itemx gpg --verify @code{sigfile} [@code{datafile}]
3499 Verify the signature of the file but do not output the data unless
3500 requested.  The second form is used for detached signatures, where
3501 @code{sigfile} is the detached signature (either ASCII armored or
3502 binary) and @code{datafile} are the signed data; if this is not given, the name of the
3503 file holding the signed data is constructed by cutting off the
3504 extension (".asc" or ".sig") of @code{sigfile} or by asking the user
3505 for the filename.  If the option @option{--output} is also used the
3506 signed data is written to the file specified by that option; use
3507 @code{-} to write the signed data to stdout.
3508 @end table
3509
3510
3511 @c *******************************************
3512 @c ***************            ****************
3513 @c ***************  USER ID   ****************
3514 @c ***************            ****************
3515 @c *******************************************
3516 @mansect how to specify a user id
3517 @ifset isman
3518 @include specify-user-id.texi
3519 @end ifset
3520
3521 @mansect filter expressions
3522 @chapheading FILTER EXPRESSIONS
3523
3524 The options @option{--import-filter} and @option{--export-filter} use
3525 expressions with this syntax (square brackets indicate an optional
3526 part and curly braces a repetition, white space between the elements
3527 are allowed):
3528
3529 @c man:.RS
3530 @example
3531   [lc] @{[@{flag@}] PROPNAME op VALUE [lc]@}
3532 @end example
3533 @c man:.RE
3534
3535 The name of a property (@var{PROPNAME}) may only consist of letters,
3536 digits and underscores.  The description for the filter type
3537 describes which properties are defined.  If an undefined property is
3538 used it evaluates to the empty string.  Unless otherwise noted, the
3539 @var{VALUE} must always be given and may not be the empty string.  No
3540 quoting is defined for the value, thus the value may not contain the
3541 strings @code{&&} or @code{||}, which are used as logical connection
3542 operators.  The flag @code{--} can be used to remove this restriction.
3543
3544 Numerical values are computed as long int; standard C notation
3545 applies.  @var{lc} is the logical connection operator; either
3546 @code{&&} for a conjunction or @code{||} for a disjunction.  A
3547 conjunction is assumed at the begin of an expression.  Conjunctions
3548 have higher precedence than disjunctions.  If @var{VALUE} starts with
3549 one of the characters used in any @var{op} a space after the
3550 @var{op} is required.
3551
3552 @noindent
3553 The supported operators (@var{op}) are:
3554
3555 @table @asis
3556
3557   @item =~
3558   Substring must match.
3559
3560   @item  !~
3561   Substring must not match.
3562
3563   @item  =
3564   The full string must match.
3565
3566   @item  <>
3567   The full string must not match.
3568
3569   @item  ==
3570   The numerical value must match.
3571
3572   @item  !=
3573   The numerical value must not match.
3574
3575   @item  <=
3576   The numerical value of the field must be LE than the value.
3577
3578   @item  <
3579   The numerical value of the field must be LT than the value.
3580
3581   @item  >
3582   The numerical value of the field must be GT than the value.
3583
3584   @item  >=
3585   The numerical value of the field must be GE than the value.
3586
3587   @item  -le
3588   The string value of the field must be less or equal than the value.
3589
3590   @item  -lt
3591   The string value of the field must be less than the value.
3592
3593   @item  -gt
3594   The string value of the field must be greater than the value.
3595
3596   @item  -ge
3597   The string value of the field must be greater or equal than the value.
3598
3599   @item  -n
3600   True if value is not empty (no value allowed).
3601
3602   @item  -z
3603   True if value is empty (no value allowed).
3604
3605   @item  -t
3606   Alias for "PROPNAME != 0" (no value allowed).
3607
3608   @item  -f
3609   Alias for "PROPNAME == 0" (no value allowed).
3610
3611 @end table
3612
3613 @noindent
3614 Values for @var{flag} must be space separated.  The supported flags
3615 are:
3616
3617 @table @asis
3618   @item --
3619   @var{VALUE} spans to the end of the expression.
3620   @item -c
3621   The string match in this part is done case-sensitive.
3622 @end table
3623
3624 The filter options concatenate several specifications for a filter of
3625 the same type.  For example the four options in this example:
3626
3627 @c man:.RS
3628 @example
3629  --import-option keep-uid="uid =~ Alfa"
3630  --import-option keep-uid="&& uid !~ Test"
3631  --import-option keep-uid="|| uid =~ Alpha"
3632  --import-option keep-uid="uid !~ Test"
3633 @end example
3634 @c man:.RE
3635
3636 @noindent
3637 which is equivalent to
3638
3639 @c man:.RS
3640 @example
3641  --import-option \
3642   keep-uid="uid =~ Alfa" && uid !~ Test" || uid =~ Alpha" && "uid !~ Test"
3643 @end example
3644 @c man:.RE
3645
3646 imports only the user ids of a key containing the strings "Alfa"
3647 or "Alpha" but not the string "test".
3648
3649
3650 @mansect return value
3651 @chapheading RETURN VALUE
3652
3653 The program returns 0 if everything was fine, 1 if at least
3654 a signature was bad, and other error codes for fatal errors.
3655
3656 @mansect warnings
3657 @chapheading WARNINGS
3658
3659 Use a *good* password for your user account and a *good* passphrase
3660 to protect your secret key. This passphrase is the weakest part of the
3661 whole system. Programs to do dictionary attacks on your secret keyring
3662 are very easy to write and so you should protect your "~/.gnupg/"
3663 directory very well.
3664
3665 Keep in mind that, if this program is used over a network (telnet), it
3666 is *very* easy to spy out your passphrase!
3667
3668 If you are going to verify detached signatures, make sure that the
3669 program knows about it; either give both filenames on the command line
3670 or use @samp{-} to specify STDIN.
3671
3672 @mansect interoperability
3673 @chapheading INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS
3674
3675 GnuPG tries to be a very flexible implementation of the OpenPGP
3676 standard. In particular, GnuPG implements many of the optional parts
3677 of the standard, such as the SHA-512 hash, and the ZLIB and BZIP2
3678 compression algorithms. It is important to be aware that not all
3679 OpenPGP programs implement these optional algorithms and that by
3680 forcing their use via the @option{--cipher-algo},
3681 @option{--digest-algo}, @option{--cert-digest-algo}, or
3682 @option{--compress-algo} options in GnuPG, it is possible to create a
3683 perfectly valid OpenPGP message, but one that cannot be read by the
3684 intended recipient.
3685
3686 There are dozens of variations of OpenPGP programs available, and each
3687 supports a slightly different subset of these optional algorithms.
3688 For example, until recently, no (unhacked) version of PGP supported
3689 the BLOWFISH cipher algorithm. A message using BLOWFISH simply could
3690 not be read by a PGP user. By default, GnuPG uses the standard
3691 OpenPGP preferences system that will always do the right thing and
3692 create messages that are usable by all recipients, regardless of which
3693 OpenPGP program they use. Only override this safe default if you
3694 really know what you are doing.
3695
3696 If you absolutely must override the safe default, or if the preferences
3697 on a given key are invalid for some reason, you are far better off using
3698 the @option{--pgp6}, @option{--pgp7}, or @option{--pgp8} options. These
3699 options are safe as they do not force any particular algorithms in
3700 violation of OpenPGP, but rather reduce the available algorithms to a
3701 "PGP-safe" list.
3702
3703 @mansect bugs
3704 @chapheading BUGS
3705
3706 On older systems this program should be installed as setuid(root). This
3707 is necessary to lock memory pages. Locking memory pages prevents the
3708 operating system from writing memory pages (which may contain
3709 passphrases or other sensitive material) to disk. If you get no
3710 warning message about insecure memory your operating system supports
3711 locking without being root. The program drops root privileges as soon
3712 as locked memory is allocated.
3713
3714 Note also that some systems (especially laptops) have the ability to
3715 ``suspend to disk'' (also known as ``safe sleep'' or ``hibernate'').
3716 This writes all memory to disk before going into a low power or even
3717 powered off mode.  Unless measures are taken in the operating system
3718 to protect the saved memory, passphrases or other sensitive material
3719 may be recoverable from it later.
3720
3721 Before you report a bug you should first search the mailing list
3722 archives for similar problems and second check whether such a bug has
3723 already been reported to our bug tracker at http://bugs.gnupg.org .
3724