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.
10 @cindex GPG command options
11 @cindex command options
12 @cindex options, GPG command
15 @c Begin standard stuff
20 \- OpenPGP encryption and signing tool
37 @c Begin gpg2 hack stuff
42 \- OpenPGP encryption and signing tool
57 @c End gpg2 hack stuff
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
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
75 If you are looking for version 1 of GnuPG, you may find that version
76 installed under the name @command{gpg1}.
79 In contrast to the standalone command @command{gpg} from GnuPG 1.x,
80 the 2.x version is commonly installed under the name
86 @xref{Option Index}, for an index to @command{@gpgname}'s commands and options.
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.
95 Developer information:
96 * Unattended Usage of GPG:: Using @command{gpg} from other programs.
99 @c * GPG Protocol:: The protocol the server mode uses.
102 @c *******************************************
103 @c *************** ****************
104 @c *************** COMMANDS ****************
105 @c *************** ****************
106 @c *******************************************
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.
115 @command{@gpgname} may be run with no commands. In this case it will
116 print a warning perform a reasonable action depending on the type of
117 file it is given as input (an encrypted message is decrypted, a
118 signature is verified, a file containing keys is listed, etc.).
120 If you run into any problems, please add the option @option{--verbose}
121 to the invocation to see more diagnostics.
125 * General GPG Commands:: Commands not specific to the functionality.
126 * Operational GPG Commands:: Commands to select the type of operation.
127 * OpenPGP Key Management:: How to manage your keys.
131 @c *******************************************
132 @c ********** GENERAL COMMANDS *************
133 @c *******************************************
134 @node General GPG Commands
135 @subsection Commands not specific to the function
140 Print the program version and licensing information. Note that you
141 cannot abbreviate this command.
146 Print a usage message summarizing the most useful command-line options.
147 Note that you cannot arbitrarily abbreviate this command
148 (though you can use its short form @option{-h}).
152 Print warranty information.
155 @opindex dump-options
156 Print a list of all available options and commands. Note that you cannot
157 abbreviate this command.
161 @c *******************************************
162 @c ******** OPERATIONAL COMMANDS ***********
163 @c *******************************************
164 @node Operational GPG Commands
165 @subsection Commands to select the type of operation
173 Sign a message. This command may be combined with @option{--encrypt}
174 (to sign and encrypt a message), @option{--symmetric} (to sign and
175 symmetrically encrypt a message), or both @option{--encrypt} and
176 @option{--symmetric} (to sign and encrypt a message that can be
177 decrypted using a secret key or a passphrase). The signing key is
178 chosen by default or can be set explicitly using the
179 @option{--local-user} and @option{--default-key} options.
185 Make a cleartext signature. The content in a cleartext signature is
186 readable without any special software. OpenPGP software is only needed
187 to verify the signature. cleartext signatures may modify end-of-line
188 whitespace for platform independence and are not intended to be
189 reversible. The signing key is chosen by default or can be set
190 explicitly using the @option{--local-user} and @option{--default-key}
197 Make a detached signature.
202 Encrypt data to one or more public keys. This command may be combined
203 with @option{--sign} (to sign and encrypt a message),
204 @option{--symmetric} (to encrypt a message that can be decrypted using a
205 secret key or a passphrase), or @option{--sign} and
206 @option{--symmetric} together (for a signed message that can be
207 decrypted using a secret key or a passphrase). @option{--recipient}
208 and related options specify which public keys to use for encryption.
213 Encrypt with a symmetric cipher using a passphrase. The default
214 symmetric cipher used is @value{GPGSYMENCALGO}, but may be chosen with the
215 @option{--cipher-algo} option. This command may be combined with
216 @option{--sign} (for a signed and symmetrically encrypted message),
217 @option{--encrypt} (for a message that may be decrypted via a secret key
218 or a passphrase), or @option{--sign} and @option{--encrypt} together
219 (for a signed message that may be decrypted via a secret key or a
220 passphrase). @command{@gpgname} caches the passphrase used for
221 symmetric encryption so that a decrypt operation may not require that
222 the user needs to enter the passphrase. The option
223 @option{--no-symkey-cache} can be used to disable this feature.
227 Store only (make a simple literal data packet).
232 Decrypt the file given on the command line (or STDIN if no file
233 is specified) and write it to STDOUT (or the file specified with
234 @option{--output}). If the decrypted file is signed, the signature is also
235 verified. This command differs from the default operation, as it never
236 writes to the filename which is included in the file and it rejects
237 files that don't begin with an encrypted message.
241 Assume that the first argument is a signed file and verify it without
242 generating any output. With no arguments, the signature packet is
243 read from STDIN. If only one argument is given, the specified file is
244 expected to include a complete signature.
246 With more than one argument, the first argument should specify a file
247 with a detached signature and the remaining files should contain the
248 signed data. To read the signed data from STDIN, use @samp{-} as the
249 second filename. For security reasons, a detached signature will not
250 read the signed material from STDIN if not explicitly specified.
252 Note: If the option @option{--batch} is not used, @command{@gpgname}
253 may assume that a single argument is a file with a detached signature,
254 and it will try to find a matching data file by stripping certain
255 suffixes. Using this historical feature to verify a detached
256 signature is strongly discouraged; you should always specify the data file
259 Note: When verifying a cleartext signature, @command{@gpgname} verifies
260 only what makes up the cleartext signed data and not any extra data
261 outside of the cleartext signature or the header lines directly following
262 the dash marker line. The option @code{--output} may be used to write
263 out the actual signed data, but there are other pitfalls with this
264 format as well. It is suggested to avoid cleartext signatures in
265 favor of detached signatures.
267 Note: To check whether a file was signed by a certain key the option
268 @option{--assert-signer} can be used. As an alternative the
269 @command{gpgv} tool can be used. @command{gpgv} is designed to
270 compare signed data against a list of trusted keys and returns with
271 success only for a good signature. It has its own manual page.
276 This modifies certain other commands to accept multiple files for
277 processing on the command line or read from STDIN with each filename on
278 a separate line. This allows for many files to be processed at
279 once. @option{--multifile} may currently be used along with
280 @option{--verify}, @option{--encrypt}, and @option{--decrypt}. Note that
281 @option{--multifile --verify} may not be used with detached signatures.
284 @opindex verify-files
285 Identical to @option{--multifile --verify}.
287 @item --encrypt-files
288 @opindex encrypt-files
289 Identical to @option{--multifile --encrypt}.
291 @item --decrypt-files
292 @opindex decrypt-files
293 Identical to @option{--multifile --decrypt}.
297 @itemx --list-public-keys
299 List the specified keys. If no keys are specified, then all keys from
300 the configured public keyrings are listed.
302 Never use the output of this command in scripts or other programs.
303 The output is intended only for humans and its format is likely to
304 change. The @option{--with-colons} option emits the output in a
305 stable, machine-parseable format, which is intended for use by scripts
308 @item --list-secret-keys
310 @opindex list-secret-keys
311 List the specified secret keys. If no keys are specified, then all
312 known secret keys are listed. A @code{#} after the initial tags
313 @code{sec} or @code{ssb} means that the secret key or subkey is
314 currently not usable. We also say that this key has been taken
315 offline (for example, a primary key can be taken offline by exporting
316 the key using the command @option{--export-secret-subkeys}). A
317 @code{>} after these tags indicate that the key is stored on a
318 smartcard. See also @option{--list-keys}.
320 @item --check-signatures
321 @opindex check-signatures
324 Same as @option{--list-keys}, but the key signatures are verified and
325 listed too. Note that for performance reasons the revocation status
326 of a signing key is not shown. This command has the same effect as
327 using @option{--list-keys} with @option{--with-sig-check}.
329 The status of the verification is indicated by a flag directly
330 following the "sig" tag (and thus before the flags described below. A
331 "!" indicates that the signature has been successfully verified, a "-"
332 denotes a bad signature and a "%" is used if an error occurred while
333 checking the signature (e.g. a non supported algorithm). Signatures
334 where the public key is not available are not listed; to see their
335 keyids the command @option{--list-sigs} can be used.
337 For each signature listed, there are several flags in between the
338 signature status flag and keyid. These flags give additional
339 information about each key signature. From left to right, they are
340 the numbers 1-3 for certificate check level (see
341 @option{--ask-cert-level}), "L" for a local or non-exportable
342 signature (see @option{--lsign-key}), "R" for a nonRevocable signature
343 (see the @option{--edit-key} command "nrsign"), "P" for a signature
344 that contains a policy URL (see @option{--cert-policy-url}), "N" for a
345 signature that contains a notation (see @option{--cert-notation}), "X"
346 for an eXpired signature (see @option{--ask-cert-expire}), and the
347 numbers 1-9 or "T" for 10 and above to indicate trust signature levels
348 (see the @option{--edit-key} command "tsign").
352 @itemx --locate-external-keys
354 @opindex locate-external-keys
355 Locate the keys given as arguments. This command basically uses the
356 same algorithm as used when locating keys for encryption and may thus
357 be used to see what keys @command{@gpgname} might use. In particular
358 external methods as defined by @option{--auto-key-locate} are used to
359 locate a key if the arguments comain valid mail addresses. Only
360 public keys are listed.
362 The variant @option{--locate-external-keys} does not consider a
363 locally existing key and can thus be used to force the refresh of a
364 key via the defined external methods. If a fingerprint is given and
365 and the methods defined by --auto-key-locate define LDAP servers, the
366 key is fetched from these resources; defined non-LDAP keyservers are
372 This commands takes OpenPGP keys as input and prints information about
373 them in the same way the command @option{--list-keys} does for locally
374 stored key. In addition the list options @code{show-unusable-uids},
375 @code{show-unusable-subkeys}, @code{show-notations} and
376 @code{show-policy-urls} are also enabled. As usual for automated
377 processing, this command should be combined with the option
378 @option{--with-colons}.
382 List all keys (or the specified ones) along with their
383 fingerprints. This is the same output as @option{--list-keys} but with
384 the additional output of a line with the fingerprint. May also be
385 combined with @option{--check-signatures}. If this
386 command is given twice, the fingerprints of all secondary keys are
387 listed too. This command also forces pretty printing of fingerprints
388 if the keyid format has been set to "none".
391 @opindex list-packets
392 List only the sequence of packets. This command is only useful for
393 debugging. When used with option @option{--verbose} the actual MPI
394 values are dumped and not only their lengths. Note that the output of
395 this command may change with new releases.
402 Present a menu to work with a smartcard. The subcommand "help"
403 provides an overview on available commands. For a detailed
404 description, please see the Card HOWTO at
405 https://gnupg.org/documentation/howtos.html#GnuPG-cardHOWTO . Please
406 note that the command "openpgp" can be used to switch to the OpenPGP
407 application of cards which by default are presenting another
408 application (e.g. PIV).
412 Show the content of the smart card.
416 Present a menu to allow changing the PIN of a smartcard. This
417 functionality is also available as the subcommand "passwd" with the
418 @option{--edit-card} command.
420 @item --delete-keys @var{name}
422 Remove key from the public keyring. In batch mode either @option{--yes} is
423 required or the key must be specified by fingerprint. This is a
424 safeguard against accidental deletion of multiple keys. If the
425 exclamation mark syntax is used with the fingerprint of a subkey only
426 that subkey is deleted; if the exclamation mark is used with the
427 fingerprint of the primary key the entire public key is deleted.
429 @item --delete-secret-keys @var{name}
430 @opindex delete-secret-keys
431 Remove key from the secret keyring. In batch mode the key must be
432 specified by fingerprint. The option @option{--yes} can be used to
433 advise gpg-agent not to request a confirmation. This extra
434 pre-caution is done because @command{@gpgname} can't be sure that the
435 secret key (as controlled by gpg-agent) is only used for the given
436 OpenPGP public key. If the exclamation mark syntax is used with the
437 fingerprint of a subkey only the secret part of that subkey is
438 deleted; if the exclamation mark is used with the fingerprint of the
439 primary key only the secret part of the primary key is deleted.
442 @item --delete-secret-and-public-key @var{name}
443 @opindex delete-secret-and-public-key
444 Same as @option{--delete-key}, but if a secret key exists, it will be
445 removed first. In batch mode the key must be specified by fingerprint.
446 The option @option{--yes} can be used to advise gpg-agent not to
447 request a confirmation.
451 Either export all keys from all keyrings (default keyring and those
452 registered via option @option{--keyring}), or if at least one name is given,
453 those of the given name. The exported keys are written to STDOUT or to the
454 file given with option @option{--output}. Use together with
455 @option{--armor} to mail those keys.
457 @item --send-keys @var{keyIDs}
459 Similar to @option{--export} but sends the keys to a keyserver.
460 Fingerprints may be used instead of key IDs.
461 Don't send your complete keyring to a keyserver --- select
462 only those keys which are new or changed by you. If no @var{keyIDs}
463 are given, @command{@gpgname} does nothing.
465 Take care: Keyservers are by design write only systems and thus it is
466 not possible to ever delete keys once they have been send to a
470 @item --export-secret-keys
471 @itemx --export-secret-subkeys
472 @opindex export-secret-keys
473 @opindex export-secret-subkeys
474 Same as @option{--export}, but exports the secret keys instead. The
475 exported keys are written to STDOUT or to the file given with option
476 @option{--output}. This command is often used along with the option
477 @option{--armor} to allow for easy printing of the key for paper backup;
478 however the external tool @command{paperkey} does a better job of
479 creating backups on paper. Note that exporting a secret key can be a
480 security risk if the exported keys are sent over an insecure channel.
482 The second form of the command has the special property to render the
483 secret part of the primary key useless; this is a GNU extension to
484 OpenPGP and other implementations can not be expected to successfully
485 import such a key. Its intended use is in generating a full key with
486 an additional signing subkey on a dedicated machine. This command
487 then exports the key without the primary key to the main machine.
489 GnuPG may ask you to enter the passphrase for the key. This is
490 required, because the internal protection method of the secret key is
491 different from the one specified by the OpenPGP protocol.
493 @item --export-ssh-key
494 @opindex export-ssh-key
495 This command is used to export a key in the OpenSSH public key format.
496 It requires the specification of one key by the usual means and
497 exports the latest valid subkey which has an authentication capability
498 to STDOUT or to the file given with option @option{--output}. That
499 output can directly be added to ssh's @file{authorized_key} file.
501 By specifying the key to export using a key ID or a fingerprint
502 suffixed with an exclamation mark (!), a specific subkey or the
503 primary key can be exported. This does not even require that the key
504 has the authentication capability flag set.
509 Import/merge keys. This adds the given keys to the
510 keyring. The fast version is currently just a synonym.
512 There are a few other options which control how this command works.
513 Most notable here is the @option{--import-options merge-only} option
514 which does not insert new keys but does only the merging of new
515 signatures, user-IDs and subkeys.
517 @item --receive-keys @var{keyIDs}
518 @opindex receive-keys
519 @itemx --recv-keys @var{keyIDs}
521 Import the keys with the given @var{keyIDs} from a keyserver.
524 @opindex refresh-keys
525 Request updates from a keyserver for keys that already exist on the
526 local keyring. This is useful for updating a key with the latest
527 signatures, user IDs, etc. Calling this with no arguments will refresh
530 @item --search-keys @var{names}
532 Search the keyserver for the given @var{names}. Multiple names given
533 here will be joined together to create the search string for the
534 keyserver. Note that keyservers search for @var{names} in a different
535 and simpler way than gpg does. The best choice is to use a mail
536 address. Due to data privacy reasons keyservers may even not even
537 allow searching by user id or mail address and thus may only return
538 results when being used with the @option{--recv-key} command to
539 search by key fingerprint or keyid.
541 @item --fetch-keys @var{URIs}
543 Retrieve keys located at the specified @var{URIs}. Note that different
544 installations of GnuPG may support different protocols (HTTP, FTP,
545 LDAP, etc.). When using HTTPS the system provided root certificates
546 are used by this command.
548 @item --update-trustdb
549 @opindex update-trustdb
550 Do trust database maintenance. This command iterates over all keys and
551 builds the Web of Trust. This is an interactive command because it may
552 have to ask for the "ownertrust" values for keys. The user has to give
553 an estimation of how far she trusts the owner of the displayed key to
554 correctly certify (sign) other keys. GnuPG only asks for the ownertrust
555 value if it has not yet been assigned to a key. Using the
556 @option{--edit-key} menu, the assigned value can be changed at any time.
558 @item --check-trustdb
559 @opindex check-trustdb
560 Do trust database maintenance without user interaction. From time to
561 time the trust database must be updated so that expired keys or
562 signatures and the resulting changes in the Web of Trust can be
563 tracked. Normally, GnuPG will calculate when this is required and do it
564 automatically unless @option{--no-auto-check-trustdb} is set. This
565 command can be used to force a trust database check at any time. The
566 processing is identical to that of @option{--update-trustdb} but it
567 skips keys with a not yet defined "ownertrust".
569 For use with cron jobs, this command can be used together with
570 @option{--batch} in which case the trust database check is done only if
571 a check is needed. To force a run even in batch mode add the option
574 @anchor{option --export-ownertrust}
575 @item --export-ownertrust
576 @opindex export-ownertrust
577 Send the ownertrust values to STDOUT. This is useful for backup purposes
578 as these values are the only ones which can't be re-created from a
579 corrupted trustdb. Example:
582 @gpgname{} --export-ownertrust > otrust.txt
587 @item --import-ownertrust
588 @opindex import-ownertrust
589 Update the trustdb with the ownertrust values stored in @code{files} (or
590 STDIN if not given); existing values will be overwritten. In case of a
591 severely damaged trustdb and if you have a recent backup of the
592 ownertrust values (e.g. in the file @file{otrust.txt}), you may re-create
593 the trustdb using these commands:
598 @gpgname{} --import-ownertrust < otrust.txt
603 @item --rebuild-keydb-caches
604 @opindex rebuild-keydb-caches
605 When updating from version 1.0.6 to 1.0.7 this command should be used
606 to create signature caches in the keyring. It might be handy in other
609 @item --print-md @var{algo}
612 Print message digest of algorithm @var{algo} for all given files or STDIN.
613 With the second form (or a deprecated "*" for @var{algo}) digests for all
614 available algorithms are printed.
616 @item --gen-random @var{0|1|2|16|30} @var{count}
618 Emit @var{count} random bytes of the given quality level 0, 1 or 2. If
619 @var{count} is not given or zero, an endless sequence of random bytes
620 will be emitted. If used with @option{--armor} the output will be
621 base64 encoded. The special level 16 uses a quality level of 1 and
622 outputs an endless stream of hex-encoded octets. The special level
623 30 outputs random as 30 zBase-32 characters.
625 @item --gen-prime @var{mode} @var{bits}
627 Use the source, Luke :-). The output format is subject to change
635 Pack or unpack an arbitrary input into/from an OpenPGP ASCII armor.
636 This is a GnuPG extension to OpenPGP and in general not very useful.
637 The @option{--dearmor} command can also be used to dearmor PEM armors.
641 This command is similar to @option{--decrypt} with the difference that the
642 output is not the usual plaintext but the original message with the
643 encryption layer removed. Thus the output will be an OpenPGP data
644 structure which often means a signed OpenPGP message. Note that this
645 option may or may not remove a compression layer which is often found
646 beneath the encryption layer.
648 @item --tofu-policy @{auto|good|unknown|bad|ask@} @var{keys}
650 Set the TOFU policy for all the bindings associated with the specified
651 @var{keys}. For more information about the meaning of the policies,
652 @pxref{trust-model-tofu}. The @var{keys} may be specified either by their
653 fingerprint (preferred) or their keyid.
657 @c Run gpg in server mode. This feature is not yet ready for use and
658 @c thus not documented.
663 @c ********************************************
664 @c ******* KEY MANAGEMENT COMMANDS **********
665 @c ********************************************
666 @node OpenPGP Key Management
667 @subsection How to manage your keys
669 This section explains the main commands for key management.
673 @item --quick-generate-key @var{user-id} [@var{algo} [@var{usage} [@var{expire}]]]
674 @itemx --quick-gen-key
675 @opindex quick-generate-key
676 @opindex quick-gen-key
677 This is a simple command to generate a standard key with one user id.
678 In contrast to @option{--generate-key} the key is generated directly
679 without the need to answer a bunch of prompts. Unless the option
680 @option{--yes} is given, the key creation will be canceled if the
681 given user id already exists in the keyring.
683 If invoked directly on the console without any special options an
684 answer to a ``Continue?'' style confirmation prompt is required. In
685 case the user id already exists in the keyring a second prompt to
686 force the creation of the key will show up.
688 If @var{algo} or @var{usage} are given, only the primary key is
689 created and no prompts are shown. To specify an expiration date but
690 still create a primary and subkey use ``default'' or
691 ``future-default'' for @var{algo} and ``default'' for @var{usage}.
692 For a description of these optional arguments see the command
693 @code{--quick-add-key}. The @var{usage} accepts also the value
694 ``cert'' which can be used to create a certification only primary key;
695 the default is to a create certification and signing key.
697 The @var{expire} argument can be used to specify an expiration date
698 for the key. Several formats are supported; commonly the ISO formats
699 ``YYYY-MM-DD'' or ``YYYYMMDDThhmmss'' are used. To make the key
700 expire in N seconds, N days, N weeks, N months, or N years use
701 ``seconds=N'', ``Nd'', ``Nw'', ``Nm'', or ``Ny'' respectively. Not
702 specifying a value, or using ``-'' results in a key expiring in a
703 reasonable default interval. The values ``never'', ``none'' can be
704 used for no expiration date.
706 If this command is used with @option{--batch},
707 @option{--pinentry-mode} has been set to @code{loopback}, and one of
708 the passphrase options (@option{--passphrase},
709 @option{--passphrase-fd}, or @option{--passphrase-file}) is used, the
710 supplied passphrase is used for the new key and the agent does not ask
711 for it. To create a key without any protection @code{--passphrase ''}
714 To create an OpenPGP key from the keys available on the currently
715 inserted smartcard, the special string ``card'' can be used for
716 @var{algo}. If the card features an encryption and a signing key, gpg
717 will figure them out and creates an OpenPGP key consisting of the
718 usual primary key and one subkey. This works only with certain
719 smartcards. Note that the interactive @option{--full-gen-key} command
720 allows to do the same but with greater flexibility in the selection of
723 Note that it is possible to create a primary key and a subkey using
724 non-default algorithms by using ``default'' and changing the default
725 parameters using the option @option{--default-new-key-algo}.
727 @item --quick-set-expire @var{fpr} @var{expire} [*|@var{subfprs}]
728 @opindex quick-set-expire
729 With two arguments given, directly set the expiration time of the
730 primary key identified by @var{fpr} to @var{expire}. To remove the
731 expiration time @code{0} can be used. With three arguments and the
732 third given as an asterisk, the expiration time of all non-revoked and
733 not yet expired subkeys are set to @var{expire}. With more than two
734 arguments and a list of fingerprints given for @var{subfprs}, all
735 non-revoked subkeys matching these fingerprints are set to
739 @item --quick-add-key @var{fpr} [@var{algo} [@var{usage} [@var{expire}]]]
740 @opindex quick-add-key
741 Directly add a subkey to the key identified by the fingerprint
742 @var{fpr}. Without the optional arguments an encryption subkey is
743 added. If any of the arguments are given a more specific subkey is
746 @var{algo} may be any of the supported algorithms or curve names
747 given in the format as used by key listings. To use the default
748 algorithm the string ``default'' or ``-'' can be used. Supported
749 algorithms are ``rsa'', ``dsa'', ``elg'', ``ed25519'', ``cv25519'',
750 and other ECC curves. For example the string ``rsa'' adds an RSA key
751 with the default key length; a string ``rsa4096'' requests that the
752 key length is 4096 bits. The string ``future-default'' is an alias
753 for the algorithm which will likely be used as default algorithm in
754 future versions of gpg. To list the supported ECC curves the command
755 @code{gpg --with-colons --list-config curve} can be used.
757 Depending on the given @var{algo} the subkey may either be an
758 encryption subkey or a signing subkey. If an algorithm is capable of
759 signing and encryption and such a subkey is desired, a @var{usage}
760 string must be given. This string is either ``default'' or ``-'' to
761 keep the default or a comma delimited list (or space delimited list)
762 of keywords: ``sign'' for a signing subkey, ``auth'' for an
763 authentication subkey, and ``encr'' for an encryption subkey
764 (``encrypt'' can be used as alias for ``encr''). The valid
765 combinations depend on the algorithm.
767 The @var{expire} argument can be used to specify an expiration date
768 for the key. Several formats are supported; commonly the ISO formats
769 ``YYYY-MM-DD'' or ``YYYYMMDDThhmmss'' are used. To make the key
770 expire in N seconds, N days, N weeks, N months, or N years use
771 ``seconds=N'', ``Nd'', ``Nw'', ``Nm'', or ``Ny'' respectively. Not
772 specifying a value, or using ``-'' results in a key expiring in a
773 reasonable default interval. The values ``never'', ``none'' can be
774 used for no expiration date.
776 @item --quick-add-adsk @var{fpr} @var{adskfpr}
777 @opindex quick-add-adsk
778 Directly add an Additional Decryption Subkey to the key identified by
779 the fingerprint @var{fpr}. @var{adskfpr} is the fingerprint of
780 another key's encryption subkey. A subkey is commonly used here
781 because by default a primary key has no encryption capability. Use
782 the option @option{--with-subkey-fingerprint} with a list command to
783 display the subkey fingerprints.
786 @opindex generate-key
789 Generate a new key pair using the current default parameters. This is
790 the standard command to create a new key. In addition to the key a
791 revocation certificate is created and stored in the
792 @file{openpgp-revocs.d} directory below the GnuPG home directory.
794 @item --full-generate-key
795 @opindex full-generate-key
796 @itemx --full-gen-key
797 @opindex full-gen-key
798 Generate a new key pair with dialogs for all options. This is an
799 extended version of @option{--generate-key}.
801 There is also a feature which allows you to create keys in batch
802 mode. See the manual section ``Unattended key generation'' on how
806 @item --generate-revocation @var{name}
807 @opindex generate-revocation
808 @itemx --gen-revoke @var{name}
810 Generate a revocation certificate for the complete key. To only revoke
811 a subkey or a key signature, use the @option{--edit} command.
813 This command merely creates the revocation certificate so that it can
814 be used to revoke the key if that is ever needed. To actually revoke
815 a key the created revocation certificate needs to be merged with the
816 key to revoke. This is done by importing the revocation certificate
817 using the @option{--import} command. Then the revoked key needs to be
818 published, which is best done by sending the key to a keyserver
819 (command @option{--send-key}) and by exporting (@option{--export}) it
820 to a file which is then send to frequent communication partners.
823 @item --generate-designated-revocation @var{name}
824 @opindex generate-designated-revocation
825 @itemx --desig-revoke @var{name}
826 @opindex desig-revoke
827 Generate a designated revocation certificate for a key. This allows a
828 user (with the permission of the keyholder) to revoke someone else's
834 Present a menu which enables you to do most of the key management
835 related tasks. It expects the specification of a key on the command
838 @c ******** Begin Edit-key Options **********
843 Toggle selection of user ID or photographic user ID with index @var{n}.
844 Use @code{*} to select all and @code{0} to deselect all.
848 Toggle selection of subkey with index @var{n} or key ID @var{n}.
849 Use @code{*} to select all and @code{0} to deselect all.
852 @opindex keyedit:sign
853 Make a signature on key of user @code{name}. If the key is not yet
854 signed by the default user (or the users given with @option{-u}), the program
855 displays the information of the key again, together with its
856 fingerprint and asks whether it should be signed. This question is
857 repeated for all users specified with
861 @opindex keyedit:lsign
862 Same as "sign" but the signature is marked as non-exportable and will
863 therefore never be used by others. This may be used to make keys
864 valid only in the local environment.
867 @opindex keyedit:nrsign
868 Same as "sign" but the signature is marked as non-revocable and can
869 therefore never be revoked.
872 @opindex keyedit:tsign
873 Make a trust signature. This is a signature that combines the notions
874 of certification (like a regular signature), and trust (like the
875 "trust" command). It is generally useful in distinct communities
876 or groups to implement the concept of a Trusted Introducer. For
877 more information please read the sections ``Trust Signature'' and
878 ``Regular Expression'' in RFC-4880.
882 Note that "l" (for local / non-exportable), "nr" (for non-revocable,
883 and "t" (for trust) may be freely mixed and prefixed to "sign" to
884 create a signature of any type desired.
887 If the option @option{--only-sign-text-ids} is specified, then any
888 non-text based user ids (e.g., photo IDs) will not be selected for
894 @opindex keyedit:delsig
895 Delete a signature. Note that it is not possible to retract a signature,
896 once it has been send to the public (i.e. to a keyserver). In that case
897 you better use @code{revsig}.
900 @opindex keyedit:revsig
901 Revoke a signature. For every signature which has been generated by
902 one of the secret keys, GnuPG asks whether a revocation certificate
906 @opindex keyedit:check
907 Check the signatures on all selected user IDs. With the extra
908 option @code{selfsig} only self-signatures are shown.
911 @opindex keyedit:adduid
912 Create an additional user ID.
915 @opindex keyedit:addphoto
916 Create a photographic user ID. This will prompt for a JPEG file that
917 will be embedded into the user ID. Note that a very large JPEG will make
918 for a very large key. Also note that some programs will display your
919 JPEG unchanged (GnuPG), and some programs will scale it to fit in a
923 @opindex keyedit:showphoto
924 Display the selected photographic user ID.
927 @opindex keyedit:deluid
928 Delete a user ID or photographic user ID. Note that it is not
929 possible to retract a user id, once it has been send to the public
930 (i.e. to a keyserver). In that case you better use @code{revuid}.
933 @opindex keyedit:revuid
934 Revoke a user ID or photographic user ID.
937 @opindex keyedit:primary
938 Flag the current user id as the primary one, removes the primary user
939 id flag from all other user ids and sets the timestamp of all affected
940 self-signatures one second ahead. Note that setting a photo user ID
941 as primary makes it primary over other photo user IDs, and setting a
942 regular user ID as primary makes it primary over other regular user
946 @opindex keyedit:keyserver
947 Set a preferred keyserver for the specified user ID(s). This allows
948 other users to know where you prefer they get your key from. See
949 @option{--keyserver-options honor-keyserver-url} for more on how this
950 works. Setting a value of "none" removes an existing preferred
954 @opindex keyedit:notation
955 Set a name=value notation for the specified user ID(s). See
956 @option{--cert-notation} for more on how this works. Setting a value of
957 "none" removes all notations, setting a notation prefixed with a minus
958 sign (-) removes that notation, and setting a notation name (without the
959 =value) prefixed with a minus sign removes all notations with that name.
962 @opindex keyedit:pref
963 List preferences from the selected user ID. This shows the actual
964 preferences, without including any implied preferences.
967 @opindex keyedit:showpref
968 More verbose preferences listing for the selected user ID. This shows
969 the preferences in effect by including the implied preferences of 3DES
970 (cipher), SHA-1 (digest), and Uncompressed (compression) if they are
971 not already included in the preference list. In addition, the
972 preferred keyserver and signature notations (if any) are shown.
974 @item setpref @var{string}
975 @opindex keyedit:setpref
976 Set the list of user ID preferences to @var{string} for all (or just
977 the selected) user IDs. Calling setpref with no arguments sets the
978 preference list to the default (either built-in or set via
979 @option{--default-preference-list}), and calling setpref with "none"
980 as the argument sets an empty preference list. Use @command{@gpgname
981 --version} to get a list of available algorithms. Note that while you
982 can change the preferences on an attribute user ID (aka "photo ID"),
983 GnuPG does not select keys via attribute user IDs so these preferences
984 will not be used by GnuPG. Note that an unattended version of this
985 command is available as @option{--quick-update-pref}.
987 When setting preferences, you should list the algorithms in the order
988 which you'd like to see them used by someone else when encrypting a
989 message to your key. If you don't include 3DES, it will be
990 automatically added at the end. Note that there are many factors that
991 go into choosing an algorithm (for example, your key may not be the
992 only recipient), and so the remote OpenPGP application being used to
993 send to you may or may not follow your exact chosen order for a given
994 message. It will, however, only choose an algorithm that is present
995 on the preference list of every recipient key. See also the
996 INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS section below.
999 @opindex keyedit:addkey
1000 Add a subkey to this key.
1003 @opindex keyedit:addcardkey
1004 Generate a subkey on a card and add it to this key.
1007 @opindex keyedit:keytocard
1008 Transfer the selected secret subkey (or the primary key if no subkey
1009 has been selected) to a smartcard. The secret key in the keyring will
1010 be replaced by a stub if the key could be stored successfully on the
1011 card and you use the save command later. Only certain key types may be
1012 transferred to the card. A sub menu allows you to select on what card
1013 to store the key. Note that it is not possible to get that key back
1014 from the card - if the card gets broken your secret key will be lost
1015 unless you have a backup somewhere.
1017 @item bkuptocard @var{file}
1018 @opindex keyedit:bkuptocard
1019 Restore the given @var{file} to a card. This command may be used to restore a
1020 backup key (as generated during card initialization) to a new card. In
1021 almost all cases this will be the encryption key. You should use this
1022 command only with the corresponding public key and make sure that the
1023 file given as argument is indeed the backup to restore. You should then
1024 select 2 to restore as encryption key. You will first be asked to enter
1025 the passphrase of the backup key and then for the Admin PIN of the card.
1028 @opindex keyedit:keytotpm
1029 Transfer the selected secret subkey (or the primary key if no subkey
1030 has been selected) to TPM form. The secret key in the keyring will
1031 be replaced by the TPM representation of that key, which can only be
1032 read by the particular TPM that created it (so the keyfile now
1033 becomes locked to the laptop containing the TPM). Only certain key
1034 types may be transferred to the TPM (all TPM 2.0 systems are
1035 mandated to have the rsa2048 and nistp256 algorithms but newer TPMs
1036 may have more). Note that the key itself is not transferred into the
1037 TPM, merely encrypted by the TPM in-place, so if the keyfile is
1038 deleted, the key will be lost. Once transferred to TPM
1039 representation, the key file can never be converted back to non-TPM
1040 form and the key will die when the TPM does, so you should first
1041 have a backup on secure offline storage of the actual secret key
1042 file before conversion. It is essential to use the physical system
1043 TPM that you have rw permission on the TPM resource manager device
1044 (/dev/tpmrm0). Usually this means you must be a member of the tss
1048 @opindex keyedit:delkey
1049 Remove a subkey (secondary key). Note that it is not possible to retract
1050 a subkey, once it has been send to the public (i.e. to a keyserver). In
1051 that case you better use @code{revkey}. Also note that this only
1052 deletes the public part of a key.
1055 @opindex keyedit:revkey
1059 @opindex keyedit:expire
1060 Change the key or subkey expiration time. If a subkey is selected, the
1061 expiration time of this subkey will be changed. With no selection, the
1062 key expiration of the primary key is changed.
1065 @opindex keyedit:trust
1066 Change the owner trust value for the key. This updates the trust-db
1067 immediately and no save is required.
1071 @opindex keyedit:disable
1072 @opindex keyedit:enable
1073 Disable or enable an entire key. A disabled key can not normally be
1074 used for encryption.
1077 @opindex keyedit:addrevoker
1078 Add a designated revoker to the key. This takes one optional argument:
1079 "sensitive". If a designated revoker is marked as sensitive, it will
1080 not be exported by default (see export-options).
1083 @opindex keyedit:addadsk
1084 Add an Additional Decryption Subkey. The user is asked to enter the
1085 fingerprint of another encryption subkey. Note that the exact
1086 fingerprint of another key's encryption subkey needs to be entered.
1087 This is because commonly the primary key has no encryption
1088 capability. Use the option @option{--with-subkey-fingerprint} with
1089 a list command to display the subkey fingerprints.
1092 @opindex keyedit:passwd
1093 Change the passphrase of the secret key.
1096 @opindex keyedit:toggle
1097 This is dummy command which exists only for backward compatibility.
1100 @opindex keyedit:clean
1101 Compact (by removing all signatures except the selfsig) any user ID
1102 that is no longer usable (e.g. revoked, or expired). Then, remove any
1103 signatures that are not usable by the trust calculations.
1104 Specifically, this removes any signature that does not validate, any
1105 signature that is superseded by a later signature, revoked signatures,
1106 and signatures issued by keys that are not present on the keyring.
1109 @opindex keyedit:minimize
1110 Make the key as small as possible. This removes all signatures from
1111 each user ID except for the most recent self-signature.
1114 @opindex keyedit:change-usage
1115 Change the usage flags (capabilities) of the primary key or of
1116 subkeys. These usage flags (e.g. Certify, Sign, Authenticate,
1117 Encrypt) are set during key creation. Sometimes it is useful to
1118 have the opportunity to change them (for example to add
1119 Authenticate) after they have been created. Please take care when
1120 doing this; the allowed usage flags depend on the key algorithm.
1123 @opindex keyedit:cross-certify
1124 Add cross-certification signatures to signing subkeys that may not
1125 currently have them. Cross-certification signatures protect against a
1126 subtle attack against signing subkeys. See
1127 @option{--require-cross-certification}. All new keys generated have
1128 this signature by default, so this command is only useful to bring
1129 older keys up to date.
1132 @opindex keyedit:save
1133 Save all changes to the keyring and quit.
1136 @opindex keyedit:quit
1137 Quit the program without updating the
1142 The listing shows you the key with its secondary keys and all user
1143 IDs. The primary user ID is indicated by a dot, and selected keys or
1144 user IDs are indicated by an asterisk. The trust
1145 value is displayed with the primary key: "trust" is the assigned owner
1146 trust and "validity" is the calculated validity of the key. Validity
1147 values are also displayed for all user IDs.
1148 For possible values of trust, @pxref{trust-values}.
1150 @c ******** End Edit-key Options **********
1152 @item --sign-key @var{name}
1154 Signs a public key with your secret key. This is a shortcut version of
1155 the subcommand "sign" from @option{--edit-key}.
1157 @item --lsign-key @var{name}
1159 Signs a public key with your secret key but marks it as
1160 non-exportable. This is a shortcut version of the subcommand "lsign"
1161 from @option{--edit-key}.
1163 @item --quick-sign-key @var{fpr} [@var{names}]
1164 @itemx --quick-lsign-key @var{fpr} [@var{names}]
1165 @opindex quick-sign-key
1166 @opindex quick-lsign-key
1167 Directly sign a key from the passphrase without any further user
1168 interaction. The @var{fpr} must be the verified primary fingerprint
1169 of a key in the local keyring. If no @var{names} are given, all
1170 useful user ids are signed; with given [@var{names}] only useful user
1171 ids matching one of these names are signed. By default, or if a name
1172 is prefixed with a '*', a case insensitive substring match is used.
1173 If a name is prefixed with a '=' a case sensitive exact match is done.
1175 The command @option{--quick-lsign-key} marks the signatures as
1176 non-exportable. If such a non-exportable signature already exists the
1177 @option{--quick-sign-key} turns it into a exportable signature. If
1178 you need to update an existing signature, for example to add or change
1179 notation data, you need to use the option @option{--force-sign-key}.
1181 This command uses reasonable defaults and thus does not provide the
1182 full flexibility of the "sign" subcommand from @option{--edit-key}.
1183 Its intended use is to help unattended key signing by utilizing a list
1184 of verified fingerprints.
1186 @item --quick-add-uid @var{user-id} @var{new-user-id}
1187 @opindex quick-add-uid
1188 This command adds a new user id to an existing key. In contrast to
1189 the interactive sub-command @code{adduid} of @option{--edit-key} the
1190 @var{new-user-id} is added verbatim with only leading and trailing
1191 white space removed, it is expected to be UTF-8 encoded, and no checks
1192 on its form are applied.
1194 @item --quick-revoke-uid @var{user-id} @var{user-id-to-revoke}
1195 @opindex quick-revoke-uid
1196 This command revokes a user ID on an existing key. It cannot be used
1197 to revoke the last user ID on key (some non-revoked user ID must
1198 remain), with revocation reason ``User ID is no longer valid''. If
1199 you want to specify a different revocation reason, or to supply
1200 supplementary revocation text, you should use the interactive
1201 sub-command @code{revuid} of @option{--edit-key}.
1203 @item --quick-revoke-sig @var{fpr} @var{signing-fpr} [@var{names}]
1204 @opindex quick-revoke-sig
1205 This command revokes the key signatures made by @var{signing-fpr} from
1206 the key specified by the fingerprint @var{fpr}. With @var{names}
1207 given only the signatures on user ids of the key matching any of the
1208 given names are affected (see @option{--quick-sign-key}). If a
1209 revocation already exists a notice is printed instead of creating a
1210 new revocation; no error is returned in this case. Note that key
1211 signature revocations may be superseded by a newer key signature and
1212 in turn again revoked.
1214 @item --quick-set-primary-uid @var{user-id} @var{primary-user-id}
1215 @opindex quick-set-primary-uid
1216 This command sets or updates the primary user ID flag on an existing
1217 key. @var{user-id} specifies the key and @var{primary-user-id} the
1218 user ID which shall be flagged as the primary user ID. The primary
1219 user ID flag is removed from all other user ids and the timestamp of
1220 all affected self-signatures is set one second ahead.
1222 @item --quick-update-pref @var{user-id}
1223 @opindex quick-update-pref
1224 This command updates the preference list of the key to the current
1225 default value (either built-in or set via
1226 @option{--default-preference-list}). This is the unattended version
1227 of of using "setpref" in the @option{--key-edit} menu without giving a
1228 list. Note that you can show the preferences in a key listing by
1229 using @option{--list-options show-pref} or @option{--list-options
1230 show-pref-verbose}. You should also re-distribute updated keys to
1233 @item --change-passphrase @var{user-id}
1234 @opindex change-passphrase
1235 @itemx --passwd @var{user-id}
1237 Change the passphrase of the secret key belonging to the certificate
1238 specified as @var{user-id}. This is a shortcut for the sub-command
1239 @code{passwd} of the @option{--edit-key} menu. When using together with the
1240 option @option{--dry-run} this will not actually change the passphrase
1241 but check that the current passphrase is correct.
1246 @c *******************************************
1247 @c *************** ****************
1248 @c *************** OPTIONS ****************
1249 @c *************** ****************
1250 @c *******************************************
1253 @section Option Summary
1255 @command{@gpgname} features a bunch of options to control the exact
1256 behaviour and to change the default configuration.
1259 * GPG Configuration Options:: How to change the configuration.
1260 * GPG Key related Options:: Key related options.
1261 * GPG Input and Output:: Input and Output.
1262 * OpenPGP Options:: OpenPGP protocol specific options.
1263 * Compliance Options:: Compliance options.
1264 * GPG Esoteric Options:: Doing things one usually doesn't want to do.
1265 * Deprecated Options:: Deprecated options.
1268 Long options can be put in an options file (default
1269 "~/.gnupg/gpg.conf"). Short option names will not work - for example,
1270 "armor" is a valid option for the options file, while "a" is not. Do not
1271 write the 2 dashes, but simply the name of the option and any required
1272 arguments. Lines with a hash ('#') as the first non-white-space
1273 character are ignored. Commands may be put in this file too, but that is
1274 not generally useful as the command will execute automatically with
1275 every execution of gpg.
1277 Please remember that option parsing stops as soon as a non-option is
1278 encountered, you can explicitly stop parsing by using the special option
1281 @c *******************************************
1282 @c ******** CONFIGURATION OPTIONS **********
1283 @c *******************************************
1284 @node GPG Configuration Options
1285 @subsection How to change the configuration
1287 These options are used to change the configuration and most of them
1288 are usually found in the option file.
1292 @item --default-key @var{name}
1293 @opindex default-key
1294 Use @var{name} as the default key to sign with. If this option is not
1295 used, the default key is the first key found in the secret keyring.
1296 Note that @option{-u} or @option{--local-user} overrides this option.
1297 This option may be given multiple times. In this case, the last key
1298 for which a secret key is available is used. If there is no secret
1299 key available for any of the specified values, GnuPG will not emit an
1300 error message but continue as if this option wasn't given.
1302 @item --default-recipient @var{name}
1303 @opindex default-recipient
1304 Use @var{name} as default recipient if option @option{--recipient} is
1305 not used and don't ask if this is a valid one. @var{name} must be
1308 @item --default-recipient-self
1309 @opindex default-recipient-self
1310 Use the default key as default recipient if option @option{--recipient} is not
1311 used and don't ask if this is a valid one. The default key is the first
1312 one from the secret keyring or the one set with @option{--default-key}.
1314 @item --no-default-recipient
1315 @opindex no-default-recipient
1316 Reset @option{--default-recipient} and @option{--default-recipient-self}.
1317 Should not be used in an option file.
1321 Give more information during processing. If used
1322 twice, the input data is listed in detail.
1326 Reset verbose level to 0. Should not be used in an option file.
1330 Try to be as quiet as possible. Should not be used in an option file.
1336 Use batch mode. Never ask, do not allow interactive commands.
1337 @option{--no-batch} disables this option. Note that even with a
1338 filename given on the command line, gpg might still need to read from
1339 STDIN (in particular if gpg figures that the input is a
1340 detached signature and no data file has been specified). Thus if you
1341 do not want to feed data via STDIN, you should connect STDIN to
1344 It is highly recommended to use this option along with the options
1345 @option{--status-fd} and @option{--with-colons} for any unattended use of
1346 @command{gpg}. Should not be used in an option file.
1350 Make sure that the TTY (terminal) is never used for any output.
1351 This option is needed in some cases because GnuPG sometimes prints
1352 warnings to the TTY even if @option{--batch} is used.
1356 Assume "yes" on most questions. Should not be used in an option file.
1360 Assume "no" on most questions. Should not be used in an option file.
1363 @item --list-filter @{select=@var{expr}@}
1364 @opindex list-filter
1365 A list filter can be used to output only certain keys during key
1366 listing commands. For the available property names, see the description
1367 of @option{--import-filter}.
1370 @item --list-options @var{parameters}
1371 @opindex list-options
1372 This is a space or comma delimited string that gives options used when
1373 listing keys and signatures (that is, @option{--list-keys},
1374 @option{--check-signatures}, @option{--list-public-keys},
1375 @option{--list-secret-keys}, and the @option{--edit-key} functions).
1376 Options can be prepended with a @option{no-} (after the two dashes) to
1377 give the opposite meaning. The options are:
1382 @opindex list-options:show-photos
1383 Causes @option{--list-keys}, @option{--check-signatures},
1384 @option{--list-public-keys}, and @option{--list-secret-keys} to
1385 display any photo IDs attached to the key. Defaults to no. See also
1386 @option{--photo-viewer}. Does not work with @option{--with-colons}:
1387 see @option{--attribute-fd} for the appropriate way to get photo data
1388 for scripts and other frontends.
1391 @opindex list-options:show-usage
1392 Show usage information for keys and subkeys in the standard key
1393 listing. This is a list of letters indicating the allowed usage for a
1394 key (@code{E}=encryption, @code{S}=signing, @code{C}=certification,
1395 @code{A}=authentication). Defaults to yes.
1397 @item show-policy-urls
1398 @opindex list-options:show-policy-urls
1399 Show policy URLs in the @option{--check-signatures}
1400 listings. Defaults to no.
1402 @item show-notations
1403 @itemx show-std-notations
1404 @itemx show-user-notations
1405 @opindex list-options:show-notations
1406 @opindex list-options:show-std-notations
1407 @opindex list-options:show-user-notations
1408 Show all, IETF standard, or user-defined signature notations in the
1409 @option{--check-signatures} listings. Defaults to no.
1411 @item show-keyserver-urls
1412 @opindex list-options:show-keyserver-urls
1413 Show any preferred keyserver URL in the
1414 @option{--check-signatures} listings. Defaults to no.
1416 @item show-uid-validity
1417 @opindex list-options:show-uid-validity
1418 Display the calculated validity of user IDs during key listings.
1421 @item show-unusable-uids
1422 @opindex list-options:show-unusable-uids
1423 Show revoked and expired user IDs in key listings. Defaults to no.
1425 @item show-unusable-subkeys
1426 @opindex list-options:show-unusable-subkeys
1427 Show revoked and expired subkeys in key listings. Defaults to no.
1429 @item show-unusable-sigs
1430 @opindex list-options:show-unusable-sigs
1431 Show key signature made using weak or unsupported algorithms.
1434 @opindex list-options:show-keyring
1435 Display the keyring name at the head of key listings to show which
1436 keyring a given key resides on. Defaults to no.
1438 @item show-sig-expire
1439 @opindex list-options:show-sig-expire
1440 Show signature expiration dates (if any) during
1441 @option{--check-signatures} listings. Defaults to no.
1443 @item show-sig-subpackets
1444 @opindex list-options:show-sig-subpackets
1445 Include signature subpackets in the key listing. This option can take an
1446 optional argument list of the subpackets to list. If no argument is
1447 passed, list all subpackets. Defaults to no. This option is only
1448 meaningful when using @option{--with-colons} along with
1449 @option{--check-signatures}.
1451 @item show-only-fpr-mbox
1452 @opindex list-options:show-only-fpr-mbox
1453 For each user-id which has a valid mail address print
1454 only the fingerprint followed by the mail address.
1457 @opindex list-options:sort-sigs
1458 With --list-sigs and --check-sigs sort the signatures by keyID and
1459 creation time to make it easier to view the history of these
1460 signatures. The self-signature is also listed before other
1461 signatures. Defaults to yes.
1465 @item --verify-options @var{parameters}
1466 @opindex verify-options
1467 This is a space or comma delimited string that gives options used when
1468 verifying signatures. Options can be prepended with a `no-' to give
1469 the opposite meaning. The options are:
1474 @opindex verify-options:show-photos
1475 Display any photo IDs present on the key that issued the signature.
1476 Defaults to no. See also @option{--photo-viewer}.
1478 @item show-policy-urls
1479 @opindex verify-options:show-policy-urls
1480 Show policy URLs in the signature being verified. Defaults to yes.
1482 @item show-notations
1483 @itemx show-std-notations
1484 @itemx show-user-notations
1485 @opindex verify-options:show-notations
1486 @opindex verify-options:show-std-notations
1487 @opindex verify-options:show-user-notations
1488 Show all, IETF standard, or user-defined signature notations in the
1489 signature being verified. Defaults to IETF standard.
1491 @item show-keyserver-urls
1492 @opindex verify-options:show-keyserver-urls
1493 Show any preferred keyserver URL in the signature being verified.
1496 @item show-uid-validity
1497 @opindex verify-options:show-uid-validity
1498 Display the calculated validity of the user IDs on the key that issued
1499 the signature. Defaults to yes.
1501 @item show-unusable-uids
1502 @opindex verify-options:show-unusable-uids
1503 Show revoked and expired user IDs during signature verification.
1506 @item show-primary-uid-only
1507 @opindex verify-options:show-primary-uid-only
1508 Show only the primary user ID during signature verification. That is
1509 all the AKA lines as well as photo Ids are not shown with the signature
1510 verification status.
1514 @item --enable-large-rsa
1515 @itemx --disable-large-rsa
1516 @opindex enable-large-rsa
1517 @opindex disable-large-rsa
1518 With --generate-key and --batch, enable the creation of RSA secret keys as
1519 large as 8192 bit. Note: 8192 bit is more than is generally
1520 recommended. These large keys don't significantly improve security,
1521 but they are more expensive to use, and their signatures and
1522 certifications are larger. This option is only available if the
1523 binary was build with large-secmem support.
1526 @itemx --disable-dsa2
1527 @opindex enable-dsa2
1528 @opindex disable-dsa2
1529 Enable hash truncation for all DSA keys even for old DSA Keys up to
1530 1024 bit. This is also the default with @option{--openpgp}. Note
1531 that older versions of GnuPG also required this flag to allow the
1532 generation of DSA larger than 1024 bit.
1534 @item --photo-viewer @var{string}
1535 @opindex photo-viewer
1536 This is the command line that should be run to view a photo ID. "%i"
1537 will be expanded to a filename containing the photo. "%I" does the
1538 same, except the file will not be deleted once the viewer exits.
1539 Other flags are "%k" for the key ID, "%K" for the long key ID, "%f"
1540 for the key fingerprint, "%t" for the extension of the image type
1541 (e.g. "jpg"), "%T" for the MIME type of the image (e.g. "image/jpeg"),
1542 "%v" for the single-character calculated validity of the image being
1543 viewed (e.g. "f"), "%V" for the calculated validity as a string (e.g.
1544 "full"), "%U" for a base32 encoded hash of the user ID,
1545 and "%%" for an actual percent sign. If neither %i or %I are present,
1546 then the photo will be supplied to the viewer on standard input.
1548 On Unix the default viewer is
1549 @code{xloadimage -fork -quiet -title 'KeyID 0x%k' STDIN}
1551 @code{display -title 'KeyID 0x%k' %i}
1555 @code{!ShellExecute 400 %i} is used; here the command is a meta
1556 command to use that API call followed by a wait time in milliseconds
1557 which is used to give the viewer time to read the temporary image file
1558 before gpg deletes it again. Note that if your image viewer program
1559 is not secure, then executing it from gpg does not make it secure.
1561 @item --exec-path @var{string}
1564 Sets a list of directories to search for photo viewers If not provided
1565 photo viewers use the @code{PATH} environment variable.
1567 @item --keyring @var{file}
1569 Add @var{file} to the current list of keyrings. If @var{file} begins
1570 with a tilde and a slash, these are replaced by the $HOME directory. If
1571 the filename does not contain a slash, it is assumed to be in the GnuPG
1572 home directory ("~/.gnupg" unless @option{--homedir} or $GNUPGHOME is
1575 Note that this adds a keyring to the current list. If the intent is to
1576 use the specified keyring alone, use @option{--keyring} along with
1577 @option{--no-default-keyring}.
1579 If the option @option{--no-keyring} has been used no keyrings will
1582 Note that if the option @option{use-keyboxd} is enabled in
1583 @file{common.conf}, no keyrings are used at all and keys are all
1584 maintained by the keyboxd process in its own database.
1586 @item --primary-keyring @var{file}
1587 @opindex primary-keyring
1588 This is a varian of @option{--keyring} and designates @var{file} as
1589 the primary public keyring. This means that newly imported keys (via
1590 @option{--import} or keyserver @option{--recv-from}) will go to this
1594 @item --secret-keyring @var{file}
1595 @opindex secret-keyring
1596 This is an obsolete option and ignored. All secret keys are stored in
1597 the @file{private-keys-v1.d} directory below the GnuPG home directory.
1599 @item --trustdb-name @var{file}
1600 @opindex trustdb-name
1601 Use @var{file} instead of the default trustdb. If @var{file} begins
1602 with a tilde and a slash, these are replaced by the $HOME directory. If
1603 the filename does not contain a slash, it is assumed to be in the GnuPG
1604 home directory (@file{~/.gnupg} if @option{--homedir} or $GNUPGHOME is
1607 @include opt-homedir.texi
1610 @item --display-charset @var{name}
1611 @opindex display-charset
1612 Set the name of the native character set. This is used to convert some
1613 informational strings like user IDs to the proper UTF-8 encoding.
1614 Note that this has nothing to do with the character set of data to be
1615 encrypted or signed; GnuPG does not recode user-supplied data. If this
1616 option is not used, the default character set is determined from the
1617 current locale. A verbosity level of 3 shows the chosen set. This
1618 option should not be used on Windows. Valid values for @var{name}
1624 @opindex display-charset:iso-8859-1
1625 This is the Latin 1 set.
1628 @opindex display-charset:iso-8859-2
1632 @opindex display-charset:iso-8859-15
1633 This is currently an alias for
1637 @opindex display-charset:koi8-r
1638 The usual Russian set (RFC-1489).
1641 @opindex display-charset:utf-8
1642 Bypass all translations and assume
1643 that the OS uses native UTF-8 encoding.
1646 @item --utf8-strings
1647 @itemx --no-utf8-strings
1648 @opindex utf8-strings
1649 Assume that command line arguments are given as UTF-8 strings. The
1650 default (@option{--no-utf8-strings}) is to assume that arguments are
1651 encoded in the character set as specified by
1652 @option{--display-charset}. These options affect all following
1653 arguments. Both options may be used multiple times.
1654 This option should not be used in an option file.
1656 This option has no effect on Windows. There the internal used UTF-8
1657 encoding is translated for console input and output. The command line
1658 arguments are expected as Unicode and translated to UTF-8. Thus when
1659 calling this program from another, make sure to use the Unicode
1660 version of CreateProcess.
1662 @anchor{gpg-option --options}
1663 @item --options @var{file}
1665 Read options from @var{file} and do not try to read them from the
1666 default options file in the homedir (see @option{--homedir}). This
1667 option is ignored if used in an options file.
1671 Shortcut for @option{--options /dev/null}. This option is detected
1672 before an attempt to open an option file. Using this option will also
1673 prevent the creation of a @file{~/.gnupg} homedir.
1676 @itemx --compress-level @var{n}
1677 @itemx --bzip2-compress-level @var{n}
1678 @itemx --no-compress
1679 @opindex compress-level
1680 @opindex bzip2-compress-level
1681 @opindex no-compress
1682 Set compression level to @var{n} for the ZIP and ZLIB compression
1683 algorithms. The default is to use the default compression level of zlib
1684 (normally 6). @option{--bzip2-compress-level} sets the compression level
1685 for the BZIP2 compression algorithm (defaulting to 6 as well). This is a
1686 different option from @option{--compress-level} since BZIP2 uses a
1687 significant amount of memory for each additional compression level.
1689 Option @option{-z} sets both. A value of 0 for @var{n} disables
1690 compression. A value of -1 forces compression using the default
1691 level. Option @option{--no-compress} is identical to @option{-z0}.
1693 Except for the @option{--store} command compression is always used
1694 unless @command{gpg} detects that the input is already compressed. To
1695 inhibit the use of compression use @option{-z0} or
1696 @option{--no-compress}; to force compression use @option{-z-1} or
1697 option @option{z} with another compression level than the default as
1698 indicated by -1. Note that this overriding of the default deection
1699 works only with @option{z} and not with the long variant of this
1703 @item --bzip2-decompress-lowmem
1704 @opindex bzip2-decompress-lowmem
1705 Use a different decompression method for BZIP2 compressed files. This
1706 alternate method uses a bit more than half the memory, but also runs
1707 at half the speed. This is useful under extreme low memory
1708 circumstances when the file was originally compressed at a high
1709 @option{--bzip2-compress-level}.
1712 @item --mangle-dos-filenames
1713 @itemx --no-mangle-dos-filenames
1714 @opindex mangle-dos-filenames
1715 @opindex no-mangle-dos-filenames
1716 Older version of Windows cannot handle filenames with more than one
1717 dot. @option{--mangle-dos-filenames} causes GnuPG to replace (rather
1718 than add to) the extension of an output filename to avoid this
1719 problem. This option is off by default and has no effect on non-Windows
1722 @item --ask-cert-level
1723 @itemx --no-ask-cert-level
1724 @opindex ask-cert-level
1725 When making a key signature, prompt for a certification level. If this
1726 option is not specified, the certification level used is set via
1727 @option{--default-cert-level}. See @option{--default-cert-level} for
1728 information on the specific levels and how they are
1729 used. @option{--no-ask-cert-level} disables this option. This option
1732 @item --default-cert-level @var{n}
1733 @opindex default-cert-level
1734 The default to use for the check level when signing a key.
1736 0 means you make no particular claim as to how carefully you verified
1739 1 means you believe the key is owned by the person who claims to own
1740 it but you could not, or did not verify the key at all. This is
1741 useful for a "persona" verification, where you sign the key of a
1744 2 means you did casual verification of the key. For example, this
1745 could mean that you verified the key fingerprint and checked the
1746 user ID on the key against a photo ID.
1748 3 means you did extensive verification of the key. For example, this
1749 could mean that you verified the key fingerprint with the owner of the
1750 key in person, and that you checked, by means of a hard to forge
1751 document with a photo ID (such as a passport) that the name of the key
1752 owner matches the name in the user ID on the key, and finally that you
1753 verified (by exchange of email) that the email address on the key
1754 belongs to the key owner.
1756 Note that the examples given above for levels 2 and 3 are just that:
1757 examples. In the end, it is up to you to decide just what "casual"
1758 and "extensive" mean to you.
1760 This option defaults to 0 (no particular claim).
1762 @item --min-cert-level
1763 @opindex min-cert-level
1764 When building the trust database, treat any signatures with a
1765 certification level below this as invalid. Defaults to 2, which
1766 disregards level 1 signatures. Note that level 0 "no particular
1767 claim" signatures are always accepted.
1769 @item --trusted-key @var{long key ID or fingerprint}
1770 @opindex trusted-key
1771 Assume that the specified key (which should be given as fingerprint)
1772 is as trustworthy as one of your own secret keys. This option is
1773 useful if you don't want to keep your secret keys (or one of them)
1774 online but still want to be able to check the validity of a given
1775 recipient's or signator's key. If the given key is not locally
1776 available but an LDAP keyserver is configured the missing key is
1777 imported from that server.
1779 @item --add-desig-revoker [sensitive:]@var{fingerprint}
1780 @opindex add-desig-revoker
1781 Add the key specified by @var{fingerprint} as a designated revoker to
1782 newly created keys. If the fingerprint is prefixed with the keyword
1783 ``sensitive:'' that info is normally not exported wit the key. This
1784 option may be given several time to add more than one designated
1785 revoker. If the keyword ``clear'' is used instead of a fingerprint,
1786 all designated options previously encountered are discarded.
1787 Designated revokers are marked on the key as non-revocable. Note that
1788 a designated revoker specified using a parameter file will also be
1792 @item --trust-model @{pgp|classic|tofu|tofu+pgp|direct|always|auto@}
1793 @opindex trust-model
1794 Set what trust model GnuPG should follow. The models are:
1799 @opindex trust-model:pgp
1800 This is the Web of Trust combined with trust signatures as used in PGP
1801 5.x and later. This is the default trust model when creating a new
1805 @opindex trust-model:classic
1806 This is the standard Web of Trust as introduced by PGP 2.
1809 @opindex trust-model:tofu
1810 @anchor{trust-model-tofu}
1811 TOFU stands for Trust On First Use. In this experimental trust
1813 time a key is seen, it is memorized. If later another key with a
1814 user id with the same email address is seen, both keys are marked as
1815 suspect. In that case, the next time either is used, a warning is
1816 displayed describing the conflict, why it might have occurred
1817 (either the user generated a new key and failed to cross sign the
1818 old and new keys, the key is forgery, or a man-in-the-middle attack
1819 is being attempted), and the user is prompted to manually confirm
1820 the validity of the key in question.
1822 Because a potential attacker is able to control the email address
1823 and thereby circumvent the conflict detection algorithm by using an
1824 email address that is similar in appearance to a trusted email
1825 address, whenever a message is verified, statistics about the number
1826 of messages signed with the key are shown. In this way, a user can
1827 easily identify attacks using fake keys for regular correspondents.
1829 When compared with the Web of Trust, TOFU offers significantly
1830 weaker security guarantees. In particular, TOFU only helps ensure
1831 consistency (that is, that the binding between a key and email
1832 address doesn't change). A major advantage of TOFU is that it
1833 requires little maintenance to use correctly. To use the web of
1834 trust properly, you need to actively sign keys and mark users as
1835 trusted introducers. This is a time-consuming process and anecdotal
1836 evidence suggests that even security-conscious users rarely take the
1837 time to do this thoroughly and instead rely on an ad-hoc TOFU
1840 In the TOFU model, policies are associated with bindings between
1841 keys and email addresses (which are extracted from user ids and
1842 normalized). There are five policies, which can be set manually
1843 using the @option{--tofu-policy} option. The default policy can be
1844 set using the @option{--tofu-default-policy} option.
1846 The TOFU policies are: @code{auto}, @code{good}, @code{unknown},
1847 @code{bad} and @code{ask}. The @code{auto} policy is used by
1848 default (unless overridden by @option{--tofu-default-policy}) and
1849 marks a binding as marginally trusted. The @code{good},
1850 @code{unknown} and @code{bad} policies mark a binding as fully
1851 trusted, as having unknown trust or as having trust never,
1852 respectively. The @code{unknown} policy is useful for just using
1853 TOFU to detect conflicts, but to never assign positive trust to a
1854 binding. The final policy, @code{ask} prompts the user to indicate
1855 the binding's trust. If batch mode is enabled (or input is
1856 inappropriate in the context), then the user is not prompted and the
1857 @code{undefined} trust level is returned.
1860 @opindex trust-model:tofu+pgp
1861 This experimental trust model combines TOFU with the Web of Trust.
1863 by computing the trust level for each model and then taking the
1864 maximum trust level where the trust levels are ordered as follows:
1865 @code{unknown < undefined < marginal < fully < ultimate < expired <
1868 By setting @option{--tofu-default-policy=unknown}, this model can be
1869 used to implement the web of trust with TOFU's conflict detection
1870 algorithm, but without its assignment of positive trust values,
1871 which some security-conscious users don't like.
1874 @opindex trust-model:direct
1875 Key validity is set directly by the user and not calculated via the
1876 Web of Trust. This model is solely based on the key and does
1877 not distinguish user IDs. Note that when changing to another trust
1878 model the trust values assigned to a key are transformed into
1879 ownertrust values, which also indicate how you trust the owner of
1880 the key to sign other keys.
1883 @opindex trust-model:always
1884 Skip key validation and assume that used keys are always fully
1885 valid. You generally won't use this unless you are using some
1886 external validation scheme. This option also suppresses the
1887 "[uncertain]" tag printed with signature checks when there is no
1888 evidence that the user ID is bound to the key. Note that this
1889 trust model still does not allow the use of expired, revoked, or
1893 @opindex trust-model:auto
1894 Select the trust model depending on whatever the internal trust
1895 database says. This is the default model if such a database already
1896 exists. Note that a tofu trust model is not considered here and
1897 must be enabled explicitly.
1900 @item --always-trust
1901 @opindex always-trust
1902 Identical to @option{--trust-model always}.
1904 @item --assert-signer @var{fpr_or_file}
1905 @opindex assert-signer
1906 This option checks whether at least one valid signature on a file has
1907 been made with the specified key. The key is either specified as a
1908 fingerprint or a file listing fingerprints. The fingerprint must be
1909 given or listed in compact format (no colons or spaces in between).
1910 This option can be given multiple times and each fingerprint is
1911 checked against the signing key as well as the corresponding primary
1912 key. If @var{fpr_or_file} specifies a file, empty lines are ignored
1913 as well as all lines starting with a hash sign. With this option gpg
1914 is guaranteed to return with an exit code of 0 if and only if a
1915 signature has been encountered, is valid, and the key matches one of
1916 the fingerprints given by this option.
1919 @item --auto-key-locate @var{mechanisms}
1920 @itemx --no-auto-key-locate
1921 @opindex auto-key-locate
1922 GnuPG can automatically locate and retrieve keys as needed using this
1923 option. This happens when encrypting to an email address (in the
1924 "user@@example.com" form), and there are no "user@@example.com" keys
1925 on the local keyring. This option takes any number of the mechanisms
1926 listed below, in the order they are to be tried. Instead of listing
1927 the mechanisms as comma delimited arguments, the option may also be
1928 given several times to add more mechanism. The option
1929 @option{--no-auto-key-locate} or the mechanism "clear" resets the
1930 list. The default is "local,wkd".
1935 Locate a key using DNS CERT, as specified in RFC-4398.
1938 Locate a key using DANE, as specified
1939 in draft-ietf-dane-openpgpkey-05.txt.
1942 Locate a key using the Web Key Directory protocol.
1945 Using DNS Service Discovery, check the domain in question for any LDAP
1946 keyservers to use. If this fails, attempt to locate the key using the
1947 PGP Universal method of checking @samp{ldap://keys.(thedomain)}.
1950 Locate the key using the Active Directory (Windows only). This
1951 method also allows to search by fingerprint using the command
1952 @option{--locate-external-key}. Note that this mechanism is
1953 actually a shortcut for the mechanism @samp{keyserver} but using
1954 "ldap:///" as the keyserver.
1957 Locate a key using a keyserver. This method also allows to search
1958 by fingerprint using the command @option{--locate-external-key} if
1959 any of the configured keyservers is an LDAP server.
1962 In addition, a keyserver URL as used in the @command{dirmngr}
1963 configuration may be used here to query that particular keyserver.
1964 This method also allows to search by fingerprint using the command
1965 @option{--locate-external-key} if the URL specifies an LDAP server.
1968 Locate the key using the local keyrings. This mechanism allows the user to
1969 select the order a local key lookup is done. Thus using
1970 @samp{--auto-key-locate local} is identical to
1971 @option{--no-auto-key-locate}.
1974 This flag disables the standard local key lookup, done before any of the
1975 mechanisms defined by the @option{--auto-key-locate} are tried. The
1976 position of this mechanism in the list does not matter. It is not
1977 required if @code{local} is also used.
1980 Clear all defined mechanisms. This is useful to override
1981 mechanisms given in a config file. Note that a @code{nodefault} in
1982 @var{mechanisms} will also be cleared unless it is given after the
1988 @item --auto-key-import
1989 @itemx --no-auto-key-import
1990 @opindex auto-key-import
1991 @opindex no-auto-key-import
1992 This is an offline mechanism to get a missing key for signature
1993 verification and for later encryption to this key. If this option is
1994 enabled and a signature includes an embedded key, that key is
1995 used to verify the signature and on verification success the key is
1996 imported. The default is @option{--no-auto-key-import}.
1998 On the sender (signing) site the option @option{--include-key-block}
1999 needs to be used to put the public part of the signing key as “Key
2000 Block subpacket” into the signature.
2002 @item --auto-key-retrieve
2003 @itemx --no-auto-key-retrieve
2004 @opindex auto-key-retrieve
2005 @opindex no-auto-key-retrieve
2006 These options enable or disable the automatic retrieving of keys from
2007 a keyserver when verifying signatures made by keys that are not on the
2008 local keyring. The default is @option{--no-auto-key-retrieve}.
2010 The order of methods tried to lookup the key is:
2012 1. If the option @option{--auto-key-import} is set and the signatures
2013 includes an embedded key, that key is used to verify the signature and
2014 on verification success that key is imported.
2016 2. If a preferred keyserver is specified in the signature and the
2017 option @option{honor-keyserver-url} is active (which is not the
2018 default), that keyserver is tried. Note that the creator of the
2019 signature uses the option @option{--sig-keyserver-url} to specify the
2020 preferred keyserver for data signatures.
2022 3. If the signature has the Signer's UID set (e.g. using
2023 @option{--sender} while creating the signature) a Web Key Directory
2024 (WKD) lookup is done. This is the default configuration but can be
2025 disabled by removing WKD from the auto-key-locate list or by using the
2026 option @option{--disable-signer-uid}.
2028 4. If any keyserver is configured and the Issuer Fingerprint is part
2029 of the signature (since GnuPG 2.1.16), the configured keyservers are
2032 Note that this option makes a "web bug" like behavior possible.
2033 Keyserver or Web Key Directory operators can see which keys you
2034 request, so by sending you a message signed by a brand new key (which
2035 you naturally will not have on your local keyring), the operator can
2036 tell both your IP address and the time when you verified the
2039 @item --keyid-format @{none|short|0xshort|long|0xlong@}
2040 @opindex keyid-format
2041 Select how to display key IDs. "none" does not show the key ID at all
2042 but shows the fingerprint in a separate line. "short" is the
2043 traditional 8-character key ID. "long" is the more accurate (but less
2044 convenient) 16-character key ID. Add an "0x" to either to include an
2045 "0x" at the beginning of the key ID, as in 0x99242560. Note that this
2046 option is ignored if the option @option{--with-colons} is used.
2048 @item --keyserver @var{name}
2050 This option is deprecated - please use the @option{--keyserver} in
2051 @file{dirmngr.conf} instead.
2053 Use @var{name} as your keyserver. This is the server that
2054 @option{--receive-keys}, @option{--send-keys}, and @option{--search-keys}
2055 will communicate with to receive keys from, send keys to, and search for
2056 keys on. The format of the @var{name} is a URI:
2057 `scheme:[//]keyservername[:port]' The scheme is the type of keyserver:
2058 "hkp"/"hkps" for the HTTP (or compatible) keyservers or "ldap"/"ldaps"
2059 for the LDAP keyservers. Note that your particular installation of
2060 GnuPG may have other keyserver types available as well. Keyserver
2061 schemes are case-insensitive.
2063 Most keyservers synchronize with each other, so there is generally no
2064 need to send keys to more than one server. The keyserver
2065 @code{hkp://keys.gnupg.net} uses round robin DNS to give a different
2066 keyserver each time you use it.
2068 @item --keyserver-options @{@var{name}=@var{value}@}
2069 @opindex keyserver-options
2070 This is a space or comma delimited string that gives options for the
2071 keyserver. Options can be prefixed with a `no-' to give the opposite
2072 meaning. Valid import-options or export-options may be used here as
2073 well to apply to importing (@option{--recv-key}) or exporting
2074 (@option{--send-key}) a key from a keyserver. While not all options
2075 are available for all keyserver types, some common options are:
2079 @item include-revoked
2080 When searching for a key with @option{--search-keys}, include keys that
2081 are marked on the keyserver as revoked. Note that not all keyservers
2082 differentiate between revoked and unrevoked keys, and for such
2083 keyservers this option is meaningless. Note also that most keyservers do
2084 not have cryptographic verification of key revocations, and so turning
2085 this option off may result in skipping keys that are incorrectly marked
2088 @item include-disabled
2089 When searching for a key with @option{--search-keys}, include keys that
2090 are marked on the keyserver as disabled. Note that this option is not
2091 used with HKP keyservers.
2093 @item auto-key-retrieve
2094 This is an obsolete alias for the option @option{auto-key-retrieve}.
2095 Please do not use it; it will be removed in future versions..
2097 @item honor-keyserver-url
2098 When using @option{--refresh-keys}, if the key in question has a preferred
2099 keyserver URL, then use that preferred keyserver to refresh the key
2100 from. In addition, if auto-key-retrieve is set, and the signature
2101 being verified has a preferred keyserver URL, then use that preferred
2102 keyserver to fetch the key from. Note that this option introduces a
2103 "web bug": The creator of the key can see when the keys is
2104 refreshed. Thus this option is not enabled by default.
2106 @item include-subkeys
2107 When receiving a key, include subkeys as potential targets. Note that
2108 this option is not used with HKP keyservers, as they do not support
2109 retrieving keys by subkey id.
2112 @itemx http-proxy=@var{value}
2117 These options have no more function since GnuPG 2.1. Use the
2118 @code{dirmngr} configuration options instead.
2122 The default list of options is: "self-sigs-only, import-clean,
2123 repair-keys, repair-pks-subkey-bug, export-attributes". However, if
2124 the actual used source is an LDAP server "no-self-sigs-only" is
2125 assumed unless "self-sigs-only" has been explicitly configured.
2128 @item --completes-needed @var{n}
2129 @opindex compliant-needed
2130 Number of completely trusted users to introduce a new
2131 key signer (defaults to 1).
2133 @item --marginals-needed @var{n}
2134 @opindex marginals-needed
2135 Number of marginally trusted users to introduce a new
2136 key signer (defaults to 3)
2138 @item --tofu-default-policy @{auto|good|unknown|bad|ask@}
2139 @opindex tofu-default-policy
2140 The default TOFU policy (defaults to @code{auto}). For more
2141 information about the meaning of this option, @pxref{trust-model-tofu}.
2143 @item --max-cert-depth @var{n}
2144 @opindex max-cert-depth
2145 Maximum depth of a certification chain (default is 5).
2147 @item --no-sig-cache
2148 @opindex no-sig-cache
2149 Do not cache the verification status of key signatures.
2150 Caching gives a much better performance in key listings. However, if
2151 you suspect that your public keyring is not safe against write
2152 modifications, you can use this option to disable the caching. It
2153 probably does not make sense to disable it because all kind of damage
2154 can be done if someone else has write access to your public keyring.
2156 @item --auto-check-trustdb
2157 @itemx --no-auto-check-trustdb
2158 @opindex auto-check-trustdb
2159 If GnuPG feels that its information about the Web of Trust has to be
2160 updated, it automatically runs the @option{--check-trustdb} command
2161 internally. This may be a time consuming
2162 process. @option{--no-auto-check-trustdb} disables this option.
2165 @itemx --no-use-agent
2167 This is dummy option. @command{@gpgname} always requires the agent.
2169 @item --gpg-agent-info
2170 @opindex gpg-agent-info
2171 This is dummy option. It has no effect when used with @command{@gpgname}.
2174 @item --agent-program @var{file}
2175 @opindex agent-program
2176 Specify an agent program to be used for secret key operations. The
2177 default value is determined by running @command{gpgconf} with the
2178 option @option{--list-dirs}. Note that the pipe symbol (@code{|}) is
2179 used for a regression test suite hack and may thus not be used in the
2182 @item --dirmngr-program @var{file}
2183 @opindex dirmngr-program
2184 Specify a dirmngr program to be used for keyserver access. The
2185 default value is @file{@value{BINDIR}/dirmngr}.
2187 @item --disable-dirmngr
2188 Entirely disable the use of the Dirmngr.
2190 @item --no-autostart
2191 @opindex no-autostart
2192 Do not start the gpg-agent or the dirmngr if it has not yet been
2193 started and its service is required. This option is mostly useful on
2194 machines where the connection to gpg-agent has been redirected to
2195 another machines. If dirmngr is required on the remote machine, it
2196 may be started manually using @command{gpgconf --launch dirmngr}.
2200 Lock the databases the first time a lock is requested
2201 and do not release the lock until the process
2204 @item --lock-multiple
2205 @opindex lock-multiple
2206 Release the locks every time a lock is no longer
2207 needed. Use this to override a previous @option{--lock-once}
2212 Disable locking entirely. This option should be used only in very
2213 special environments, where it can be assured that only one process
2214 is accessing those files. A bootable floppy with a stand-alone
2215 encryption system will probably use this. Improper usage of this
2216 option may lead to data and key corruption.
2218 @item --exit-on-status-write-error
2219 @opindex exit-on-status-write-error
2220 This option will cause write errors on the status FD to immediately
2221 terminate the process. That should in fact be the default but it never
2222 worked this way and thus we need an option to enable this, so that the
2223 change won't break applications which close their end of a status fd
2224 connected pipe too early. Using this option along with
2225 @option{--enable-progress-filter} may be used to cleanly cancel long
2226 running gpg operations.
2228 @item --limit-card-insert-tries @var{n}
2229 @opindex limit-card-insert-tries
2230 With @var{n} greater than 0 the number of prompts asking to insert a
2231 smartcard gets limited to N-1. Thus with a value of 1 gpg won't at
2232 all ask to insert a card if none has been inserted at startup. This
2233 option is useful in the configuration file in case an application does
2234 not know about the smartcard support and waits ad infinitum for an
2237 @item --no-random-seed-file
2238 @opindex no-random-seed-file
2239 GnuPG uses a file to store its internal random pool over invocations.
2240 This makes random generation faster; however sometimes write operations
2241 are not desired. This option can be used to achieve that with the cost of
2242 slower random generation.
2245 @opindex no-greeting
2246 Suppress the initial copyright message.
2248 @item --no-secmem-warning
2249 @opindex no-secmem-warning
2250 Suppress the warning about "using insecure memory".
2252 @item --no-permission-warning
2253 @opindex permission-warning
2254 Suppress the warning about unsafe file and home directory (@option{--homedir})
2255 permissions. Note that the permission checks that GnuPG performs are
2256 not intended to be authoritative, but rather they simply warn about
2257 certain common permission problems. Do not assume that the lack of a
2258 warning means that your system is secure.
2260 Note that the warning for unsafe @option{--homedir} permissions cannot be
2261 suppressed in the gpg.conf file, as this would allow an attacker to
2262 place an unsafe gpg.conf file in place, and use this file to suppress
2263 warnings about itself. The @option{--homedir} permissions warning may only be
2264 suppressed on the command line.
2266 @item --require-secmem
2267 @itemx --no-require-secmem
2268 @opindex require-secmem
2269 Refuse to run if GnuPG cannot get secure memory. Defaults to no
2270 (i.e. run, but give a warning).
2273 @item --require-cross-certification
2274 @itemx --no-require-cross-certification
2275 @opindex require-cross-certification
2276 When verifying a signature made from a subkey, ensure that the cross
2277 certification "back signature" on the subkey is present and valid. This
2278 protects against a subtle attack against subkeys that can sign.
2279 Defaults to @option{--require-cross-certification} for
2285 Allow the user to do certain nonsensical or "silly" things like
2286 signing an expired or revoked key, or certain potentially incompatible
2287 things like generating unusual key types. This also disables certain
2288 warning messages about potentially incompatible actions. As the name
2289 implies, this option is for experts only. If you don't fully
2290 understand the implications of what it allows you to do, leave this
2291 off. @option{--no-expert} disables this option.
2296 @c *******************************************
2297 @c ******** KEY RELATED OPTIONS ************
2298 @c *******************************************
2299 @node GPG Key related Options
2300 @subsection Key related options
2304 @item --recipient @var{name}
2307 Encrypt for user id @var{name}. If this option or
2308 @option{--hidden-recipient} is not specified, GnuPG asks for the user-id
2309 unless @option{--default-recipient} is given.
2311 @item --hidden-recipient @var{name}
2313 @opindex hidden-recipient
2314 Encrypt for user ID @var{name}, but hide the key ID of this user's
2315 key. This option helps to hide the receiver of the message and is a
2316 limited countermeasure against traffic analysis. If this option or
2317 @option{--recipient} is not specified, GnuPG asks for the user ID unless
2318 @option{--default-recipient} is given.
2320 @item --recipient-file @var{file}
2322 @opindex recipient-file
2323 This option is similar to @option{--recipient} except that it
2324 encrypts to a key stored in the given file. @var{file} must be the
2325 name of a file containing exactly one key. @command{@gpgname} assumes that
2326 the key in this file is fully valid.
2328 @item --hidden-recipient-file @var{file}
2330 @opindex hidden-recipient-file
2331 This option is similar to @option{--hidden-recipient} except that it
2332 encrypts to a key stored in the given file. @var{file} must be the
2333 name of a file containing exactly one key. @command{@gpgname} assumes that
2334 the key in this file is fully valid.
2336 @item --encrypt-to @var{name}
2338 Same as @option{--recipient} but this one is intended for use in the
2339 options file and may be used with your own user-id as an
2340 "encrypt-to-self". These keys are only used when there are other
2341 recipients given either by use of @option{--recipient} or by the asked
2342 user id. No trust checking is performed for these user ids and even
2343 disabled keys can be used.
2345 @item --hidden-encrypt-to @var{name}
2346 @opindex hidden-encrypt-to
2347 Same as @option{--hidden-recipient} but this one is intended for use in the
2348 options file and may be used with your own user-id as a hidden
2349 "encrypt-to-self". These keys are only used when there are other
2350 recipients given either by use of @option{--recipient} or by the asked user id.
2351 No trust checking is performed for these user ids and even disabled
2354 @item --no-encrypt-to
2355 @opindex no-encrypt-to
2356 Disable the use of all @option{--encrypt-to} and
2357 @option{--hidden-encrypt-to} keys.
2359 @item --group @{@var{name}=@var{value}@}
2361 Sets up a named group, which is similar to aliases in email programs.
2362 Any time the group name is a recipient (@option{-r} or
2363 @option{--recipient}), it will be expanded to the values
2364 specified. Multiple groups with the same name are automatically merged
2365 into a single group.
2367 The values are @code{key IDs} or fingerprints, but any key description
2368 is accepted. Note that a value with spaces in it will be treated as
2369 two different values. Note also there is only one level of expansion
2370 --- you cannot make an group that points to another group. When used
2371 from the command line, it may be necessary to quote the argument to
2372 this option to prevent the shell from treating it as multiple
2375 @item --ungroup @var{name}
2377 Remove a given entry from the @option{--group} list.
2381 Remove all entries from the @option{--group} list.
2383 @item --local-user @var{name}
2386 Use @var{name} as the key to sign with. Note that this option overrides
2387 @option{--default-key}.
2389 @item --sender @var{mbox}
2391 This option has two purposes. @var{mbox} must either be a complete
2392 user ID containing a proper mail address or just a plain mail address.
2393 The option can be given multiple times.
2395 When creating a signature this option tells gpg the signing key's user
2396 id used to make the signature and embeds that user ID into the created
2397 signature (using OpenPGP's ``Signer's User ID'' subpacket). If the
2398 option is given multiple times a suitable user ID is picked. However,
2399 if the signing key was specified directly by using a mail address
2400 (i.e. not by using a fingerprint or key ID) this option is used and
2401 the mail address is embedded in the created signature.
2403 When verifying a signature @var{mbox} is used to restrict the
2404 information printed by the TOFU code to matching user IDs. If the
2405 option is used and the signature contains a ``Signer's User ID''
2406 subpacket that information is is also used to restrict the printed
2407 information. Note that GnuPG considers only the mail address part of
2410 If this option or the said subpacket is available the TRUST lines as
2411 printed by option @option{status-fd} correspond to the corresponding
2412 User ID; if no User ID is known the TRUST lines are computed directly
2413 on the key and do not give any information about the User ID. In the
2414 latter case it his highly recommended to scripts and other frontends
2415 to evaluate the VALIDSIG line, retrieve the key and print all User IDs
2416 along with their validity (trust) information.
2419 @item --try-secret-key @var{name}
2420 @opindex try-secret-key
2421 For hidden recipients GPG needs to know the keys to use for trial
2422 decryption. The key set with @option{--default-key} is always tried
2423 first, but this is often not sufficient. This option allows setting more
2424 keys to be used for trial decryption. Although any valid user-id
2425 specification may be used for @var{name} it makes sense to use at least
2426 the long keyid to avoid ambiguities. Note that gpg-agent might pop up a
2427 pinentry for a lot keys to do the trial decryption. If you want to stop
2428 all further trial decryption you may use close-window button instead of
2431 @item --try-all-secrets
2432 @opindex try-all-secrets
2433 Don't look at the key ID as stored in the message but try all secret
2434 keys in turn to find the right decryption key. This option forces the
2435 behaviour as used by anonymous recipients (created by using
2436 @option{--throw-keyids} or @option{--hidden-recipient}) and might come
2437 handy in case where an encrypted message contains a bogus key ID.
2439 @item --skip-hidden-recipients
2440 @itemx --no-skip-hidden-recipients
2441 @opindex skip-hidden-recipients
2442 @opindex no-skip-hidden-recipients
2443 During decryption skip all anonymous recipients. This option helps in
2444 the case that people use the hidden recipients feature to hide their
2445 own encrypt-to key from others. If one has many secret keys this
2446 may lead to a major annoyance because all keys are tried in turn to
2447 decrypt something which was not really intended for it. The drawback
2448 of this option is that it is currently not possible to decrypt a
2449 message which includes real anonymous recipients.
2454 @c *******************************************
2455 @c ******** INPUT AND OUTPUT ***************
2456 @c *******************************************
2457 @node GPG Input and Output
2458 @subsection Input and Output
2465 Create ASCII armored output. The default is to create the binary
2470 Assume the input data is not in ASCII armored format.
2472 @item --output @var{file}
2473 @itemx -o @var{file}
2475 Write output to @var{file}. To write to stdout use @code{-} as the
2478 @item --max-output @var{n}
2480 This option sets a limit on the number of bytes that will be generated
2481 when processing a file. Since OpenPGP supports various levels of
2482 compression, it is possible that the plaintext of a given message may be
2483 significantly larger than the original OpenPGP message. While GnuPG
2484 works properly with such messages, there is often a desire to set a
2485 maximum file size that will be generated before processing is forced to
2486 stop by the OS limits. Defaults to 0, which means "no limit".
2488 @item --chunk-size @var{n}
2490 The AEAD encryption mode encrypts the data in chunks so that a
2491 receiving side can check for transmission errors or tampering at the
2492 end of each chunk and does not need to delay this until all data has
2493 been received. The used chunk size is 2^@var{n} byte. The lowest
2494 allowed value for @var{n} is 6 (64 byte) and the largest is the
2495 default of 22 which creates chunks not larger than 4 MiB.
2497 @item --input-size-hint @var{n}
2498 @opindex input-size-hint
2499 This option can be used to tell GPG the size of the input data in
2500 bytes. @var{n} must be a positive base-10 number. This option is
2501 only useful if the input is not taken from a file. GPG may use this
2502 hint to optimize its buffer allocation strategy. It is also used by
2503 the @option{--status-fd} line ``PROGRESS'' to provide a value for
2504 ``total'' if that is not available by other means.
2506 @item --key-origin @var{string}[,@var{url}]
2508 gpg can track the origin of a key. Certain origins are implicitly
2509 known (e.g. keyserver, web key directory) and set. For a standard
2510 import the origin of the keys imported can be set with this option.
2511 To list the possible values use "help" for @var{string}. Some origins
2512 can store an optional @var{url} argument. That URL can appended to
2513 @var{string} after a comma.
2515 @item --import-options @var{parameters}
2516 @opindex import-options
2517 This is a space or comma delimited string that gives options for
2518 importing keys. Options can be prepended with a `no-' to give the
2519 opposite meaning. The options are:
2523 @item import-local-sigs
2524 Allow importing key signatures marked as "local". This is not
2525 generally useful unless a shared keyring scheme is being used.
2528 @item keep-ownertrust
2529 Normally possible still existing ownertrust values of a key are
2530 cleared if a key is imported. This is in general desirable so that
2531 a formerly deleted key does not automatically gain an ownertrust
2532 values merely due to import. On the other hand it is sometimes
2533 necessary to re-import a trusted set of keys again but keeping
2534 already assigned ownertrust values. This can be achieved by using
2537 @item repair-pks-subkey-bug
2538 During import, attempt to repair the damage caused by the PKS keyserver
2539 bug (pre version 0.9.6) that mangles keys with multiple subkeys. Note
2540 that this cannot completely repair the damaged key as some crucial data
2541 is removed by the keyserver, but it does at least give you back one
2542 subkey. Defaults to no for regular @option{--import} and to yes for
2543 keyserver @option{--receive-keys}.
2547 Show a listing of the key as imported right before it is stored.
2548 This can be combined with the option @option{--dry-run} to only look
2549 at keys; the option @option{show-only} is a shortcut for this
2550 combination. The command @option{--show-keys} is another shortcut
2551 for this. Note that suffixes like '#' for "sec" and "sbb" lines
2552 may or may not be printed.
2555 Run the entire import code but instead of storing the key to the
2556 local keyring write it to the output. The export option
2557 @option{export-dane} affect the output. This option can for example
2558 be used to remove all invalid parts from a key without the
2562 During import, allow key updates to existing keys, but do not allow
2563 any new keys to be imported. Defaults to no.
2566 After import, compact (remove all signatures except the
2567 self-signature) any user IDs from the new key that are not usable.
2568 Then, remove any signatures from the new key that are not usable.
2569 This includes signatures that were issued by keys that are not present
2570 on the keyring. This option is the same as running the @option{--edit-key}
2571 command "clean" after import. Defaults to no.
2573 @item self-sigs-only
2574 Accept only self-signatures while importing a key. All other key
2575 signatures are skipped at an early import stage. This option can be
2576 used with @code{keyserver-options} to mitigate attempts to flood a
2577 key with bogus signatures from a keyserver. The drawback is that
2578 all other valid key signatures, as required by the Web of Trust are
2579 also not imported. Note that when using this option along with
2580 import-clean it suppresses the final clean step after merging the
2581 imported key into the existing key.
2584 After import, fix various problems with the
2585 keys. For example, this reorders signatures, and strips duplicate
2586 signatures. Defaults to yes.
2589 When used the keyboxd (option @option{use-keyboxd} in @file{common.conf})
2590 does the import within a single
2593 @item import-minimal
2594 Import the smallest key possible. This removes all signatures except
2595 the most recent self-signature on each user ID. This option is the
2596 same as running the @option{--edit-key} command "minimize" after import.
2600 @itemx import-restore
2601 Import in key restore mode. This imports all data which is usually
2602 skipped during import; including all GnuPG specific data. All other
2603 contradicting options are overridden.
2606 @item --import-filter @{@var{name}=@var{expr}@}
2607 @itemx --export-filter @{@var{name}=@var{expr}@}
2608 @opindex import-filter
2609 @opindex export-filter
2610 These options define an import/export filter which are applied to the
2611 imported/exported keyblock right before it will be stored/written.
2612 @var{name} defines the type of filter to use, @var{expr} the
2613 expression to evaluate. The option can be used several times which
2614 then appends more expression to the same @var{name}.
2617 The available filter types are:
2622 This filter will keep a user id packet and its dependent packets in
2623 the keyblock if the expression evaluates to true.
2626 This filter drops the selected subkeys.
2627 Currently only implemented for --export-filter.
2630 This filter drops the selected key signatures on user ids.
2631 Self-signatures are not considered.
2632 Currently only implemented for --import-filter.
2635 This filter is only implemented by @option{--list-filter}. All
2636 property names may be used.
2640 For the syntax of the expression see the chapter "FILTER EXPRESSIONS".
2641 The property names for the expressions depend on the actual filter
2642 type and are indicated in the following table. Note that all property
2643 names may also be used by @option{--list-filter}.
2645 Property names may be prefix with a scope delimited by a slash. Valid
2646 scopes are "pub" for public and secret primary keys, "sub" for public
2647 and secret subkeys, "uid" for for user-ID packets, and "sig" for
2648 signature packets. Invalid scopes are currently ignored.
2650 The available properties are:
2655 A string with the user id. (keep-uid)
2658 The addr-spec part of a user id with mailbox or the empty string.
2662 A string with the key algorithm description. For example "rsa3072"
2666 A number with the public key algorithm of a key or subkey packet.
2670 A number with the effective key size of a key or subkey packet.
2674 @itemx key_created_d
2675 The first is the timestamp a public key or subkey packet was
2676 created. The second is the same but given as an ISO string,
2677 e.g. "2016-08-17". (drop-subkey)
2680 @itemx key_expires_d
2681 The expiration time of a public key or subkey or 0 if it does not
2682 expire. The second is the same but given as an ISO date string or
2683 an empty string e.g. "2038-01-19".
2686 The hexified fingerprint of the current subkey or primary key.
2690 Boolean indicating whether the user id is the primary one. (keep-uid)
2693 Boolean indicating whether a user id (keep-uid), a key (drop-subkey), or a
2694 signature (drop-sig) expired.
2697 Boolean indicating whether a user id (keep-uid) or a key (drop-subkey) has
2701 Boolean indicating whether a primary key is disabled.
2704 Boolean indicating whether a key or subkey is a secret one.
2708 A string indicating the usage flags for the subkey, from the
2709 sequence ``ecsa?''. For example, a subkey capable of just signing
2710 and authentication would be an exact match for ``sa''. (drop-subkey)
2713 @itemx sig_created_d
2714 The first is the timestamp a signature packet was created. The
2715 second is the same but given as an ISO date string,
2716 e.g. "2016-08-17". (drop-sig)
2719 A number with the public key algorithm of a signature packet. (drop-sig)
2721 @item sig_digest_algo
2722 A number with the digest algorithm of a signature packet. (drop-sig)
2725 A string with the key origin or a question mark. For example the
2726 string ``wkd'' is used if a key originated from a Web Key Directory
2730 The timestamp the key was last updated from a keyserver or the Web
2734 A string with the the URL associated wit the last key lookup.
2738 @item --export-options @var{parameters}
2739 @opindex export-options
2740 This is a space or comma delimited string that gives options for
2741 exporting keys. Options can be prepended with a `no-' to give the
2742 opposite meaning. The options are:
2746 @item export-local-sigs
2747 Allow exporting key signatures marked as "local". This is not
2748 generally useful unless a shared keyring scheme is being used.
2751 @item export-attributes
2752 Include attribute user IDs (photo IDs) while exporting. Not
2753 including attribute user IDs is useful to export keys that are going
2754 to be used by an OpenPGP program that does not accept attribute user
2755 IDs. Defaults to yes.
2757 @item export-sensitive-revkeys
2758 Include designated revoker information that was marked as
2759 "sensitive". Defaults to no.
2761 @c Since GnuPG 2.1 gpg-agent manages the secret key and thus the
2762 @c export-reset-subkey-passwd hack is not anymore justified. Such use
2763 @c cases may be implemented using a specialized secret key export
2765 @c @item export-reset-subkey-passwd
2766 @c When using the @option{--export-secret-subkeys} command, this option resets
2767 @c the passphrases for all exported subkeys to empty. This is useful
2768 @c when the exported subkey is to be used on an unattended machine where
2769 @c a passphrase doesn't necessarily make sense. Defaults to no.
2772 @itemx export-backup
2773 Export for use as a backup. The exported data includes all data
2774 which is needed to restore the key or keys later with GnuPG. The
2775 format is basically the OpenPGP format but enhanced with GnuPG
2776 specific data. All other contradicting options are overridden.
2779 Compact (remove all signatures from) user IDs on the key being
2780 exported if the user IDs are not usable. Also, do not export any
2781 signatures that are not usable. This includes signatures that were
2782 issued by keys that are not present on the keyring. This option is
2783 the same as running the @option{--edit-key} command "clean" before export
2784 except that the local copy of the key is not modified. Defaults to
2787 @item export-minimal
2788 Export the smallest key possible. This removes all signatures except the
2789 most recent self-signature on each user ID. This option is the same as
2790 running the @option{--edit-key} command "minimize" before export except
2791 that the local copy of the key is not modified. Defaults to no.
2794 Export only standalone revocation certificates of the key. This
2795 option does not export revocations of 3rd party certificate
2799 Instead of outputting the key material output OpenPGP DANE records
2800 suitable to put into DNS zone files. An ORIGIN line is printed before
2801 each record to allow diverting the records to the corresponding zone
2805 Enable the use of a new secret key export format. This format
2806 avoids the re-encryption as required with the current OpenPGP format
2807 and also improves the security of the secret key if it has been
2808 protected with a passphrase. Note that an unprotected key is
2809 exported as-is and thus not secure; the general rule to convey
2810 secret keys in an OpenPGP encrypted file still applies with this
2811 mode. Versions of GnuPG before 2.4.0 are not able to import such a
2817 @opindex with-colons
2818 Print key listings delimited by colons. Note that the output will be
2819 encoded in UTF-8 regardless of any @option{--display-charset} setting. This
2820 format is useful when GnuPG is called from scripts and other programs
2821 as it is easily machine parsed. The details of this format are
2822 documented in the file @file{doc/DETAILS}, which is included in the GnuPG
2823 source distribution.
2825 @item --fixed-list-mode
2826 @opindex fixed-list-mode
2827 Do not merge primary user ID and primary key in @option{--with-colon}
2828 listing mode and print all timestamps as seconds since 1970-01-01.
2829 Since GnuPG 2.0.10, this mode is always used and thus this option is
2830 obsolete; it does not harm to use it though.
2832 @item --legacy-list-mode
2833 @opindex legacy-list-mode
2834 Revert to the pre-2.1 public key list mode. This only affects the
2835 human readable output and not the machine interface
2836 (i.e. @code{--with-colons}). Note that the legacy format does not
2837 convey suitable information for elliptic curves.
2839 @item --with-fingerprint
2840 @opindex with-fingerprint
2841 Same as the command @option{--fingerprint} but changes only the format
2842 of the output and may be used together with another command.
2844 @item --with-subkey-fingerprint
2845 @opindex with-subkey-fingerprint
2846 If a fingerprint is printed for the primary key, this option forces
2847 printing of the fingerprint for all subkeys. This could also be
2848 achieved by using the @option{--with-fingerprint} twice but by using
2849 this option along with keyid-format "none" a compact fingerprint is
2852 @item --with-icao-spelling
2853 @opindex with-icao-spelling
2854 Print the ICAO spelling of the fingerprint in addition to the hex digits.
2856 @item --with-keygrip
2857 @opindex with-keygrip
2858 Include the keygrip in the key listings. In @code{--with-colons} mode
2859 this is implicitly enable for secret keys.
2861 @item --with-key-origin
2862 @opindex with-key-origin
2863 Include the locally held information on the origin and last update of
2864 a key in a key listing. In @code{--with-colons} mode this is always
2865 printed. This data is currently experimental and shall not be
2866 considered part of the stable API.
2868 @item --with-wkd-hash
2869 @opindex with-wkd-hash
2870 Print a Web Key Directory identifier along with each user ID in key
2871 listings. This is an experimental feature and semantics may change.
2874 @opindex with-secret
2875 Include info about the presence of a secret key in public key listings
2876 done with @code{--with-colons}.
2880 @c *******************************************
2881 @c ******** OPENPGP OPTIONS ****************
2882 @c *******************************************
2883 @node OpenPGP Options
2884 @subsection OpenPGP protocol specific options
2888 @item -t, --textmode
2889 @itemx --no-textmode
2891 Treat input files as text and store them in the OpenPGP canonical text
2892 form with standard "CRLF" line endings. This also sets the necessary
2893 flags to inform the recipient that the encrypted or signed data is text
2894 and may need its line endings converted back to whatever the local
2895 system uses. This option is useful when communicating between two
2896 platforms that have different line ending conventions (UNIX-like to Mac,
2897 Mac to Windows, etc). @option{--no-textmode} disables this option, and
2900 @item --force-v3-sigs
2901 @itemx --no-force-v3-sigs
2902 @item --force-v4-certs
2903 @itemx --no-force-v4-certs
2904 These options are obsolete and have no effect since GnuPG 2.1.
2910 Force the use of AEAD encryption over MDC encryption. AEAD is a
2911 modern and faster way to do authenticated encryption than the old MDC
2912 method. @option{--force-aead} is an alias and deprecated. See also
2913 option @option{--chunk-size}.
2916 @itemx --disable-mdc
2918 @opindex disable-mdc
2919 These options are obsolete and have no effect since GnuPG 2.2.8. The
2920 MDC is always used unless the keys indicate that an AEAD algorithm can
2921 be used in which case AEAD is used. But note: If the creation of a
2922 legacy non-MDC message is exceptionally required, the option
2923 @option{--rfc2440} allows for this.
2925 @item --disable-signer-uid
2926 @opindex disable-signer-uid
2927 By default the user ID of the signing key is embedded in the data signature.
2928 As of now this is only done if the signing key has been specified with
2929 @option{local-user} using a mail address, or with @option{sender}. This
2930 information can be helpful for verifier to locate the key; see option
2931 @option{--auto-key-retrieve}.
2933 @item --include-key-block
2934 @itemx --no-include-key-block
2935 @opindex include-key-block
2936 @opindex no-include-key-block
2937 This option is used to embed the actual signing key into a data
2938 signature. The embedded key is stripped down to a single user id and
2939 includes only the signing subkey used to create the signature as well
2940 as as valid encryption subkeys. All other info is removed from the
2941 key to keep it and thus the signature small. This option is the
2942 OpenPGP counterpart to the @command{gpgsm} option
2943 @option{--include-certs} and allows the recipient of a signed message
2944 to reply encrypted to the sender without using any online directories
2945 to lookup the key. The default is @option{--no-include-key-block}.
2946 See also the option @option{--auto-key-import}.
2948 @item --personal-cipher-preferences @var{string}
2949 @opindex personal-cipher-preferences
2950 Set the list of personal cipher preferences to @var{string}. Use
2951 @command{@gpgname --version} to get a list of available algorithms,
2952 and use @code{none} to set no preference at all. This allows the user
2953 to safely override the algorithm chosen by the recipient key
2954 preferences, as GPG will only select an algorithm that is usable by
2955 all recipients. The most highly ranked cipher in this list is also
2956 used for the @option{--symmetric} encryption command.
2958 @item --personal-digest-preferences @var{string}
2959 @opindex personal-digest-preferences
2960 Set the list of personal digest preferences to @var{string}. Use
2961 @command{@gpgname --version} to get a list of available algorithms,
2962 and use @code{none} to set no preference at all. This allows the user
2963 to safely override the algorithm chosen by the recipient key
2964 preferences, as GPG will only select an algorithm that is usable by
2965 all recipients. The most highly ranked digest algorithm in this list
2966 is also used when signing without encryption
2967 (e.g. @option{--clear-sign} or @option{--sign}).
2969 @item --personal-compress-preferences @var{string}
2970 @opindex personal-compress-preferences
2971 Set the list of personal compression preferences to @var{string}.
2972 Use @command{@gpgname --version} to get a list of available
2973 algorithms, and use @code{none} to set no preference at all. This
2974 allows the user to safely override the algorithm chosen by the
2975 recipient key preferences, as GPG will only select an algorithm that
2976 is usable by all recipients. The most highly ranked compression
2977 algorithm in this list is also used when there are no recipient keys
2978 to consider (e.g. @option{--symmetric}).
2980 @item --s2k-cipher-algo @var{name}
2981 @opindex s2k-cipher-algo
2982 Use @var{name} as the cipher algorithm for symmetric encryption with
2983 a passphrase if @option{--personal-cipher-preferences} and
2984 @option{--cipher-algo} are not given. The default is @value{GPGSYMENCALGO}.
2986 @item --s2k-digest-algo @var{name}
2987 @opindex s2k-digest-algo
2988 Use @var{name} as the digest algorithm used to mangle the passphrases
2989 for symmetric encryption. The default is SHA-1.
2991 @item --s2k-mode @var{n}
2993 Selects how passphrases for symmetric encryption are mangled. If
2994 @var{n} is 0 a plain passphrase (which is in general not recommended)
2995 will be used, a 1 adds a salt (which should not be used) to the
2996 passphrase and a 3 (the default) iterates the whole process a number
2997 of times (see @option{--s2k-count}).
2999 @item --s2k-count @var{n}
3001 Specify how many times the passphrases mangling for symmetric
3002 encryption is repeated. This value may range between 1024 and
3003 65011712 inclusive. The default is inquired from gpg-agent. Note
3004 that not all values in the 1024-65011712 range are legal and if an
3005 illegal value is selected, GnuPG will round up to the nearest legal
3006 value. This option is only meaningful if @option{--s2k-mode} is set
3007 to the default of 3.
3012 @c ***************************
3013 @c ******* Compliance ********
3014 @c ***************************
3015 @node Compliance Options
3016 @subsection Compliance options
3018 These options control what GnuPG is compliant to. Only one of these
3019 options may be active at a time. Note that the default setting of
3020 this is nearly always the correct one. See the INTEROPERABILITY WITH
3021 OTHER OPENPGP PROGRAMS section below before using one of these
3028 Use standard GnuPG behavior. This is essentially OpenPGP behavior (see
3029 @option{--openpgp}), but with extension from the proposed update to
3030 OpenPGP and with some additional workarounds for common compatibility
3031 problems in different versions of PGP. This is the default option, so
3032 it is not generally needed, but it may be useful to override a
3033 different compliance option in the gpg.conf file.
3037 Reset all packet, cipher and digest options to strict OpenPGP
3038 behavior. This option implies @option{--allow-old-cipher-algos}. Use
3039 this option to reset all previous options like @option{--s2k-*},
3040 @option{--cipher-algo}, @option{--digest-algo} and
3041 @option{--compress-algo} to OpenPGP compliant values. All PGP
3042 workarounds are disabled.
3046 Reset all packet, cipher and digest options to strict RFC-4880
3047 behavior. This option implies @option{--allow-old-cipher-algos}.
3048 Note that this is currently the same thing as @option{--openpgp}.
3052 Reset all packet, cipher and digest options to strict according to the
3053 proposed updates of RFC-4880.
3057 Reset all packet, cipher and digest options to strict RFC-2440
3058 behavior. Note that by using this option encryption packets are
3059 created in a legacy mode without MDC protection. This is dangerous
3060 and should thus only be used for experiments. This option implies
3061 @option{--allow-old-cipher-algos}. See also option
3062 @option{--ignore-mdc-error}.
3066 This option is obsolete; it is handled as an alias for @option{--pgp7}
3070 Set up all options to be as PGP 7 compliant as possible. This allowed
3071 the ciphers IDEA, 3DES, CAST5,AES128, AES192, AES256, and TWOFISH.,
3072 the hashes MD5, SHA1 and RIPEMD160, and the compression algorithms
3073 none and ZIP. This option implies @option{--escape-from-lines} and
3074 disables @option{--throw-keyids},
3078 Set up all options to be as PGP 8 compliant as possible. PGP 8 is a lot
3079 closer to the OpenPGP standard than previous versions of PGP, so all
3080 this does is disable @option{--throw-keyids} and set
3081 @option{--escape-from-lines}. All algorithms are allowed except for the
3082 SHA224, SHA384, and SHA512 digests.
3084 @item --compliance @var{string}
3086 This option can be used instead of one of the options above. Valid
3087 values for @var{string} are the above option names (without the double
3088 dash) and possibly others as shown when using "help" for @var{string}.
3090 @item --min-rsa-length @var{n}
3091 @opindex min-rsa-length
3092 This option adjusts the compliance mode "de-vs" for stricter key size
3093 requirements. For example, a value of 3000 turns rsa2048 and dsa2048
3094 keys into non-VS-NfD compliant keys.
3096 @item --require-compliance
3097 @opindex require-compliance
3098 To check that data has been encrypted according to the rules of the
3099 current compliance mode, a gpg user needs to evaluate the status
3100 lines. This is allows frontends to handle compliance check in a more
3101 flexible way. However, for scripted use the required evaluation of
3102 the status-line requires quite some effort; this option can be used
3103 instead to make sure that the gpg process exits with a failure if the
3104 compliance rules are not fulfilled. Note that this option has
3105 currently an effect only in "de-vs" mode.
3110 @c *******************************************
3111 @c ******** ESOTERIC OPTIONS ***************
3112 @c *******************************************
3113 @node GPG Esoteric Options
3114 @subsection Doing things one usually doesn't want to do
3121 Don't make any changes (this is not completely implemented).
3125 Changes the behaviour of some commands. This is like @option{--dry-run} but
3126 different in some cases. The semantic of this option may be extended in
3127 the future. Currently it only skips the actual decryption pass and
3128 therefore enables a fast listing of the encryption keys.
3131 @itemx --interactive
3132 @opindex interactive
3133 Prompt before overwriting any files.
3135 @item --compatibility-flags @var{flags}
3136 @opindex compatibility-flags
3137 Set compatibility flags to work around problems due to non-compliant
3138 keys or data. The @var{flags} are given as a comma separated
3139 list of flag names and are OR-ed together. The special flag "none"
3140 clears the list and allows to start over with an empty list. To get a
3141 list of available flags the sole word "help" can be used.
3143 @item --debug-level @var{level}
3144 @opindex debug-level
3145 Select the debug level for investigating problems. @var{level} may be
3146 a numeric value or by a keyword:
3150 No debugging at all. A value of less than 1 may be used instead of
3153 Some basic debug messages. A value between 1 and 2 may be used
3154 instead of the keyword.
3156 More verbose debug messages. A value between 3 and 5 may be used
3157 instead of the keyword.
3159 Even more detailed messages. A value between 6 and 8 may be used
3160 instead of the keyword.
3162 All of the debug messages you can get. A value greater than 8 may be
3163 used instead of the keyword. The creation of hash tracing files is
3164 only enabled if the keyword is used.
3167 How these messages are mapped to the actual debugging flags is not
3168 specified and may change with newer releases of this program. They are
3169 however carefully selected to best aid in debugging.
3171 @item --debug @var{flags}
3173 Set debug flags. All flags are or-ed and @var{flags} may be given
3174 in C syntax (e.g. 0x0042) or as a comma separated list of flag names.
3175 To get a list of all supported flags the single word "help" can be
3176 used. This option is only useful for debugging and the behavior may
3177 change at any time without notice.
3181 Set all useful debugging flags.
3184 @opindex debug-iolbf
3185 Set stdout into line buffered mode. This option is only honored when
3186 given on the command line.
3188 @item --debug-set-iobuf-size @var{n}
3189 @opindex debug-iolbf
3190 Change the buffer size of the IOBUFs to @var{n} kilobyte. Using 0
3191 prints the current size. Note well: This is a maintainer only option
3192 and may thus be changed or removed at any time without notice.
3194 @item --debug-allow-large-chunks
3195 @opindex debug-allow-large-chunks
3196 To facilitate software tests and experiments this option allows to
3197 specify a limit of up to 4 EiB (@code{--chunk-size 62}).
3199 @item --debug-ignore-expiration
3200 @opindex debug-ignore-expiration
3201 This option tries to override certain key expiration dates. It is
3202 only useful for certain regression tests.
3204 @item --faked-system-time @var{epoch}
3205 @opindex faked-system-time
3206 This option is only useful for testing; it sets the system time back
3207 or forth to @var{epoch} which is the number of seconds elapsed since
3208 the year 1970. Alternatively @var{epoch} may be given as a full ISO
3209 time string (e.g. "20070924T154812").
3211 If you suffix @var{epoch} with an exclamation mark (!), the system time
3212 will appear to be frozen at the specified time.
3214 @item --full-timestrings
3215 @opindex full-timestrings
3216 Change the format of printed creation and expiration times from just
3217 the date to the date and time. This is in general not useful and the
3218 same information is anyway available in @option{--with-colons} mode.
3219 These longer strings are also not well aligned with other printed
3222 @item --enable-progress-filter
3223 @opindex enable-progress-filter
3224 Enable certain PROGRESS status outputs. This option allows frontends
3225 to display a progress indicator while gpg is processing larger files.
3226 There is a slight performance overhead using it.
3228 @item --status-fd @var{n}
3230 Write special status strings to the file descriptor @var{n}.
3231 See the file DETAILS in the documentation for a listing of them.
3233 @item --status-file @var{file}
3234 @opindex status-file
3235 Same as @option{--status-fd}, except the status data is written to file
3238 @item --logger-fd @var{n}
3240 Write log output to file descriptor @var{n} and not to STDERR.
3242 @item --log-file @var{file}
3243 @itemx --logger-file @var{file}
3245 Same as @option{--logger-fd}, except the logger data is written to
3246 file @var{file}. Use @file{socket://} to log to s socket.
3250 Prefix all log output with a timestamp even if no log file is used.
3252 @item --attribute-fd @var{n}
3253 @opindex attribute-fd
3254 Write attribute subpackets to the file descriptor @var{n}. This is most
3255 useful for use with @option{--status-fd}, since the status messages are
3256 needed to separate out the various subpackets from the stream delivered
3257 to the file descriptor.
3259 @item --attribute-file @var{file}
3260 @opindex attribute-file
3261 Same as @option{--attribute-fd}, except the attribute data is written to
3264 @item --comment @var{string}
3265 @itemx --no-comments
3267 Use @var{string} as a comment string in cleartext signatures and ASCII
3268 armored messages or keys (see @option{--armor}). The default behavior is
3269 not to use a comment string. @option{--comment} may be repeated multiple
3270 times to get multiple comment strings. @option{--no-comments} removes
3271 all comments. It is a good idea to keep the length of a single comment
3272 below 60 characters to avoid problems with mail programs wrapping such
3273 lines. Note that comment lines, like all other header lines, are not
3274 protected by the signature.
3276 @item --emit-version
3277 @itemx --no-emit-version
3278 @opindex emit-version
3279 Force inclusion of the version string in ASCII armored output. If
3280 given once only the name of the program and the major number is
3281 emitted, given twice the minor is also emitted, given thrice
3282 the micro is added, and given four times an operating system identification
3283 is also emitted. @option{--no-emit-version} (default) disables the version
3286 @item --sig-notation @{@var{name}=@var{value}@}
3287 @itemx --cert-notation @{@var{name}=@var{value}@}
3288 @itemx -N, --set-notation @{@var{name}=@var{value}@}
3289 @opindex sig-notation
3290 @opindex cert-notation
3291 @opindex set-notation
3292 Put the name value pair into the signature as notation data.
3293 @var{name} must consist only of printable characters or spaces, and
3294 must contain a '@@' character in the form keyname@@domain.example.com
3295 (substituting the appropriate keyname and domain name, of course). This
3296 is to help prevent pollution of the IETF reserved notation
3297 namespace. The @option{--expert} flag overrides the '@@'
3298 check. @var{value} may be any printable string; it will be encoded in
3299 UTF-8, so you should check that your @option{--display-charset} is set
3300 correctly. If you prefix @var{name} with an exclamation mark (!), the
3301 notation data will be flagged as critical
3302 (rfc4880:5.2.3.16). @option{--sig-notation} sets a notation for data
3303 signatures. @option{--cert-notation} sets a notation for key signatures
3304 (certifications). @option{--set-notation} sets both.
3306 There are special codes that may be used in notation names. "%k" will
3307 be expanded into the key ID of the key being signed, "%K" into the
3308 long key ID of the key being signed, "%f" into the fingerprint of the
3309 key being signed, "%s" into the key ID of the key making the
3310 signature, "%S" into the long key ID of the key making the signature,
3311 "%g" into the fingerprint of the key making the signature (which might
3312 be a subkey), "%p" into the fingerprint of the primary key of the key
3313 making the signature, "%c" into the signature count from the OpenPGP
3314 smartcard, and "%%" results in a single "%". %k, %K, and %f are only
3315 meaningful when making a key signature (certification), and %c is only
3316 meaningful when using the OpenPGP smartcard.
3318 @item --known-notation @var{name}
3319 @opindex known-notation
3320 Adds @var{name} to a list of known critical signature notations. The
3321 effect of this is that gpg will not mark a signature with a critical
3322 signature notation of that name as bad. Note that gpg already knows
3323 by default about a few critical signatures notation names.
3325 @item --sig-policy-url @var{string}
3326 @itemx --cert-policy-url @var{string}
3327 @itemx --set-policy-url @var{string}
3328 @opindex sig-policy-url
3329 @opindex cert-policy-url
3330 @opindex set-policy-url
3331 Use @var{string} as a Policy URL for signatures (rfc4880:5.2.3.20). If
3332 you prefix it with an exclamation mark (!), the policy URL packet will
3333 be flagged as critical. @option{--sig-policy-url} sets a policy url for
3334 data signatures. @option{--cert-policy-url} sets a policy url for key
3335 signatures (certifications). @option{--set-policy-url} sets both.
3337 The same %-expandos used for notation data are available here as well.
3339 @item --sig-keyserver-url @var{string}
3340 @opindex sig-keyserver-url
3341 Use @var{string} as a preferred keyserver URL for data signatures. If
3342 you prefix it with an exclamation mark (!), the keyserver URL packet
3343 will be flagged as critical.
3345 The same %-expandos used for notation data are available here as well.
3347 @item --set-filename @var{string}
3348 @opindex set-filename
3349 Use @var{string} as the filename which is stored inside messages.
3350 This overrides the default, which is to use the actual filename of the
3351 file being encrypted. Using the empty string for @var{string}
3352 effectively removes the filename from the output.
3354 @item --for-your-eyes-only
3355 @itemx --no-for-your-eyes-only
3356 @opindex for-your-eyes-only
3357 Set the `for your eyes only' flag in the message. This causes GnuPG to
3358 refuse to save the file unless the @option{--output} option is given,
3359 and PGP to use a "secure viewer" with a claimed Tempest-resistant font
3360 to display the message. This option overrides @option{--set-filename}.
3361 @option{--no-for-your-eyes-only} disables this option.
3363 @item --use-embedded-filename
3364 @itemx --no-use-embedded-filename
3365 @opindex use-embedded-filename
3366 Try to create a file with a name as embedded in the data. This can be
3367 a dangerous option as it enables overwriting files. Defaults to no.
3368 Note that the option @option{--output} overrides this option.
3370 @item --cipher-algo @var{name}
3371 @opindex cipher-algo
3372 Use @var{name} as cipher algorithm. Running the program with the
3373 command @option{--version} yields a list of supported algorithms. If
3374 this is not used the cipher algorithm is selected from the preferences
3375 stored with the key. In general, you do not want to use this option as
3376 it allows you to violate the OpenPGP standard. The option
3377 @option{--personal-cipher-preferences} is the safe way to accomplish the
3380 @item --digest-algo @var{name}
3381 @opindex digest-algo
3382 Use @var{name} as the message digest algorithm. Running the program
3383 with the command @option{--version} yields a list of supported
3384 algorithms. In general, you do not want to use this option as it
3385 allows you to violate the OpenPGP standard. The option
3386 @option{--personal-digest-preferences} is the safe way to accomplish
3389 @item --compress-algo @var{name}
3390 @opindex compress-algo
3391 Use compression algorithm @var{name}. "zlib" is RFC-1950 ZLIB
3392 compression. "zip" is RFC-1951 ZIP compression which is used by PGP.
3393 "bzip2" is a more modern compression scheme that can compress some
3394 things better than zip or zlib, but at the cost of more memory used
3395 during compression and decompression. "uncompressed" or "none"
3396 disables compression. If this option is not used, the default
3397 behavior is to examine the recipient key preferences to see which
3398 algorithms the recipient supports. If all else fails, ZIP is used for
3399 maximum compatibility.
3401 ZLIB may give better compression results than ZIP, as the compression
3402 window size is not limited to 8k. BZIP2 may give even better
3403 compression results than that, but will use a significantly larger
3404 amount of memory while compressing and decompressing. This may be
3405 significant in low memory situations. Note, however, that PGP (all
3406 versions) only supports ZIP compression. Using any algorithm other
3407 than ZIP or "none" will make the message unreadable with PGP. In
3408 general, you do not want to use this option as it allows you to
3409 violate the OpenPGP standard. The option
3410 @option{--personal-compress-preferences} is the safe way to accomplish
3413 @item --cert-digest-algo @var{name}
3414 @opindex cert-digest-algo
3415 Use @var{name} as the message digest algorithm used when signing a
3416 key. Running the program with the command @option{--version} yields a
3417 list of supported algorithms. Be aware that if you choose an
3418 algorithm that GnuPG supports but other OpenPGP implementations do
3419 not, then some users will not be able to use the key signatures you
3420 make, or quite possibly your entire key. Note also that a public key
3421 algorithm must be compatible with the specified digest algorithm; thus
3422 selecting an arbitrary digest algorithm may result in error messages
3423 from lower crypto layers or lead to security flaws.
3426 @item --disable-cipher-algo @var{name}
3427 @opindex disable-cipher-algo
3428 Never allow the use of @var{name} as cipher algorithm.
3429 The given name will not be checked so that a later loaded algorithm
3430 will still get disabled.
3432 @item --disable-pubkey-algo @var{name}
3433 @opindex disable-pubkey-algo
3434 Never allow the use of @var{name} as public key algorithm.
3435 The given name will not be checked so that a later loaded algorithm
3436 will still get disabled.
3438 @item --throw-keyids
3439 @itemx --no-throw-keyids
3440 @opindex throw-keyids
3441 Do not put the recipient key IDs into encrypted messages. This helps to
3442 hide the receivers of the message and is a limited countermeasure
3443 against traffic analysis.@footnote{Using a little social engineering
3444 anyone who is able to decrypt the message can check whether one of the
3445 other recipients is the one he suspects.} On the receiving side, it may
3446 slow down the decryption process because all available secret keys must
3447 be tried. @option{--no-throw-keyids} disables this option. This option
3448 is essentially the same as using @option{--hidden-recipient} for all
3451 @item --not-dash-escaped
3452 @opindex not-dash-escaped
3453 This option changes the behavior of cleartext signatures
3454 so that they can be used for patch files. You should not
3455 send such an armored file via email because all spaces
3456 and line endings are hashed too. You can not use this
3457 option for data which has 5 dashes at the beginning of a
3458 line, patch files don't have this. A special armor header
3459 line tells GnuPG about this cleartext signature option.
3461 @item --escape-from-lines
3462 @itemx --no-escape-from-lines
3463 @opindex escape-from-lines
3464 Because some mailers change lines starting with "From " to ">From " it
3465 is good to handle such lines in a special way when creating cleartext
3466 signatures to prevent the mail system from breaking the signature. Note
3467 that all other PGP versions do it this way too. Enabled by
3468 default. @option{--no-escape-from-lines} disables this option.
3470 @item --passphrase-repeat @var{n}
3471 @opindex passphrase-repeat
3472 Specify how many times @command{@gpgname} will request a new
3473 passphrase be repeated. This is useful for helping memorize a
3474 passphrase. Defaults to 1 repetition; can be set to 0 to disable any
3475 passphrase repetition. Note that a @var{n} greater than 1 will pop up
3476 the pinentry window @var{n}+1 times even if a modern pinentry with
3477 two entry fields is used.
3479 @item --passphrase-fd @var{n}
3480 @opindex passphrase-fd
3481 Read the passphrase from file descriptor @var{n}. Only the first line
3482 will be read from file descriptor @var{n}. If you use 0 for @var{n},
3483 the passphrase will be read from STDIN. This can only be used if only
3484 one passphrase is supplied.
3486 Note that since Version 2.0 this passphrase is only used if the
3487 option @option{--batch} has also been given. Since Version 2.1
3488 the @option{--pinentry-mode} also needs to be set to @code{loopback}.
3490 @item --passphrase-file @var{file}
3491 @opindex passphrase-file
3492 Read the passphrase from file @var{file}. Only the first line will
3493 be read from file @var{file}. This can only be used if only one
3494 passphrase is supplied. Obviously, a passphrase stored in a file is
3495 of questionable security if other users can read this file. Don't use
3496 this option if you can avoid it.
3498 Note that since Version 2.0 this passphrase is only used if the
3499 option @option{--batch} has also been given. Since Version 2.1
3500 the @option{--pinentry-mode} also needs to be set to @code{loopback}.
3502 @item --passphrase @var{string}
3504 Use @var{string} as the passphrase. This can only be used if only one
3505 passphrase is supplied. Obviously, this is of very questionable
3506 security on a multi-user system. Don't use this option if you can
3509 Note that since Version 2.0 this passphrase is only used if the
3510 option @option{--batch} has also been given. Since Version 2.1
3511 the @option{--pinentry-mode} also needs to be set to @code{loopback}.
3513 @item --pinentry-mode @var{mode}
3514 @opindex pinentry-mode
3515 Set the pinentry mode to @var{mode}. Allowed values for @var{mode}
3519 Use the default of the agent, which is @code{ask}.
3521 Force the use of the Pinentry.
3523 Emulate use of Pinentry's cancel button.
3525 Return a Pinentry error (``No Pinentry'').
3527 Redirect Pinentry queries to the caller. Note that in contrast to
3528 Pinentry the user is not prompted again if he enters a bad password.
3531 @item --no-symkey-cache
3532 @opindex no-symkey-cache
3533 Disable the passphrase cache used for symmetrical en- and decryption.
3534 This cache is based on the message specific salt value
3535 (cf. @option{--s2k-mode}).
3537 @item --request-origin @var{origin}
3538 @opindex request-origin
3539 Tell gpg to assume that the operation ultimately originated at
3540 @var{origin}. Depending on the origin certain restrictions are applied
3541 and the Pinentry may include an extra note on the origin. Supported
3542 values for @var{origin} are: @code{local} which is the default,
3543 @code{remote} to indicate a remote origin or @code{browser} for an
3544 operation requested by a web browser.
3546 @item --command-fd @var{n}
3548 This is a replacement for the deprecated shared-memory IPC mode.
3549 If this option is enabled, user input on questions is not expected
3550 from the TTY but from the given file descriptor. It should be used
3551 together with @option{--status-fd}. See the file doc/DETAILS in the source
3552 distribution for details on how to use it.
3554 @item --command-file @var{file}
3555 @opindex command-file
3556 Same as @option{--command-fd}, except the commands are read out of file
3559 @item --allow-non-selfsigned-uid
3560 @itemx --no-allow-non-selfsigned-uid
3561 @opindex allow-non-selfsigned-uid
3562 Allow the import and use of keys with user IDs which are not
3563 self-signed. This is not recommended, as a non self-signed user ID is
3564 trivial to forge. @option{--no-allow-non-selfsigned-uid} disables.
3566 @item --allow-freeform-uid
3567 @opindex allow-freeform-uid
3568 Disable all checks on the form of the user ID while generating a new
3569 one. This option should only be used in very special environments as
3570 it does not ensure the de-facto standard format of user IDs.
3572 @item --ignore-time-conflict
3573 @opindex ignore-time-conflict
3574 GnuPG normally checks that the timestamps associated with keys and
3575 signatures have plausible values. However, sometimes a signature
3576 seems to be older than the key due to clock problems. This option
3577 makes these checks just a warning. See also @option{--ignore-valid-from} for
3578 timestamp issues on subkeys.
3580 @item --ignore-valid-from
3581 @opindex ignore-valid-from
3582 GnuPG normally does not select and use subkeys created in the future.
3583 This option allows the use of such keys and thus exhibits the
3584 pre-1.0.7 behaviour. You should not use this option unless there
3585 is some clock problem. See also @option{--ignore-time-conflict} for timestamp
3586 issues with signatures.
3588 @item --ignore-crc-error
3589 @opindex ignore-crc-error
3590 The ASCII armor used by OpenPGP is protected by a CRC checksum against
3591 transmission errors. Occasionally the CRC gets mangled somewhere on
3592 the transmission channel but the actual content (which is protected by
3593 the OpenPGP protocol anyway) is still okay. This option allows GnuPG
3594 to ignore CRC errors.
3596 @item --ignore-mdc-error
3597 @opindex ignore-mdc-error
3598 This option changes a MDC integrity protection failure into a warning.
3599 It is required to decrypt old messages which did not use an MDC. It
3600 may also be useful if a message is partially garbled, but it is
3601 necessary to get as much data as possible out of that garbled message.
3602 Be aware that a missing or failed MDC can be an indication of an
3603 attack. Use with great caution; see also option @option{--rfc2440}.
3605 @item --allow-old-cipher-algos
3606 @opindex allow-old-cipher-algos
3607 Old cipher algorithms like 3DES, IDEA, or CAST5 encrypt data using
3608 blocks of 64 bits; modern algorithms use blocks of 128 bit instead.
3609 To avoid certain attack on these old algorithms it is suggested not to
3610 encrypt more than 150 MiByte using the same key. For this reason gpg
3611 does not allow the use of 64 bit block size algorithms for encryption
3612 unless this option is specified.
3614 @item --allow-weak-digest-algos
3615 @opindex allow-weak-digest-algos
3616 Signatures made with known-weak digest algorithms are normally
3617 rejected with an ``invalid digest algorithm'' message. This option
3618 allows the verification of signatures made with such weak algorithms.
3619 MD5 is the only digest algorithm considered weak by default. See also
3620 @option{--weak-digest} to reject other digest algorithms.
3622 @item --weak-digest @var{name}
3623 @opindex weak-digest
3624 Treat the specified digest algorithm as weak. Signatures made over
3625 weak digests algorithms are normally rejected. This option can be
3626 supplied multiple times if multiple algorithms should be considered
3627 weak. See also @option{--allow-weak-digest-algos} to disable
3628 rejection of weak digests. MD5 is always considered weak, and does
3629 not need to be listed explicitly.
3631 @item --allow-weak-key-signatures
3632 @opindex allow-weak-key-signatures
3633 To avoid a minor risk of collision attacks on third-party key
3634 signatures made using SHA-1, those key signatures are considered
3635 invalid. This options allows to override this restriction.
3637 @item --override-compliance-check
3638 This was a temporary introduced option and has no more effect.
3640 @item --no-default-keyring
3641 @opindex no-default-keyring
3642 Do not add the default keyring to the list of keyrings. Note that
3643 GnuPG needs for almost all operations a keyring. Thus if you use this
3644 option and do not provide alternate keyrings via @option{--keyring},
3645 then GnuPG will still use the default keyring.
3647 Note that if the option @option{use-keyboxd} is enabled in
3648 @file{common.conf}, no keyrings are used at all and keys are all
3649 maintained by the keyboxd process in its own database.
3653 Do not use any keyring at all. This overrides the default and all
3654 options which specify keyrings.
3657 @opindex skip-verify
3658 Skip the signature verification step. This may be
3659 used to make the decryption faster if the signature
3660 verification is not needed.
3662 @item --with-key-data
3663 @opindex with-key-data
3664 Print key listings delimited by colons (like @option{--with-colons}) and
3665 print the public key data.
3667 @item --list-signatures
3668 @opindex list-signatures
3671 Same as @option{--list-keys}, but the signatures are listed too. This
3672 command has the same effect as using @option{--list-keys} with
3673 @option{--with-sig-list}. Note that in contrast to
3674 @option{--check-signatures} the key signatures are not verified. This
3675 command can be used to create a list of signing keys missing in the
3676 local keyring; for example:
3679 gpg --list-sigs --with-colons USERID | \
3680 awk -F: '$1=="sig" && $2=="?" @{if($13)@{print $13@}else@{print $5@}@}'
3683 @item --fast-list-mode
3684 @opindex fast-list-mode
3685 Changes the output of the list commands to work faster; this is achieved
3686 by leaving some parts empty. Some applications don't need the user ID
3687 and the trust information given in the listings. By using this options
3688 they can get a faster listing. The exact behaviour of this option may
3689 change in future versions. If you are missing some information, don't
3694 This is not for normal use. Use the source to see for what it might be useful.
3696 @item --set-filesize
3697 @opindex set-filesize
3698 This is not for normal use. Use the source to see for what it might be useful.
3700 @item --show-session-key
3701 @opindex show-session-key
3702 Display the session key used for one message. See
3703 @option{--override-session-key} for the counterpart of this option.
3705 We think that Key Escrow is a Bad Thing; however the user should have
3706 the freedom to decide whether to go to prison or to reveal the content
3707 of one specific message without compromising all messages ever
3708 encrypted for one secret key.
3710 You can also use this option if you receive an encrypted message which
3711 is abusive or offensive, to prove to the administrators of the
3712 messaging system that the ciphertext transmitted corresponds to an
3713 inappropriate plaintext so they can take action against the offending
3716 @item --override-session-key @var{string}
3717 @itemx --override-session-key-fd @var{fd}
3718 @opindex override-session-key
3719 Don't use the public key but the session key @var{string} respective
3720 the session key taken from the first line read from file descriptor
3721 @var{fd}. The format of this string is the same as the one printed by
3722 @option{--show-session-key}. This option is normally not used but
3723 comes handy in case someone forces you to reveal the content of an
3724 encrypted message; using this option you can do this without handing
3725 out the secret key. Note that using @option{--override-session-key}
3726 may reveal the session key to all local users via the global process
3727 table. Often it is useful to combine this option with
3728 @option{--no-keyring}.
3730 @item --ask-sig-expire
3731 @itemx --no-ask-sig-expire
3732 @opindex ask-sig-expire
3733 When making a data signature, prompt for an expiration time. If this
3734 option is not specified, the expiration time set via
3735 @option{--default-sig-expire} is used. @option{--no-ask-sig-expire}
3736 disables this option.
3738 @item --default-sig-expire
3739 @opindex default-sig-expire
3740 The default expiration time to use for signature expiration. Valid
3741 values are "0" for no expiration, a number followed by the letter d
3742 (for days), w (for weeks), m (for months), or y (for years) (for
3743 example "2m" for two months, or "5y" for five years), or an absolute
3744 date in the form YYYY-MM-DD. Defaults to "0".
3746 @item --ask-cert-expire
3747 @itemx --no-ask-cert-expire
3748 @opindex ask-cert-expire
3749 When making a key signature, prompt for an expiration time. If this
3750 option is not specified, the expiration time set via
3751 @option{--default-cert-expire} is used. @option{--no-ask-cert-expire}
3752 disables this option.
3754 @item --default-cert-expire
3755 @opindex default-cert-expire
3756 The default expiration time to use for key signature expiration.
3757 Valid values are "0" for no expiration, a number followed by the
3758 letter d (for days), w (for weeks), m (for months), or y (for years)
3759 (for example "2m" for two months, or "5y" for five years), or an
3760 absolute date in the form YYYY-MM-DD. Defaults to "0".
3762 @item --default-new-key-algo @var{string}
3763 @opindex default-new-key-algo @var{string}
3764 This option can be used to change the default algorithms for key
3765 generation. The @var{string} is similar to the arguments required for
3766 the command @option{--quick-add-key} but slightly different. For
3767 example the current default of @code{"rsa2048/cert,sign+rsa2048/encr"}
3768 (or @code{"rsa3072"}) can be changed to the value of what we currently
3769 call future default, which is @code{"ed25519/cert,sign+cv25519/encr"}.
3770 You need to consult the source code to learn the details. Note that
3771 the advanced key generation commands can always be used to specify a
3772 key algorithm directly.
3774 @item --no-auto-trust-new-key
3775 @opindex no-auto-trust-new-key
3776 When creating a new key the ownertrust of the new key is set to
3777 ultimate. This option disables this and the user needs to manually
3778 assign an ownertrust value.
3780 @item --force-sign-key
3781 @opindex force-sign-key
3782 This option modifies the behaviour of the commands
3783 @option{--quick-sign-key}, @option{--quick-lsign-key}, and the "sign"
3784 sub-commands of @option{--edit-key} by forcing the creation of a key
3785 signature, even if one already exists.
3787 @item --forbid-gen-key
3788 @opindex forbid-gen-key
3789 This option is intended for use in the global config file to disallow
3790 the use of generate key commands. Those commands will then fail with
3791 the error code for Not Enabled.
3793 @item --allow-secret-key-import
3794 @opindex allow-secret-key-import
3795 This is an obsolete option and is not used anywhere.
3797 @item --allow-multiple-messages
3798 @item --no-allow-multiple-messages
3799 These are obsolete options; they have no more effect since GnuPG 2.2.8.
3801 @item --enable-special-filenames
3802 @opindex enable-special-filenames
3803 This option enables a mode in which filenames of the form
3804 @file{-&n}, where n is a non-negative decimal number,
3805 refer to the file descriptor n and not to a file with that name.
3807 @item --no-expensive-trust-checks
3808 @opindex no-expensive-trust-checks
3809 Experimental use only.
3811 @item --preserve-permissions
3812 @opindex preserve-permissions
3813 Don't change the permissions of a secret keyring back to user
3814 read/write only. Use this option only if you really know what you are doing.
3816 @item --default-preference-list @var{string}
3817 @opindex default-preference-list
3818 Set the list of default preferences to @var{string}. This preference
3819 list is used for new keys and becomes the default for "setpref" in the
3820 @option{--edit-key} menu.
3822 @item --default-keyserver-url @var{name}
3823 @opindex default-keyserver-url
3824 Set the default keyserver URL to @var{name}. This keyserver will be
3825 used as the keyserver URL when writing a new self-signature on a key,
3826 which includes key generation and changing preferences.
3829 @opindex list-config
3830 Display various internal configuration parameters of GnuPG. This option
3831 is intended for external programs that call GnuPG to perform tasks, and
3832 is thus not generally useful. See the file @file{doc/DETAILS} in the
3833 source distribution for the details of which configuration items may be
3834 listed. @option{--list-config} is only usable with
3835 @option{--with-colons} set.
3837 @item --list-gcrypt-config
3838 @opindex list-gcrypt-config
3839 Display various internal configuration parameters of Libgcrypt.
3841 @item --gpgconf-list
3842 @opindex gpgconf-list
3843 This command is similar to @option{--list-config} but in general only
3844 internally used by the @command{gpgconf} tool.
3846 @item --gpgconf-test
3847 @opindex gpgconf-test
3848 This is more or less dummy action. However it parses the configuration
3849 file and returns with failure if the configuration file would prevent
3850 @command{@gpgname} from startup. Thus it may be used to run a syntax check
3851 on the configuration file.
3853 @c @item --use-only-openpgp-card
3854 @c @opindex use-only-openpgp-card
3855 @c Only access OpenPGP card's and no other cards. This is a hidden
3856 @c option which could be used in case an old use case required the
3857 @c OpenPGP card while several cards are available. This option might be
3858 @c removed if it turns out that nobody requires it.
3860 @item --chuid @var{uid}
3862 Change the current user to @var{uid} which may either be a number or a
3863 name. This can be used from the root account to run gpg for
3864 another user. If @var{uid} is not the current UID a standard PATH is
3865 set and the envvar GNUPGHOME is unset. To override the latter the
3866 option @option{--homedir} can be used. This option has only an effect
3867 when used on the command line. This option has currently no effect at
3872 @c *******************************
3873 @c ******* Deprecated ************
3874 @c *******************************
3875 @node Deprecated Options
3876 @subsection Deprecated options
3881 @itemx --no-show-photos
3882 @opindex show-photos
3883 Causes @option{--list-keys}, @option{--list-signatures},
3884 @option{--list-public-keys}, @option{--list-secret-keys}, and verifying
3885 a signature to also display the photo ID attached to the key, if
3886 any. See also @option{--photo-viewer}. These options are deprecated. Use
3887 @option{--list-options [no-]show-photos} and/or @option{--verify-options
3888 [no-]show-photos} instead.
3890 @item --show-keyring
3891 @opindex show-keyring
3892 Display the keyring name at the head of key listings to show which
3893 keyring a given key resides on. This option is deprecated: use
3894 @option{--list-options [no-]show-keyring} instead.
3896 @item --show-notation
3897 @itemx --no-show-notation
3898 @opindex show-notation
3899 Show signature notations in the @option{--list-signatures} or @option{--check-signatures} listings
3900 as well as when verifying a signature with a notation in it. These
3901 options are deprecated. Use @option{--list-options [no-]show-notation}
3902 and/or @option{--verify-options [no-]show-notation} instead.
3904 @item --show-policy-url
3905 @itemx --no-show-policy-url
3906 @opindex show-policy-url
3907 Show policy URLs in the @option{--list-signatures} or @option{--check-signatures}
3908 listings as well as when verifying a signature with a policy URL in
3909 it. These options are deprecated. Use @option{--list-options
3910 [no-]show-policy-url} and/or @option{--verify-options
3911 [no-]show-policy-url} instead.
3913 @item --personal-aead-preferences @var{string}
3914 @opindex personal-aead-preferences
3915 This option is deprecated and has no more effect since version 2.3.9.
3917 @item --aead-algo @var{name}
3918 This option is deprecated and has no more effect since version 2.3.9.
3924 @c *******************************************
3925 @c *************** ****************
3926 @c *************** FILES ****************
3927 @c *************** ****************
3928 @c *******************************************
3930 @node GPG Configuration
3931 @section Configuration files
3933 There are a few configuration files to control certain aspects of
3934 @command{@gpgname}'s operation. Unless noted, they are expected in the
3935 current home directory (@pxref{option --homedir}).
3941 This is the standard configuration file read by @command{@gpgname} on
3942 startup. It may contain any valid long option; the leading two dashes
3943 may not be entered and the option may not be abbreviated. This default
3944 name may be changed on the command line (@pxref{gpg-option --options}).
3945 You should backup this file.
3948 @efindex common.conf
3949 This is an optional configuration file read by @command{@gpgname} on
3950 startup. It may contain options pertaining to all components of
3951 GnuPG. Its current main use is for the "use-keyboxd" option. If
3952 the default home directory @file{~/.gnupg} does not exist, GnuPG creates
3953 this directory and a @file{common.conf} file with "use_keyboxd".
3957 Note that on larger installations, it is useful to put predefined files
3958 into the directory @file{@value{SYSCONFSKELDIR}} so that
3959 newly created users start up with a working configuration.
3960 For existing users a small
3961 helper script is provided to create these files (@pxref{addgnupghome}).
3963 For internal purposes @command{@gpgname} creates and maintains a few other
3964 files; They all live in the current home directory (@pxref{option
3965 --homedir}). Only the @command{@gpgname} program may modify these files.
3971 This is the default home directory which is used if neither the
3972 environment variable @code{GNUPGHOME} nor the option
3973 @option{--homedir} is given.
3975 @item ~/.gnupg/pubring.gpg
3976 @efindex pubring.gpg
3977 The public keyring using a legacy format. You should backup this file.
3979 If this file is not available, @command{gpg} defaults to the new
3980 keybox format and creates a file @file{pubring.kbx} unless that file
3981 already exists in which case that file will also be used for OpenPGP
3984 Note that in the case that both files, @file{pubring.gpg} and
3985 @file{pubring.kbx} exists but the latter has no OpenPGP keys, the
3986 legacy file @file{pubring.gpg} will be used. Take care: GnuPG
3987 versions before 2.1 will always use the file @file{pubring.gpg}
3988 because they do not know about the new keybox format. In the case
3989 that you have to use GnuPG 1.4 to decrypt archived data you should
3992 @item ~/.gnupg/pubring.gpg.lock
3993 The lock file for the public keyring.
3995 @item ~/.gnupg/pubring.kbx
3996 @efindex pubring.kbx
3997 The public keyring using the new keybox format. This file is shared
3998 with @command{gpgsm}. You should backup this file. See above for
3999 the relation between this file and it predecessor.
4001 To convert an existing @file{pubring.gpg} file to the keybox format, you
4002 first backup the ownertrust values, then rename @file{pubring.gpg} to
4003 @file{publickeys.backup}, so it won’t be recognized by any GnuPG version,
4004 run import, and finally restore the ownertrust values:
4008 $ gpg --export-ownertrust >otrust.lst
4009 $ mv pubring.gpg publickeys.backup
4010 $ gpg --import-options restore --import publickeys.backup
4011 $ gpg --import-ownertrust otrust.lst
4014 @item ~/.gnupg/pubring.kbx.lock
4015 The lock file for @file{pubring.kbx}.
4017 @item ~/.gnupg/secring.gpg
4018 @efindex secring.gpg
4019 The legacy secret keyring as used by GnuPG versions before 2.1. It is not
4020 used by GnuPG 2.1 and later. You may want to keep it in case you
4021 have to use GnuPG 1.4 to decrypt archived data.
4023 @item ~/.gnupg/secring.gpg.lock
4024 The lock file for the legacy secret keyring.
4026 @item ~/.gnupg/.gpg-v21-migrated
4027 @efindex .gpg-v21-migrated
4028 File indicating that a migration to GnuPG 2.1 has been done.
4030 @item ~/.gnupg/trustdb.gpg
4031 @efindex trustdb.gpg
4032 The trust database. There is no need to backup this file; it is better
4033 to backup the ownertrust values (@pxref{option --export-ownertrust}).
4035 @item ~/.gnupg/trustdb.gpg.lock
4036 The lock file for the trust database.
4038 @item ~/.gnupg/random_seed
4039 @efindex random_seed
4040 A file used to preserve the state of the internal random pool.
4042 @item ~/.gnupg/openpgp-revocs.d/
4043 @efindex openpgp-revocs.d
4044 This is the directory where gpg stores pre-generated revocation
4045 certificates. The file name corresponds to the OpenPGP fingerprint of
4046 the respective key. It is suggested to backup those certificates and
4047 if the primary private key is not stored on the disk to move them to
4048 an external storage device. Anyone who can access these files is
4049 able to revoke the corresponding key. You may want to print them out.
4050 You should backup all files in this directory and take care to keep
4051 this backup closed away.
4055 Operation is further controlled by a few environment variables:
4061 Used to locate the default home directory.
4065 If set directory used instead of "~/.gnupg".
4067 @item GPG_AGENT_INFO
4068 This variable is obsolete; it was used by GnuPG versions before 2.1.
4070 @item PINENTRY_USER_DATA
4071 @efindex PINENTRY_USER_DATA
4072 This value is passed via gpg-agent to pinentry. It is useful to convey
4073 extra information to a custom pinentry.
4079 Used to size some displays to the full size of the screen.
4083 Apart from its use by GNU, it is used in the W32 version to override the
4084 language selection done through the Registry. If used and set to a
4085 valid and available language name (@var{langid}), the file with the
4086 translation is loaded from
4087 @code{@var{gpgdir}/gnupg.nls/@var{langid}.mo}. Here @var{gpgdir} is the
4088 directory out of which the gpg binary has been loaded. If it can't be
4089 loaded the Registry is tried and as last resort the native Windows
4090 locale system is used.
4092 @item GNUPG_BUILD_ROOT
4093 @efindex GNUPG_BUILD_ROOT
4094 This variable is only used by the regression test suite as a helper
4095 under operating systems without proper support to figure out the
4096 name of a process' text file.
4098 @item GNUPG_EXEC_DEBUG_FLAGS
4099 @efindex GNUPG_EXEC_DEBUG_FLAGS
4100 This variable allows to enable diagnostics for process management.
4101 A numeric decimal value is expected. Bit 0 enables general
4102 diagnostics, bit 1 enables certain warnings on Windows.
4106 When calling the gpg-agent component @command{@gpgname} sends a set of
4107 environment variables to gpg-agent. The names of these variables can
4108 be listed using the command:
4111 gpg-connect-agent 'getinfo std_env_names' /bye | awk '$1=="D" @{print $2@}'
4116 @c *******************************************
4117 @c *************** ****************
4118 @c *************** EXAMPLES ****************
4119 @c *************** ****************
4120 @c *******************************************
4127 @item gpg -se -r @code{Bob} @code{file}
4128 sign and encrypt for user Bob
4130 @item gpg --clear-sign @code{file}
4131 make a cleartext signature
4133 @item gpg -sb @code{file}
4134 make a detached signature
4136 @item gpg -u 0x12345678 -sb @code{file}
4137 make a detached signature with the key 0x12345678
4139 @item gpg --list-keys @code{user_ID}
4142 @item gpg --fingerprint @code{user_ID}
4145 @item gpg --verify @code{pgpfile}
4146 @itemx gpg --verify @code{sigfile} [@code{datafile}]
4147 Verify the signature of the file but do not output the data unless
4148 requested. The second form is used for detached signatures, where
4149 @code{sigfile} is the detached signature (either ASCII armored or
4150 binary) and @code{datafile} are the signed data; if this is not given, the name of the
4151 file holding the signed data is constructed by cutting off the
4152 extension (".asc" or ".sig") of @code{sigfile} or by asking the user
4153 for the filename. If the option @option{--output} is also used the
4154 signed data is written to the file specified by that option; use
4155 @code{-} to write the signed data to stdout.
4159 @c *******************************************
4160 @c *************** ****************
4161 @c *************** USER ID ****************
4162 @c *************** ****************
4163 @c *******************************************
4164 @mansect how to specify a user id
4166 @include specify-user-id.texi
4169 @mansect filter expressions
4170 @chapheading FILTER EXPRESSIONS
4172 The options @option{--import-filter} and @option{--export-filter} use
4173 expressions with this syntax (square brackets indicate an optional
4174 part and curly braces a repetition, white space between the elements
4179 [lc] @{[@{flag@}] PROPNAME op VALUE [lc]@}
4183 The name of a property (@var{PROPNAME}) may only consist of letters,
4184 digits and underscores. The description for the filter type
4185 describes which properties are defined. If an undefined property is
4186 used it evaluates to the empty string. Unless otherwise noted, the
4187 @var{VALUE} must always be given and may not be the empty string. No
4188 quoting is defined for the value, thus the value may not contain the
4189 strings @code{&&} or @code{||}, which are used as logical connection
4190 operators. The flag @code{--} can be used to remove this restriction.
4192 Numerical values are computed as long int; standard C notation
4193 applies. @var{lc} is the logical connection operator; either
4194 @code{&&} for a conjunction or @code{||} for a disjunction. A
4195 conjunction is assumed at the begin of an expression. Conjunctions
4196 have higher precedence than disjunctions. If @var{VALUE} starts with
4197 one of the characters used in any @var{op} a space after the
4198 @var{op} is required.
4201 The supported operators (@var{op}) are:
4206 Substring must match.
4209 Substring must not match.
4212 The full string must match.
4215 The full string must not match.
4218 The numerical value must match.
4221 The numerical value must not match.
4224 The numerical value of the field must be LE than the value.
4227 The numerical value of the field must be LT than the value.
4230 The numerical value of the field must be GT than the value.
4233 The numerical value of the field must be GE than the value.
4236 The string value of the field must be less or equal than the value.
4239 The string value of the field must be less than the value.
4242 The string value of the field must be greater than the value.
4245 The string value of the field must be greater or equal than the value.
4248 True if value is not empty (no value allowed).
4251 True if value is empty (no value allowed).
4254 Alias for "PROPNAME != 0" (no value allowed).
4257 Alias for "PROPNAME == 0" (no value allowed).
4262 Values for @var{flag} must be space separated. The supported flags
4267 @var{VALUE} spans to the end of the expression.
4269 The string match in this part is done case-sensitive.
4271 Leading and trailing spaces are not removed from @var{VALUE}.
4272 The optional single space after @var{op} is here required.
4275 The filter options concatenate several specifications for a filter of
4276 the same type. For example the four options in this example:
4280 --import-filter keep-uid="uid =~ Alfa"
4281 --import-filter keep-uid="&& uid !~ Test"
4282 --import-filter keep-uid="|| uid =~ Alpha"
4283 --import-filter keep-uid="uid !~ Test"
4288 which is equivalent to
4293 keep-uid="uid =~ Alfa" && uid !~ Test" || uid =~ Alpha" && "uid !~ Test"
4297 imports only the user ids of a key containing the strings "Alfa"
4298 or "Alpha" but not the string "test".
4300 @mansect trust values
4302 @include trust-values.texi
4305 @mansect return value
4306 @chapheading RETURN VALUE
4308 The program returns 0 if there are no severe errors, 1 if at least a
4309 signature was bad, and other error codes for fatal errors.
4311 Note that signature verification requires exact knowledge of what has
4312 been signed and by whom it has been signed. Using only the return code
4313 is thus not an appropriate way to verify a signature by a script.
4314 Either make proper use or the status codes or use the @command{gpgv}
4315 tool which has been designed to make signature verification easy for
4319 @chapheading WARNINGS
4321 Use a good password for your user account and make sure that all
4322 security issues are always fixed on your machine. Also employ
4323 diligent physical protection to your machine. Consider to use a good
4324 passphrase as a last resort protection to your secret key in the case
4325 your machine gets stolen. It is important that your secret key is
4326 never leaked. Using an easy to carry around token or smartcard with
4327 the secret key is often a advisable.
4329 If you are going to verify detached signatures, make sure that the
4330 program knows about it; either give both filenames on the command line
4331 or use @samp{-} to specify STDIN.
4333 For scripted or other unattended use of @command{gpg} make sure to use
4334 the machine-parseable interface and not the default interface which is
4335 intended for direct use by humans. The machine-parseable interface
4336 provides a stable and well documented API independent of the locale or
4337 future changes of @command{gpg}. To enable this interface use the
4338 options @option{--with-colons} and @option{--status-fd}. For certain
4339 operations the option @option{--command-fd} may come handy too. See
4340 this man page and the file @file{DETAILS} for the specification of the
4341 interface. Note that the GnuPG ``info'' pages as well as the PDF
4342 version of the GnuPG manual features a chapter on unattended use of
4343 GnuPG. As an alternative the library @command{GPGME} can be used as a
4344 high-level abstraction on top of that interface.
4346 @mansect interoperability
4347 @chapheading INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS
4349 GnuPG tries to be a very flexible implementation of the OpenPGP
4350 standard. In particular, GnuPG implements many of the optional parts
4351 of the standard, such as the SHA-512 hash, and the ZLIB and BZIP2
4352 compression algorithms. It is important to be aware that not all
4353 OpenPGP programs implement these optional algorithms and that by
4354 forcing their use via the @option{--cipher-algo},
4355 @option{--digest-algo}, @option{--cert-digest-algo}, or
4356 @option{--compress-algo} options in GnuPG, it is possible to create a
4357 perfectly valid OpenPGP message, but one that cannot be read by the
4360 There are dozens of variations of OpenPGP programs available, and each
4361 supports a slightly different subset of these optional algorithms.
4362 For example, until recently, no (unhacked) version of PGP supported
4363 the BLOWFISH cipher algorithm. A message using BLOWFISH simply could
4364 not be read by a PGP user. By default, GnuPG uses the standard
4365 OpenPGP preferences system that will always do the right thing and
4366 create messages that are usable by all recipients, regardless of which
4367 OpenPGP program they use. Only override this safe default if you
4368 really know what you are doing.
4370 If you absolutely must override the safe default, or if the preferences
4371 on a given key are invalid for some reason, you are far better off using
4372 the @option{--pgp6}, @option{--pgp7}, or @option{--pgp8} options. These
4373 options are safe as they do not force any particular algorithms in
4374 violation of OpenPGP, but rather reduce the available algorithms to a
4380 On older systems this program should be installed as setuid(root). This
4381 is necessary to lock memory pages. Locking memory pages prevents the
4382 operating system from writing memory pages (which may contain
4383 passphrases or other sensitive material) to disk. If you get no
4384 warning message about insecure memory your operating system supports
4385 locking without being root. The program drops root privileges as soon
4386 as locked memory is allocated.
4388 Note also that some systems (especially laptops) have the ability to
4389 ``suspend to disk'' (also known as ``safe sleep'' or ``hibernate'').
4390 This writes all memory to disk before going into a low power or even
4391 powered off mode. Unless measures are taken in the operating system
4392 to protect the saved memory, passphrases or other sensitive material
4393 may be recoverable from it later.
4395 Before you report a bug you should first search the mailing list
4396 archives for similar problems and second check whether such a bug has
4397 already been reported to our bug tracker at @url{https://bugs.gnupg.org}.
4399 @c *******************************************
4400 @c *************** **************
4401 @c *************** UNATTENDED **************
4402 @c *************** **************
4403 @c *******************************************
4405 @node Unattended Usage of GPG
4406 @section Unattended Usage
4408 @command{@gpgname} is often used as a backend engine by other software. To help
4409 with this a machine interface has been defined to have an unambiguous
4410 way to do this. The options @option{--status-fd} and @option{--batch}
4411 are almost always required for this.
4414 * Programmatic use of GnuPG:: Programmatic use of GnuPG
4415 * Ephemeral home directories:: Ephemeral home directories
4416 * The quick key manipulation interface:: The quick key manipulation interface
4417 * Unattended GPG key generation:: Unattended key generation
4421 @node Programmatic use of GnuPG
4422 @subsection Programmatic use of GnuPG
4424 Please consider using GPGME instead of calling @command{@gpgname}
4425 directly. GPGME offers a stable, backend-independent interface for
4426 many cryptographic operations. It supports OpenPGP and S/MIME, and
4427 also allows interaction with various GnuPG components.
4429 GPGME provides a C-API, and comes with bindings for C++, Qt, and
4430 Python. Bindings for other languages are available.
4432 @node Ephemeral home directories
4433 @subsection Ephemeral home directories
4435 Sometimes you want to contain effects of some operation, for example
4436 you want to import a key to inspect it, but you do not want this key
4437 to be added to your keyring. In earlier versions of GnuPG, it was
4438 possible to specify alternate keyring files for both public and secret
4439 keys. In modern GnuPG versions, however, we changed how secret keys
4440 are stored in order to better protect secret key material, and it was
4441 not possible to preserve this interface.
4443 The preferred way to do this is to use ephemeral home directories.
4444 This technique works across all versions of GnuPG.
4446 Create a temporary directory, create (or copy) a configuration that
4447 meets your needs, make @command{@gpgname} use this directory either
4448 using the environment variable @var{GNUPGHOME}, or the option
4449 @option{--homedir}. GPGME supports this too on a per-context basis,
4450 by modifying the engine info of contexts. Now execute whatever
4451 operation you like, import and export key material as necessary. Once
4452 finished, you can delete the directory. All GnuPG backend services
4453 that were started will detect this and shut down.
4455 @node The quick key manipulation interface
4456 @subsection The quick key manipulation interface
4458 Recent versions of GnuPG have an interface to manipulate keys without
4459 using the interactive command @option{--edit-key}. This interface was
4460 added mainly for the benefit of GPGME (please consider using GPGME,
4461 see the manual subsection ``Programmatic use of GnuPG''). This
4462 interface is described in the subsection ``How to manage your keys''.
4464 @node Unattended GPG key generation
4465 @subsection Unattended key generation
4467 The command @option{--generate-key} may be used along with the option
4468 @option{--batch} for unattended key generation. This is the most
4469 flexible way of generating keys, but it is also the most complex one.
4470 Consider using the quick key manipulation interface described in the
4471 previous subsection ``The quick key manipulation interface''.
4473 The parameters for the key are either read from stdin or given as a
4474 file on the command line. The format of the parameter file is as
4475 follows: Text only, line length is limited to about 1000 characters.
4476 UTF-8 encoding must be used to specify non-ASCII characters. Empty
4477 lines are ignored. Leading and trailing white space is ignored. A
4478 hash sign as the first non white space character indicates a comment
4479 line. Control statements are indicated by a leading percent sign,
4480 their arguments are separated by white space from the keyword.
4481 Parameters are specified by a keyword, followed by a colon; arguments
4482 are separated by white space. The first parameter must be
4483 @samp{Key-Type} but control statements may be placed anywhere. The
4484 order of the parameters does not matter except for @samp{Key-Type}.
4485 The parameters are only used for the generated keyblock (primary and
4486 subkeys); parameters from previous sets are not used. Some syntax
4487 checks may be performed. Key commences when either the end of the
4488 parameter file is reached, the next @samp{Key-Type} parameter is
4489 encountered, or the control statement @samp{%commit} is encountered.
4496 @item %echo @var{text}
4497 Print @var{text} as diagnostic.
4500 Suppress actual key generation (useful for syntax checking).
4503 Perform the key generation. Note that an implicit commit is done at
4504 the next @asis{Key-Type} parameter.
4506 @item %pubring @var{filename}
4507 Do not write the key to the default or commandline given keyring but
4508 to @var{filename}. This must be given before the first commit to take
4509 place, duplicate specification of the same filename is ignored, the
4510 last filename before a commit is used. The filename is used until a
4511 new filename is used (at commit points) and all keys are written to
4512 that file. If a new filename is given, this file is created (and
4513 overwrites an existing one).
4515 See the previous subsection ``Ephemeral home directories'' for a more
4516 robust way to contain side-effects.
4518 @item %secring @var{filename}
4519 This option is a no-op for GnuPG 2.1 and later.
4521 See the previous subsection ``Ephemeral home directories''.
4523 @item %ask-passphrase
4524 @itemx %no-ask-passphrase
4525 This option is a no-op since GnuPG version 2.1.
4527 @item %no-protection
4528 Using this option allows the creation of keys without any passphrase
4529 protection. This option is mainly intended for regression tests.
4531 @item %transient-key
4532 If given the keys are created using a faster and a somewhat less
4533 secure random number generator. This option may be used for keys
4534 which are only used for a short time and do not require full
4535 cryptographic strength. It takes only effect if used together with
4536 the control statement @samp{%no-protection}.
4545 @item Key-Type: @var{algo}
4546 Starts a new parameter block by giving the type of the primary
4547 key. The algorithm must be capable of signing. This is a required
4548 parameter. @var{algo} may either be an OpenPGP algorithm number or a
4549 string with the algorithm name. The special value @samp{default} may
4550 be used for @var{algo} to create the default key type; in this case a
4551 @samp{Key-Usage} shall not be given and @samp{default} also be used
4552 for @samp{Subkey-Type}.
4554 @item Key-Length: @var{nbits}
4555 The requested length of the generated key in bits. The default is
4556 returned by running the command @samp{@gpgname --gpgconf-list}.
4557 For ECC keys this parameter is ignored.
4559 @item Key-Curve: @var{curve}
4560 The requested elliptic curve of the generated key. This is a required
4561 parameter for ECC keys. It is ignored for non-ECC keys.
4563 @item Key-Grip: @var{hexstring}
4564 This is optional and used to generate a CSR or certificate for an
4565 already existing key. Key-Length will be ignored when given.
4567 @item Key-Usage: @var{usage-list}
4568 Space or comma delimited list of key usages. Allowed values are
4569 @samp{encrypt}, @samp{sign}, and @samp{auth}. This is used to
4570 generate the key flags. Please make sure that the algorithm is
4571 capable of this usage. Note that OpenPGP requires that all primary
4572 keys are capable of certification, so no matter what usage is given
4573 here, the @samp{cert} flag will be on. If no @samp{Key-Usage} is
4574 specified and the @samp{Key-Type} is not @samp{default}, all allowed
4575 usages for that particular algorithm are used; if it is not given but
4576 @samp{default} is used the usage will be @samp{sign}.
4578 @item Subkey-Type: @var{algo}
4579 This generates a secondary key (subkey). Currently only one subkey
4580 can be handled. See also @samp{Key-Type} above.
4582 @item Subkey-Length: @var{nbits}
4583 Length of the secondary key (subkey) in bits. The default is returned
4584 by running the command @samp{@gpgname --gpgconf-list}.
4586 @item Subkey-Curve: @var{curve}
4587 Key curve for a subkey; similar to @samp{Key-Curve}.
4589 @item Subkey-Usage: @var{usage-list}
4590 Key usage lists for a subkey; similar to @samp{Key-Usage}.
4592 @item Passphrase: @var{string}
4593 If you want to specify a passphrase for the secret key, enter it here.
4594 Default is to use the Pinentry dialog to ask for a passphrase.
4596 @item Name-Real: @var{name}
4597 @itemx Name-Comment: @var{comment}
4598 @itemx Name-Email: @var{email}
4599 The three parts of a user name. Remember to use UTF-8 encoding here.
4600 If you don't give any of them, no user ID is created.
4602 @item Expire-Date: @var{iso-date}|(@var{number}[d|w|m|y])
4603 Set the expiration date for the key (and the subkey). It may either
4604 be entered in ISO date format (e.g. "20000815T145012") or as number of
4605 days, weeks, month or years after the creation date. The special
4606 notation "seconds=N" is also allowed to specify a number of seconds
4607 since creation. Without a letter days are assumed. Note that there
4608 is no check done on the overflow of the type used by OpenPGP for
4609 timestamps. Thus you better make sure that the given value make
4610 sense. Although OpenPGP works with time intervals, GnuPG uses an
4611 absolute value internally and thus the last year we can represent is
4614 @item Creation-Date: @var{iso-date}
4615 Set the creation date of the key as stored in the key information and
4616 which is also part of the fingerprint calculation. Either a date like
4617 "1986-04-26" or a full timestamp like "19860426T042640" may be used.
4618 The time is considered to be UTC. The special notation "seconds=N"
4619 may be used to directly specify a the number of seconds since Epoch
4620 (Unix time). If it is not given the current time is used.
4622 @item Preferences: @var{string}
4623 Set the cipher, hash, and compression preference values for this key.
4624 This expects the same type of string as the sub-command @samp{setpref}
4625 in the @option{--edit-key} menu.
4627 @item Revoker: @var{algo}:@var{fpr} [sensitive]
4628 Add a designated revoker to the generated key. Algo is the public key
4629 algorithm of the designated revoker (i.e. RSA=1, DSA=17, etc.)
4630 @var{fpr} is the fingerprint of the designated revoker. The optional
4631 @samp{sensitive} flag marks the designated revoker as sensitive
4632 information. Only v4 keys may be designated revokers.
4634 @item Keyserver: @var{string}
4635 This is an optional parameter that specifies the preferred keyserver
4638 @item Handle: @var{string}
4639 This is an optional parameter only used with the status lines
4640 KEY_CREATED and KEY_NOT_CREATED. @var{string} may be up to 100
4641 characters and should not contain spaces. It is useful for batch key
4642 generation to associate a key parameter block with a status line.
4647 Here is an example on how to create a key in an ephemeral home directory:
4649 $ export GNUPGHOME="$(mktemp -d)"
4651 %echo Generating a basic OpenPGP key
4656 Name-Real: Joe Tester
4657 Name-Comment: with stupid passphrase
4658 Name-Email: joe@@foo.bar
4661 # Do a commit here, so that we can later print "done" :-)
4665 $ @gpgname --batch --generate-key foo
4667 $ @gpgname --list-secret-keys
4668 /tmp/tmp.0NQxB74PEf/pubring.kbx
4669 -------------------------------
4670 sec dsa1024 2016-12-16 [SCA]
4671 768E895903FC1C44045C8CB95EEBDB71E9E849D0
4672 uid [ultimate] Joe Tester (with stupid passphrase) <joe@@foo.bar>
4673 ssb elg1024 2016-12-16 [E]
4677 If you want to create a key with the default algorithms you would use
4680 %echo Generating a default key
4682 Subkey-Type: default
4683 Name-Real: Joe Tester
4684 Name-Comment: with stupid passphrase
4685 Name-Email: joe@@foo.bar
4688 # Do a commit here, so that we can later print "done" :-)
4700 @command{gpg-agent}(1)
4702 @include see-also-note.texi