1 This is gnupg.info, produced by makeinfo version 6.7 from gnupg.texi.
3 This is the 'The GNU Privacy Guard Manual' (version 2.4.3-beta30, June
6 (C) 2002, 2004, 2005, 2006, 2007, 2010 Free Software Foundation, Inc.
7 (C) 2013, 2014, 2015 Werner Koch.
8 (C) 2015, 2016, 2017 g10 Code GmbH.
10 Permission is granted to copy, distribute and/or modify this
11 document under the terms of the GNU General Public License as
12 published by the Free Software Foundation; either version 3 of the
13 License, or (at your option) any later version. The text of the
14 license can be found in the section entitled "Copying".
15 INFO-DIR-SECTION GNU Utilities
17 * gpg2: (gnupg). OpenPGP encryption and signing tool.
18 * gpgsm: (gnupg). S/MIME encryption and signing tool.
19 * gpg-agent: (gnupg). The secret key daemon.
20 * dirmngr: (gnupg). X.509 CRL and OCSP server.
21 * dirmngr-client: (gnupg). X.509 CRL and OCSP client.
25 File: gnupg.info, Node: Top, Next: Installation, Up: (dir)
27 Using the GNU Privacy Guard
28 ***************************
30 This is the 'The GNU Privacy Guard Manual' (version 2.4.3-beta30, June
33 (C) 2002, 2004, 2005, 2006, 2007, 2010 Free Software Foundation, Inc.
34 (C) 2013, 2014, 2015 Werner Koch.
35 (C) 2015, 2016, 2017 g10 Code GmbH.
37 Permission is granted to copy, distribute and/or modify this
38 document under the terms of the GNU General Public License as
39 published by the Free Software Foundation; either version 3 of the
40 License, or (at your option) any later version. The text of the
41 license can be found in the section entitled "Copying".
43 This manual documents how to use the GNU Privacy Guard system as well
44 as the administration and the architecture.
48 * Installation:: A short installation guide.
50 * Invoking GPG-AGENT:: How to launch the secret key daemon.
51 * Invoking DIRMNGR:: How to launch the CRL and OCSP daemon.
52 * Invoking GPG:: Using the OpenPGP protocol.
53 * Invoking GPGSM:: Using the S/MIME protocol.
54 * Invoking SCDAEMON:: How to handle Smartcards.
55 * Specify a User ID:: How to Specify a User Id.
56 * Trust Values:: How GnuPG displays trust values.
58 * Smart Card Tool:: Tool to administrate smart cards.
59 * Helper Tools:: Description of small helper tools.
60 * Web Key Service:: Tools for the Web Key Service.
62 * Howtos:: How to do certain things.
63 * System Notes:: Notes pertaining to certain OSes.
64 * Debugging:: How to solve problems.
66 * Copying:: GNU General Public License says
67 how you can copy and share GnuPG.
68 * Contributors:: People who have contributed to GnuPG.
70 * Glossary:: Short description of terms used.
71 * Option Index:: Index to command line options.
72 * Environment Index:: Index to environment variables and files.
73 * Index:: Index of concepts and symbol names.
76 File: gnupg.info, Node: Installation, Next: Invoking GPG-AGENT, Prev: Top, Up: Top
78 1 A short installation guide
79 ****************************
81 Unfortunately the installation guide has not been finished in time.
82 Instead of delaying the release of GnuPG 2.0 even further, I decided to
83 release without that guide. The chapter on gpg-agent and gpgsm do
84 include brief information on how to set up the whole thing. Please
85 watch the GnuPG website for updates of the documentation. In the
86 meantime you may search the GnuPG mailing list archives or ask on the
87 gnupg-users mailing list for advise on how to solve problems or how to
88 get that whole thing up and running.
90 ** Building the software
92 Building the software is described in the file 'INSTALL'. Given that
93 you are already reading this documentation we can only give some extra
96 To comply with the rules on GNU systems you should have build time
97 configured 'gnupg' using:
99 ./configure --sysconfdir=/etc --localstatedir=/var
101 This is to make sure that system wide configuration files are
102 searched in the directory '/etc' and variable data below '/var'; the
103 default would be to also install them below '/usr/local' where the
104 binaries get installed. If you selected to use the '--prefix=/' you
105 obviously don't need those option as they are the default then.
107 ** Notes on setting a root CA key to trusted
109 X.509 is based on a hierarchical key infrastructure. At the root of
110 the tree a trusted anchor (root certificate) is required. There are
111 usually no other means of verifying whether this root certificate is
112 trustworthy than looking it up in a list. GnuPG uses a file
113 ('trustlist.txt') to keep track of all root certificates it knows about.
114 There are 3 ways to get certificates into this list:
116 * Use the list which comes with GnuPG. However this list only
117 contains a few root certificates. Most installations will need
120 * Let 'gpgsm' ask you whether you want to insert a new root
121 certificate. This feature is enabled by default; you may disable
122 it using the option 'no-allow-mark-trusted' into 'gpg-agent.conf'.
124 * Manually maintain the list of trusted root certificates. For a
125 multi user installation this can be done once for all users on a
126 machine. Specific changes on a per-user base are also possible.
129 File: gnupg.info, Node: Invoking GPG-AGENT, Next: Invoking DIRMNGR, Prev: Installation, Up: Top
134 'gpg-agent' is a daemon to manage secret (private) keys independently
135 from any protocol. It is used as a backend for 'gpg' and 'gpgsm' as
136 well as for a couple of other utilities.
138 The agent is automatically started on demand by 'gpg', 'gpgsm',
139 'gpgconf', or 'gpg-connect-agent'. Thus there is no reason to start it
140 manually. In case you want to use the included Secure Shell Agent you
141 may start the agent using:
143 gpg-connect-agent /bye
145 If you want to manually terminate the currently-running agent, you can
148 gpgconf --kill gpg-agent
150 You should always add the following lines to your '.bashrc' or whatever
151 initialization file is used for all shell invocations:
156 It is important that this environment variable always reflects the
157 output of the 'tty' command. For W32 systems this option is not
160 Please make sure that a proper pinentry program has been installed
161 under the default filename (which is system dependent) or use the option
162 'pinentry-program' to specify the full name of that program. It is
163 often useful to install a symbolic link from the actual used pinentry
164 (e.g. '/usr/local/bin/pinentry-gtk') to the expected one (e.g.
165 '/usr/local/bin/pinentry').
167 *Note Option Index::, for an index to 'GPG-AGENT''s commands and
172 * Agent Commands:: List of all commands.
173 * Agent Options:: List of all options.
174 * Agent Configuration:: Configuration files.
175 * Agent Signals:: Use of some signals.
176 * Agent Examples:: Some usage examples.
177 * Agent Protocol:: The protocol the agent uses.
180 File: gnupg.info, Node: Agent Commands, Next: Agent Options, Up: Invoking GPG-AGENT
185 Commands are not distinguished from options except for the fact that
186 only one command is allowed.
189 Print the program version and licensing information. Note that you
190 cannot abbreviate this command.
194 Print a usage message summarizing the most useful command-line
195 options. Note that you cannot abbreviate this command.
198 Print a list of all available options and commands. Note that you
199 cannot abbreviate this command.
202 Run in server mode and wait for commands on the 'stdin'. The
203 default mode is to create a socket and listen for commands there.
205 '--daemon [COMMAND LINE]'
206 Start the gpg-agent as a daemon; that is, detach it from the
207 console and run it in the background.
209 As an alternative you may create a new process as a child of
210 gpg-agent: 'gpg-agent --daemon /bin/sh'. This way you get a new
211 shell with the environment setup properly; after you exit from this
212 shell, gpg-agent terminates within a few seconds.
215 Run in the foreground, sending logs by default to stderr, and
216 listening on provided file descriptors, which must already be bound
217 to listening sockets. This option is deprecated and not supported
220 If in 'common.conf' the option 'no-autostart' is set, any start
221 attempts will be ignored.
223 In -supervised mode, different file descriptors can be provided for
224 use as different socket types (e.g. ssh, extra) as long as they
225 are identified in the environment variable 'LISTEN_FDNAMES' (see
226 sd_listen_fds(3) on some Linux distributions for more information
230 File: gnupg.info, Node: Agent Options, Next: Agent Configuration, Prev: Agent Commands, Up: Invoking GPG-AGENT
235 Options may either be used on the command line or, after stripping off
236 the two leading dashes, in the configuration file.
239 Reads configuration from FILE instead of from the default per-user
240 configuration file. The default configuration file is named
241 'gpg-agent.conf' and expected in the '.gnupg' directory directly
242 below the home directory of the user. This option is ignored if
243 used in an options file.
246 Set the name of the home directory to DIR. If this option is not
247 used, the home directory defaults to '~/.gnupg'. It is only
248 recognized when given on the command line. It also overrides any
249 home directory stated through the environment variable 'GNUPGHOME'
250 or (on Windows systems) by means of the Registry entry
251 HKCU\SOFTWARE\GNU\GNUPG:HOMEDIR.
253 On Windows systems it is possible to install GnuPG as a portable
254 application. In this case only this command line option is
255 considered, all other ways to set a home directory are ignored.
257 To install GnuPG as a portable application under Windows, create an
258 empty file named 'gpgconf.ctl' in the same directory as the tool
259 'gpgconf.exe'. The root of the installation is then that
260 directory; or, if 'gpgconf.exe' has been installed directly below a
261 directory named 'bin', its parent directory. You also need to make
262 sure that the following directories exist and are writable:
263 'ROOT/home' for the GnuPG home and 'ROOT/usr/local/var/cache/gnupg'
264 for internal cache files.
268 Outputs additional information while running. You can increase the
269 verbosity by giving several verbose commands to 'gpg-agent', such
274 Try to be as quiet as possible.
277 Don't invoke a pinentry or do any other thing requiring human
280 '--faked-system-time EPOCH'
281 This option is only useful for testing; it sets the system time
282 back or forth to EPOCH which is the number of seconds elapsed since
285 '--debug-level LEVEL'
286 Select the debug level for investigating problems. LEVEL may be a
287 numeric value or a keyword:
290 No debugging at all. A value of less than 1 may be used
291 instead of the keyword.
293 Some basic debug messages. A value between 1 and 2 may be
294 used instead of the keyword.
296 More verbose debug messages. A value between 3 and 5 may be
297 used instead of the keyword.
299 Even more detailed messages. A value between 6 and 8 may be
300 used instead of the keyword.
302 All of the debug messages you can get. A value greater than 8
303 may be used instead of the keyword. The creation of hash
304 tracing files is only enabled if the keyword is used.
306 How these messages are mapped to the actual debugging flags is not
307 specified and may change with newer releases of this program. They
308 are however carefully selected to best aid in debugging.
311 Set debug flags. All flags are or-ed and FLAGS may be given in C
312 syntax (e.g. 0x0042) or as a comma separated list of flag names.
313 To get a list of all supported flags the single word "help" can be
314 used. This option is only useful for debugging and the behavior
315 may change at any time without notice.
318 Same as '--debug=0xffffffff'
321 When running in server mode, wait N seconds before entering the
322 actual processing loop and print the pid. This gives time to
325 '--debug-quick-random'
326 This option inhibits the use of the very secure random quality
327 level (Libgcrypt’s 'GCRY_VERY_STRONG_RANDOM') and degrades all
328 request down to standard random quality. It is only used for
329 testing and should not be used for any production quality keys.
330 This option is only effective when given on the command line.
332 On GNU/Linux, another way to quickly generate insecure keys is to
333 use 'rngd' to fill the kernel's entropy pool with lower quality
334 random data. 'rngd' is typically provided by the 'rng-tools'
335 package. It can be run as follows: 'sudo rngd -f -r /dev/urandom'.
338 This option enables extra debug information pertaining to the
339 Pinentry. As of now it is only useful when used along with
343 Don't detach the process from the console. This is mainly useful
347 In '--daemon' mode, gpg-agent detects an already running gpg-agent
348 and does not allow to start a new instance. This option can be
349 used to override this check: the new gpg-agent process will try to
350 take over the communication sockets from the already running
351 process and start anyway. This option should in general not be
358 Format the info output in daemon mode for use with the standard
359 Bourne shell or the C-shell respectively. The default is to guess
360 it based on the environment variable 'SHELL' which is correct in
365 Tell the pinentry to grab the keyboard and mouse. This option
366 should be used on X-Servers to avoid X-sniffing attacks. Any use
367 of the option '--grab' overrides an used option '--no-grab'. The
368 default is '--no-grab'.
371 Append all logging output to FILE. This is very helpful in seeing
372 what the agent actually does. Use 'socket://' to log to socket.
373 If neither a log file nor a log file descriptor has been set on a
374 Windows platform, the Registry entry
375 'HKCU\Software\GNU\GnuPG:DefaultLogFile', if set, is used to
376 specify the logging output.
378 '--no-allow-mark-trusted'
379 Do not allow clients to mark keys as trusted, i.e. put them into
380 the 'trustlist.txt' file. This makes it harder for users to
381 inadvertently accept Root-CA keys.
383 '--no-user-trustlist'
384 Entirely ignore the user trust list and consider only the global
385 trustlist ('/usr/local/etc/gnupg/trustlist.txt'). This implies the
386 *note option --no-allow-mark-trusted::.
388 '--sys-trustlist-name FILE'
389 Changes the default name for the global trustlist from
390 "trustlist.txt" to FILE. If FILE does not contain any slashes and
391 does not start with "~/" it is searched in the system configuration
392 directory ('/usr/local/etc/gnupg').
394 '--allow-preset-passphrase'
395 This option allows the use of 'gpg-preset-passphrase' to seed the
396 internal cache of 'gpg-agent' with passphrases.
398 '--no-allow-loopback-pinentry'
399 '--allow-loopback-pinentry'
400 Disallow or allow clients to use the loopback pinentry features;
401 see the option 'pinentry-mode' for details. Allow is the default.
403 The '--force' option of the Assuan command 'DELETE_KEY' is also
404 controlled by this option: The option is ignored if a loopback
405 pinentry is disallowed.
407 '--no-allow-external-cache'
408 Tell Pinentry not to enable features which use an external cache
411 Some desktop environments prefer to unlock all credentials with one
412 master password and may have installed a Pinentry which employs an
413 additional external cache to implement such a policy. By using
414 this option the Pinentry is advised not to make use of such a cache
415 and instead always ask the user for the requested passphrase.
417 '--allow-emacs-pinentry'
418 Tell Pinentry to allow features to divert the passphrase entry to a
419 running Emacs instance. How this is exactly handled depends on the
420 version of the used Pinentry.
422 '--ignore-cache-for-signing'
423 This option will let 'gpg-agent' bypass the passphrase cache for
424 all signing operation. Note that there is also a per-session
425 option to control this behavior but this command line option takes
428 '--default-cache-ttl N'
429 Set the time a cache entry is valid to N seconds. The default is
430 600 seconds. Each time a cache entry is accessed, the entry's
431 timer is reset. To set an entry's maximum lifetime, use
432 'max-cache-ttl'. Note that a cached passphrase may not be evicted
433 immediately from memory if no client requests a cache operation.
434 This is due to an internal housekeeping function which is only run
437 '--default-cache-ttl-ssh N'
438 Set the time a cache entry used for SSH keys is valid to N seconds.
439 The default is 1800 seconds. Each time a cache entry is accessed,
440 the entry's timer is reset. To set an entry's maximum lifetime,
441 use 'max-cache-ttl-ssh'.
444 Set the maximum time a cache entry is valid to N seconds. After
445 this time a cache entry will be expired even if it has been
446 accessed recently or has been set using 'gpg-preset-passphrase'.
447 The default is 2 hours (7200 seconds).
449 '--max-cache-ttl-ssh N'
450 Set the maximum time a cache entry used for SSH keys is valid to N
451 seconds. After this time a cache entry will be expired even if it
452 has been accessed recently or has been set using
453 'gpg-preset-passphrase'. The default is 2 hours (7200 seconds).
455 '--enforce-passphrase-constraints'
456 Enforce the passphrase constraints by not allowing the user to
457 bypass them using the "Take it anyway" button.
459 '--min-passphrase-len N'
460 Set the minimal length of a passphrase. When entering a new
461 passphrase shorter than this value a warning will be displayed.
464 '--min-passphrase-nonalpha N'
465 Set the minimal number of digits or special characters required in
466 a passphrase. When entering a new passphrase with less than this
467 number of digits or special characters a warning will be displayed.
470 '--check-passphrase-pattern FILE'
471 '--check-sym-passphrase-pattern FILE'
472 Check the passphrase against the pattern given in FILE. When
473 entering a new passphrase matching one of these pattern a warning
474 will be displayed. If FILE does not contain any slashes and does
475 not start with "~/" it is searched in the system configuration
476 directory ('/usr/local/etc/gnupg'). The default is not to use any
477 pattern file. The second version of this option is only used when
478 creating a new symmetric key to allow the use of different patterns
479 for such passphrases.
481 Security note: It is known that checking a passphrase against a
482 list of pattern or even against a complete dictionary is not very
483 effective to enforce good passphrases. Users will soon figure up
484 ways to bypass such a policy. A better policy is to educate users
485 on good security behavior and optionally to run a passphrase
486 cracker regularly on all users passphrases to catch the very simple
489 '--max-passphrase-days N'
490 Ask the user to change the passphrase if N days have passed since
491 the last change. With '--enforce-passphrase-constraints' set the
492 user may not bypass this check.
494 '--enable-passphrase-history'
495 This option does nothing yet.
497 '--pinentry-invisible-char CHAR'
498 This option asks the Pinentry to use CHAR for displaying hidden
499 characters. CHAR must be one character UTF-8 string. A Pinentry
500 may or may not honor this request.
502 '--pinentry-timeout N'
503 This option asks the Pinentry to timeout after N seconds with no
504 user input. The default value of 0 does not ask the pinentry to
505 timeout, however a Pinentry may use its own default timeout value
506 in this case. A Pinentry may or may not honor this request.
508 '--pinentry-formatted-passphrase'
509 This option asks the Pinentry to enable passphrase formatting when
510 asking the user for a new passphrase and masking of the passphrase
513 If passphrase formatting is enabled, then all non-breaking space
514 characters are stripped from the entered passphrase. Passphrase
515 formatting is mostly useful in combination with passphrases
516 generated with the GENPIN feature of some Pinentries. Note that
517 such a generated passphrase, if not modified by the user, skips all
518 passphrase constraints checking because such constraints would
519 actually weaken the generated passphrase.
521 '--pinentry-program FILENAME'
522 Use program FILENAME as the PIN entry. The default is installation
523 dependent. With the default configuration the name of the default
524 pinentry is 'pinentry'; if that file does not exist but a
525 'pinentry-basic' exist the latter is used.
527 On a Windows platform the default is to use the first existing
528 program from this list: 'bin\pinentry.exe',
529 '..\Gpg4win\bin\pinentry.exe', '..\Gpg4win\pinentry.exe',
530 '..\GNU\GnuPG\pinentry.exe', '..\GNU\bin\pinentry.exe',
531 'bin\pinentry-basic.exe' where the file names are relative to the
532 GnuPG installation directory.
534 '--pinentry-touch-file FILENAME'
535 By default the filename of the socket gpg-agent is listening for
536 requests is passed to Pinentry, so that it can touch that file
537 before exiting (it does this only in curses mode). This option
538 changes the file passed to Pinentry to FILENAME. The special name
539 '/dev/null' may be used to completely disable this feature. Note
540 that Pinentry will not create that file, it will only change the
541 modification and access time.
543 '--scdaemon-program FILENAME'
544 Use program FILENAME as the Smartcard daemon. The default is
545 installation dependent and can be shown with the 'gpgconf' command.
548 Do not make use of the scdaemon tool. This option has the effect
549 of disabling the ability to do smartcard operations. Note, that
550 enabling this option at runtime does not kill an already forked
553 '--disable-check-own-socket'
554 'gpg-agent' employs a periodic self-test to detect a stolen socket.
555 This usually means a second instance of 'gpg-agent' has taken over
556 the socket and 'gpg-agent' will then terminate itself. This option
557 may be used to disable this self-test for debugging purposes.
559 '--use-standard-socket'
560 '--no-use-standard-socket'
561 '--use-standard-socket-p'
562 Since GnuPG 2.1 the standard socket is always used. These options
563 have no more effect. The command 'gpg-agent
564 --use-standard-socket-p' will thus always return success.
570 '--lc-messages STRING'
571 '--xauthority STRING'
572 These options are used with the server mode to pass localization
577 Ignore requests to change the current 'tty' or X window system's
578 'DISPLAY' variable respectively. This is useful to lock the
579 pinentry to pop up at the 'tty' or display you started the agent.
582 Set the size of the queue for pending connections. The default is
585 '--extra-socket NAME'
586 The extra socket is created by default, you may use this option to
587 change the name of the socket. To disable the creation of the
588 socket use "none" or "/dev/null" for NAME.
590 Also listen on native gpg-agent connections on the given socket.
591 The intended use for this extra socket is to setup a Unix domain
592 socket forwarding from a remote machine to this socket on the local
593 machine. A 'gpg' running on the remote machine may then connect to
594 the local gpg-agent and use its private keys. This enables
595 decrypting or signing data on a remote machine without exposing the
596 private keys to the remote machine.
598 '--enable-extended-key-format'
599 '--disable-extended-key-format'
600 These options are obsolete and have no effect. The extended key
601 format is used for years now and has been supported since 2.1.12.
602 Existing keys in the old format are migrated to the new format as
603 soon as they are touched.
605 '--enable-ssh-support'
606 '--enable-putty-support'
608 The OpenSSH Agent protocol is always enabled, but 'gpg-agent' will
609 only set the 'SSH_AUTH_SOCK' variable if this flag is given.
611 In this mode of operation, the agent does not only implement the
612 gpg-agent protocol, but also the agent protocol used by OpenSSH
613 (through a separate socket). Consequently, it should be possible
614 to use the gpg-agent as a drop-in replacement for the well known
617 SSH Keys, which are to be used through the agent, need to be added
618 to the gpg-agent initially through the ssh-add utility. When a key
619 is added, ssh-add will ask for the password of the provided key
620 file and send the unprotected key material to the agent; this
621 causes the gpg-agent to ask for a passphrase, which is to be used
622 for encrypting the newly received key and storing it in a gpg-agent
625 Once a key has been added to the gpg-agent this way, the gpg-agent
626 will be ready to use the key.
628 Note: in case the gpg-agent receives a signature request, the user
629 might need to be prompted for a passphrase, which is necessary for
630 decrypting the stored key. Since the ssh-agent protocol does not
631 contain a mechanism for telling the agent on which display/terminal
632 it is running, gpg-agent's ssh-support will use the TTY or X
633 display where gpg-agent has been started. To switch this display
634 to the current one, the following command may be used:
636 gpg-connect-agent updatestartuptty /bye
638 Although all GnuPG components try to start the gpg-agent as needed,
639 this is not possible for the ssh support because ssh does not know
640 about it. Thus if no GnuPG tool which accesses the agent has been
641 run, there is no guarantee that ssh is able to use gpg-agent for
642 authentication. To fix this you may start gpg-agent if needed
643 using this simple command:
645 gpg-connect-agent /bye
647 Adding the '--verbose' shows the progress of starting the agent.
649 The '--enable-putty-support' is only available under Windows and
650 allows the use of gpg-agent with the ssh implementation 'putty'.
651 This is similar to the regular ssh-agent support but makes use of
652 Windows message queue as required by 'putty'.
654 The order in which keys are presented to ssh are:
656 'Negative Use-for-ssh values'
657 If a key file has the attribute "Use-for-ssh" and its value is
658 negative, these keys are presented first to ssh. The negative
659 values are capped at -999 with -999 beeing lower ranked than
660 -1. These values can be used to prefer on-disk keys over keys
661 taken from active cards.
664 Active cards (inserted into a card reader or plugged in
665 tokens) are always tried; they are ordered by their serial
668 'Keys listed in the sshcontrol file'
669 Non-disabled keys from the sshcontrol file are presented in
670 the order they appear in this file. Note that the sshcontrol
673 'Positive Use-for-ssh values'
674 If a key file has the attribute "Use-for-ssh" and its value is
675 "yes", "true", or any positive number the key is presented in
676 the order of their values. "yes" and "true" have a value of
677 1; other values are capped at 99999.
679 Editing the "Use-for-ssh" values can be done with an editor or
680 using 'gpg-connect-agent' and "KEYATTR" (Remember to append a colon
681 to the key; i.e. use "Use-for-ssh:").
683 '--ssh-fingerprint-digest'
685 Select the digest algorithm used to compute ssh fingerprints that
686 are communicated to the user, e.g. in pinentry dialogs. OpenSSH
687 has transitioned from using MD5 to the more secure SHA256.
689 '--auto-expand-secmem N'
690 Allow Libgcrypt to expand its secure memory area as required. The
691 optional value N is a non-negative integer with a suggested size in
692 bytes of each additionally allocated secure memory area. The value
693 is rounded up to the next 32 KiB; usual C style prefixes are
694 allowed. For an heavy loaded gpg-agent with many concurrent
695 connection this option avoids sign or decrypt errors due to out of
696 secure memory error returns.
698 '--s2k-calibration MILLISECONDS'
699 Change the default calibration time to MILLISECONDS. The given
700 value is capped at 60 seconds; a value of 0 resets to the
701 compiled-in default. This option is re-read on a SIGHUP (or
702 'gpgconf --reload gpg-agent') and the S2K count is then
706 Specify the iteration count used to protect the passphrase. This
707 option can be used to override the auto-calibration done by
708 default. The auto-calibration computes a count which requires by
709 default 100ms to mangle a given passphrase. See also
712 To view the actually used iteration count and the milliseconds
713 required for an S2K operation use:
715 gpg-connect-agent 'GETINFO s2k_count' /bye
716 gpg-connect-agent 'GETINFO s2k_time' /bye
718 To view the auto-calibrated count use:
720 gpg-connect-agent 'GETINFO s2k_count_cal' /bye
723 File: gnupg.info, Node: Agent Configuration, Next: Agent Signals, Prev: Agent Options, Up: Invoking GPG-AGENT
728 There are a few configuration files needed for the operation of the
729 agent. By default they may all be found in the current home directory
730 (*note option --homedir::).
733 This is the standard configuration file read by 'gpg-agent' on
734 startup. It may contain any valid long option; the leading two
735 dashes may not be entered and the option may not be abbreviated.
736 This file is also read after a 'SIGHUP' however only a few options
737 will actually have an effect. This default name may be changed on
738 the command line (*note option --options::). You should backup
742 This is the list of trusted keys. You should backup this file.
744 Comment lines, indicated by a leading hash mark, as well as empty
745 lines are ignored. To mark a key as trusted you need to enter its
746 fingerprint followed by a space and a capital letter 'S'. Colons
747 may optionally be used to separate the bytes of a fingerprint; this
748 enables cutting and pasting the fingerprint from a key listing
749 output. If the line is prefixed with a '!' the key is explicitly
750 marked as not trusted.
752 Here is an example where two keys are marked as ultimately trusted
753 and one as not trusted:
755 # CN=Wurzel ZS 3,O=Intevation GmbH,C=DE
756 A6935DD34EF3087973C706FC311AA2CCF733765B S
758 # CN=PCA-1-Verwaltung-02/O=PKI-1-Verwaltung/C=DE
759 DC:BD:69:25:48:BD:BB:7E:31:6E:BB:80:D3:00:80:35:D4:F8:A6:CD S
761 # CN=Root-CA/O=Schlapphuete/L=Pullach/C=DE
762 !14:56:98:D3:FE:9C:CA:5A:31:6E:BC:81:D3:11:4E:00:90:A3:44:C2 S
764 Before entering a key into this file, you need to ensure its
765 authenticity. How to do this depends on your organisation; your
766 administrator might have already entered those keys which are
767 deemed trustworthy enough into this file. Places where to look for
768 the fingerprint of a root certificate are letters received from the
769 CA or the website of the CA (after making 100% sure that this is
770 indeed the website of that CA). You may want to consider
771 disallowing interactive updates of this file by using the *note
772 option --no-allow-mark-trusted::. It might even be advisable to
773 change the permissions to read-only so that this file can't be
774 changed inadvertently.
776 As a special feature a line 'include-default' will include a global
777 list of trusted certificates (e.g.
778 '/usr/local/etc/gnupg/trustlist.txt'). This global list is also
779 used if the local list is not available; the *note option
780 --no-user-trustlist:: enforces the use of only this global list.
782 It is possible to add further flags after the 'S' for use by the
786 Relax checking of some root certificate requirements. As of
787 now this flag allows the use of root certificates with a
788 missing basicConstraints attribute (despite that it is a MUST
789 for CA certificates) and disables CRL checking for the root
793 If validation of a certificate finally issued by a CA with
794 this flag set fails, try again using the chain validation
798 The CA is allowed to issue certificates for qualified
799 signatures. This flag has an effect only if used in the
800 global list. This is now the preferred way to mark such CA;
801 the old way of having a separate file 'qualified.txt' is still
805 The CA is part of an approved PKI for the German
806 classification level VS-NfD. It is only valid in the global
807 trustlist. As of now this is used only for documentation
811 This file is used when support for the secure shell agent protocol
812 has been enabled (*note option --enable-ssh-support::). Only keys
813 present in this file are used in the SSH protocol. You should
816 This file is deprecated in favor of the "Use-for-ssh" attribute in
819 The 'ssh-add' tool may be used to add new entries to this file; you
820 may also add them manually. Comment lines, indicated by a leading
821 hash mark, as well as empty lines are ignored. An entry starts
822 with optional whitespace, followed by the keygrip of the key given
823 as 40 hex digits, optionally followed by the caching TTL in seconds
824 and another optional field for arbitrary flags. A non-zero TTL
825 overrides the global default as set by '--default-cache-ttl-ssh'.
827 The only flag support is 'confirm'. If this flag is found for a
828 key, each use of the key will pop up a pinentry to confirm the use
829 of that key. The flag is automatically set if a new key was loaded
830 into 'gpg-agent' using the option '-c' of the 'ssh-add' command.
832 The keygrip may be prefixed with a '!' to disable an entry.
834 The following example lists exactly one key. Note that keys
835 available through a OpenPGP smartcard in the active smartcard
836 reader are implicitly added to this list; i.e. there is no need to
839 # Key added on: 2011-07-20 20:38:46
840 # Fingerprint: 5e:8d:c4:ad:e7:af:6e:27:8a:d6:13:e4:79:ad:0b:81
841 34B62F25E277CF13D3C6BCEBFD3F85D08F0A864B 0 confirm
845 This is the directory where gpg-agent stores the private keys.
846 Each key is stored in a file with the name made up of the keygrip
847 and the suffix 'key'. You should backup all files in this
848 directory and take great care to keep this backup closed away.
850 Note that on larger installations, it is useful to put predefined
851 files into the directory '/usr/local/etc/skel/.gnupg' so that newly
852 created users start up with a working configuration. For existing users
853 the a small helper script is provided to create these files (*note
857 File: gnupg.info, Node: Agent Signals, Next: Agent Examples, Prev: Agent Configuration, Up: Invoking GPG-AGENT
859 2.4 Use of some signals
860 =======================
862 A running 'gpg-agent' may be controlled by signals, i.e. using the
863 'kill' command to send a signal to the process.
865 Here is a list of supported signals:
868 This signal flushes all cached passphrases and if the program has
869 been started with a configuration file, the configuration file is
870 read again. Only certain options are honored: 'quiet', 'verbose',
871 'debug', 'debug-all', 'debug-level', 'debug-pinentry', 'no-grab',
872 'pinentry-program', 'pinentry-invisible-char', 'default-cache-ttl',
873 'max-cache-ttl', 'ignore-cache-for-signing', 's2k-count',
874 'no-allow-external-cache', 'allow-emacs-pinentry',
875 'no-allow-mark-trusted', 'disable-scdaemon', and
876 'disable-check-own-socket'. 'scdaemon-program' is also supported
877 but due to the current implementation, which calls the scdaemon
878 only once, it is not of much use unless you manually kill the
882 Shuts down the process but waits until all current requests are
883 fulfilled. If the process has received 3 of these signals and
884 requests are still pending, a shutdown is forced.
887 Shuts down the process immediately.
890 Dump internal information to the log file.
893 This signal is used for internal purposes.
896 File: gnupg.info, Node: Agent Examples, Next: Agent Protocol, Prev: Agent Signals, Up: Invoking GPG-AGENT
901 It is important to set the environment variable 'GPG_TTY' in your login
902 shell, for example in the '~/.bashrc' init script:
904 export GPG_TTY=$(tty)
906 If you enabled the Ssh Agent Support, you also need to tell ssh about
907 it by adding this to your init script:
910 if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then
911 export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"
915 File: gnupg.info, Node: Agent Protocol, Prev: Agent Examples, Up: Invoking GPG-AGENT
917 2.6 Agent's Assuan Protocol
918 ===========================
920 Note: this section does only document the protocol, which is used by
921 GnuPG components; it does not deal with the ssh-agent protocol. To see
922 the full specification of each command, use
924 gpg-connect-agent 'help COMMAND' /bye
926 or just 'help' to list all available commands.
928 The 'gpg-agent' daemon is started on demand by the GnuPG components.
930 To identify a key we use a thing called keygrip which is the SHA-1
931 hash of an canonical encoded S-Expression of the public key as used in
932 Libgcrypt. For the purpose of this interface the keygrip is given as a
933 hex string. The advantage of using this and not the hash of a
934 certificate is that it will be possible to use the same keypair for
935 different protocols, thereby saving space on the token used to keep the
938 The 'gpg-agent' may send status messages during a command or when
939 returning from a command to inform a client about the progress or result
940 of an operation. For example, the INQUIRE_MAXLEN status message may be
941 sent during a server inquire to inform the client of the maximum usable
942 length of the inquired data (which should not be exceeded).
946 * Agent PKDECRYPT:: Decrypting a session key
947 * Agent PKSIGN:: Signing a Hash
948 * Agent GENKEY:: Generating a Key
949 * Agent IMPORT:: Importing a Secret Key
950 * Agent EXPORT:: Exporting a Secret Key
951 * Agent ISTRUSTED:: Importing a Root Certificate
952 * Agent GET_PASSPHRASE:: Ask for a passphrase
953 * Agent CLEAR_PASSPHRASE:: Expire a cached passphrase
954 * Agent PRESET_PASSPHRASE:: Set a passphrase for a keygrip
955 * Agent GET_CONFIRMATION:: Ask for confirmation
956 * Agent HAVEKEY:: Check whether a key is available
957 * Agent LEARN:: Register a smartcard
958 * Agent PASSWD:: Change a Passphrase
959 * Agent UPDATESTARTUPTTY:: Change the Standard Display
960 * Agent GETEVENTCOUNTER:: Get the Event Counters
961 * Agent GETINFO:: Return information about the process
962 * Agent OPTION:: Set options for the session
965 File: gnupg.info, Node: Agent PKDECRYPT, Next: Agent PKSIGN, Up: Agent Protocol
967 2.6.1 Decrypting a session key
968 ------------------------------
970 The client asks the server to decrypt a session key. The encrypted
971 session key should have all information needed to select the appropriate
972 secret key or to delegate it to a smartcard.
976 Tell the server about the key to be used for decryption. If this is
977 not used, 'gpg-agent' may try to figure out the key by trying to decrypt
978 the message with each key available.
982 The agent checks whether this command is allowed and then does an
983 INQUIRY to get the ciphertext the client should then send the cipher
986 S: INQUIRE CIPHERTEXT
991 Please note that the server may send status info lines while reading
992 the data lines from the client. The data send is a SPKI like S-Exp with
997 (<param_name1> <mpi>)
999 (<param_namen> <mpi>)))
1001 Where algo is a string with the name of the algorithm; see the
1002 libgcrypt documentation for a list of valid algorithms. The number and
1003 names of the parameters depend on the algorithm. The agent does return
1004 an error if there is an inconsistency.
1006 If the decryption was successful the decrypted data is returned by
1009 Here is an example session:
1011 S: INQUIRE CIPHERTEXT
1012 C: D (enc-val elg (a 349324324)
1013 C: D (b 3F444677CA)))
1015 S: # session key follows
1017 S: D (value 1234567890ABCDEF0)
1018 S: OK decryption successful
1020 The “PADDING” status line is only send if gpg-agent can tell what
1021 kind of padding is used. As of now only the value 0 is used to indicate
1022 that the padding has been removed.
1025 File: gnupg.info, Node: Agent PKSIGN, Next: Agent GENKEY, Prev: Agent PKDECRYPT, Up: Agent Protocol
1027 2.6.2 Signing a Hash
1028 --------------------
1030 The client asks the agent to sign a given hash value. A default key
1031 will be chosen if no key has been set. To set a key a client first
1036 This can be used multiple times to create multiple signature, the
1037 list of keys is reset with the next PKSIGN command or a RESET. The
1038 server tests whether the key is a valid key to sign something and
1041 SETHASH --hash=<name>|<algo> <hexstring>
1043 The client can use this command to tell the server about the data
1044 <hexstring> (which usually is a hash) to be signed. <algo> is the
1045 decimal encoded hash algorithm number as used by Libgcrypt. Either
1046 <algo> or -hash=<name> must be given. Valid names for <name> are:
1049 The SHA-1 hash algorithm
1051 The SHA-256 hash algorithm
1053 The RIPE-MD160 hash algorithm
1055 The old and broken MD5 hash algorithm
1057 A combined hash algorithm as used by the TLS protocol.
1059 The actual signing is done using
1063 Options are not yet defined, but may later be used to choose among
1064 different algorithms. The agent does then some checks, asks for the
1065 passphrase and as a result the server returns the signature as an SPKI
1066 like S-expression in "D" lines:
1070 (<param_name1> <mpi>)
1072 (<param_namen> <mpi>)))
1074 The operation is affected by the option
1076 OPTION use-cache-for-signing=0|1
1078 The default of '1' uses the cache. Setting this option to '0' will
1079 lead 'gpg-agent' to ignore the passphrase cache. Note, that there is
1080 also a global command line option for 'gpg-agent' to globally disable
1083 Here is an example session:
1089 S: # I did ask the user whether he really wants to sign
1090 S: # I did ask the user for the passphrase
1092 C: D ABCDEF012345678901234
1094 S: # signature follows
1095 S: D (sig-val rsa (s 45435453654612121212))
1099 File: gnupg.info, Node: Agent GENKEY, Next: Agent IMPORT, Prev: Agent PKSIGN, Up: Agent Protocol
1101 2.6.3 Generating a Key
1102 ----------------------
1104 This is used to create a new keypair and store the secret key inside the
1105 active PSE -- which is in most cases a Soft-PSE. A not-yet-defined
1106 option allows choosing the storage location. To get the secret key out
1107 of the PSE, a special export tool has to be used.
1109 GENKEY [--no-protection] [--preset] [<cache_nonce>]
1111 Invokes the key generation process and the server will then inquire
1112 on the generation parameters, like:
1115 C: D (genkey (rsa (nbits 1024)))
1118 The format of the key parameters which depends on the algorithm is of
1123 (parameter_name_1 ....)
1125 (parameter_name_n ....)))
1127 If everything succeeds, the server returns the *public key* in a SPKI
1128 like S-Expression like this:
1135 Here is an example session:
1138 C: D (genkey (rsa (nbits 1024)))
1141 S: D (rsa (n 326487324683264) (e 10001)))
1144 The '--no-protection' option may be used to prevent prompting for a
1145 passphrase to protect the secret key while leaving the secret key
1146 unprotected. The '--preset' option may be used to add the passphrase to
1147 the cache using the default cache parameters.
1149 The '--inq-passwd' option may be used to create the key with a
1150 supplied passphrase. When used the agent does an inquiry with the
1151 keyword 'NEWPASSWD' to retrieve that passphrase. This option takes
1152 precedence over '--no-protection'; however if the client sends a empty
1153 (zero-length) passphrase, this is identical to '--no-protection'.
1156 File: gnupg.info, Node: Agent IMPORT, Next: Agent EXPORT, Prev: Agent GENKEY, Up: Agent Protocol
1158 2.6.4 Importing a Secret Key
1159 ----------------------------
1161 This operation is not yet supported by GpgAgent. Specialized tools are
1162 to be used for this.
1164 There is no actual need because we can expect that secret keys
1165 created by a 3rd party are stored on a smartcard. If we have generated
1166 the key ourselves, we do not need to import it.
1169 File: gnupg.info, Node: Agent EXPORT, Next: Agent ISTRUSTED, Prev: Agent IMPORT, Up: Agent Protocol
1171 2.6.5 Export a Secret Key
1172 -------------------------
1176 Should be done by an extra tool.
1179 File: gnupg.info, Node: Agent ISTRUSTED, Next: Agent GET_PASSPHRASE, Prev: Agent EXPORT, Up: Agent Protocol
1181 2.6.6 Importing a Root Certificate
1182 ----------------------------------
1184 Actually we do not import a Root Cert but provide a way to validate any
1185 piece of data by storing its Hash along with a description and an
1186 identifier in the PSE. Here is the interface description:
1188 ISTRUSTED <fingerprint>
1190 Check whether the OpenPGP primary key or the X.509 certificate with
1191 the given fingerprint is an ultimately trusted key or a trusted Root CA
1192 certificate. The fingerprint should be given as a hexstring (without
1193 any blanks or colons or whatever in between) and may be left padded with
1194 00 in case of an MD5 fingerprint. GPGAgent will answer with:
1198 The key is in the table of trusted keys.
1200 ERR 304 (Not Trusted)
1202 The key is not in this table.
1204 Gpg needs the entire list of trusted keys to maintain the web of
1205 trust; the following command is therefore quite helpful:
1209 GpgAgent returns a list of trusted keys line by line:
1211 S: D 000000001234454556565656677878AF2F1ECCFF P
1212 S: D 340387563485634856435645634856438576457A P
1213 S: D FEDC6532453745367FD83474357495743757435D S
1216 The first item on a line is the hexified fingerprint where MD5
1217 fingerprints are '00' padded to the left and the second item is a flag
1218 to indicate the type of key (so that gpg is able to only take care of
1219 PGP keys). P = OpenPGP, S = S/MIME. A client should ignore the rest of
1220 the line, so that we can extend the format in the future.
1222 Finally a client should be able to mark a key as trusted:
1224 MARKTRUSTED FINGERPRINT "P"|"S"
1226 The server will then pop up a window to ask the user whether she
1227 really trusts this key. For this it will probably ask for a text to be
1228 displayed like this:
1230 S: INQUIRE TRUSTDESC
1231 C: D Do you trust the key with the fingerprint @FPR@
1232 C: D bla fasel blurb.
1236 Known sequences with the pattern @foo@ are replaced according to this
1240 Format the fingerprint according to gpg rules for a v3 keys.
1242 Format the fingerprint according to gpg rules for a v4 keys.
1244 Choose an appropriate format to format the fingerprint.
1246 Replaced by a single '@'.
1249 File: gnupg.info, Node: Agent GET_PASSPHRASE, Next: Agent CLEAR_PASSPHRASE, Prev: Agent ISTRUSTED, Up: Agent Protocol
1251 2.6.7 Ask for a passphrase
1252 --------------------------
1254 This function is usually used to ask for a passphrase to be used for
1255 symmetric encryption, but may also be used by programs which need
1256 special handling of passphrases. This command uses a syntax which helps
1257 clients to use the agent with minimum effort.
1259 GET_PASSPHRASE [--data] [--check] [--no-ask] [--repeat[=N]] \
1260 [--qualitybar] CACHE_ID \
1261 [ERROR_MESSAGE PROMPT DESCRIPTION]
1263 CACHE_ID is expected to be a string used to identify a cached
1264 passphrase. Use a 'X' to bypass the cache. With no other arguments the
1265 agent returns a cached passphrase or an error. By convention either the
1266 hexified fingerprint of the key shall be used for CACHE_ID or an
1267 arbitrary string prefixed with the name of the calling application and a
1268 colon: Like 'gpg:somestring'.
1270 ERROR_MESSAGE is either a single 'X' for no error message or a string
1271 to be shown as an error message like (e.g. "invalid passphrase").
1272 Blanks must be percent escaped or replaced by '+''.
1274 PROMPT is either a single 'X' for a default prompt or the text to be
1275 shown as the prompt. Blanks must be percent escaped or replaced by '+'.
1277 DESCRIPTION is a text shown above the entry field. Blanks must be
1278 percent escaped or replaced by '+'.
1280 The agent either returns with an error or with a OK followed by the
1281 hex encoded passphrase. Note that the length of the strings is
1282 implicitly limited by the maximum length of a command. If the option
1283 '--data' is used, the passphrase is not returned on the OK line but by
1284 regular data lines; this is the preferred method.
1286 If the option '--check' is used, the standard passphrase constraints
1287 checks are applied. A check is not done if the passphrase has been
1290 If the option '--no-ask' is used and the passphrase is not in the
1291 cache the user will not be asked to enter a passphrase but the error
1292 code 'GPG_ERR_NO_DATA' is returned.
1294 If the option '--qualitybar' is used and a minimum passphrase length
1295 has been configured, a visual indication of the entered passphrase
1298 CLEAR_PASSPHRASE CACHE_ID
1300 may be used to invalidate the cache entry for a passphrase. The
1301 function returns with OK even when there is no cached passphrase.
1304 File: gnupg.info, Node: Agent CLEAR_PASSPHRASE, Next: Agent PRESET_PASSPHRASE, Prev: Agent GET_PASSPHRASE, Up: Agent Protocol
1306 2.6.8 Remove a cached passphrase
1307 --------------------------------
1309 Use this command to remove a cached passphrase.
1311 CLEAR_PASSPHRASE [--mode=normal] <cache_id>
1313 The '--mode=normal' option can be used to clear a CACHE_ID that was
1317 File: gnupg.info, Node: Agent PRESET_PASSPHRASE, Next: Agent GET_CONFIRMATION, Prev: Agent CLEAR_PASSPHRASE, Up: Agent Protocol
1319 2.6.9 Set a passphrase for a keygrip
1320 ------------------------------------
1322 This command adds a passphrase to the cache for the specified KEYGRIP.
1324 PRESET_PASSPHRASE [--inquire] <string_or_keygrip> <timeout> [<hexstring>]
1326 The passphrase is a hexadecimal string when specified. When not
1327 specified, the passphrase will be retrieved from the pinentry module
1328 unless the '--inquire' option was specified in which case the passphrase
1329 will be retrieved from the client.
1331 The TIMEOUT parameter keeps the passphrase cached for the specified
1332 number of seconds. A value of '-1' means infinite while '0' means the
1333 default (currently only a timeout of -1 is allowed, which means to never
1337 File: gnupg.info, Node: Agent GET_CONFIRMATION, Next: Agent HAVEKEY, Prev: Agent PRESET_PASSPHRASE, Up: Agent Protocol
1339 2.6.10 Ask for confirmation
1340 ---------------------------
1342 This command may be used to ask for a simple confirmation by presenting
1343 a text and 2 buttons: Okay and Cancel.
1345 GET_CONFIRMATION DESCRIPTION
1347 DESCRIPTIONis displayed along with a Okay and Cancel button. Blanks
1348 must be percent escaped or replaced by '+'. A 'X' may be used to
1349 display confirmation dialog with a default text.
1351 The agent either returns with an error or with a OK. Note, that the
1352 length of DESCRIPTION is implicitly limited by the maximum length of a
1356 File: gnupg.info, Node: Agent HAVEKEY, Next: Agent LEARN, Prev: Agent GET_CONFIRMATION, Up: Agent Protocol
1358 2.6.11 Check whether a key is available
1359 ---------------------------------------
1361 This can be used to see whether a secret key is available. It does not
1362 return any information on whether the key is somehow protected.
1366 The agent answers either with OK or 'No_Secret_Key' (208). The
1367 caller may want to check for other error codes as well. More than one
1368 keygrip may be given. In this case the command returns success if at
1369 least one of the keygrips corresponds to an available secret key.
1372 File: gnupg.info, Node: Agent LEARN, Next: Agent PASSWD, Prev: Agent HAVEKEY, Up: Agent Protocol
1374 2.6.12 Register a smartcard
1375 ---------------------------
1379 This command is used to register a smartcard. With the '--send'
1380 option given the certificates are sent back.
1383 File: gnupg.info, Node: Agent PASSWD, Next: Agent UPDATESTARTUPTTY, Prev: Agent LEARN, Up: Agent Protocol
1385 2.6.13 Change a Passphrase
1386 --------------------------
1388 PASSWD [--cache-nonce=<c>] [--passwd-nonce=<s>] [--preset] KEYGRIP
1390 This command is used to interactively change the passphrase of the
1391 key identified by the hex string KEYGRIP. The '--preset' option may be
1392 used to add the new passphrase to the cache using the default cache
1396 File: gnupg.info, Node: Agent UPDATESTARTUPTTY, Next: Agent GETEVENTCOUNTER, Prev: Agent PASSWD, Up: Agent Protocol
1398 2.6.14 Change the standard display
1399 ----------------------------------
1403 Set the startup TTY and X-DISPLAY variables to the values of this
1404 session. This command is useful to direct future pinentry invocations
1405 to another screen. It is only required because there is no way in the
1406 ssh-agent protocol to convey this information.
1409 File: gnupg.info, Node: Agent GETEVENTCOUNTER, Next: Agent GETINFO, Prev: Agent UPDATESTARTUPTTY, Up: Agent Protocol
1411 2.6.15 Get the Event Counters
1412 -----------------------------
1416 This function return one status line with the current values of the
1417 event counters. The event counters are useful to avoid polling by
1418 delaying a poll until something has changed. The values are decimal
1419 numbers in the range '0' to 'UINT_MAX' and wrapping around to 0. The
1420 actual values should not be relied upon; they shall only be used to
1423 The currently defined counters are:
1425 Incremented with any change of any of the other counters.
1427 Incremented for added or removed private keys.
1429 Incremented for each change of the card reader's status.
1432 File: gnupg.info, Node: Agent GETINFO, Next: Agent OPTION, Prev: Agent GETEVENTCOUNTER, Up: Agent Protocol
1434 2.6.16 Return information about the process
1435 -------------------------------------------
1437 This is a multipurpose function to return a variety of information.
1441 The value of WHAT specifies the kind of information returned:
1443 Return the version of the program.
1445 Return the process id of the process.
1447 Return the name of the socket used to connect the agent.
1449 Return the name of the socket used for SSH connections. If SSH
1450 support has not been enabled the error 'GPG_ERR_NO_DATA' will be
1454 File: gnupg.info, Node: Agent OPTION, Prev: Agent GETINFO, Up: Agent Protocol
1456 2.6.17 Set options for the session
1457 ----------------------------------
1459 Here is a list of session options which are not yet described with other
1460 commands. The general syntax for an Assuan option is:
1467 This may be used to tell gpg-agent of which gpg-agent version the
1468 client is aware of. gpg-agent uses this information to enable
1469 features which might break older clients.
1472 Change the session's environment to be used for the Pinentry.
1478 Set envvar NAME to the empty string
1480 Set envvar NAME to the string VALUE.
1482 'use-cache-for-signing'
1483 See Assuan command 'PKSIGN'.
1485 'allow-pinentry-notify'
1486 This does not need any value. It is used to enable the
1487 PINENTRY_LAUNCHED inquiry.
1490 This option is used to change the operation mode of the pinentry.
1491 The following values are defined:
1494 This is the default mode which pops up a pinentry as needed.
1497 Instead of popping up a pinentry, return the error code
1501 Instead of popping up a pinentry, return the error code
1502 'GPG_ERR_NO_PIN_ENTRY'.
1505 Use a loopback pinentry. This fakes a pinentry by using
1506 inquiries back to the caller to ask for a passphrase. This
1507 option may only be set if the agent has been configured for
1508 that. To disable this feature use *note option
1509 --no-allow-loopback-pinentry::.
1511 'cache-ttl-opt-preset'
1512 This option sets the cache TTL for new entries created by GENKEY
1513 and PASSWD commands when using the '--preset' option. It is not
1514 used a default value is used.
1517 Instead of using the standard S2K count (which is computed on the
1518 fly), the given S2K count is used for new keys or when changing the
1519 passphrase of a key. Values below 65536 are considered to be 0.
1520 This option is valid for the entire session or until reset to 0.
1521 This option is useful if the key is later used on boxes which are
1522 either much slower or faster than the actual box.
1524 'pretend-request-origin'
1525 This option switches the connection into a restricted mode which
1526 handles all further commands in the same way as they would be
1527 handled when originating from the extra or browser socket. Note
1528 that this option is not available in the restricted mode. Valid
1529 values for this option are:
1533 This is a NOP and leaves the connection in the standard way.
1536 Pretend to come from a remote origin in the same way as
1537 connections from the '--extra-socket'.
1540 Pretend to come from a local web browser in the same way as
1541 connections from the '--browser-socket'.
1544 File: gnupg.info, Node: Invoking DIRMNGR, Next: Invoking GPG, Prev: Invoking GPG-AGENT, Up: Top
1549 Since version 2.1 of GnuPG, 'dirmngr' takes care of accessing the
1550 OpenPGP keyservers. As with previous versions it is also used as a
1551 server for managing and downloading certificate revocation lists (CRLs)
1552 for X.509 certificates, downloading X.509 certificates, and providing
1553 access to OCSP providers. Dirmngr is invoked internally by 'gpg',
1554 'gpgsm', or via the 'gpg-connect-agent' tool.
1556 *Note Option Index::,for an index to 'DIRMNGR''s commands and options.
1560 * Dirmngr Commands:: List of all commands.
1561 * Dirmngr Options:: List of all options.
1562 * Dirmngr Configuration:: Configuration files.
1563 * Dirmngr Signals:: Use of signals.
1564 * Dirmngr Examples:: Some usage examples.
1565 * Dirmngr Protocol:: The protocol dirmngr uses.
1568 File: gnupg.info, Node: Dirmngr Commands, Next: Dirmngr Options, Up: Invoking DIRMNGR
1573 Commands are not distinguished from options except for the fact that
1574 only one command is allowed.
1577 Print the program version and licensing information. Note that you
1578 cannot abbreviate this command.
1581 Print a usage message summarizing the most useful command-line
1582 options. Note that you cannot abbreviate this command.
1585 Print a list of all available options and commands. Note that you
1586 cannot abbreviate this command.
1589 Run in server mode and wait for commands on the 'stdin'. The
1590 default mode is to create a socket and listen for commands there.
1591 This is only used for testing.
1594 Run in background daemon mode and listen for commands on a socket.
1595 This is the way 'dirmngr' is started on demand by the other GnuPG
1596 components. To force starting 'dirmngr' it is in general best to
1597 use 'gpgconf --launch dirmngr'.
1600 Run in the foreground, sending logs to stderr, and listening on
1601 file descriptor 3, which must already be bound to a listening
1602 socket. This option is deprecated and not supported on Windows.
1605 List the contents of the CRL cache on 'stdout'. This is probably
1606 only useful for debugging purposes.
1609 This command requires a filename as additional argument, and it
1610 will make Dirmngr try to import the CRL in FILE into it's cache.
1611 Note, that this is only possible if Dirmngr is able to retrieve the
1612 CA's certificate directly by its own means. In general it is
1613 better to use 'gpgsm''s '--call-dirmngr loadcrl filename' command
1614 so that 'gpgsm' can help dirmngr.
1617 This command requires an URL as additional argument, and it will
1618 make dirmngr try to retrieve and import the CRL from that URL into
1619 it's cache. This is mainly useful for debugging purposes. The
1620 'dirmngr-client' provides the same feature for a running dirmngr.
1623 This commands shuts down an running instance of Dirmngr. This
1624 command has currently no effect.
1627 This command removes all CRLs from Dirmngr's cache. Client
1628 requests will thus trigger reading of fresh CRLs.
1631 File: gnupg.info, Node: Dirmngr Options, Next: Dirmngr Configuration, Prev: Dirmngr Commands, Up: Invoking DIRMNGR
1636 Note that all long options with the exception of '--options' and
1637 '--homedir' may also be given in the configuration file after stripping
1638 off the two leading dashes.
1641 Reads configuration from FILE instead of from the default per-user
1642 configuration file. The default configuration file is named
1643 'dirmngr.conf' and expected in the home directory.
1646 Set the name of the home directory to DIR. This option is only
1647 effective when used on the command line. The default is the
1648 directory named '.gnupg' directly below the home directory of the
1649 user unless the environment variable 'GNUPGHOME' has been set in
1650 which case its value will be used. Many kinds of data are stored
1651 within this directory.
1655 Outputs additional information while running. You can increase the
1656 verbosity by giving several verbose commands to DIRMNGR, such as
1660 Append all logging output to FILE. This is very helpful in seeing
1661 what the agent actually does. Use 'socket://' to log to socket.
1663 '--compatibility-flags FLAGS'
1664 Set compatibility flags to work around certain problems or to
1665 emulate bugs. The FLAGS are given as a comma separated list of
1666 flag names and are OR-ed together. The special flag "none" clears
1667 the list and allows to start over with an empty list. To get a
1668 list of available flags the sole word "help" can be used.
1670 '--debug-level LEVEL'
1671 Select the debug level for investigating problems. LEVEL may be a
1672 numeric value or by a keyword:
1675 No debugging at all. A value of less than 1 may be used
1676 instead of the keyword.
1678 Some basic debug messages. A value between 1 and 2 may be
1679 used instead of the keyword.
1681 More verbose debug messages. A value between 3 and 5 may be
1682 used instead of the keyword.
1684 Even more detailed messages. A value between 6 and 8 may be
1685 used instead of the keyword.
1687 All of the debug messages you can get. A value greater than 8
1688 may be used instead of the keyword. The creation of hash
1689 tracing files is only enabled if the keyword is used.
1691 How these messages are mapped to the actual debugging flags is not
1692 specified and may change with newer releases of this program. They
1693 are however carefully selected to best aid in debugging.
1696 Set debug flags. All flags are or-ed and FLAGS may be given in C
1697 syntax (e.g. 0x0042) or as a comma separated list of flag names.
1698 To get a list of all supported flags the single word "help" can be
1699 used. This option is only useful for debugging and the behavior
1700 may change at any time without notice.
1703 Same as '--debug=0xffffffff'
1706 Enable debugging of the TLS layer at LEVEL. The details of the
1707 debug level depend on the used TLS library and are not set in
1711 When running in server mode, wait N seconds before entering the
1712 actual processing loop and print the pid. This gives time to
1715 '--disable-check-own-socket'
1716 On some platforms 'dirmngr' is able to detect the removal of its
1717 socket file and shutdown itself. This option disable this
1718 self-test for debugging purposes.
1724 Format the info output in daemon mode for use with the standard
1725 Bourne shell respective the C-shell. The default is to guess it
1726 based on the environment variable 'SHELL' which is in almost all
1730 Enabling this option forces loading of expired CRLs; this is only
1731 useful for debugging.
1735 The option '--use-tor' switches Dirmngr and thus GnuPG into "Tor
1736 mode" to route all network access via Tor (an anonymity network).
1737 Certain other features are disabled in this mode. The effect of
1738 '--use-tor' cannot be overridden by any other command or even by
1739 reloading dirmngr. The use of '--no-use-tor' disables the use of
1740 Tor. The default is to use Tor if it is available on startup or
1741 after reloading dirmngr. The test on the availability of Tor is
1742 done by trying to connect to a SOCKS proxy at either port 9050 or
1743 9150; if another type of proxy is listening on one of these ports,
1744 you should use '--no-use-tor'.
1746 '--standard-resolver'
1747 This option forces the use of the system's standard DNS resolver
1748 code. This is mainly used for debugging. Note that on Windows a
1749 standard resolver is not used and all DNS access will return the
1750 error "Not Implemented" if this option is used. Using this
1751 together with enabled Tor mode returns the error "Not Enabled".
1753 '--recursive-resolver'
1754 When possible use a recursive resolver instead of a stub resolver.
1756 '--resolver-timeout N'
1757 Set the timeout for the DNS resolver to N seconds. The default are
1760 '--connect-timeout N'
1761 '--connect-quick-timeout N'
1762 Set the timeout for HTTP and generic TCP connection attempts to N
1763 seconds. The value set with the quick variant is used when the
1764 -quick option has been given to certain Assuan commands. The quick
1765 value is capped at the value of the regular connect timeout. The
1766 default values are 15 and 2 seconds. Note that the timeout values
1767 are for each connection attempt; the connection code will attempt
1768 to connect all addresses listed for a server.
1770 '--listen-backlog N'
1771 Set the size of the queue for pending connections. The default is
1774 '--allow-version-check'
1775 Allow Dirmngr to connect to 'https://versions.gnupg.org' to get the
1776 list of current software versions. If this option is enabled the
1777 list is retrieved in case the local copy does not exist or is older
1778 than 5 to 7 days. See the option '--query-swdb' of the command
1779 'gpgconf' for more details. Note, that regardless of this option a
1780 version check can always be triggered using this command:
1782 gpg-connect-agent --dirmngr 'loadswdb --force' /bye
1785 Use NAME as your keyserver. This is the server that 'gpg'
1786 communicates with to receive keys, send keys, and search for keys.
1787 The format of the NAME is a URI: 'scheme:[//]keyservername[:port]'
1788 The scheme is the type of keyserver: "hkp" for the HTTP (or
1789 compatible) keyservers or "ldap" for the LDAP keyservers. Note
1790 that your particular installation of GnuPG may have other keyserver
1791 types available as well. Keyserver schemes are case-insensitive.
1792 After the keyserver name, optional keyserver configuration options
1793 may be provided. These are the same as the '--keyserver-options'
1794 of 'gpg', but apply only to this particular keyserver.
1796 Some keyservers synchronize with each other, so there is not always
1797 a need to send keys to more than one server. Some keyservers use
1798 round robin DNS to give a different keyserver each time you use it.
1800 If exactly two keyservers are configured and only one is a Tor
1801 hidden service (.onion), Dirmngr selects the keyserver to use
1802 depending on whether Tor is locally running or not. The check for
1803 a running Tor is done for each new connection.
1805 If no keyserver is explicitly configured, dirmngr will use the
1806 built-in default of 'https://keyserver.ubuntu.com'.
1808 Windows users with a keyserver running on their Active Directory
1809 may use the short form 'ldap:///' for NAME to access this
1812 For accessing anonymous LDAP keyservers NAME is in general just a
1813 'ldaps://ldap.example.com'. A BaseDN parameter should never be
1814 specified. If authentication is required things are more
1815 complicated and two methods are available:
1817 The modern method (since version 2.2.28) is to use the very same
1818 syntax as used with the option '--ldapserver'. Please see over
1819 there for details; here is an example:
1821 keyserver ldap:ldap.example.com::uid=USERNAME,ou=GnuPG Users,
1822 dc=example,dc=com:PASSWORD::starttls
1824 The other method is to use a full URL for NAME; for example:
1826 keyserver ldaps://ldap.example.com/????bindname=uid=USERNAME
1827 %2Cou=GnuPG%20Users%2Cdc=example%2Cdc=com,password=PASSWORD
1829 Put this all on one line without any spaces and keep the '%2C' as
1830 given. Replace USERNAME, PASSWORD, and the 'dc' parts according to
1831 the instructions received from your LDAP administrator. Note that
1832 only simple authentication (i.e. cleartext passwords) is supported
1833 and thus using ldaps is strongly suggested (since 2.2.28 "ldaps"
1834 defaults to port 389 and uses STARTTLS). On Windows authentication
1835 via AD can be requested by adding 'gpgNtds=1' after the fourth
1836 question mark instead of the bindname and password parameter.
1838 '--nameserver IPADDR'
1839 In "Tor mode" Dirmngr uses a public resolver via Tor to resolve DNS
1840 names. If the default public resolver, which is '8.8.8.8', shall
1841 not be used a different one can be given using this option. Note
1842 that a numerical IP address must be given (IPv6 or IPv4) and that
1843 no error checking is done for IPADDR.
1847 Disable the use of all IPv4 or IPv6 addresses.
1850 Entirely disables the use of LDAP.
1853 Entirely disables the use of HTTP.
1856 When looking for the location of a CRL, the to be tested
1857 certificate usually contains so called "CRL Distribution Point"
1858 (DP) entries which are URLs describing the way to access the CRL.
1859 The first found DP entry is used. With this option all entries
1860 using the HTTP scheme are ignored when looking for a suitable DP.
1863 This is similar to '--ignore-http-dp' but ignores entries using the
1864 LDAP scheme. Both options may be combined resulting in ignoring
1867 '--ignore-ocsp-service-url'
1868 Ignore all OCSP URLs contained in the certificate. The effect is
1869 to force the use of the default responder.
1871 '--honor-http-proxy'
1872 If the environment variable 'http_proxy' has been set, use its
1873 value to access HTTP servers.
1875 '--http-proxy HOST[:PORT]'
1876 Use HOST and PORT to access HTTP servers. The use of this option
1877 overrides the environment variable 'http_proxy' regardless whether
1878 '--honor-http-proxy' has been set.
1880 '--ldap-proxy HOST[:PORT]'
1881 Use HOST and PORT to connect to LDAP servers. If PORT is omitted,
1882 port 389 (standard LDAP port) is used. This overrides any
1883 specified host and port part in a LDAP URL and will also be used if
1884 host and port have been omitted from the URL.
1887 Never use anything else but the LDAP "proxy" as configured with
1888 '--ldap-proxy'. Usually 'dirmngr' tries to use other configured
1889 LDAP server if the connection using the "proxy" failed.
1891 '--ldapserverlist-file FILE'
1892 Read the list of LDAP servers to consult for CRLs and X.509
1893 certificates from file instead of the default per-user ldap server
1894 list file. The default value for FILE is
1895 'dirmngr_ldapservers.conf'.
1897 This server list file contains one LDAP server per line in the
1900 HOSTNAME:PORT:USERNAME:PASSWORD:BASE_DN:FLAGS
1902 Lines starting with a '#' are comments.
1904 Note that as usual all strings entered are expected to be UTF-8
1905 encoded. Obviously this will lead to problems if the password has
1906 originally been encoded as Latin-1. There is no other solution
1907 here than to put such a password in the binary encoding into the
1908 file (i.e. non-ascii characters won't show up readable).(1)
1911 This is an alternative way to specify LDAP servers for CRL and
1912 X.509 certificate retrieval. If this option is used the servers
1913 configured in 'dirmngr_ldapservers.conf' (or the file given by
1914 '--ldapserverlist-file') are cleared. Note that
1915 'dirmngr_ldapservers.conf' is not read again by a reload signal.
1916 However, '--ldapserver' options are read again.
1918 SPEC is either a proper LDAP URL or a colon delimited list of the
1921 HOSTNAME:PORT:USERNAME:PASSWORD:BASE_DN:FLAGS:
1923 with an optional prefix of 'ldap:' (but without the two slashes
1924 which would turn this into a proper LDAP URL). FLAGS is a list of
1925 one or more comma delimited keywords:
1927 The default: Do not use a TLS secured connection at all; the
1928 default port is 389.
1930 Use STARTTLS to secure the connection; the default port is
1933 Tunnel LDAP through a TLS connection; the default port is 636.
1935 On Windows authenticate the LDAP connection using the Active
1936 Directory with the current user.
1938 On Windows use only the A or AAAA record when resolving the
1941 Note that in an URL style specification the scheme 'ldaps://'
1942 refers to STARTTLS and _not_ to LDAP-over-TLS.
1944 '--ldaptimeout SECS'
1945 Specify the number of seconds to wait for an LDAP query before
1946 timing out. The default are 15 seconds. 0 will never timeout.
1949 This option makes dirmngr add any servers it discovers when
1950 validating certificates against CRLs to the internal list of
1951 servers to consult for certificates and CRLs. This option should
1952 in general not be used.
1954 This option might be useful when trying to validate a certificate
1955 that has a CRL distribution point that points to a server that is
1956 not already listed in the ldapserverlist. Dirmngr will always go
1957 to this server and try to download the CRL, but chances are high
1958 that the certificate used to sign the CRL is located on the same
1959 server. So if dirmngr doesn't add that new server to list, it will
1960 often not be able to verify the signature of the CRL unless the
1961 '--add-servers' option is used.
1963 Caveat emptor: Using this option may enable denial-of-service
1964 attacks and leak search requests to unknown third parties. This is
1965 because arbitrary servers are added to the internal list of LDAP
1966 servers which in turn is used for all unspecific LDAP queries as
1967 well as a fallback for queries which did not return a result.
1970 This option enables OCSP support if requested by the client.
1972 OCSP requests are rejected by default because they may violate the
1973 privacy of the user; for example it is possible to track the time
1974 when a user is reading a mail.
1976 '--ocsp-responder URL'
1977 Use URL as the default OCSP Responder if the certificate does not
1978 contain information about an assigned responder. Note, that
1979 '--ocsp-signer' must also be set to a valid certificate.
1981 '--ocsp-signer FPR|FILE'
1982 Use the certificate with the fingerprint FPR to check the responses
1983 of the default OCSP Responder. Alternatively a filename can be
1984 given in which case the response is expected to be signed by one of
1985 the certificates described in that file. Any argument which
1986 contains a slash, dot or tilde is considered a filename. Usual
1987 filename expansion takes place: A tilde at the start followed by a
1988 slash is replaced by the content of 'HOME', no slash at start
1989 describes a relative filename which will be searched at the home
1990 directory. To make sure that the FILE is searched in the home
1991 directory, either prepend the name with "./" or use a name which
1994 If a response has been signed by a certificate described by these
1995 fingerprints no further check upon the validity of this certificate
1998 The format of the FILE is a list of SHA-1 fingerprint, one per line
1999 with optional colons between the bytes. Empty lines and lines
2000 prefix with a hash mark are ignored.
2002 '--ocsp-max-clock-skew N'
2003 The number of seconds a skew between the OCSP responder and them
2004 local clock is accepted. Default is 600 (10 minutes).
2006 '--ocsp-max-period N'
2007 Seconds a response is at maximum considered valid after the time
2008 given in the thisUpdate field. Default is 7776000 (90 days).
2010 '--ocsp-current-period N'
2011 The number of seconds an OCSP response is considered valid after
2012 the time given in the NEXT_UPDATE datum. Default is 10800 (3
2016 Do not return more that N items in one query. The default is 10.
2018 '--ignore-cert-extension OID'
2019 Add OID to the list of ignored certificate extensions. The OID is
2020 expected to be in dotted decimal form, like '2.5.29.3'. This
2021 option may be used more than once. Critical flagged certificate
2022 extensions matching one of the OIDs in the list are treated as if
2023 they are actually handled and thus the certificate won't be
2024 rejected due to an unknown critical extension. Use this option
2025 with care because extensions are usually flagged as critical for a
2028 '--ignore-crl-extension OID'
2029 Add OID to the list of ignored CRL extensions. The OID is expected
2030 to be in dotted decimal form. Critical flagged CRL extensions
2031 matching one of the OIDs in the list are treated as if they are
2032 actually handled and thus the certificate won't be rejected due to
2033 an unknown critical extension. Use this option with care because
2034 extensions are usually flagged as critical for a reason.
2036 '--ignore-cert FPR|FILE'
2037 Entirely ignore certificates with the fingerprint FPR. As an
2038 alternative to the fingerprint a filename can be given in which
2039 case all certificates described in that file are ignored. Any
2040 argument which contains a slash, dot or tilde is considered a
2041 filename. Usual filename expansion takes place: A tilde at the
2042 start followed by a slash is replaced by the content of 'HOME', no
2043 slash at start describes a relative filename which will be searched
2044 at the home directory. To make sure that the FILE is searched in
2045 the home directory, either prepend the name with "./" or use a name
2046 which contains a dot. The format of such a file is a list of SHA-1
2047 fingerprint, one per line with optional colons between the bytes.
2048 Empty lines and lines prefixed with a hash mark are ignored.
2050 This option is useful as a quick workaround to exclude certain
2051 certificates from the system store.
2054 Use the root certificates in FILE for verification of the TLS
2055 certificates used with 'hkps' (keyserver access over TLS). If the
2056 file is in PEM format a suffix of '.pem' is expected for FILE.
2057 This option may be given multiple times to add more root
2058 certificates. Tilde expansion is supported.
2060 If no 'hkp-cacert' directive is present, dirmngr will use the
2063 ---------- Footnotes ----------
2065 (1) The 'gpgconf' tool might be helpful for frontends as it enables
2066 editing this configuration file using percent-escaped strings.
2069 File: gnupg.info, Node: Dirmngr Configuration, Next: Dirmngr Signals, Prev: Dirmngr Options, Up: Invoking DIRMNGR
2074 Dirmngr makes use of several directories when running in daemon mode:
2075 There are a few configuration files to control the operation of dirmngr.
2076 By default they may all be found in the current home directory (*note
2077 option --homedir::).
2080 This is the standard configuration file read by 'dirmngr' on
2081 startup. It may contain any valid long option; the leading two
2082 dashes may not be entered and the option may not be abbreviated.
2083 This file is also read after a 'SIGHUP' however not all options
2084 will actually have an effect. This default name may be changed on
2085 the command line (*note option --options::). You should backup
2088 '/etc/gnupg/trusted-certs'
2089 This directory should be filled with certificates of Root CAs you
2090 are trusting in checking the CRLs and signing OCSP Responses.
2092 Usually these are the same certificates you use with the
2093 applications making use of dirmngr. It is expected that each of
2094 these certificate files contain exactly one DER encoded certificate
2095 in a file with the suffix '.crt' or '.der'. 'dirmngr' reads those
2096 certificates on startup and when given a SIGHUP. Certificates which
2097 are not readable or do not make up a proper X.509 certificate are
2098 ignored; see the log file for details.
2100 Applications using dirmngr (e.g. gpgsm) can request these
2101 certificates to complete a trust chain in the same way as with the
2102 extra-certs directory (see below).
2104 Note that for OCSP responses the certificate specified using the
2105 option '--ocsp-signer' is always considered valid to sign OCSP
2108 '/etc/gnupg/extra-certs'
2109 This directory may contain extra certificates which are preloaded
2110 into the internal cache on startup. Applications using dirmngr
2111 (e.g. gpgsm) can request cached certificates to complete a trust
2112 chain. This is convenient in cases you have a couple intermediate
2113 CA certificates or certificates usually used to sign OCSP
2114 responses. These certificates are first tried before going out to
2115 the net to look for them. These certificates must also be DER
2116 encoded and suffixed with '.crt' or '.der'.
2119 This directory is used to store cached CRLs. The 'crls.d' part
2120 will be created by dirmngr if it does not exists but you need to
2121 make sure that the upper directory exists.
2123 Several options control the use of trusted certificates for TLS and
2124 CRLs. Here is an Overview on the use and origin of those Root CA
2129 These System root certificates are used by: FIXME
2131 The origin of the system provided certificates depends on the
2132 platform. On Windows all certificates from the Windows System
2133 Stores 'ROOT' and 'CA' are used.
2135 On other platforms the certificates are read from the first file
2136 found form this list: '/etc/ssl/ca-bundle.pem',
2137 '/etc/ssl/certs/ca-certificates.crt', '/etc/pki/tls/cert.pem',
2138 '/usr/local/share/certs/ca-root-nss.crt', '/etc/ssl/cert.pem'.
2142 The GnuPG specific certificates stored in the directory
2143 '/etc/gnupg/trusted-certs' are only used to validate CRLs.
2147 For accessing the OpenPGP keyservers the only certificates used are
2148 those set with the configuration option 'hkp-cacert'.
2150 OpenPGP keyserver pool
2152 This is usually only one certificate read from the file
2153 '/usr/local/share/gnupg/gnupg/sks-keyservers.netCA.pem'. If this
2154 certificate exists it is used to access the special keyservers
2155 'hkps.pool.sks-keyservers.net' (or 'hkps://keys.gnupg.net').
2157 Please note that 'gpgsm' accepts Root CA certificates for its own
2158 purposes only if they are listed in its file 'trustlist.txt'. 'dirmngr'
2159 does not make use of this list - except FIXME.
2161 To be able to see diagnostics it is often useful to put at least the
2162 following lines into the configuration file '~/gnupg/dirmngr.conf':
2164 log-file ~/dirmngr.log
2167 You may want to check the log file to see whether all desired root CA
2168 certificates are correctly loaded.
2170 To be able to perform OCSP requests you probably want to add the
2175 To make sure that new options are read or that after the installation
2176 of a new GnuPG versions the right dirmngr version is running, you should
2177 kill an existing dirmngr so that a new instance is started as needed by
2178 the other components:
2180 gpgconf --kill dirmngr
2182 Direct interfaction with the dirmngr is possible by using the command
2184 gpg-connect-agent --dirmngr
2186 Enter 'HELP' at the prompt to see a list of commands and enter 'HELP'
2187 followed by a command name to get help on that command.
2190 File: gnupg.info, Node: Dirmngr Signals, Next: Dirmngr Examples, Prev: Dirmngr Configuration, Up: Invoking DIRMNGR
2195 A running 'dirmngr' may be controlled by signals, i.e. using the 'kill'
2196 command to send a signal to the process.
2198 Here is a list of supported signals:
2201 This signal flushes all internally cached CRLs as well as any
2202 cached certificates. Then the certificate cache is reinitialized
2203 as on startup. Options are re-read from the configuration file.
2204 Instead of sending this signal it is better to use
2205 gpgconf --reload dirmngr
2208 Shuts down the process but waits until all current requests are
2209 fulfilled. If the process has received 3 of these signals and
2210 requests are still pending, a shutdown is forced. You may also use
2211 gpgconf --kill dirmngr
2212 instead of this signal
2215 Shuts down the process immediately.
2218 This prints some caching statistics to the log file.
2221 File: gnupg.info, Node: Dirmngr Examples, Next: Dirmngr Protocol, Prev: Dirmngr Signals, Up: Invoking DIRMNGR
2226 Here is an example on how to show dirmngr's internal table of OpenPGP
2227 keyserver addresses. The output is intended for debugging purposes and
2228 not part of a defined API.
2230 gpg-connect-agent --dirmngr 'keyserver --hosttable' /bye
2232 To inhibit the use of a particular host you have noticed in one of
2233 the keyserver pools, you may use
2235 gpg-connect-agent --dirmngr 'keyserver --dead pgpkeys.bnd.de' /bye
2237 The description of the 'keyserver' command can be printed using
2239 gpg-connect-agent --dirmngr 'help keyserver' /bye
2242 File: gnupg.info, Node: Dirmngr Protocol, Prev: Dirmngr Examples, Up: Invoking DIRMNGR
2244 3.6 Dirmngr's Assuan Protocol
2245 =============================
2247 Assuan is the IPC protocol used to access dirmngr. This is a
2248 description of the commands implemented by dirmngr.
2252 * Dirmngr LOOKUP:: Look up a certificate via LDAP
2253 * Dirmngr ISVALID:: Validate a certificate using a CRL or OCSP.
2254 * Dirmngr CHECKCRL:: Validate a certificate using a CRL.
2255 * Dirmngr CHECKOCSP:: Validate a certificate using OCSP.
2256 * Dirmngr CACHECERT:: Put a certificate into the internal cache.
2257 * Dirmngr VALIDATE:: Validate a certificate for debugging.
2260 File: gnupg.info, Node: Dirmngr LOOKUP, Next: Dirmngr ISVALID, Up: Dirmngr Protocol
2262 3.6.1 Return the certificate(s) found
2263 -------------------------------------
2265 Lookup certificate. To allow multiple patterns (which are ORed) quoting
2266 is required: Spaces are to be translated into "+" or into "%20";
2267 obviously this requires that the usual escape quoting rules are applied.
2268 The server responds with:
2270 S: D <DER encoded certificate>
2272 S: D <second DER encoded certificate>
2276 In this example 2 certificates are returned. The server may return
2277 any number of certificates; OK will also be returned when no
2278 certificates were found. The dirmngr might return a status line
2282 To indicate that the output was truncated to N items due to a
2283 limitation of the server or by an arbitrary set limit.
2285 The option '--url' may be used if instead of a search pattern a
2286 complete URL to the certificate is known:
2288 C: LOOKUP --url CN%3DWerner%20Koch,o%3DIntevation%20GmbH,c%3DDE?userCertificate
2290 If the option '--cache-only' is given, no external lookup is done so
2291 that only certificates from the cache are returned.
2293 With the option '--single', the first and only the first match will
2294 be returned. Unless option '--cache-only' is also used, no local lookup
2295 will be done in this case.
2298 File: gnupg.info, Node: Dirmngr ISVALID, Next: Dirmngr CHECKCRL, Prev: Dirmngr LOOKUP, Up: Dirmngr Protocol
2300 3.6.2 Validate a certificate using a CRL or OCSP
2301 ------------------------------------------------
2303 ISVALID [--only-ocsp] [--force-default-responder] CERTID|CERTFPR
2305 Check whether the certificate described by the CERTID has been
2306 revoked. Due to caching, the Dirmngr is able to answer immediately in
2309 The CERTID is a hex encoded string consisting of two parts, delimited
2310 by a single dot. The first part is the SHA-1 hash of the issuer name
2311 and the second part the serial number.
2313 Alternatively the certificate's SHA-1 fingerprint CERTFPR may be
2314 given in which case an OCSP request is done before consulting the CRL.
2315 If the option '--only-ocsp' is given, no fallback to a CRL check will be
2316 used. If the option '--force-default-responder' is given, only the
2317 default OCSP responder will be used and any other methods of obtaining
2318 an OCSP responder URL won't be used.
2320 Common return values are:
2322 'GPG_ERR_NO_ERROR (0)'
2323 This is the positive answer: The certificate is not revoked and we
2324 have an up-to-date revocation list for that certificate. If OCSP
2325 was used the responder confirmed that the certificate has not been
2328 'GPG_ERR_CERT_REVOKED'
2329 This is the negative answer: The certificate has been revoked.
2330 Either it is in a CRL and that list is up to date or an OCSP
2331 responder informed us that it has been revoked.
2333 'GPG_ERR_NO_CRL_KNOWN'
2334 No CRL is known for this certificate or the CRL is not valid or out
2338 The OCSP responder returned an "unknown" status. This means that
2339 it is not aware of the certificate's status.
2341 'GPG_ERR_NOT_SUPPORTED'
2342 This is commonly seen if OCSP support has not been enabled in the
2345 If DirMngr has not enough information about the given certificate
2346 (which is the case for not yet cached certificates), it will inquire the
2349 S: INQUIRE SENDCERT <CertID>
2350 C: D <DER encoded certificate>
2353 A client should be aware that DirMngr may ask for more than one
2356 If Dirmngr has a certificate but the signature of the certificate
2357 could not been validated because the root certificate is not known to
2358 dirmngr as trusted, it may ask back to see whether the client trusts
2359 this the root certificate:
2361 S: INQUIRE ISTRUSTED <CertHexfpr>
2365 Only this answer will let Dirmngr consider the certificate as valid.
2368 File: gnupg.info, Node: Dirmngr CHECKCRL, Next: Dirmngr CHECKOCSP, Prev: Dirmngr ISVALID, Up: Dirmngr Protocol
2370 3.6.3 Validate a certificate using a CRL
2371 ----------------------------------------
2373 Check whether the certificate with FINGERPRINT (SHA-1 hash of the entire
2374 X.509 certificate blob) is valid or not by consulting the CRL
2375 responsible for this certificate. If the fingerprint has not been given
2376 or the certificate is not known, the function inquires the certificate
2379 S: INQUIRE TARGETCERT
2380 C: D <DER encoded certificate>
2383 Thus the caller is expected to return the certificate for the request
2384 (which should match FINGERPRINT) as a binary blob. Processing then
2385 takes place without further interaction; in particular dirmngr tries to
2386 locate other required certificate by its own mechanism which includes a
2387 local certificate store as well as a list of trusted root certificates.
2389 The return code is 0 for success; i.e. the certificate has not been
2390 revoked or one of the usual error codes from libgpg-error.
2393 File: gnupg.info, Node: Dirmngr CHECKOCSP, Next: Dirmngr CACHECERT, Prev: Dirmngr CHECKCRL, Up: Dirmngr Protocol
2395 3.6.4 Validate a certificate using OCSP
2396 ---------------------------------------
2398 CHECKOCSP [--force-default-responder] [FINGERPRINT]
2400 Check whether the certificate with FINGERPRINT (the SHA-1 hash of the
2401 entire X.509 certificate blob) is valid by consulting the appropriate
2402 OCSP responder. If the fingerprint has not been given or the
2403 certificate is not known by Dirmngr, the function inquires the
2406 S: INQUIRE TARGETCERT
2407 C: D <DER encoded certificate>
2410 Thus the caller is expected to return the certificate for the request
2411 (which should match FINGERPRINT) as a binary blob. Processing then
2412 takes place without further interaction; in particular dirmngr tries to
2413 locate other required certificates by its own mechanism which includes a
2414 local certificate store as well as a list of trusted root certificates.
2416 If the option '--force-default-responder' is given, only the default
2417 OCSP responder is used. This option is the per-command variant of the
2418 global option '--ignore-ocsp-service-url'.
2420 The return code is 0 for success; i.e. the certificate has not been
2421 revoked or one of the usual error codes from libgpg-error.
2424 File: gnupg.info, Node: Dirmngr CACHECERT, Next: Dirmngr VALIDATE, Prev: Dirmngr CHECKOCSP, Up: Dirmngr Protocol
2426 3.6.5 Put a certificate into the internal cache
2427 -----------------------------------------------
2429 Put a certificate into the internal cache. This command might be useful
2430 if a client knows in advance certificates required for a test and wants
2431 to make sure they get added to the internal cache. It is also helpful
2432 for debugging. To get the actual certificate, this command immediately
2435 S: INQUIRE TARGETCERT
2436 C: D <DER encoded certificate>
2439 Thus the caller is expected to return the certificate for the request
2442 The return code is 0 for success; i.e. the certificate has not been
2443 successfully cached or one of the usual error codes from libgpg-error.
2446 File: gnupg.info, Node: Dirmngr VALIDATE, Prev: Dirmngr CACHECERT, Up: Dirmngr Protocol
2448 3.6.6 Validate a certificate for debugging
2449 ------------------------------------------
2451 Validate a certificate using the certificate validation function used
2452 internally by dirmngr. This command is only useful for debugging. To
2453 get the actual certificate, this command immediately inquires it using
2455 S: INQUIRE TARGETCERT
2456 C: D <DER encoded certificate>
2459 Thus the caller is expected to return the certificate for the request
2463 File: gnupg.info, Node: Invoking GPG, Next: Invoking GPGSM, Prev: Invoking DIRMNGR, Up: Top
2468 'gpg' is the OpenPGP part of the GNU Privacy Guard (GnuPG). It is a tool
2469 to provide digital encryption and signing services using the OpenPGP
2470 standard. 'gpg' features complete key management and all the bells and
2471 whistles you would expect from a full OpenPGP implementation.
2473 There are two main versions of GnuPG: GnuPG 1.x and GnuPG 2.x. GnuPG
2474 2.x supports modern encryption algorithms and thus should be preferred
2475 over GnuPG 1.x. You only need to use GnuPG 1.x if your platform doesn't
2476 support GnuPG 2.x, or you need support for some features that GnuPG 2.x
2477 has deprecated, e.g., decrypting data created with PGP-2 keys.
2479 If you are looking for version 1 of GnuPG, you may find that version
2480 installed under the name 'gpg1'.
2482 *Note Option Index::, for an index to 'gpg''s commands and options.
2486 * GPG Commands:: List of all commands.
2487 * GPG Options:: List of all options.
2488 * GPG Configuration:: Configuration files.
2489 * GPG Examples:: Some usage examples.
2491 Developer information:
2492 * Unattended Usage of GPG:: Using 'gpg' from other programs.
2495 File: gnupg.info, Node: GPG Commands, Next: GPG Options, Up: Invoking GPG
2500 Commands are not distinguished from options except for the fact that
2501 only one command is allowed. Generally speaking, irrelevant options are
2502 silently ignored, and may not be checked for correctness.
2504 'gpg' may be run with no commands. In this case it will print a
2505 warning perform a reasonable action depending on the type of file it is
2506 given as input (an encrypted message is decrypted, a signature is
2507 verified, a file containing keys is listed, etc.).
2509 If you run into any problems, please add the option '--verbose' to
2510 the invocation to see more diagnostics.
2514 * General GPG Commands:: Commands not specific to the functionality.
2515 * Operational GPG Commands:: Commands to select the type of operation.
2516 * OpenPGP Key Management:: How to manage your keys.
2519 File: gnupg.info, Node: General GPG Commands, Next: Operational GPG Commands, Up: GPG Commands
2521 4.1.1 Commands not specific to the function
2522 -------------------------------------------
2525 Print the program version and licensing information. Note that you
2526 cannot abbreviate this command.
2530 Print a usage message summarizing the most useful command-line
2531 options. Note that you cannot arbitrarily abbreviate this command
2532 (though you can use its short form '-h').
2535 Print warranty information.
2538 Print a list of all available options and commands. Note that you
2539 cannot abbreviate this command.
2542 File: gnupg.info, Node: Operational GPG Commands, Next: OpenPGP Key Management, Prev: General GPG Commands, Up: GPG Commands
2544 4.1.2 Commands to select the type of operation
2545 ----------------------------------------------
2549 Sign a message. This command may be combined with '--encrypt' (to
2550 sign and encrypt a message), '--symmetric' (to sign and
2551 symmetrically encrypt a message), or both '--encrypt' and
2552 '--symmetric' (to sign and encrypt a message that can be decrypted
2553 using a secret key or a passphrase). The signing key is chosen by
2554 default or can be set explicitly using the '--local-user' and
2555 '--default-key' options.
2559 Make a cleartext signature. The content in a cleartext signature
2560 is readable without any special software. OpenPGP software is only
2561 needed to verify the signature. cleartext signatures may modify
2562 end-of-line whitespace for platform independence and are not
2563 intended to be reversible. The signing key is chosen by default or
2564 can be set explicitly using the '--local-user' and '--default-key'
2569 Make a detached signature.
2573 Encrypt data to one or more public keys. This command may be
2574 combined with '--sign' (to sign and encrypt a message),
2575 '--symmetric' (to encrypt a message that can be decrypted using a
2576 secret key or a passphrase), or '--sign' and '--symmetric' together
2577 (for a signed message that can be decrypted using a secret key or a
2578 passphrase). '--recipient' and related options specify which
2579 public keys to use for encryption.
2583 Encrypt with a symmetric cipher using a passphrase. The default
2584 symmetric cipher used is AES-128, but may be chosen with the
2585 '--cipher-algo' option. This command may be combined with '--sign'
2586 (for a signed and symmetrically encrypted message), '--encrypt'
2587 (for a message that may be decrypted via a secret key or a
2588 passphrase), or '--sign' and '--encrypt' together (for a signed
2589 message that may be decrypted via a secret key or a passphrase).
2590 'gpg' caches the passphrase used for symmetric encryption so that a
2591 decrypt operation may not require that the user needs to enter the
2592 passphrase. The option '--no-symkey-cache' can be used to disable
2596 Store only (make a simple literal data packet).
2600 Decrypt the file given on the command line (or STDIN if no file is
2601 specified) and write it to STDOUT (or the file specified with
2602 '--output'). If the decrypted file is signed, the signature is
2603 also verified. This command differs from the default operation, as
2604 it never writes to the filename which is included in the file and
2605 it rejects files that don't begin with an encrypted message.
2608 Assume that the first argument is a signed file and verify it
2609 without generating any output. With no arguments, the signature
2610 packet is read from STDIN. If only one argument is given, the
2611 specified file is expected to include a complete signature.
2613 With more than one argument, the first argument should specify a
2614 file with a detached signature and the remaining files should
2615 contain the signed data. To read the signed data from STDIN, use
2616 '-' as the second filename. For security reasons, a detached
2617 signature will not read the signed material from STDIN if not
2618 explicitly specified.
2620 Note: If the option '--batch' is not used, 'gpg' may assume that a
2621 single argument is a file with a detached signature, and it will
2622 try to find a matching data file by stripping certain suffixes.
2623 Using this historical feature to verify a detached signature is
2624 strongly discouraged; you should always specify the data file
2627 Note: When verifying a cleartext signature, 'gpg' verifies only
2628 what makes up the cleartext signed data and not any extra data
2629 outside of the cleartext signature or the header lines directly
2630 following the dash marker line. The option '--output' may be used
2631 to write out the actual signed data, but there are other pitfalls
2632 with this format as well. It is suggested to avoid cleartext
2633 signatures in favor of detached signatures.
2635 Note: To check whether a file was signed by a certain key the
2636 option '--assert-signer' can be used. As an alternative the 'gpgv'
2637 tool can be used. 'gpgv' is designed to compare signed data
2638 against a list of trusted keys and returns with success only for a
2639 good signature. It has its own manual page.
2642 This modifies certain other commands to accept multiple files for
2643 processing on the command line or read from STDIN with each
2644 filename on a separate line. This allows for many files to be
2645 processed at once. '--multifile' may currently be used along with
2646 '--verify', '--encrypt', and '--decrypt'. Note that '--multifile
2647 --verify' may not be used with detached signatures.
2650 Identical to '--multifile --verify'.
2653 Identical to '--multifile --encrypt'.
2656 Identical to '--multifile --decrypt'.
2660 '--list-public-keys'
2661 List the specified keys. If no keys are specified, then all keys
2662 from the configured public keyrings are listed.
2664 Never use the output of this command in scripts or other programs.
2665 The output is intended only for humans and its format is likely to
2666 change. The '--with-colons' option emits the output in a stable,
2667 machine-parseable format, which is intended for use by scripts and
2670 '--list-secret-keys'
2672 List the specified secret keys. If no keys are specified, then all
2673 known secret keys are listed. A '#' after the initial tags 'sec'
2674 or 'ssb' means that the secret key or subkey is currently not
2675 usable. We also say that this key has been taken offline (for
2676 example, a primary key can be taken offline by exporting the key
2677 using the command '--export-secret-subkeys'). A '>' after these
2678 tags indicate that the key is stored on a smartcard. See also
2681 '--check-signatures'
2683 Same as '--list-keys', but the key signatures are verified and
2684 listed too. Note that for performance reasons the revocation
2685 status of a signing key is not shown. This command has the same
2686 effect as using '--list-keys' with '--with-sig-check'.
2688 The status of the verification is indicated by a flag directly
2689 following the "sig" tag (and thus before the flags described below.
2690 A "!" indicates that the signature has been successfully verified,
2691 a "-" denotes a bad signature and a "%" is used if an error
2692 occurred while checking the signature (e.g. a non supported
2693 algorithm). Signatures where the public key is not available are
2694 not listed; to see their keyids the command '--list-sigs' can be
2697 For each signature listed, there are several flags in between the
2698 signature status flag and keyid. These flags give additional
2699 information about each key signature. From left to right, they are
2700 the numbers 1-3 for certificate check level (see
2701 '--ask-cert-level'), "L" for a local or non-exportable signature
2702 (see '--lsign-key'), "R" for a nonRevocable signature (see the
2703 '--edit-key' command "nrsign"), "P" for a signature that contains a
2704 policy URL (see '--cert-policy-url'), "N" for a signature that
2705 contains a notation (see '--cert-notation'), "X" for an eXpired
2706 signature (see '--ask-cert-expire'), and the numbers 1-9 or "T" for
2707 10 and above to indicate trust signature levels (see the
2708 '--edit-key' command "tsign").
2711 '--locate-external-keys'
2712 Locate the keys given as arguments. This command basically uses
2713 the same algorithm as used when locating keys for encryption and
2714 may thus be used to see what keys 'gpg' might use. In particular
2715 external methods as defined by '--auto-key-locate' are used to
2716 locate a key if the arguments comain valid mail addresses. Only
2717 public keys are listed.
2719 The variant '--locate-external-keys' does not consider a locally
2720 existing key and can thus be used to force the refresh of a key via
2721 the defined external methods. If a fingerprint is given and and
2722 the methods defined by -auto-key-locate define LDAP servers, the
2723 key is fetched from these resources; defined non-LDAP keyservers
2727 This commands takes OpenPGP keys as input and prints information
2728 about them in the same way the command '--list-keys' does for
2729 locally stored key. In addition the list options
2730 'show-unusable-uids', 'show-unusable-subkeys', 'show-notations' and
2731 'show-policy-urls' are also enabled. As usual for automated
2732 processing, this command should be combined with the option
2736 List all keys (or the specified ones) along with their
2737 fingerprints. This is the same output as '--list-keys' but with
2738 the additional output of a line with the fingerprint. May also be
2739 combined with '--check-signatures'. If this command is given
2740 twice, the fingerprints of all secondary keys are listed too. This
2741 command also forces pretty printing of fingerprints if the keyid
2742 format has been set to "none".
2745 List only the sequence of packets. This command is only useful for
2746 debugging. When used with option '--verbose' the actual MPI values
2747 are dumped and not only their lengths. Note that the output of
2748 this command may change with new releases.
2752 Present a menu to work with a smartcard. The subcommand "help"
2753 provides an overview on available commands. For a detailed
2754 description, please see the Card HOWTO at
2755 https://gnupg.org/documentation/howtos.html#GnuPG-cardHOWTO .
2756 Please note that the command "openpgp" can be used to switch to the
2757 OpenPGP application of cards which by default are presenting
2758 another application (e.g. PIV).
2761 Show the content of the smart card.
2764 Present a menu to allow changing the PIN of a smartcard. This
2765 functionality is also available as the subcommand "passwd" with the
2766 '--edit-card' command.
2768 '--delete-keys NAME'
2769 Remove key from the public keyring. In batch mode either '--yes'
2770 is required or the key must be specified by fingerprint. This is a
2771 safeguard against accidental deletion of multiple keys. If the
2772 exclamation mark syntax is used with the fingerprint of a subkey
2773 only that subkey is deleted; if the exclamation mark is used with
2774 the fingerprint of the primary key the entire public key is
2777 '--delete-secret-keys NAME'
2778 Remove key from the secret keyring. In batch mode the key must be
2779 specified by fingerprint. The option '--yes' can be used to advise
2780 gpg-agent not to request a confirmation. This extra pre-caution is
2781 done because 'gpg' can't be sure that the secret key (as controlled
2782 by gpg-agent) is only used for the given OpenPGP public key. If
2783 the exclamation mark syntax is used with the fingerprint of a
2784 subkey only the secret part of that subkey is deleted; if the
2785 exclamation mark is used with the fingerprint of the primary key
2786 only the secret part of the primary key is deleted.
2788 '--delete-secret-and-public-key NAME'
2789 Same as '--delete-key', but if a secret key exists, it will be
2790 removed first. In batch mode the key must be specified by
2791 fingerprint. The option '--yes' can be used to advise gpg-agent
2792 not to request a confirmation.
2795 Either export all keys from all keyrings (default keyring and those
2796 registered via option '--keyring'), or if at least one name is
2797 given, those of the given name. The exported keys are written to
2798 STDOUT or to the file given with option '--output'. Use together
2799 with '--armor' to mail those keys.
2801 '--send-keys KEYIDS'
2802 Similar to '--export' but sends the keys to a keyserver.
2803 Fingerprints may be used instead of key IDs. Don't send your
2804 complete keyring to a keyserver -- select only those keys which are
2805 new or changed by you. If no KEYIDS are given, 'gpg' does nothing.
2807 Take care: Keyservers are by design write only systems and thus it
2808 is not possible to ever delete keys once they have been send to a
2811 '--export-secret-keys'
2812 '--export-secret-subkeys'
2813 Same as '--export', but exports the secret keys instead. The
2814 exported keys are written to STDOUT or to the file given with
2815 option '--output'. This command is often used along with the
2816 option '--armor' to allow for easy printing of the key for paper
2817 backup; however the external tool 'paperkey' does a better job of
2818 creating backups on paper. Note that exporting a secret key can be
2819 a security risk if the exported keys are sent over an insecure
2822 The second form of the command has the special property to render
2823 the secret part of the primary key useless; this is a GNU extension
2824 to OpenPGP and other implementations can not be expected to
2825 successfully import such a key. Its intended use is in generating
2826 a full key with an additional signing subkey on a dedicated
2827 machine. This command then exports the key without the primary key
2828 to the main machine.
2830 GnuPG may ask you to enter the passphrase for the key. This is
2831 required, because the internal protection method of the secret key
2832 is different from the one specified by the OpenPGP protocol.
2835 This command is used to export a key in the OpenSSH public key
2836 format. It requires the specification of one key by the usual
2837 means and exports the latest valid subkey which has an
2838 authentication capability to STDOUT or to the file given with
2839 option '--output'. That output can directly be added to ssh's
2840 'authorized_key' file.
2842 By specifying the key to export using a key ID or a fingerprint
2843 suffixed with an exclamation mark (!), a specific subkey or the
2844 primary key can be exported. This does not even require that the
2845 key has the authentication capability flag set.
2849 Import/merge keys. This adds the given keys to the keyring. The
2850 fast version is currently just a synonym.
2852 There are a few other options which control how this command works.
2853 Most notable here is the '--import-options merge-only' option which
2854 does not insert new keys but does only the merging of new
2855 signatures, user-IDs and subkeys.
2857 '--receive-keys KEYIDS'
2858 '--recv-keys KEYIDS'
2859 Import the keys with the given KEYIDS from a keyserver.
2862 Request updates from a keyserver for keys that already exist on the
2863 local keyring. This is useful for updating a key with the latest
2864 signatures, user IDs, etc. Calling this with no arguments will
2865 refresh the entire keyring.
2867 '--search-keys NAMES'
2868 Search the keyserver for the given NAMES. Multiple names given
2869 here will be joined together to create the search string for the
2870 keyserver. Note that keyservers search for NAMES in a different
2871 and simpler way than gpg does. The best choice is to use a mail
2872 address. Due to data privacy reasons keyservers may even not even
2873 allow searching by user id or mail address and thus may only return
2874 results when being used with the '--recv-key' command to search by
2875 key fingerprint or keyid.
2878 Retrieve keys located at the specified URIS. Note that different
2879 installations of GnuPG may support different protocols (HTTP, FTP,
2880 LDAP, etc.). When using HTTPS the system provided root
2881 certificates are used by this command.
2884 Do trust database maintenance. This command iterates over all keys
2885 and builds the Web of Trust. This is an interactive command
2886 because it may have to ask for the "ownertrust" values for keys.
2887 The user has to give an estimation of how far she trusts the owner
2888 of the displayed key to correctly certify (sign) other keys. GnuPG
2889 only asks for the ownertrust value if it has not yet been assigned
2890 to a key. Using the '--edit-key' menu, the assigned value can be
2891 changed at any time.
2894 Do trust database maintenance without user interaction. From time
2895 to time the trust database must be updated so that expired keys or
2896 signatures and the resulting changes in the Web of Trust can be
2897 tracked. Normally, GnuPG will calculate when this is required and
2898 do it automatically unless '--no-auto-check-trustdb' is set. This
2899 command can be used to force a trust database check at any time.
2900 The processing is identical to that of '--update-trustdb' but it
2901 skips keys with a not yet defined "ownertrust".
2903 For use with cron jobs, this command can be used together with
2904 '--batch' in which case the trust database check is done only if a
2905 check is needed. To force a run even in batch mode add the option
2908 '--export-ownertrust'
2909 Send the ownertrust values to STDOUT. This is useful for backup
2910 purposes as these values are the only ones which can't be
2911 re-created from a corrupted trustdb. Example:
2912 gpg --export-ownertrust > otrust.txt
2914 '--import-ownertrust'
2915 Update the trustdb with the ownertrust values stored in 'files' (or
2916 STDIN if not given); existing values will be overwritten. In case
2917 of a severely damaged trustdb and if you have a recent backup of
2918 the ownertrust values (e.g. in the file 'otrust.txt'), you may
2919 re-create the trustdb using these commands:
2922 gpg --import-ownertrust < otrust.txt
2924 '--rebuild-keydb-caches'
2925 When updating from version 1.0.6 to 1.0.7 this command should be
2926 used to create signature caches in the keyring. It might be handy
2927 in other situations too.
2931 Print message digest of algorithm ALGO for all given files or
2932 STDIN. With the second form (or a deprecated "*" for ALGO) digests
2933 for all available algorithms are printed.
2935 '--gen-random 0|1|2|16|30 COUNT'
2936 Emit COUNT random bytes of the given quality level 0, 1 or 2. If
2937 COUNT is not given or zero, an endless sequence of random bytes
2938 will be emitted. If used with '--armor' the output will be base64
2939 encoded. The special level 16 uses a quality level of 1 and
2940 outputs an endless stream of hex-encoded octets. The special level
2941 30 outputs random as 30 zBase-32 characters.
2943 '--gen-prime MODE BITS'
2944 Use the source, Luke :-). The output format is subject to change
2949 Pack or unpack an arbitrary input into/from an OpenPGP ASCII armor.
2950 This is a GnuPG extension to OpenPGP and in general not very
2951 useful. The '--dearmor' command can also be used to dearmor PEM
2955 This command is similar to '--decrypt' with the difference that the
2956 output is not the usual plaintext but the original message with the
2957 encryption layer removed. Thus the output will be an OpenPGP data
2958 structure which often means a signed OpenPGP message. Note that
2959 this option may or may not remove a compression layer which is
2960 often found beneath the encryption layer.
2962 '--tofu-policy {auto|good|unknown|bad|ask} KEYS'
2963 Set the TOFU policy for all the bindings associated with the
2964 specified KEYS. For more information about the meaning of the
2965 policies, *note trust-model-tofu::. The KEYS may be specified
2966 either by their fingerprint (preferred) or their keyid.
2969 File: gnupg.info, Node: OpenPGP Key Management, Prev: Operational GPG Commands, Up: GPG Commands
2971 4.1.3 How to manage your keys
2972 -----------------------------
2974 This section explains the main commands for key management.
2976 '--quick-generate-key USER-ID [ALGO [USAGE [EXPIRE]]]'
2978 This is a simple command to generate a standard key with one user
2979 id. In contrast to '--generate-key' the key is generated directly
2980 without the need to answer a bunch of prompts. Unless the option
2981 '--yes' is given, the key creation will be canceled if the given
2982 user id already exists in the keyring.
2984 If invoked directly on the console without any special options an
2985 answer to a "Continue?" style confirmation prompt is required. In
2986 case the user id already exists in the keyring a second prompt to
2987 force the creation of the key will show up.
2989 If ALGO or USAGE are given, only the primary key is created and no
2990 prompts are shown. To specify an expiration date but still create
2991 a primary and subkey use "default" or "future-default" for ALGO and
2992 "default" for USAGE. For a description of these optional arguments
2993 see the command '--quick-add-key'. The USAGE accepts also the
2994 value "cert" which can be used to create a certification only
2995 primary key; the default is to a create certification and signing
2998 The EXPIRE argument can be used to specify an expiration date for
2999 the key. Several formats are supported; commonly the ISO formats
3000 "YYYY-MM-DD" or "YYYYMMDDThhmmss" are used. To make the key expire
3001 in N seconds, N days, N weeks, N months, or N years use
3002 "seconds=N", "Nd", "Nw", "Nm", or "Ny" respectively. Not
3003 specifying a value, or using "-" results in a key expiring in a
3004 reasonable default interval. The values "never", "none" can be
3005 used for no expiration date.
3007 If this command is used with '--batch', '--pinentry-mode' has been
3008 set to 'loopback', and one of the passphrase options
3009 ('--passphrase', '--passphrase-fd', or '--passphrase-file') is
3010 used, the supplied passphrase is used for the new key and the agent
3011 does not ask for it. To create a key without any protection
3012 '--passphrase ''' may be used.
3014 To create an OpenPGP key from the keys available on the currently
3015 inserted smartcard, the special string "card" can be used for ALGO.
3016 If the card features an encryption and a signing key, gpg will
3017 figure them out and creates an OpenPGP key consisting of the usual
3018 primary key and one subkey. This works only with certain
3019 smartcards. Note that the interactive '--full-gen-key' command
3020 allows to do the same but with greater flexibility in the selection
3021 of the smartcard keys.
3023 Note that it is possible to create a primary key and a subkey using
3024 non-default algorithms by using "default" and changing the default
3025 parameters using the option '--default-new-key-algo'.
3027 '--quick-set-expire FPR EXPIRE [*|SUBFPRS]'
3028 With two arguments given, directly set the expiration time of the
3029 primary key identified by FPR to EXPIRE. To remove the expiration
3030 time '0' can be used. With three arguments and the third given as
3031 an asterisk, the expiration time of all non-revoked and not yet
3032 expired subkeys are set to EXPIRE. With more than two arguments
3033 and a list of fingerprints given for SUBFPRS, all non-revoked
3034 subkeys matching these fingerprints are set to EXPIRE.
3036 '--quick-add-key FPR [ALGO [USAGE [EXPIRE]]]'
3037 Directly add a subkey to the key identified by the fingerprint FPR.
3038 Without the optional arguments an encryption subkey is added. If
3039 any of the arguments are given a more specific subkey is added.
3041 ALGO may be any of the supported algorithms or curve names given in
3042 the format as used by key listings. To use the default algorithm
3043 the string "default" or "-" can be used. Supported algorithms are
3044 "rsa", "dsa", "elg", "ed25519", "cv25519", and other ECC curves.
3045 For example the string "rsa" adds an RSA key with the default key
3046 length; a string "rsa4096" requests that the key length is 4096
3047 bits. The string "future-default" is an alias for the algorithm
3048 which will likely be used as default algorithm in future versions
3049 of gpg. To list the supported ECC curves the command 'gpg
3050 --with-colons --list-config curve' can be used.
3052 Depending on the given ALGO the subkey may either be an encryption
3053 subkey or a signing subkey. If an algorithm is capable of signing
3054 and encryption and such a subkey is desired, a USAGE string must be
3055 given. This string is either "default" or "-" to keep the default
3056 or a comma delimited list (or space delimited list) of keywords:
3057 "sign" for a signing subkey, "auth" for an authentication subkey,
3058 and "encr" for an encryption subkey ("encrypt" can be used as alias
3059 for "encr"). The valid combinations depend on the algorithm.
3061 The EXPIRE argument can be used to specify an expiration date for
3062 the key. Several formats are supported; commonly the ISO formats
3063 "YYYY-MM-DD" or "YYYYMMDDThhmmss" are used. To make the key expire
3064 in N seconds, N days, N weeks, N months, or N years use
3065 "seconds=N", "Nd", "Nw", "Nm", or "Ny" respectively. Not
3066 specifying a value, or using "-" results in a key expiring in a
3067 reasonable default interval. The values "never", "none" can be
3068 used for no expiration date.
3070 '--quick-add-adsk FPR ADSKFPR'
3071 Directly add an Additional Decryption Subkey to the key identified
3072 by the fingerprint FPR. ADSKFPR is the fingerprint of another
3073 key's encryption subkey. A subkey is commonly used here because by
3074 default a primary key has no encryption capability. Use the option
3075 '--with-subkey-fingerprint' with a list command to display the
3076 subkey fingerprints.
3080 Generate a new key pair using the current default parameters. This
3081 is the standard command to create a new key. In addition to the
3082 key a revocation certificate is created and stored in the
3083 'openpgp-revocs.d' directory below the GnuPG home directory.
3085 '--full-generate-key'
3087 Generate a new key pair with dialogs for all options. This is an
3088 extended version of '--generate-key'.
3090 There is also a feature which allows you to create keys in batch
3091 mode. See the manual section "Unattended key generation" on how to
3094 '--generate-revocation NAME'
3096 Generate a revocation certificate for the complete key. To only
3097 revoke a subkey or a key signature, use the '--edit' command.
3099 This command merely creates the revocation certificate so that it
3100 can be used to revoke the key if that is ever needed. To actually
3101 revoke a key the created revocation certificate needs to be merged
3102 with the key to revoke. This is done by importing the revocation
3103 certificate using the '--import' command. Then the revoked key
3104 needs to be published, which is best done by sending the key to a
3105 keyserver (command '--send-key') and by exporting ('--export') it
3106 to a file which is then send to frequent communication partners.
3108 '--generate-designated-revocation NAME'
3109 '--desig-revoke NAME'
3110 Generate a designated revocation certificate for a key. This
3111 allows a user (with the permission of the keyholder) to revoke
3115 Present a menu which enables you to do most of the key management
3116 related tasks. It expects the specification of a key on the
3120 Toggle selection of user ID or photographic user ID with index
3121 N. Use '*' to select all and '0' to deselect all.
3124 Toggle selection of subkey with index N or key ID N. Use '*'
3125 to select all and '0' to deselect all.
3128 Make a signature on key of user 'name'. If the key is not yet
3129 signed by the default user (or the users given with '-u'), the
3130 program displays the information of the key again, together
3131 with its fingerprint and asks whether it should be signed.
3132 This question is repeated for all users specified with '-u'.
3135 Same as "sign" but the signature is marked as non-exportable
3136 and will therefore never be used by others. This may be used
3137 to make keys valid only in the local environment.
3140 Same as "sign" but the signature is marked as non-revocable
3141 and can therefore never be revoked.
3144 Make a trust signature. This is a signature that combines the
3145 notions of certification (like a regular signature), and trust
3146 (like the "trust" command). It is generally useful in
3147 distinct communities or groups to implement the concept of a
3148 Trusted Introducer. For more information please read the
3149 sections "Trust Signature" and "Regular Expression" in
3152 Note that "l" (for local / non-exportable), "nr" (for
3153 non-revocable, and "t" (for trust) may be freely mixed and prefixed
3154 to "sign" to create a signature of any type desired.
3156 If the option '--only-sign-text-ids' is specified, then any
3157 non-text based user ids (e.g., photo IDs) will not be selected for
3161 Delete a signature. Note that it is not possible to retract a
3162 signature, once it has been send to the public (i.e. to a
3163 keyserver). In that case you better use 'revsig'.
3166 Revoke a signature. For every signature which has been
3167 generated by one of the secret keys, GnuPG asks whether a
3168 revocation certificate should be generated.
3171 Check the signatures on all selected user IDs. With the extra
3172 option 'selfsig' only self-signatures are shown.
3175 Create an additional user ID.
3178 Create a photographic user ID. This will prompt for a JPEG
3179 file that will be embedded into the user ID. Note that a very
3180 large JPEG will make for a very large key. Also note that
3181 some programs will display your JPEG unchanged (GnuPG), and
3182 some programs will scale it to fit in a dialog box (PGP).
3185 Display the selected photographic user ID.
3188 Delete a user ID or photographic user ID. Note that it is not
3189 possible to retract a user id, once it has been send to the
3190 public (i.e. to a keyserver). In that case you better use
3194 Revoke a user ID or photographic user ID.
3197 Flag the current user id as the primary one, removes the
3198 primary user id flag from all other user ids and sets the
3199 timestamp of all affected self-signatures one second ahead.
3200 Note that setting a photo user ID as primary makes it primary
3201 over other photo user IDs, and setting a regular user ID as
3202 primary makes it primary over other regular user IDs.
3205 Set a preferred keyserver for the specified user ID(s). This
3206 allows other users to know where you prefer they get your key
3207 from. See '--keyserver-options honor-keyserver-url' for more
3208 on how this works. Setting a value of "none" removes an
3209 existing preferred keyserver.
3212 Set a name=value notation for the specified user ID(s). See
3213 '--cert-notation' for more on how this works. Setting a value
3214 of "none" removes all notations, setting a notation prefixed
3215 with a minus sign (-) removes that notation, and setting a
3216 notation name (without the =value) prefixed with a minus sign
3217 removes all notations with that name.
3220 List preferences from the selected user ID. This shows the
3221 actual preferences, without including any implied preferences.
3224 More verbose preferences listing for the selected user ID.
3225 This shows the preferences in effect by including the implied
3226 preferences of 3DES (cipher), SHA-1 (digest), and Uncompressed
3227 (compression) if they are not already included in the
3228 preference list. In addition, the preferred keyserver and
3229 signature notations (if any) are shown.
3232 Set the list of user ID preferences to STRING for all (or just
3233 the selected) user IDs. Calling setpref with no arguments
3234 sets the preference list to the default (either built-in or
3235 set via '--default-preference-list'), and calling setpref with
3236 "none" as the argument sets an empty preference list. Use
3237 'gpg --version' to get a list of available algorithms. Note
3238 that while you can change the preferences on an attribute user
3239 ID (aka "photo ID"), GnuPG does not select keys via attribute
3240 user IDs so these preferences will not be used by GnuPG. Note
3241 that an unattended version of this command is available as
3242 '--quick-update-pref'.
3244 When setting preferences, you should list the algorithms in
3245 the order which you'd like to see them used by someone else
3246 when encrypting a message to your key. If you don't include
3247 3DES, it will be automatically added at the end. Note that
3248 there are many factors that go into choosing an algorithm (for
3249 example, your key may not be the only recipient), and so the
3250 remote OpenPGP application being used to send to you may or
3251 may not follow your exact chosen order for a given message.
3252 It will, however, only choose an algorithm that is present on
3253 the preference list of every recipient key. See also the
3254 INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS section below.
3257 Add a subkey to this key.
3260 Generate a subkey on a card and add it to this key.
3263 Transfer the selected secret subkey (or the primary key if no
3264 subkey has been selected) to a smartcard. The secret key in
3265 the keyring will be replaced by a stub if the key could be
3266 stored successfully on the card and you use the save command
3267 later. Only certain key types may be transferred to the card.
3268 A sub menu allows you to select on what card to store the key.
3269 Note that it is not possible to get that key back from the
3270 card - if the card gets broken your secret key will be lost
3271 unless you have a backup somewhere.
3274 Restore the given FILE to a card. This command may be used to
3275 restore a backup key (as generated during card initialization)
3276 to a new card. In almost all cases this will be the
3277 encryption key. You should use this command only with the
3278 corresponding public key and make sure that the file given as
3279 argument is indeed the backup to restore. You should then
3280 select 2 to restore as encryption key. You will first be
3281 asked to enter the passphrase of the backup key and then for
3282 the Admin PIN of the card.
3285 Transfer the selected secret subkey (or the primary key if no
3286 subkey has been selected) to TPM form. The secret key in the
3287 keyring will be replaced by the TPM representation of that
3288 key, which can only be read by the particular TPM that created
3289 it (so the keyfile now becomes locked to the laptop containing
3290 the TPM). Only certain key types may be transferred to the TPM
3291 (all TPM 2.0 systems are mandated to have the rsa2048 and
3292 nistp256 algorithms but newer TPMs may have more). Note that
3293 the key itself is not transferred into the TPM, merely
3294 encrypted by the TPM in-place, so if the keyfile is deleted,
3295 the key will be lost. Once transferred to TPM representation,
3296 the key file can never be converted back to non-TPM form and
3297 the key will die when the TPM does, so you should first have a
3298 backup on secure offline storage of the actual secret key file
3299 before conversion. It is essential to use the physical system
3300 TPM that you have rw permission on the TPM resource manager
3301 device (/dev/tpmrm0). Usually this means you must be a member
3305 Remove a subkey (secondary key). Note that it is not possible
3306 to retract a subkey, once it has been send to the public (i.e.
3307 to a keyserver). In that case you better use 'revkey'. Also
3308 note that this only deletes the public part of a key.
3314 Change the key or subkey expiration time. If a subkey is
3315 selected, the expiration time of this subkey will be changed.
3316 With no selection, the key expiration of the primary key is
3320 Change the owner trust value for the key. This updates the
3321 trust-db immediately and no save is required.
3325 Disable or enable an entire key. A disabled key can not
3326 normally be used for encryption.
3329 Add a designated revoker to the key. This takes one optional
3330 argument: "sensitive". If a designated revoker is marked as
3331 sensitive, it will not be exported by default (see
3335 Add an Additional Decryption Subkey. The user is asked to
3336 enter the fingerprint of another encryption subkey. Note that
3337 the exact fingerprint of another key's encryption subkey needs
3338 to be entered. This is because commonly the primary key has
3339 no encryption capability. Use the option
3340 '--with-subkey-fingerprint' with a list command to display the
3341 subkey fingerprints.
3344 Change the passphrase of the secret key.
3347 This is dummy command which exists only for backward
3351 Compact (by removing all signatures except the selfsig) any
3352 user ID that is no longer usable (e.g. revoked, or expired).
3353 Then, remove any signatures that are not usable by the trust
3354 calculations. Specifically, this removes any signature that
3355 does not validate, any signature that is superseded by a later
3356 signature, revoked signatures, and signatures issued by keys
3357 that are not present on the keyring.
3360 Make the key as small as possible. This removes all
3361 signatures from each user ID except for the most recent
3365 Change the usage flags (capabilities) of the primary key or of
3366 subkeys. These usage flags (e.g. Certify, Sign,
3367 Authenticate, Encrypt) are set during key creation. Sometimes
3368 it is useful to have the opportunity to change them (for
3369 example to add Authenticate) after they have been created.
3370 Please take care when doing this; the allowed usage flags
3371 depend on the key algorithm.
3374 Add cross-certification signatures to signing subkeys that may
3375 not currently have them. Cross-certification signatures
3376 protect against a subtle attack against signing subkeys. See
3377 '--require-cross-certification'. All new keys generated have
3378 this signature by default, so this command is only useful to
3379 bring older keys up to date.
3382 Save all changes to the keyring and quit.
3385 Quit the program without updating the keyring.
3387 The listing shows you the key with its secondary keys and all user
3388 IDs. The primary user ID is indicated by a dot, and selected keys
3389 or user IDs are indicated by an asterisk. The trust value is
3390 displayed with the primary key: "trust" is the assigned owner trust
3391 and "validity" is the calculated validity of the key. Validity
3392 values are also displayed for all user IDs. For possible values of
3393 trust, *note trust-values::.
3396 Signs a public key with your secret key. This is a shortcut
3397 version of the subcommand "sign" from '--edit-key'.
3400 Signs a public key with your secret key but marks it as
3401 non-exportable. This is a shortcut version of the subcommand
3402 "lsign" from '--edit-key'.
3404 '--quick-sign-key FPR [NAMES]'
3405 '--quick-lsign-key FPR [NAMES]'
3406 Directly sign a key from the passphrase without any further user
3407 interaction. The FPR must be the verified primary fingerprint of a
3408 key in the local keyring. If no NAMES are given, all useful user
3409 ids are signed; with given [NAMES] only useful user ids matching
3410 one of these names are signed. By default, or if a name is
3411 prefixed with a '*', a case insensitive substring match is used.
3412 If a name is prefixed with a '=' a case sensitive exact match is
3415 The command '--quick-lsign-key' marks the signatures as
3416 non-exportable. If such a non-exportable signature already exists
3417 the '--quick-sign-key' turns it into a exportable signature. If
3418 you need to update an existing signature, for example to add or
3419 change notation data, you need to use the option
3422 This command uses reasonable defaults and thus does not provide the
3423 full flexibility of the "sign" subcommand from '--edit-key'. Its
3424 intended use is to help unattended key signing by utilizing a list
3425 of verified fingerprints.
3427 '--quick-add-uid USER-ID NEW-USER-ID'
3428 This command adds a new user id to an existing key. In contrast to
3429 the interactive sub-command 'adduid' of '--edit-key' the
3430 NEW-USER-ID is added verbatim with only leading and trailing white
3431 space removed, it is expected to be UTF-8 encoded, and no checks on
3432 its form are applied.
3434 '--quick-revoke-uid USER-ID USER-ID-TO-REVOKE'
3435 This command revokes a user ID on an existing key. It cannot be
3436 used to revoke the last user ID on key (some non-revoked user ID
3437 must remain), with revocation reason "User ID is no longer valid".
3438 If you want to specify a different revocation reason, or to supply
3439 supplementary revocation text, you should use the interactive
3440 sub-command 'revuid' of '--edit-key'.
3442 '--quick-revoke-sig FPR SIGNING-FPR [NAMES]'
3443 This command revokes the key signatures made by SIGNING-FPR from
3444 the key specified by the fingerprint FPR. With NAMES given only
3445 the signatures on user ids of the key matching any of the given
3446 names are affected (see '--quick-sign-key'). If a revocation
3447 already exists a notice is printed instead of creating a new
3448 revocation; no error is returned in this case. Note that key
3449 signature revocations may be superseded by a newer key signature
3450 and in turn again revoked.
3452 '--quick-set-primary-uid USER-ID PRIMARY-USER-ID'
3453 This command sets or updates the primary user ID flag on an
3454 existing key. USER-ID specifies the key and PRIMARY-USER-ID the
3455 user ID which shall be flagged as the primary user ID. The primary
3456 user ID flag is removed from all other user ids and the timestamp
3457 of all affected self-signatures is set one second ahead.
3459 '--quick-update-pref USER-ID'
3460 This command updates the preference list of the key to the current
3461 default value (either built-in or set via
3462 '--default-preference-list'). This is the unattended version of of
3463 using "setpref" in the '--key-edit' menu without giving a list.
3464 Note that you can show the preferences in a key listing by using
3465 '--list-options show-pref' or '--list-options show-pref-verbose'.
3466 You should also re-distribute updated keys to your peers.
3468 '--change-passphrase USER-ID'
3470 Change the passphrase of the secret key belonging to the
3471 certificate specified as USER-ID. This is a shortcut for the
3472 sub-command 'passwd' of the '--edit-key' menu. When using together
3473 with the option '--dry-run' this will not actually change the
3474 passphrase but check that the current passphrase is correct.
3477 File: gnupg.info, Node: GPG Options, Next: GPG Configuration, Prev: GPG Commands, Up: Invoking GPG
3482 'gpg' features a bunch of options to control the exact behaviour and to
3483 change the default configuration.
3487 * GPG Configuration Options:: How to change the configuration.
3488 * GPG Key related Options:: Key related options.
3489 * GPG Input and Output:: Input and Output.
3490 * OpenPGP Options:: OpenPGP protocol specific options.
3491 * Compliance Options:: Compliance options.
3492 * GPG Esoteric Options:: Doing things one usually doesn't want to do.
3493 * Deprecated Options:: Deprecated options.
3495 Long options can be put in an options file (default
3496 "~/.gnupg/gpg.conf"). Short option names will not work - for example,
3497 "armor" is a valid option for the options file, while "a" is not. Do
3498 not write the 2 dashes, but simply the name of the option and any
3499 required arguments. Lines with a hash ('#') as the first
3500 non-white-space character are ignored. Commands may be put in this file
3501 too, but that is not generally useful as the command will execute
3502 automatically with every execution of gpg.
3504 Please remember that option parsing stops as soon as a non-option is
3505 encountered, you can explicitly stop parsing by using the special option
3509 File: gnupg.info, Node: GPG Configuration Options, Next: GPG Key related Options, Up: GPG Options
3511 4.2.1 How to change the configuration
3512 -------------------------------------
3514 These options are used to change the configuration and most of them are
3515 usually found in the option file.
3517 '--default-key NAME'
3518 Use NAME as the default key to sign with. If this option is not
3519 used, the default key is the first key found in the secret keyring.
3520 Note that '-u' or '--local-user' overrides this option. This
3521 option may be given multiple times. In this case, the last key for
3522 which a secret key is available is used. If there is no secret key
3523 available for any of the specified values, GnuPG will not emit an
3524 error message but continue as if this option wasn't given.
3526 '--default-recipient NAME'
3527 Use NAME as default recipient if option '--recipient' is not used
3528 and don't ask if this is a valid one. NAME must be non-empty.
3530 '--default-recipient-self'
3531 Use the default key as default recipient if option '--recipient' is
3532 not used and don't ask if this is a valid one. The default key is
3533 the first one from the secret keyring or the one set with
3536 '--no-default-recipient'
3537 Reset '--default-recipient' and '--default-recipient-self'. Should
3538 not be used in an option file.
3541 Give more information during processing. If used twice, the input
3542 data is listed in detail.
3545 Reset verbose level to 0. Should not be used in an option file.
3548 Try to be as quiet as possible. Should not be used in an option
3553 Use batch mode. Never ask, do not allow interactive commands.
3554 '--no-batch' disables this option. Note that even with a filename
3555 given on the command line, gpg might still need to read from STDIN
3556 (in particular if gpg figures that the input is a detached
3557 signature and no data file has been specified). Thus if you do not
3558 want to feed data via STDIN, you should connect STDIN to
3561 It is highly recommended to use this option along with the options
3562 '--status-fd' and '--with-colons' for any unattended use of 'gpg'.
3563 Should not be used in an option file.
3566 Make sure that the TTY (terminal) is never used for any output.
3567 This option is needed in some cases because GnuPG sometimes prints
3568 warnings to the TTY even if '--batch' is used.
3571 Assume "yes" on most questions. Should not be used in an option
3575 Assume "no" on most questions. Should not be used in an option
3578 '--list-filter {select=EXPR}'
3579 A list filter can be used to output only certain keys during key
3580 listing commands. For the available property names, see the
3581 description of '--import-filter'.
3583 '--list-options PARAMETERS'
3584 This is a space or comma delimited string that gives options used
3585 when listing keys and signatures (that is, '--list-keys',
3586 '--check-signatures', '--list-public-keys', '--list-secret-keys',
3587 and the '--edit-key' functions). Options can be prepended with a
3588 'no-' (after the two dashes) to give the opposite meaning. The
3592 Causes '--list-keys', '--check-signatures',
3593 '--list-public-keys', and '--list-secret-keys' to display any
3594 photo IDs attached to the key. Defaults to no. See also
3595 '--photo-viewer'. Does not work with '--with-colons': see
3596 '--attribute-fd' for the appropriate way to get photo data for
3597 scripts and other frontends.
3600 Show usage information for keys and subkeys in the standard
3601 key listing. This is a list of letters indicating the allowed
3602 usage for a key ('E'=encryption, 'S'=signing,
3603 'C'=certification, 'A'=authentication). Defaults to yes.
3606 Show policy URLs in the '--check-signatures' listings.
3612 Show all, IETF standard, or user-defined signature notations
3613 in the '--check-signatures' listings. Defaults to no.
3616 Show any preferred keyserver URL in the '--check-signatures'
3617 listings. Defaults to no.
3620 Display the calculated validity of user IDs during key
3621 listings. Defaults to yes.
3624 Show revoked and expired user IDs in key listings. Defaults
3627 show-unusable-subkeys
3628 Show revoked and expired subkeys in key listings. Defaults to
3632 Show key signature made using weak or unsupported algorithms.
3635 Display the keyring name at the head of key listings to show
3636 which keyring a given key resides on. Defaults to no.
3639 Show signature expiration dates (if any) during
3640 '--check-signatures' listings. Defaults to no.
3643 Include signature subpackets in the key listing. This option
3644 can take an optional argument list of the subpackets to list.
3645 If no argument is passed, list all subpackets. Defaults to
3646 no. This option is only meaningful when using '--with-colons'
3647 along with '--check-signatures'.
3650 For each user-id which has a valid mail address print only the
3651 fingerprint followed by the mail address.
3654 With -list-sigs and -check-sigs sort the signatures by keyID
3655 and creation time to make it easier to view the history of
3656 these signatures. The self-signature is also listed before
3657 other signatures. Defaults to yes.
3659 '--verify-options PARAMETERS'
3660 This is a space or comma delimited string that gives options used
3661 when verifying signatures. Options can be prepended with a 'no-'
3662 to give the opposite meaning. The options are:
3665 Display any photo IDs present on the key that issued the
3666 signature. Defaults to no. See also '--photo-viewer'.
3669 Show policy URLs in the signature being verified. Defaults to
3675 Show all, IETF standard, or user-defined signature notations
3676 in the signature being verified. Defaults to IETF standard.
3679 Show any preferred keyserver URL in the signature being
3680 verified. Defaults to yes.
3683 Display the calculated validity of the user IDs on the key
3684 that issued the signature. Defaults to yes.
3687 Show revoked and expired user IDs during signature
3688 verification. Defaults to no.
3690 show-primary-uid-only
3691 Show only the primary user ID during signature verification.
3692 That is all the AKA lines as well as photo Ids are not shown
3693 with the signature verification status.
3695 '--enable-large-rsa'
3696 '--disable-large-rsa'
3697 With -generate-key and -batch, enable the creation of RSA secret
3698 keys as large as 8192 bit. Note: 8192 bit is more than is
3699 generally recommended. These large keys don't significantly
3700 improve security, but they are more expensive to use, and their
3701 signatures and certifications are larger. This option is only
3702 available if the binary was build with large-secmem support.
3706 Enable hash truncation for all DSA keys even for old DSA Keys up to
3707 1024 bit. This is also the default with '--openpgp'. Note that
3708 older versions of GnuPG also required this flag to allow the
3709 generation of DSA larger than 1024 bit.
3711 '--photo-viewer STRING'
3712 This is the command line that should be run to view a photo ID.
3713 "%i" will be expanded to a filename containing the photo. "%I"
3714 does the same, except the file will not be deleted once the viewer
3715 exits. Other flags are "%k" for the key ID, "%K" for the long key
3716 ID, "%f" for the key fingerprint, "%t" for the extension of the
3717 image type (e.g. "jpg"), "%T" for the MIME type of the image (e.g.
3718 "image/jpeg"), "%v" for the single-character calculated validity of
3719 the image being viewed (e.g. "f"), "%V" for the calculated
3720 validity as a string (e.g. "full"), "%U" for a base32 encoded hash
3721 of the user ID, and "%%" for an actual percent sign. If neither %i
3722 or %I are present, then the photo will be supplied to the viewer on
3725 On Unix the default viewer is 'xloadimage -fork -quiet -title
3726 'KeyID 0x%k' STDIN' with a fallback to 'display -title 'KeyID 0x%k'
3727 %i' and finally to 'xdg-open %i'. On Windows '!ShellExecute 400
3728 %i' is used; here the command is a meta command to use that API
3729 call followed by a wait time in milliseconds which is used to give
3730 the viewer time to read the temporary image file before gpg deletes
3731 it again. Note that if your image viewer program is not secure,
3732 then executing it from gpg does not make it secure.
3734 '--exec-path STRING'
3735 Sets a list of directories to search for photo viewers If not
3736 provided photo viewers use the 'PATH' environment variable.
3739 Add FILE to the current list of keyrings. If FILE begins with a
3740 tilde and a slash, these are replaced by the $HOME directory. If
3741 the filename does not contain a slash, it is assumed to be in the
3742 GnuPG home directory ("~/.gnupg" unless '--homedir' or $GNUPGHOME
3745 Note that this adds a keyring to the current list. If the intent
3746 is to use the specified keyring alone, use '--keyring' along with
3747 '--no-default-keyring'.
3749 If the option '--no-keyring' has been used no keyrings will be used
3752 Note that if the option 'use-keyboxd' is enabled in 'common.conf',
3753 no keyrings are used at all and keys are all maintained by the
3754 keyboxd process in its own database.
3756 '--primary-keyring FILE'
3757 This is a varian of '--keyring' and designates FILE as the primary
3758 public keyring. This means that newly imported keys (via
3759 '--import' or keyserver '--recv-from') will go to this keyring.
3761 '--secret-keyring FILE'
3762 This is an obsolete option and ignored. All secret keys are stored
3763 in the 'private-keys-v1.d' directory below the GnuPG home
3766 '--trustdb-name FILE'
3767 Use FILE instead of the default trustdb. If FILE begins with a
3768 tilde and a slash, these are replaced by the $HOME directory. If
3769 the filename does not contain a slash, it is assumed to be in the
3770 GnuPG home directory ('~/.gnupg' if '--homedir' or $GNUPGHOME is
3774 Set the name of the home directory to DIR. If this option is not
3775 used, the home directory defaults to '~/.gnupg'. It is only
3776 recognized when given on the command line. It also overrides any
3777 home directory stated through the environment variable 'GNUPGHOME'
3778 or (on Windows systems) by means of the Registry entry
3779 HKCU\SOFTWARE\GNU\GNUPG:HOMEDIR.
3781 On Windows systems it is possible to install GnuPG as a portable
3782 application. In this case only this command line option is
3783 considered, all other ways to set a home directory are ignored.
3785 To install GnuPG as a portable application under Windows, create an
3786 empty file named 'gpgconf.ctl' in the same directory as the tool
3787 'gpgconf.exe'. The root of the installation is then that
3788 directory; or, if 'gpgconf.exe' has been installed directly below a
3789 directory named 'bin', its parent directory. You also need to make
3790 sure that the following directories exist and are writable:
3791 'ROOT/home' for the GnuPG home and 'ROOT/usr/local/var/cache/gnupg'
3792 for internal cache files.
3794 '--display-charset NAME'
3795 Set the name of the native character set. This is used to convert
3796 some informational strings like user IDs to the proper UTF-8
3797 encoding. Note that this has nothing to do with the character set
3798 of data to be encrypted or signed; GnuPG does not recode
3799 user-supplied data. If this option is not used, the default
3800 character set is determined from the current locale. A verbosity
3801 level of 3 shows the chosen set. This option should not be used on
3802 Windows. Valid values for NAME are:
3805 This is the Latin 1 set.
3811 This is currently an alias for the Latin 1 set.
3814 The usual Russian set (RFC-1489).
3817 Bypass all translations and assume that the OS uses native
3822 Assume that command line arguments are given as UTF-8 strings. The
3823 default ('--no-utf8-strings') is to assume that arguments are
3824 encoded in the character set as specified by '--display-charset'.
3825 These options affect all following arguments. Both options may be
3826 used multiple times. This option should not be used in an option
3829 This option has no effect on Windows. There the internal used
3830 UTF-8 encoding is translated for console input and output. The
3831 command line arguments are expected as Unicode and translated to
3832 UTF-8. Thus when calling this program from another, make sure to
3833 use the Unicode version of CreateProcess.
3836 Read options from FILE and do not try to read them from the default
3837 options file in the homedir (see '--homedir'). This option is
3838 ignored if used in an options file.
3841 Shortcut for '--options /dev/null'. This option is detected before
3842 an attempt to open an option file. Using this option will also
3843 prevent the creation of a '~/.gnupg' homedir.
3846 '--compress-level N'
3847 '--bzip2-compress-level N'
3849 Set compression level to N for the ZIP and ZLIB compression
3850 algorithms. The default is to use the default compression level of
3851 zlib (normally 6). '--bzip2-compress-level' sets the compression
3852 level for the BZIP2 compression algorithm (defaulting to 6 as
3853 well). This is a different option from '--compress-level' since
3854 BZIP2 uses a significant amount of memory for each additional
3857 Option '-z' sets both. A value of 0 for N disables compression. A
3858 value of -1 forces compression using the default level. Option
3859 '--no-compress' is identical to '-z0'.
3861 Except for the '--store' command compression is always used unless
3862 'gpg' detects that the input is already compressed. To inhibit the
3863 use of compression use '-z0' or '--no-compress'; to force
3864 compression use '-z-1' or option 'z' with another compression level
3865 than the default as indicated by -1. Note that this overriding of
3866 the default deection works only with 'z' and not with the long
3867 variant of this option.
3869 '--bzip2-decompress-lowmem'
3870 Use a different decompression method for BZIP2 compressed files.
3871 This alternate method uses a bit more than half the memory, but
3872 also runs at half the speed. This is useful under extreme low
3873 memory circumstances when the file was originally compressed at a
3874 high '--bzip2-compress-level'.
3876 '--mangle-dos-filenames'
3877 '--no-mangle-dos-filenames'
3878 Older version of Windows cannot handle filenames with more than one
3879 dot. '--mangle-dos-filenames' causes GnuPG to replace (rather than
3880 add to) the extension of an output filename to avoid this problem.
3881 This option is off by default and has no effect on non-Windows
3885 '--no-ask-cert-level'
3886 When making a key signature, prompt for a certification level. If
3887 this option is not specified, the certification level used is set
3888 via '--default-cert-level'. See '--default-cert-level' for
3889 information on the specific levels and how they are used.
3890 '--no-ask-cert-level' disables this option. This option defaults
3893 '--default-cert-level N'
3894 The default to use for the check level when signing a key.
3896 0 means you make no particular claim as to how carefully you
3899 1 means you believe the key is owned by the person who claims to
3900 own it but you could not, or did not verify the key at all. This
3901 is useful for a "persona" verification, where you sign the key of a
3904 2 means you did casual verification of the key. For example, this
3905 could mean that you verified the key fingerprint and checked the
3906 user ID on the key against a photo ID.
3908 3 means you did extensive verification of the key. For example,
3909 this could mean that you verified the key fingerprint with the
3910 owner of the key in person, and that you checked, by means of a
3911 hard to forge document with a photo ID (such as a passport) that
3912 the name of the key owner matches the name in the user ID on the
3913 key, and finally that you verified (by exchange of email) that the
3914 email address on the key belongs to the key owner.
3916 Note that the examples given above for levels 2 and 3 are just
3917 that: examples. In the end, it is up to you to decide just what
3918 "casual" and "extensive" mean to you.
3920 This option defaults to 0 (no particular claim).
3923 When building the trust database, treat any signatures with a
3924 certification level below this as invalid. Defaults to 2, which
3925 disregards level 1 signatures. Note that level 0 "no particular
3926 claim" signatures are always accepted.
3928 '--trusted-key LONG KEY ID OR FINGERPRINT'
3929 Assume that the specified key (which should be given as
3930 fingerprint) is as trustworthy as one of your own secret keys.
3931 This option is useful if you don't want to keep your secret keys
3932 (or one of them) online but still want to be able to check the
3933 validity of a given recipient's or signator's key. If the given
3934 key is not locally available but an LDAP keyserver is configured
3935 the missing key is imported from that server.
3937 '--add-desig-revoker [sensitive:]FINGERPRINT'
3938 Add the key specified by FINGERPRINT as a designated revoker to
3939 newly created keys. If the fingerprint is prefixed with the
3940 keyword "sensitive:" that info is normally not exported wit the
3941 key. This option may be given several time to add more than one
3942 designated revoker. If the keyword "clear" is used instead of a
3943 fingerprint, all designated options previously encountered are
3944 discarded. Designated revokers are marked on the key as
3945 non-revocable. Note that a designated revoker specified using a
3946 parameter file will also be added to the key.
3948 '--trust-model {pgp|classic|tofu|tofu+pgp|direct|always|auto}'
3949 Set what trust model GnuPG should follow. The models are:
3952 This is the Web of Trust combined with trust signatures as
3953 used in PGP 5.x and later. This is the default trust model
3954 when creating a new trust database.
3957 This is the standard Web of Trust as introduced by PGP 2.
3960 TOFU stands for Trust On First Use. In this experimental
3961 trust model, the first time a key is seen, it is memorized.
3962 If later another key with a user id with the same email
3963 address is seen, both keys are marked as suspect. In that
3964 case, the next time either is used, a warning is displayed
3965 describing the conflict, why it might have occurred (either
3966 the user generated a new key and failed to cross sign the old
3967 and new keys, the key is forgery, or a man-in-the-middle
3968 attack is being attempted), and the user is prompted to
3969 manually confirm the validity of the key in question.
3971 Because a potential attacker is able to control the email
3972 address and thereby circumvent the conflict detection
3973 algorithm by using an email address that is similar in
3974 appearance to a trusted email address, whenever a message is
3975 verified, statistics about the number of messages signed with
3976 the key are shown. In this way, a user can easily identify
3977 attacks using fake keys for regular correspondents.
3979 When compared with the Web of Trust, TOFU offers significantly
3980 weaker security guarantees. In particular, TOFU only helps
3981 ensure consistency (that is, that the binding between a key
3982 and email address doesn't change). A major advantage of TOFU
3983 is that it requires little maintenance to use correctly. To
3984 use the web of trust properly, you need to actively sign keys
3985 and mark users as trusted introducers. This is a
3986 time-consuming process and anecdotal evidence suggests that
3987 even security-conscious users rarely take the time to do this
3988 thoroughly and instead rely on an ad-hoc TOFU process.
3990 In the TOFU model, policies are associated with bindings
3991 between keys and email addresses (which are extracted from
3992 user ids and normalized). There are five policies, which can
3993 be set manually using the '--tofu-policy' option. The default
3994 policy can be set using the '--tofu-default-policy' option.
3996 The TOFU policies are: 'auto', 'good', 'unknown', 'bad' and
3997 'ask'. The 'auto' policy is used by default (unless
3998 overridden by '--tofu-default-policy') and marks a binding as
3999 marginally trusted. The 'good', 'unknown' and 'bad' policies
4000 mark a binding as fully trusted, as having unknown trust or as
4001 having trust never, respectively. The 'unknown' policy is
4002 useful for just using TOFU to detect conflicts, but to never
4003 assign positive trust to a binding. The final policy, 'ask'
4004 prompts the user to indicate the binding's trust. If batch
4005 mode is enabled (or input is inappropriate in the context),
4006 then the user is not prompted and the 'undefined' trust level
4010 This experimental trust model combines TOFU with the Web of
4011 Trust. This is done by computing the trust level for each
4012 model and then taking the maximum trust level where the trust
4013 levels are ordered as follows: 'unknown < undefined < marginal
4014 < fully < ultimate < expired < never'.
4016 By setting '--tofu-default-policy=unknown', this model can be
4017 used to implement the web of trust with TOFU's conflict
4018 detection algorithm, but without its assignment of positive
4019 trust values, which some security-conscious users don't like.
4022 Key validity is set directly by the user and not calculated
4023 via the Web of Trust. This model is solely based on the key
4024 and does not distinguish user IDs. Note that when changing to
4025 another trust model the trust values assigned to a key are
4026 transformed into ownertrust values, which also indicate how
4027 you trust the owner of the key to sign other keys.
4030 Skip key validation and assume that used keys are always fully
4031 valid. You generally won't use this unless you are using some
4032 external validation scheme. This option also suppresses the
4033 "[uncertain]" tag printed with signature checks when there is
4034 no evidence that the user ID is bound to the key. Note that
4035 this trust model still does not allow the use of expired,
4036 revoked, or disabled keys.
4039 Select the trust model depending on whatever the internal
4040 trust database says. This is the default model if such a
4041 database already exists. Note that a tofu trust model is not
4042 considered here and must be enabled explicitly.
4045 Identical to '--trust-model always'.
4047 '--assert-signer FPR_OR_FILE'
4048 This option checks whether at least one valid signature on a file
4049 has been made with the specified key. The key is either specified
4050 as a fingerprint or a file listing fingerprints. The fingerprint
4051 must be given or listed in compact format (no colons or spaces in
4052 between). This option can be given multiple times and each
4053 fingerprint is checked against the signing key as well as the
4054 corresponding primary key. If FPR_OR_FILE specifies a file, empty
4055 lines are ignored as well as all lines starting with a hash sign.
4056 With this option gpg is guaranteed to return with an exit code of 0
4057 if and only if a signature has been encountered, is valid, and the
4058 key matches one of the fingerprints given by this option.
4060 '--auto-key-locate MECHANISMS'
4061 '--no-auto-key-locate'
4062 GnuPG can automatically locate and retrieve keys as needed using
4063 this option. This happens when encrypting to an email address (in
4064 the "user@example.com" form), and there are no "user@example.com"
4065 keys on the local keyring. This option takes any number of the
4066 mechanisms listed below, in the order they are to be tried.
4067 Instead of listing the mechanisms as comma delimited arguments, the
4068 option may also be given several times to add more mechanism. The
4069 option '--no-auto-key-locate' or the mechanism "clear" resets the
4070 list. The default is "local,wkd".
4073 Locate a key using DNS CERT, as specified in RFC-4398.
4076 Locate a key using DANE, as specified in
4077 draft-ietf-dane-openpgpkey-05.txt.
4080 Locate a key using the Web Key Directory protocol.
4083 Using DNS Service Discovery, check the domain in question for
4084 any LDAP keyservers to use. If this fails, attempt to locate
4085 the key using the PGP Universal method of checking
4086 'ldap://keys.(thedomain)'.
4089 Locate the key using the Active Directory (Windows only).
4090 This method also allows to search by fingerprint using the
4091 command '--locate-external-key'. Note that this mechanism is
4092 actually a shortcut for the mechanism 'keyserver' but using
4093 "ldap:///" as the keyserver.
4096 Locate a key using a keyserver. This method also allows to
4097 search by fingerprint using the command
4098 '--locate-external-key' if any of the configured keyservers is
4102 In addition, a keyserver URL as used in the 'dirmngr'
4103 configuration may be used here to query that particular
4104 keyserver. This method also allows to search by fingerprint
4105 using the command '--locate-external-key' if the URL specifies
4109 Locate the key using the local keyrings. This mechanism
4110 allows the user to select the order a local key lookup is
4111 done. Thus using '--auto-key-locate local' is identical to
4112 '--no-auto-key-locate'.
4115 This flag disables the standard local key lookup, done before
4116 any of the mechanisms defined by the '--auto-key-locate' are
4117 tried. The position of this mechanism in the list does not
4118 matter. It is not required if 'local' is also used.
4121 Clear all defined mechanisms. This is useful to override
4122 mechanisms given in a config file. Note that a 'nodefault' in
4123 MECHANISMS will also be cleared unless it is given after the
4127 '--no-auto-key-import'
4128 This is an offline mechanism to get a missing key for signature
4129 verification and for later encryption to this key. If this option
4130 is enabled and a signature includes an embedded key, that key is
4131 used to verify the signature and on verification success the key is
4132 imported. The default is '--no-auto-key-import'.
4134 On the sender (signing) site the option '--include-key-block' needs
4135 to be used to put the public part of the signing key as “Key Block
4136 subpacket” into the signature.
4138 '--auto-key-retrieve'
4139 '--no-auto-key-retrieve'
4140 These options enable or disable the automatic retrieving of keys
4141 from a keyserver when verifying signatures made by keys that are
4142 not on the local keyring. The default is '--no-auto-key-retrieve'.
4144 The order of methods tried to lookup the key is:
4146 1. If the option '--auto-key-import' is set and the signatures
4147 includes an embedded key, that key is used to verify the signature
4148 and on verification success that key is imported.
4150 2. If a preferred keyserver is specified in the signature and the
4151 option 'honor-keyserver-url' is active (which is not the default),
4152 that keyserver is tried. Note that the creator of the signature
4153 uses the option '--sig-keyserver-url' to specify the preferred
4154 keyserver for data signatures.
4156 3. If the signature has the Signer's UID set (e.g. using
4157 '--sender' while creating the signature) a Web Key Directory (WKD)
4158 lookup is done. This is the default configuration but can be
4159 disabled by removing WKD from the auto-key-locate list or by using
4160 the option '--disable-signer-uid'.
4162 4. If any keyserver is configured and the Issuer Fingerprint is
4163 part of the signature (since GnuPG 2.1.16), the configured
4164 keyservers are tried.
4166 Note that this option makes a "web bug" like behavior possible.
4167 Keyserver or Web Key Directory operators can see which keys you
4168 request, so by sending you a message signed by a brand new key
4169 (which you naturally will not have on your local keyring), the
4170 operator can tell both your IP address and the time when you
4171 verified the signature.
4173 '--keyid-format {none|short|0xshort|long|0xlong}'
4174 Select how to display key IDs. "none" does not show the key ID at
4175 all but shows the fingerprint in a separate line. "short" is the
4176 traditional 8-character key ID. "long" is the more accurate (but
4177 less convenient) 16-character key ID. Add an "0x" to either to
4178 include an "0x" at the beginning of the key ID, as in 0x99242560.
4179 Note that this option is ignored if the option '--with-colons' is
4183 This option is deprecated - please use the '--keyserver' in
4184 'dirmngr.conf' instead.
4186 Use NAME as your keyserver. This is the server that
4187 '--receive-keys', '--send-keys', and '--search-keys' will
4188 communicate with to receive keys from, send keys to, and search for
4189 keys on. The format of the NAME is a URI:
4190 'scheme:[//]keyservername[:port]' The scheme is the type of
4191 keyserver: "hkp"/"hkps" for the HTTP (or compatible) keyservers or
4192 "ldap"/"ldaps" for the LDAP keyservers. Note that your particular
4193 installation of GnuPG may have other keyserver types available as
4194 well. Keyserver schemes are case-insensitive.
4196 Most keyservers synchronize with each other, so there is generally
4197 no need to send keys to more than one server. The keyserver
4198 'hkp://keys.gnupg.net' uses round robin DNS to give a different
4199 keyserver each time you use it.
4201 '--keyserver-options {NAME=VALUE}'
4202 This is a space or comma delimited string that gives options for
4203 the keyserver. Options can be prefixed with a 'no-' to give the
4204 opposite meaning. Valid import-options or export-options may be
4205 used here as well to apply to importing ('--recv-key') or exporting
4206 ('--send-key') a key from a keyserver. While not all options are
4207 available for all keyserver types, some common options are:
4210 When searching for a key with '--search-keys', include keys
4211 that are marked on the keyserver as revoked. Note that not
4212 all keyservers differentiate between revoked and unrevoked
4213 keys, and for such keyservers this option is meaningless.
4214 Note also that most keyservers do not have cryptographic
4215 verification of key revocations, and so turning this option
4216 off may result in skipping keys that are incorrectly marked as
4220 When searching for a key with '--search-keys', include keys
4221 that are marked on the keyserver as disabled. Note that this
4222 option is not used with HKP keyservers.
4225 This is an obsolete alias for the option 'auto-key-retrieve'.
4226 Please do not use it; it will be removed in future versions..
4229 When using '--refresh-keys', if the key in question has a
4230 preferred keyserver URL, then use that preferred keyserver to
4231 refresh the key from. In addition, if auto-key-retrieve is
4232 set, and the signature being verified has a preferred
4233 keyserver URL, then use that preferred keyserver to fetch the
4234 key from. Note that this option introduces a "web bug": The
4235 creator of the key can see when the keys is refreshed. Thus
4236 this option is not enabled by default.
4239 When receiving a key, include subkeys as potential targets.
4240 Note that this option is not used with HKP keyservers, as they
4241 do not support retrieving keys by subkey id.
4249 These options have no more function since GnuPG 2.1. Use the
4250 'dirmngr' configuration options instead.
4252 The default list of options is: "self-sigs-only, import-clean,
4253 repair-keys, repair-pks-subkey-bug, export-attributes". However,
4254 if the actual used source is an LDAP server "no-self-sigs-only" is
4255 assumed unless "self-sigs-only" has been explicitly configured.
4257 '--completes-needed N'
4258 Number of completely trusted users to introduce a new key signer
4261 '--marginals-needed N'
4262 Number of marginally trusted users to introduce a new key signer
4265 '--tofu-default-policy {auto|good|unknown|bad|ask}'
4266 The default TOFU policy (defaults to 'auto'). For more information
4267 about the meaning of this option, *note trust-model-tofu::.
4269 '--max-cert-depth N'
4270 Maximum depth of a certification chain (default is 5).
4273 Do not cache the verification status of key signatures. Caching
4274 gives a much better performance in key listings. However, if you
4275 suspect that your public keyring is not safe against write
4276 modifications, you can use this option to disable the caching. It
4277 probably does not make sense to disable it because all kind of
4278 damage can be done if someone else has write access to your public
4281 '--auto-check-trustdb'
4282 '--no-auto-check-trustdb'
4283 If GnuPG feels that its information about the Web of Trust has to
4284 be updated, it automatically runs the '--check-trustdb' command
4285 internally. This may be a time consuming process.
4286 '--no-auto-check-trustdb' disables this option.
4290 This is dummy option. 'gpg' always requires the agent.
4293 This is dummy option. It has no effect when used with 'gpg'.
4295 '--agent-program FILE'
4296 Specify an agent program to be used for secret key operations. The
4297 default value is determined by running 'gpgconf' with the option
4298 '--list-dirs'. Note that the pipe symbol ('|') is used for a
4299 regression test suite hack and may thus not be used in the file
4302 '--dirmngr-program FILE'
4303 Specify a dirmngr program to be used for keyserver access. The
4304 default value is '/usr/local/bin/dirmngr'.
4307 Entirely disable the use of the Dirmngr.
4310 Do not start the gpg-agent or the dirmngr if it has not yet been
4311 started and its service is required. This option is mostly useful
4312 on machines where the connection to gpg-agent has been redirected
4313 to another machines. If dirmngr is required on the remote machine,
4314 it may be started manually using 'gpgconf --launch dirmngr'.
4317 Lock the databases the first time a lock is requested and do not
4318 release the lock until the process terminates.
4321 Release the locks every time a lock is no longer needed. Use this
4322 to override a previous '--lock-once' from a config file.
4325 Disable locking entirely. This option should be used only in very
4326 special environments, where it can be assured that only one process
4327 is accessing those files. A bootable floppy with a stand-alone
4328 encryption system will probably use this. Improper usage of this
4329 option may lead to data and key corruption.
4331 '--exit-on-status-write-error'
4332 This option will cause write errors on the status FD to immediately
4333 terminate the process. That should in fact be the default but it
4334 never worked this way and thus we need an option to enable this, so
4335 that the change won't break applications which close their end of a
4336 status fd connected pipe too early. Using this option along with
4337 '--enable-progress-filter' may be used to cleanly cancel long
4338 running gpg operations.
4340 '--limit-card-insert-tries N'
4341 With N greater than 0 the number of prompts asking to insert a
4342 smartcard gets limited to N-1. Thus with a value of 1 gpg won't at
4343 all ask to insert a card if none has been inserted at startup.
4344 This option is useful in the configuration file in case an
4345 application does not know about the smartcard support and waits ad
4346 infinitum for an inserted card.
4348 '--no-random-seed-file'
4349 GnuPG uses a file to store its internal random pool over
4350 invocations. This makes random generation faster; however
4351 sometimes write operations are not desired. This option can be
4352 used to achieve that with the cost of slower random generation.
4355 Suppress the initial copyright message.
4357 '--no-secmem-warning'
4358 Suppress the warning about "using insecure memory".
4360 '--no-permission-warning'
4361 Suppress the warning about unsafe file and home directory
4362 ('--homedir') permissions. Note that the permission checks that
4363 GnuPG performs are not intended to be authoritative, but rather
4364 they simply warn about certain common permission problems. Do not
4365 assume that the lack of a warning means that your system is secure.
4367 Note that the warning for unsafe '--homedir' permissions cannot be
4368 suppressed in the gpg.conf file, as this would allow an attacker to
4369 place an unsafe gpg.conf file in place, and use this file to
4370 suppress warnings about itself. The '--homedir' permissions
4371 warning may only be suppressed on the command line.
4374 '--no-require-secmem'
4375 Refuse to run if GnuPG cannot get secure memory. Defaults to no
4376 (i.e. run, but give a warning).
4378 '--require-cross-certification'
4379 '--no-require-cross-certification'
4380 When verifying a signature made from a subkey, ensure that the
4381 cross certification "back signature" on the subkey is present and
4382 valid. This protects against a subtle attack against subkeys that
4383 can sign. Defaults to '--require-cross-certification' for 'gpg'.
4387 Allow the user to do certain nonsensical or "silly" things like
4388 signing an expired or revoked key, or certain potentially
4389 incompatible things like generating unusual key types. This also
4390 disables certain warning messages about potentially incompatible
4391 actions. As the name implies, this option is for experts only. If
4392 you don't fully understand the implications of what it allows you
4393 to do, leave this off. '--no-expert' disables this option.
4396 File: gnupg.info, Node: GPG Key related Options, Next: GPG Input and Output, Prev: GPG Configuration Options, Up: GPG Options
4398 4.2.2 Key related options
4399 -------------------------
4403 Encrypt for user id NAME. If this option or '--hidden-recipient'
4404 is not specified, GnuPG asks for the user-id unless
4405 '--default-recipient' is given.
4407 '--hidden-recipient NAME'
4409 Encrypt for user ID NAME, but hide the key ID of this user's key.
4410 This option helps to hide the receiver of the message and is a
4411 limited countermeasure against traffic analysis. If this option or
4412 '--recipient' is not specified, GnuPG asks for the user ID unless
4413 '--default-recipient' is given.
4415 '--recipient-file FILE'
4417 This option is similar to '--recipient' except that it encrypts to
4418 a key stored in the given file. FILE must be the name of a file
4419 containing exactly one key. 'gpg' assumes that the key in this
4420 file is fully valid.
4422 '--hidden-recipient-file FILE'
4424 This option is similar to '--hidden-recipient' except that it
4425 encrypts to a key stored in the given file. FILE must be the name
4426 of a file containing exactly one key. 'gpg' assumes that the key
4427 in this file is fully valid.
4430 Same as '--recipient' but this one is intended for use in the
4431 options file and may be used with your own user-id as an
4432 "encrypt-to-self". These keys are only used when there are other
4433 recipients given either by use of '--recipient' or by the asked
4434 user id. No trust checking is performed for these user ids and
4435 even disabled keys can be used.
4437 '--hidden-encrypt-to NAME'
4438 Same as '--hidden-recipient' but this one is intended for use in
4439 the options file and may be used with your own user-id as a hidden
4440 "encrypt-to-self". These keys are only used when there are other
4441 recipients given either by use of '--recipient' or by the asked
4442 user id. No trust checking is performed for these user ids and
4443 even disabled keys can be used.
4446 Disable the use of all '--encrypt-to' and '--hidden-encrypt-to'
4449 '--group {NAME=VALUE}'
4450 Sets up a named group, which is similar to aliases in email
4451 programs. Any time the group name is a recipient ('-r' or
4452 '--recipient'), it will be expanded to the values specified.
4453 Multiple groups with the same name are automatically merged into a
4456 The values are 'key IDs' or fingerprints, but any key description
4457 is accepted. Note that a value with spaces in it will be treated
4458 as two different values. Note also there is only one level of
4459 expansion -- you cannot make an group that points to another group.
4460 When used from the command line, it may be necessary to quote the
4461 argument to this option to prevent the shell from treating it as
4465 Remove a given entry from the '--group' list.
4468 Remove all entries from the '--group' list.
4472 Use NAME as the key to sign with. Note that this option overrides
4476 This option has two purposes. MBOX must either be a complete user
4477 ID containing a proper mail address or just a plain mail address.
4478 The option can be given multiple times.
4480 When creating a signature this option tells gpg the signing key's
4481 user id used to make the signature and embeds that user ID into the
4482 created signature (using OpenPGP's "Signer's User ID" subpacket).
4483 If the option is given multiple times a suitable user ID is picked.
4484 However, if the signing key was specified directly by using a mail
4485 address (i.e. not by using a fingerprint or key ID) this option is
4486 used and the mail address is embedded in the created signature.
4488 When verifying a signature MBOX is used to restrict the information
4489 printed by the TOFU code to matching user IDs. If the option is
4490 used and the signature contains a "Signer's User ID" subpacket that
4491 information is is also used to restrict the printed information.
4492 Note that GnuPG considers only the mail address part of a User ID.
4494 If this option or the said subpacket is available the TRUST lines
4495 as printed by option 'status-fd' correspond to the corresponding
4496 User ID; if no User ID is known the TRUST lines are computed
4497 directly on the key and do not give any information about the User
4498 ID. In the latter case it his highly recommended to scripts and
4499 other frontends to evaluate the VALIDSIG line, retrieve the key and
4500 print all User IDs along with their validity (trust) information.
4502 '--try-secret-key NAME'
4503 For hidden recipients GPG needs to know the keys to use for trial
4504 decryption. The key set with '--default-key' is always tried
4505 first, but this is often not sufficient. This option allows
4506 setting more keys to be used for trial decryption. Although any
4507 valid user-id specification may be used for NAME it makes sense to
4508 use at least the long keyid to avoid ambiguities. Note that
4509 gpg-agent might pop up a pinentry for a lot keys to do the trial
4510 decryption. If you want to stop all further trial decryption you
4511 may use close-window button instead of the cancel button.
4514 Don't look at the key ID as stored in the message but try all
4515 secret keys in turn to find the right decryption key. This option
4516 forces the behaviour as used by anonymous recipients (created by
4517 using '--throw-keyids' or '--hidden-recipient') and might come
4518 handy in case where an encrypted message contains a bogus key ID.
4520 '--skip-hidden-recipients'
4521 '--no-skip-hidden-recipients'
4522 During decryption skip all anonymous recipients. This option helps
4523 in the case that people use the hidden recipients feature to hide
4524 their own encrypt-to key from others. If one has many secret keys
4525 this may lead to a major annoyance because all keys are tried in
4526 turn to decrypt something which was not really intended for it.
4527 The drawback of this option is that it is currently not possible to
4528 decrypt a message which includes real anonymous recipients.
4531 File: gnupg.info, Node: GPG Input and Output, Next: OpenPGP Options, Prev: GPG Key related Options, Up: GPG Options
4533 4.2.3 Input and Output
4534 ----------------------
4538 Create ASCII armored output. The default is to create the binary
4542 Assume the input data is not in ASCII armored format.
4546 Write output to FILE. To write to stdout use '-' as the filename.
4549 This option sets a limit on the number of bytes that will be
4550 generated when processing a file. Since OpenPGP supports various
4551 levels of compression, it is possible that the plaintext of a given
4552 message may be significantly larger than the original OpenPGP
4553 message. While GnuPG works properly with such messages, there is
4554 often a desire to set a maximum file size that will be generated
4555 before processing is forced to stop by the OS limits. Defaults to
4556 0, which means "no limit".
4559 The AEAD encryption mode encrypts the data in chunks so that a
4560 receiving side can check for transmission errors or tampering at
4561 the end of each chunk and does not need to delay this until all
4562 data has been received. The used chunk size is 2^N byte. The
4563 lowest allowed value for N is 6 (64 byte) and the largest is the
4564 default of 22 which creates chunks not larger than 4 MiB.
4566 '--input-size-hint N'
4567 This option can be used to tell GPG the size of the input data in
4568 bytes. N must be a positive base-10 number. This option is only
4569 useful if the input is not taken from a file. GPG may use this
4570 hint to optimize its buffer allocation strategy. It is also used
4571 by the '--status-fd' line "PROGRESS" to provide a value for "total"
4572 if that is not available by other means.
4574 '--key-origin STRING[,URL]'
4575 gpg can track the origin of a key. Certain origins are implicitly
4576 known (e.g. keyserver, web key directory) and set. For a standard
4577 import the origin of the keys imported can be set with this option.
4578 To list the possible values use "help" for STRING. Some origins
4579 can store an optional URL argument. That URL can appended to
4580 STRING after a comma.
4582 '--import-options PARAMETERS'
4583 This is a space or comma delimited string that gives options for
4584 importing keys. Options can be prepended with a 'no-' to give the
4585 opposite meaning. The options are:
4588 Allow importing key signatures marked as "local". This is not
4589 generally useful unless a shared keyring scheme is being used.
4593 Normally possible still existing ownertrust values of a key
4594 are cleared if a key is imported. This is in general
4595 desirable so that a formerly deleted key does not
4596 automatically gain an ownertrust values merely due to import.
4597 On the other hand it is sometimes necessary to re-import a
4598 trusted set of keys again but keeping already assigned
4599 ownertrust values. This can be achieved by using this option.
4601 repair-pks-subkey-bug
4602 During import, attempt to repair the damage caused by the PKS
4603 keyserver bug (pre version 0.9.6) that mangles keys with
4604 multiple subkeys. Note that this cannot completely repair the
4605 damaged key as some crucial data is removed by the keyserver,
4606 but it does at least give you back one subkey. Defaults to no
4607 for regular '--import' and to yes for keyserver
4612 Show a listing of the key as imported right before it is
4613 stored. This can be combined with the option '--dry-run' to
4614 only look at keys; the option 'show-only' is a shortcut for
4615 this combination. The command '--show-keys' is another
4616 shortcut for this. Note that suffixes like '#' for "sec" and
4617 "sbb" lines may or may not be printed.
4620 Run the entire import code but instead of storing the key to
4621 the local keyring write it to the output. The export option
4622 'export-dane' affect the output. This option can for example
4623 be used to remove all invalid parts from a key without the
4627 During import, allow key updates to existing keys, but do not
4628 allow any new keys to be imported. Defaults to no.
4631 After import, compact (remove all signatures except the
4632 self-signature) any user IDs from the new key that are not
4633 usable. Then, remove any signatures from the new key that are
4634 not usable. This includes signatures that were issued by keys
4635 that are not present on the keyring. This option is the same
4636 as running the '--edit-key' command "clean" after import.
4640 Accept only self-signatures while importing a key. All other
4641 key signatures are skipped at an early import stage. This
4642 option can be used with 'keyserver-options' to mitigate
4643 attempts to flood a key with bogus signatures from a
4644 keyserver. The drawback is that all other valid key
4645 signatures, as required by the Web of Trust are also not
4646 imported. Note that when using this option along with
4647 import-clean it suppresses the final clean step after merging
4648 the imported key into the existing key.
4651 After import, fix various problems with the keys. For
4652 example, this reorders signatures, and strips duplicate
4653 signatures. Defaults to yes.
4656 When used the keyboxd (option 'use-keyboxd' in 'common.conf')
4657 does the import within a single transaction.
4660 Import the smallest key possible. This removes all signatures
4661 except the most recent self-signature on each user ID. This
4662 option is the same as running the '--edit-key' command
4663 "minimize" after import. Defaults to no.
4667 Import in key restore mode. This imports all data which is
4668 usually skipped during import; including all GnuPG specific
4669 data. All other contradicting options are overridden.
4671 '--import-filter {NAME=EXPR}'
4672 '--export-filter {NAME=EXPR}'
4673 These options define an import/export filter which are applied to
4674 the imported/exported keyblock right before it will be
4675 stored/written. NAME defines the type of filter to use, EXPR the
4676 expression to evaluate. The option can be used several times which
4677 then appends more expression to the same NAME.
4679 The available filter types are:
4682 This filter will keep a user id packet and its dependent
4683 packets in the keyblock if the expression evaluates to true.
4686 This filter drops the selected subkeys. Currently only
4687 implemented for -export-filter.
4690 This filter drops the selected key signatures on user ids.
4691 Self-signatures are not considered. Currently only
4692 implemented for -import-filter.
4695 This filter is only implemented by '--list-filter'. All
4696 property names may be used.
4698 For the syntax of the expression see the chapter "FILTER
4699 EXPRESSIONS". The property names for the expressions depend on the
4700 actual filter type and are indicated in the following table. Note
4701 that all property names may also be used by '--list-filter'.
4703 Property names may be prefix with a scope delimited by a slash.
4704 Valid scopes are "pub" for public and secret primary keys, "sub"
4705 for public and secret subkeys, "uid" for for user-ID packets, and
4706 "sig" for signature packets. Invalid scopes are currently ignored.
4708 The available properties are:
4711 A string with the user id. (keep-uid)
4714 The addr-spec part of a user id with mailbox or the empty
4718 A string with the key algorithm description. For example
4719 "rsa3072" or "ed25519".
4722 A number with the public key algorithm of a key or subkey
4723 packet. (drop-subkey)
4726 A number with the effective key size of a key or subkey
4727 packet. (drop-subkey)
4731 The first is the timestamp a public key or subkey packet was
4732 created. The second is the same but given as an ISO string,
4733 e.g. "2016-08-17". (drop-subkey)
4737 The expiration time of a public key or subkey or 0 if it does
4738 not expire. The second is the same but given as an ISO date
4739 string or an empty string e.g. "2038-01-19".
4742 The hexified fingerprint of the current subkey or primary key.
4746 Boolean indicating whether the user id is the primary one.
4750 Boolean indicating whether a user id (keep-uid), a key
4751 (drop-subkey), or a signature (drop-sig) expired.
4754 Boolean indicating whether a user id (keep-uid) or a key
4755 (drop-subkey) has been revoked.
4758 Boolean indicating whether a primary key is disabled.
4761 Boolean indicating whether a key or subkey is a secret one.
4765 A string indicating the usage flags for the subkey, from the
4766 sequence "ecsa?". For example, a subkey capable of just
4767 signing and authentication would be an exact match for "sa".
4772 The first is the timestamp a signature packet was created.
4773 The second is the same but given as an ISO date string, e.g.
4774 "2016-08-17". (drop-sig)
4777 A number with the public key algorithm of a signature packet.
4781 A number with the digest algorithm of a signature packet.
4785 A string with the key origin or a question mark. For example
4786 the string "wkd" is used if a key originated from a Web Key
4790 The timestamp the key was last updated from a keyserver or the
4794 A string with the the URL associated wit the last key lookup.
4796 '--export-options PARAMETERS'
4797 This is a space or comma delimited string that gives options for
4798 exporting keys. Options can be prepended with a 'no-' to give the
4799 opposite meaning. The options are:
4802 Allow exporting key signatures marked as "local". This is not
4803 generally useful unless a shared keyring scheme is being used.
4807 Include attribute user IDs (photo IDs) while exporting. Not
4808 including attribute user IDs is useful to export keys that are
4809 going to be used by an OpenPGP program that does not accept
4810 attribute user IDs. Defaults to yes.
4812 export-sensitive-revkeys
4813 Include designated revoker information that was marked as
4814 "sensitive". Defaults to no.
4818 Export for use as a backup. The exported data includes all
4819 data which is needed to restore the key or keys later with
4820 GnuPG. The format is basically the OpenPGP format but enhanced
4821 with GnuPG specific data. All other contradicting options are
4825 Compact (remove all signatures from) user IDs on the key being
4826 exported if the user IDs are not usable. Also, do not export
4827 any signatures that are not usable. This includes signatures
4828 that were issued by keys that are not present on the keyring.
4829 This option is the same as running the '--edit-key' command
4830 "clean" before export except that the local copy of the key is
4831 not modified. Defaults to no.
4834 Export the smallest key possible. This removes all signatures
4835 except the most recent self-signature on each user ID. This
4836 option is the same as running the '--edit-key' command
4837 "minimize" before export except that the local copy of the key
4838 is not modified. Defaults to no.
4841 Export only standalone revocation certificates of the key.
4842 This option does not export revocations of 3rd party
4843 certificate revocations.
4846 Instead of outputting the key material output OpenPGP DANE
4847 records suitable to put into DNS zone files. An ORIGIN line
4848 is printed before each record to allow diverting the records
4849 to the corresponding zone file.
4852 Enable the use of a new secret key export format. This format
4853 avoids the re-encryption as required with the current OpenPGP
4854 format and also improves the security of the secret key if it
4855 has been protected with a passphrase. Note that an
4856 unprotected key is exported as-is and thus not secure; the
4857 general rule to convey secret keys in an OpenPGP encrypted
4858 file still applies with this mode. Versions of GnuPG before
4859 2.4.0 are not able to import such a secret file.
4862 Print key listings delimited by colons. Note that the output will
4863 be encoded in UTF-8 regardless of any '--display-charset' setting.
4864 This format is useful when GnuPG is called from scripts and other
4865 programs as it is easily machine parsed. The details of this
4866 format are documented in the file 'doc/DETAILS', which is included
4867 in the GnuPG source distribution.
4870 Do not merge primary user ID and primary key in '--with-colon'
4871 listing mode and print all timestamps as seconds since 1970-01-01.
4872 Since GnuPG 2.0.10, this mode is always used and thus this option
4873 is obsolete; it does not harm to use it though.
4875 '--legacy-list-mode'
4876 Revert to the pre-2.1 public key list mode. This only affects the
4877 human readable output and not the machine interface (i.e.
4878 '--with-colons'). Note that the legacy format does not convey
4879 suitable information for elliptic curves.
4881 '--with-fingerprint'
4882 Same as the command '--fingerprint' but changes only the format of
4883 the output and may be used together with another command.
4885 '--with-subkey-fingerprint'
4886 If a fingerprint is printed for the primary key, this option forces
4887 printing of the fingerprint for all subkeys. This could also be
4888 achieved by using the '--with-fingerprint' twice but by using this
4889 option along with keyid-format "none" a compact fingerprint is
4892 '--with-icao-spelling'
4893 Print the ICAO spelling of the fingerprint in addition to the hex
4897 Include the keygrip in the key listings. In '--with-colons' mode
4898 this is implicitly enable for secret keys.
4901 Include the locally held information on the origin and last update
4902 of a key in a key listing. In '--with-colons' mode this is always
4903 printed. This data is currently experimental and shall not be
4904 considered part of the stable API.
4907 Print a Web Key Directory identifier along with each user ID in key
4908 listings. This is an experimental feature and semantics may
4912 Include info about the presence of a secret key in public key
4913 listings done with '--with-colons'.
4916 File: gnupg.info, Node: OpenPGP Options, Next: Compliance Options, Prev: GPG Input and Output, Up: GPG Options
4918 4.2.4 OpenPGP protocol specific options
4919 ---------------------------------------
4923 Treat input files as text and store them in the OpenPGP canonical
4924 text form with standard "CRLF" line endings. This also sets the
4925 necessary flags to inform the recipient that the encrypted or
4926 signed data is text and may need its line endings converted back to
4927 whatever the local system uses. This option is useful when
4928 communicating between two platforms that have different line ending
4929 conventions (UNIX-like to Mac, Mac to Windows, etc).
4930 '--no-textmode' disables this option, and is the default.
4933 '--no-force-v3-sigs'
4935 '--no-force-v4-certs'
4936 These options are obsolete and have no effect since GnuPG 2.1.
4940 Force the use of AEAD encryption over MDC encryption. AEAD is a
4941 modern and faster way to do authenticated encryption than the old
4942 MDC method. '--force-aead' is an alias and deprecated. See also
4943 option '--chunk-size'.
4947 These options are obsolete and have no effect since GnuPG 2.2.8.
4948 The MDC is always used unless the keys indicate that an AEAD
4949 algorithm can be used in which case AEAD is used. But note: If the
4950 creation of a legacy non-MDC message is exceptionally required, the
4951 option '--rfc2440' allows for this.
4953 '--disable-signer-uid'
4954 By default the user ID of the signing key is embedded in the data
4955 signature. As of now this is only done if the signing key has been
4956 specified with 'local-user' using a mail address, or with 'sender'.
4957 This information can be helpful for verifier to locate the key; see
4958 option '--auto-key-retrieve'.
4960 '--include-key-block'
4961 '--no-include-key-block'
4962 This option is used to embed the actual signing key into a data
4963 signature. The embedded key is stripped down to a single user id
4964 and includes only the signing subkey used to create the signature
4965 as well as as valid encryption subkeys. All other info is removed
4966 from the key to keep it and thus the signature small. This option
4967 is the OpenPGP counterpart to the 'gpgsm' option '--include-certs'
4968 and allows the recipient of a signed message to reply encrypted to
4969 the sender without using any online directories to lookup the key.
4970 The default is '--no-include-key-block'. See also the option
4971 '--auto-key-import'.
4973 '--personal-cipher-preferences STRING'
4974 Set the list of personal cipher preferences to STRING. Use 'gpg
4975 --version' to get a list of available algorithms, and use 'none' to
4976 set no preference at all. This allows the user to safely override
4977 the algorithm chosen by the recipient key preferences, as GPG will
4978 only select an algorithm that is usable by all recipients. The
4979 most highly ranked cipher in this list is also used for the
4980 '--symmetric' encryption command.
4982 '--personal-digest-preferences STRING'
4983 Set the list of personal digest preferences to STRING. Use 'gpg
4984 --version' to get a list of available algorithms, and use 'none' to
4985 set no preference at all. This allows the user to safely override
4986 the algorithm chosen by the recipient key preferences, as GPG will
4987 only select an algorithm that is usable by all recipients. The
4988 most highly ranked digest algorithm in this list is also used when
4989 signing without encryption (e.g. '--clear-sign' or '--sign').
4991 '--personal-compress-preferences STRING'
4992 Set the list of personal compression preferences to STRING. Use
4993 'gpg --version' to get a list of available algorithms, and use
4994 'none' to set no preference at all. This allows the user to safely
4995 override the algorithm chosen by the recipient key preferences, as
4996 GPG will only select an algorithm that is usable by all recipients.
4997 The most highly ranked compression algorithm in this list is also
4998 used when there are no recipient keys to consider (e.g.
5001 '--s2k-cipher-algo NAME'
5002 Use NAME as the cipher algorithm for symmetric encryption with a
5003 passphrase if '--personal-cipher-preferences' and '--cipher-algo'
5004 are not given. The default is AES-128.
5006 '--s2k-digest-algo NAME'
5007 Use NAME as the digest algorithm used to mangle the passphrases for
5008 symmetric encryption. The default is SHA-1.
5011 Selects how passphrases for symmetric encryption are mangled. If N
5012 is 0 a plain passphrase (which is in general not recommended) will
5013 be used, a 1 adds a salt (which should not be used) to the
5014 passphrase and a 3 (the default) iterates the whole process a
5015 number of times (see '--s2k-count').
5018 Specify how many times the passphrases mangling for symmetric
5019 encryption is repeated. This value may range between 1024 and
5020 65011712 inclusive. The default is inquired from gpg-agent. Note
5021 that not all values in the 1024-65011712 range are legal and if an
5022 illegal value is selected, GnuPG will round up to the nearest legal
5023 value. This option is only meaningful if '--s2k-mode' is set to
5027 File: gnupg.info, Node: Compliance Options, Next: GPG Esoteric Options, Prev: OpenPGP Options, Up: GPG Options
5029 4.2.5 Compliance options
5030 ------------------------
5032 These options control what GnuPG is compliant to. Only one of these
5033 options may be active at a time. Note that the default setting of this
5034 is nearly always the correct one. See the INTEROPERABILITY WITH OTHER
5035 OPENPGP PROGRAMS section below before using one of these options.
5038 Use standard GnuPG behavior. This is essentially OpenPGP behavior
5039 (see '--openpgp'), but with extension from the proposed update to
5040 OpenPGP and with some additional workarounds for common
5041 compatibility problems in different versions of PGP. This is the
5042 default option, so it is not generally needed, but it may be useful
5043 to override a different compliance option in the gpg.conf file.
5046 Reset all packet, cipher and digest options to strict OpenPGP
5047 behavior. This option implies '--allow-old-cipher-algos'. Use
5048 this option to reset all previous options like '--s2k-*',
5049 '--cipher-algo', '--digest-algo' and '--compress-algo' to OpenPGP
5050 compliant values. All PGP workarounds are disabled.
5053 Reset all packet, cipher and digest options to strict RFC-4880
5054 behavior. This option implies '--allow-old-cipher-algos'. Note
5055 that this is currently the same thing as '--openpgp'.
5058 Reset all packet, cipher and digest options to strict according to
5059 the proposed updates of RFC-4880.
5062 Reset all packet, cipher and digest options to strict RFC-2440
5063 behavior. Note that by using this option encryption packets are
5064 created in a legacy mode without MDC protection. This is dangerous
5065 and should thus only be used for experiments. This option implies
5066 '--allow-old-cipher-algos'. See also option '--ignore-mdc-error'.
5069 This option is obsolete; it is handled as an alias for '--pgp7'
5072 Set up all options to be as PGP 7 compliant as possible. This
5073 allowed the ciphers IDEA, 3DES, CAST5,AES128, AES192, AES256, and
5074 TWOFISH., the hashes MD5, SHA1 and RIPEMD160, and the compression
5075 algorithms none and ZIP. This option implies '--escape-from-lines'
5076 and disables '--throw-keyids',
5079 Set up all options to be as PGP 8 compliant as possible. PGP 8 is
5080 a lot closer to the OpenPGP standard than previous versions of PGP,
5081 so all this does is disable '--throw-keyids' and set
5082 '--escape-from-lines'. All algorithms are allowed except for the
5083 SHA224, SHA384, and SHA512 digests.
5085 '--compliance STRING'
5086 This option can be used instead of one of the options above. Valid
5087 values for STRING are the above option names (without the double
5088 dash) and possibly others as shown when using "help" for STRING.
5090 '--min-rsa-length N'
5091 This option adjusts the compliance mode "de-vs" for stricter key
5092 size requirements. For example, a value of 3000 turns rsa2048 and
5093 dsa2048 keys into non-VS-NfD compliant keys.
5095 '--require-compliance'
5096 To check that data has been encrypted according to the rules of the
5097 current compliance mode, a gpg user needs to evaluate the status
5098 lines. This is allows frontends to handle compliance check in a
5099 more flexible way. However, for scripted use the required
5100 evaluation of the status-line requires quite some effort; this
5101 option can be used instead to make sure that the gpg process exits
5102 with a failure if the compliance rules are not fulfilled. Note
5103 that this option has currently an effect only in "de-vs" mode.
5106 File: gnupg.info, Node: GPG Esoteric Options, Next: Deprecated Options, Prev: Compliance Options, Up: GPG Options
5108 4.2.6 Doing things one usually doesn't want to do
5109 -------------------------------------------------
5113 Don't make any changes (this is not completely implemented).
5116 Changes the behaviour of some commands. This is like '--dry-run'
5117 but different in some cases. The semantic of this option may be
5118 extended in the future. Currently it only skips the actual
5119 decryption pass and therefore enables a fast listing of the
5124 Prompt before overwriting any files.
5126 '--compatibility-flags FLAGS'
5127 Set compatibility flags to work around problems due to
5128 non-compliant keys or data. The FLAGS are given as a comma
5129 separated list of flag names and are OR-ed together. The special
5130 flag "none" clears the list and allows to start over with an empty
5131 list. To get a list of available flags the sole word "help" can be
5134 '--debug-level LEVEL'
5135 Select the debug level for investigating problems. LEVEL may be a
5136 numeric value or by a keyword:
5139 No debugging at all. A value of less than 1 may be used
5140 instead of the keyword.
5142 Some basic debug messages. A value between 1 and 2 may be
5143 used instead of the keyword.
5145 More verbose debug messages. A value between 3 and 5 may be
5146 used instead of the keyword.
5148 Even more detailed messages. A value between 6 and 8 may be
5149 used instead of the keyword.
5151 All of the debug messages you can get. A value greater than 8
5152 may be used instead of the keyword. The creation of hash
5153 tracing files is only enabled if the keyword is used.
5155 How these messages are mapped to the actual debugging flags is not
5156 specified and may change with newer releases of this program. They
5157 are however carefully selected to best aid in debugging.
5160 Set debug flags. All flags are or-ed and FLAGS may be given in C
5161 syntax (e.g. 0x0042) or as a comma separated list of flag names.
5162 To get a list of all supported flags the single word "help" can be
5163 used. This option is only useful for debugging and the behavior
5164 may change at any time without notice.
5167 Set all useful debugging flags.
5170 Set stdout into line buffered mode. This option is only honored
5171 when given on the command line.
5173 '--debug-set-iobuf-size N'
5174 Change the buffer size of the IOBUFs to N kilobyte. Using 0 prints
5175 the current size. Note well: This is a maintainer only option and
5176 may thus be changed or removed at any time without notice.
5178 '--debug-allow-large-chunks'
5179 To facilitate software tests and experiments this option allows to
5180 specify a limit of up to 4 EiB ('--chunk-size 62').
5182 '--debug-ignore-expiration'
5183 This option tries to override certain key expiration dates. It is
5184 only useful for certain regression tests.
5186 '--faked-system-time EPOCH'
5187 This option is only useful for testing; it sets the system time
5188 back or forth to EPOCH which is the number of seconds elapsed since
5189 the year 1970. Alternatively EPOCH may be given as a full ISO time
5190 string (e.g. "20070924T154812").
5192 If you suffix EPOCH with an exclamation mark (!), the system time
5193 will appear to be frozen at the specified time.
5195 '--full-timestrings'
5196 Change the format of printed creation and expiration times from
5197 just the date to the date and time. This is in general not useful
5198 and the same information is anyway available in '--with-colons'
5199 mode. These longer strings are also not well aligned with other
5202 '--enable-progress-filter'
5203 Enable certain PROGRESS status outputs. This option allows
5204 frontends to display a progress indicator while gpg is processing
5205 larger files. There is a slight performance overhead using it.
5208 Write special status strings to the file descriptor N. See the
5209 file DETAILS in the documentation for a listing of them.
5211 '--status-file FILE'
5212 Same as '--status-fd', except the status data is written to file
5216 Write log output to file descriptor N and not to STDERR.
5219 '--logger-file FILE'
5220 Same as '--logger-fd', except the logger data is written to file
5221 FILE. Use 'socket://' to log to s socket.
5224 Prefix all log output with a timestamp even if no log file is used.
5227 Write attribute subpackets to the file descriptor N. This is most
5228 useful for use with '--status-fd', since the status messages are
5229 needed to separate out the various subpackets from the stream
5230 delivered to the file descriptor.
5232 '--attribute-file FILE'
5233 Same as '--attribute-fd', except the attribute data is written to
5238 Use STRING as a comment string in cleartext signatures and ASCII
5239 armored messages or keys (see '--armor'). The default behavior is
5240 not to use a comment string. '--comment' may be repeated multiple
5241 times to get multiple comment strings. '--no-comments' removes all
5242 comments. It is a good idea to keep the length of a single comment
5243 below 60 characters to avoid problems with mail programs wrapping
5244 such lines. Note that comment lines, like all other header lines,
5245 are not protected by the signature.
5249 Force inclusion of the version string in ASCII armored output. If
5250 given once only the name of the program and the major number is
5251 emitted, given twice the minor is also emitted, given thrice the
5252 micro is added, and given four times an operating system
5253 identification is also emitted. '--no-emit-version' (default)
5254 disables the version line.
5256 '--sig-notation {NAME=VALUE}'
5257 '--cert-notation {NAME=VALUE}'
5258 '-N, --set-notation {NAME=VALUE}'
5259 Put the name value pair into the signature as notation data. NAME
5260 must consist only of printable characters or spaces, and must
5261 contain a '@' character in the form keyname@domain.example.com
5262 (substituting the appropriate keyname and domain name, of course).
5263 This is to help prevent pollution of the IETF reserved notation
5264 namespace. The '--expert' flag overrides the '@' check. VALUE may
5265 be any printable string; it will be encoded in UTF-8, so you should
5266 check that your '--display-charset' is set correctly. If you
5267 prefix NAME with an exclamation mark (!), the notation data will be
5268 flagged as critical (rfc4880:5.2.3.16). '--sig-notation' sets a
5269 notation for data signatures. '--cert-notation' sets a notation
5270 for key signatures (certifications). '--set-notation' sets both.
5272 There are special codes that may be used in notation names. "%k"
5273 will be expanded into the key ID of the key being signed, "%K" into
5274 the long key ID of the key being signed, "%f" into the fingerprint
5275 of the key being signed, "%s" into the key ID of the key making the
5276 signature, "%S" into the long key ID of the key making the
5277 signature, "%g" into the fingerprint of the key making the
5278 signature (which might be a subkey), "%p" into the fingerprint of
5279 the primary key of the key making the signature, "%c" into the
5280 signature count from the OpenPGP smartcard, and "%%" results in a
5281 single "%". %k, %K, and %f are only meaningful when making a key
5282 signature (certification), and %c is only meaningful when using the
5285 '--known-notation NAME'
5286 Adds NAME to a list of known critical signature notations. The
5287 effect of this is that gpg will not mark a signature with a
5288 critical signature notation of that name as bad. Note that gpg
5289 already knows by default about a few critical signatures notation
5292 '--sig-policy-url STRING'
5293 '--cert-policy-url STRING'
5294 '--set-policy-url STRING'
5295 Use STRING as a Policy URL for signatures (rfc4880:5.2.3.20). If
5296 you prefix it with an exclamation mark (!), the policy URL packet
5297 will be flagged as critical. '--sig-policy-url' sets a policy url
5298 for data signatures. '--cert-policy-url' sets a policy url for key
5299 signatures (certifications). '--set-policy-url' sets both.
5301 The same %-expandos used for notation data are available here as
5304 '--sig-keyserver-url STRING'
5305 Use STRING as a preferred keyserver URL for data signatures. If
5306 you prefix it with an exclamation mark (!), the keyserver URL
5307 packet will be flagged as critical.
5309 The same %-expandos used for notation data are available here as
5312 '--set-filename STRING'
5313 Use STRING as the filename which is stored inside messages. This
5314 overrides the default, which is to use the actual filename of the
5315 file being encrypted. Using the empty string for STRING
5316 effectively removes the filename from the output.
5318 '--for-your-eyes-only'
5319 '--no-for-your-eyes-only'
5320 Set the 'for your eyes only' flag in the message. This causes
5321 GnuPG to refuse to save the file unless the '--output' option is
5322 given, and PGP to use a "secure viewer" with a claimed
5323 Tempest-resistant font to display the message. This option
5324 overrides '--set-filename'. '--no-for-your-eyes-only' disables
5327 '--use-embedded-filename'
5328 '--no-use-embedded-filename'
5329 Try to create a file with a name as embedded in the data. This can
5330 be a dangerous option as it enables overwriting files. Defaults to
5331 no. Note that the option '--output' overrides this option.
5333 '--cipher-algo NAME'
5334 Use NAME as cipher algorithm. Running the program with the command
5335 '--version' yields a list of supported algorithms. If this is not
5336 used the cipher algorithm is selected from the preferences stored
5337 with the key. In general, you do not want to use this option as it
5338 allows you to violate the OpenPGP standard. The option
5339 '--personal-cipher-preferences' is the safe way to accomplish the
5342 '--digest-algo NAME'
5343 Use NAME as the message digest algorithm. Running the program with
5344 the command '--version' yields a list of supported algorithms. In
5345 general, you do not want to use this option as it allows you to
5346 violate the OpenPGP standard. The option
5347 '--personal-digest-preferences' is the safe way to accomplish the
5350 '--compress-algo NAME'
5351 Use compression algorithm NAME. "zlib" is RFC-1950 ZLIB
5352 compression. "zip" is RFC-1951 ZIP compression which is used by
5353 PGP. "bzip2" is a more modern compression scheme that can compress
5354 some things better than zip or zlib, but at the cost of more memory
5355 used during compression and decompression. "uncompressed" or
5356 "none" disables compression. If this option is not used, the
5357 default behavior is to examine the recipient key preferences to see
5358 which algorithms the recipient supports. If all else fails, ZIP is
5359 used for maximum compatibility.
5361 ZLIB may give better compression results than ZIP, as the
5362 compression window size is not limited to 8k. BZIP2 may give even
5363 better compression results than that, but will use a significantly
5364 larger amount of memory while compressing and decompressing. This
5365 may be significant in low memory situations. Note, however, that
5366 PGP (all versions) only supports ZIP compression. Using any
5367 algorithm other than ZIP or "none" will make the message unreadable
5368 with PGP. In general, you do not want to use this option as it
5369 allows you to violate the OpenPGP standard. The option
5370 '--personal-compress-preferences' is the safe way to accomplish the
5373 '--cert-digest-algo NAME'
5374 Use NAME as the message digest algorithm used when signing a key.
5375 Running the program with the command '--version' yields a list of
5376 supported algorithms. Be aware that if you choose an algorithm
5377 that GnuPG supports but other OpenPGP implementations do not, then
5378 some users will not be able to use the key signatures you make, or
5379 quite possibly your entire key. Note also that a public key
5380 algorithm must be compatible with the specified digest algorithm;
5381 thus selecting an arbitrary digest algorithm may result in error
5382 messages from lower crypto layers or lead to security flaws.
5384 '--disable-cipher-algo NAME'
5385 Never allow the use of NAME as cipher algorithm. The given name
5386 will not be checked so that a later loaded algorithm will still get
5389 '--disable-pubkey-algo NAME'
5390 Never allow the use of NAME as public key algorithm. The given
5391 name will not be checked so that a later loaded algorithm will
5396 Do not put the recipient key IDs into encrypted messages. This
5397 helps to hide the receivers of the message and is a limited
5398 countermeasure against traffic analysis.(1) On the receiving side,
5399 it may slow down the decryption process because all available
5400 secret keys must be tried. '--no-throw-keyids' disables this
5401 option. This option is essentially the same as using
5402 '--hidden-recipient' for all recipients.
5404 '--not-dash-escaped'
5405 This option changes the behavior of cleartext signatures so that
5406 they can be used for patch files. You should not send such an
5407 armored file via email because all spaces and line endings are
5408 hashed too. You can not use this option for data which has 5
5409 dashes at the beginning of a line, patch files don't have this. A
5410 special armor header line tells GnuPG about this cleartext
5413 '--escape-from-lines'
5414 '--no-escape-from-lines'
5415 Because some mailers change lines starting with "From " to ">From "
5416 it is good to handle such lines in a special way when creating
5417 cleartext signatures to prevent the mail system from breaking the
5418 signature. Note that all other PGP versions do it this way too.
5419 Enabled by default. '--no-escape-from-lines' disables this option.
5421 '--passphrase-repeat N'
5422 Specify how many times 'gpg' will request a new passphrase be
5423 repeated. This is useful for helping memorize a passphrase.
5424 Defaults to 1 repetition; can be set to 0 to disable any passphrase
5425 repetition. Note that a N greater than 1 will pop up the pinentry
5426 window N+1 times even if a modern pinentry with two entry fields is
5430 Read the passphrase from file descriptor N. Only the first line
5431 will be read from file descriptor N. If you use 0 for N, the
5432 passphrase will be read from STDIN. This can only be used if only
5433 one passphrase is supplied.
5435 Note that since Version 2.0 this passphrase is only used if the
5436 option '--batch' has also been given. Since Version 2.1 the
5437 '--pinentry-mode' also needs to be set to 'loopback'.
5439 '--passphrase-file FILE'
5440 Read the passphrase from file FILE. Only the first line will be
5441 read from file FILE. This can only be used if only one passphrase
5442 is supplied. Obviously, a passphrase stored in a file is of
5443 questionable security if other users can read this file. Don't use
5444 this option if you can avoid it.
5446 Note that since Version 2.0 this passphrase is only used if the
5447 option '--batch' has also been given. Since Version 2.1 the
5448 '--pinentry-mode' also needs to be set to 'loopback'.
5450 '--passphrase STRING'
5451 Use STRING as the passphrase. This can only be used if only one
5452 passphrase is supplied. Obviously, this is of very questionable
5453 security on a multi-user system. Don't use this option if you can
5456 Note that since Version 2.0 this passphrase is only used if the
5457 option '--batch' has also been given. Since Version 2.1 the
5458 '--pinentry-mode' also needs to be set to 'loopback'.
5460 '--pinentry-mode MODE'
5461 Set the pinentry mode to MODE. Allowed values for MODE are:
5463 Use the default of the agent, which is 'ask'.
5465 Force the use of the Pinentry.
5467 Emulate use of Pinentry's cancel button.
5469 Return a Pinentry error ("No Pinentry").
5471 Redirect Pinentry queries to the caller. Note that in
5472 contrast to Pinentry the user is not prompted again if he
5473 enters a bad password.
5476 Disable the passphrase cache used for symmetrical en- and
5477 decryption. This cache is based on the message specific salt value
5480 '--request-origin ORIGIN'
5481 Tell gpg to assume that the operation ultimately originated at
5482 ORIGIN. Depending on the origin certain restrictions are applied
5483 and the Pinentry may include an extra note on the origin.
5484 Supported values for ORIGIN are: 'local' which is the default,
5485 'remote' to indicate a remote origin or 'browser' for an operation
5486 requested by a web browser.
5489 This is a replacement for the deprecated shared-memory IPC mode.
5490 If this option is enabled, user input on questions is not expected
5491 from the TTY but from the given file descriptor. It should be used
5492 together with '--status-fd'. See the file doc/DETAILS in the
5493 source distribution for details on how to use it.
5495 '--command-file FILE'
5496 Same as '--command-fd', except the commands are read out of file
5499 '--allow-non-selfsigned-uid'
5500 '--no-allow-non-selfsigned-uid'
5501 Allow the import and use of keys with user IDs which are not
5502 self-signed. This is not recommended, as a non self-signed user ID
5503 is trivial to forge. '--no-allow-non-selfsigned-uid' disables.
5505 '--allow-freeform-uid'
5506 Disable all checks on the form of the user ID while generating a
5507 new one. This option should only be used in very special
5508 environments as it does not ensure the de-facto standard format of
5511 '--ignore-time-conflict'
5512 GnuPG normally checks that the timestamps associated with keys and
5513 signatures have plausible values. However, sometimes a signature
5514 seems to be older than the key due to clock problems. This option
5515 makes these checks just a warning. See also '--ignore-valid-from'
5516 for timestamp issues on subkeys.
5518 '--ignore-valid-from'
5519 GnuPG normally does not select and use subkeys created in the
5520 future. This option allows the use of such keys and thus exhibits
5521 the pre-1.0.7 behaviour. You should not use this option unless
5522 there is some clock problem. See also '--ignore-time-conflict' for
5523 timestamp issues with signatures.
5525 '--ignore-crc-error'
5526 The ASCII armor used by OpenPGP is protected by a CRC checksum
5527 against transmission errors. Occasionally the CRC gets mangled
5528 somewhere on the transmission channel but the actual content (which
5529 is protected by the OpenPGP protocol anyway) is still okay. This
5530 option allows GnuPG to ignore CRC errors.
5532 '--ignore-mdc-error'
5533 This option changes a MDC integrity protection failure into a
5534 warning. It is required to decrypt old messages which did not use
5535 an MDC. It may also be useful if a message is partially garbled,
5536 but it is necessary to get as much data as possible out of that
5537 garbled message. Be aware that a missing or failed MDC can be an
5538 indication of an attack. Use with great caution; see also option
5541 '--allow-old-cipher-algos'
5542 Old cipher algorithms like 3DES, IDEA, or CAST5 encrypt data using
5543 blocks of 64 bits; modern algorithms use blocks of 128 bit instead.
5544 To avoid certain attack on these old algorithms it is suggested not
5545 to encrypt more than 150 MiByte using the same key. For this
5546 reason gpg does not allow the use of 64 bit block size algorithms
5547 for encryption unless this option is specified.
5549 '--allow-weak-digest-algos'
5550 Signatures made with known-weak digest algorithms are normally
5551 rejected with an "invalid digest algorithm" message. This option
5552 allows the verification of signatures made with such weak
5553 algorithms. MD5 is the only digest algorithm considered weak by
5554 default. See also '--weak-digest' to reject other digest
5557 '--weak-digest NAME'
5558 Treat the specified digest algorithm as weak. Signatures made over
5559 weak digests algorithms are normally rejected. This option can be
5560 supplied multiple times if multiple algorithms should be considered
5561 weak. See also '--allow-weak-digest-algos' to disable rejection of
5562 weak digests. MD5 is always considered weak, and does not need to
5563 be listed explicitly.
5565 '--allow-weak-key-signatures'
5566 To avoid a minor risk of collision attacks on third-party key
5567 signatures made using SHA-1, those key signatures are considered
5568 invalid. This options allows to override this restriction.
5570 '--override-compliance-check'
5571 This was a temporary introduced option and has no more effect.
5573 '--no-default-keyring'
5574 Do not add the default keyring to the list of keyrings. Note that
5575 GnuPG needs for almost all operations a keyring. Thus if you use
5576 this option and do not provide alternate keyrings via '--keyring',
5577 then GnuPG will still use the default keyring.
5579 Note that if the option 'use-keyboxd' is enabled in 'common.conf',
5580 no keyrings are used at all and keys are all maintained by the
5581 keyboxd process in its own database.
5584 Do not use any keyring at all. This overrides the default and all
5585 options which specify keyrings.
5588 Skip the signature verification step. This may be used to make the
5589 decryption faster if the signature verification is not needed.
5592 Print key listings delimited by colons (like '--with-colons') and
5593 print the public key data.
5597 Same as '--list-keys', but the signatures are listed too. This
5598 command has the same effect as using '--list-keys' with
5599 '--with-sig-list'. Note that in contrast to '--check-signatures'
5600 the key signatures are not verified. This command can be used to
5601 create a list of signing keys missing in the local keyring; for
5604 gpg --list-sigs --with-colons USERID | \
5605 awk -F: '$1=="sig" && $2=="?" {if($13){print $13}else{print $5}}'
5608 Changes the output of the list commands to work faster; this is
5609 achieved by leaving some parts empty. Some applications don't need
5610 the user ID and the trust information given in the listings. By
5611 using this options they can get a faster listing. The exact
5612 behaviour of this option may change in future versions. If you are
5613 missing some information, don't use this option.
5616 This is not for normal use. Use the source to see for what it
5620 This is not for normal use. Use the source to see for what it
5623 '--show-session-key'
5624 Display the session key used for one message. See
5625 '--override-session-key' for the counterpart of this option.
5627 We think that Key Escrow is a Bad Thing; however the user should
5628 have the freedom to decide whether to go to prison or to reveal the
5629 content of one specific message without compromising all messages
5630 ever encrypted for one secret key.
5632 You can also use this option if you receive an encrypted message
5633 which is abusive or offensive, to prove to the administrators of
5634 the messaging system that the ciphertext transmitted corresponds to
5635 an inappropriate plaintext so they can take action against the
5638 '--override-session-key STRING'
5639 '--override-session-key-fd FD'
5640 Don't use the public key but the session key STRING respective the
5641 session key taken from the first line read from file descriptor FD.
5642 The format of this string is the same as the one printed by
5643 '--show-session-key'. This option is normally not used but comes
5644 handy in case someone forces you to reveal the content of an
5645 encrypted message; using this option you can do this without
5646 handing out the secret key. Note that using
5647 '--override-session-key' may reveal the session key to all local
5648 users via the global process table. Often it is useful to combine
5649 this option with '--no-keyring'.
5652 '--no-ask-sig-expire'
5653 When making a data signature, prompt for an expiration time. If
5654 this option is not specified, the expiration time set via
5655 '--default-sig-expire' is used. '--no-ask-sig-expire' disables
5658 '--default-sig-expire'
5659 The default expiration time to use for signature expiration. Valid
5660 values are "0" for no expiration, a number followed by the letter d
5661 (for days), w (for weeks), m (for months), or y (for years) (for
5662 example "2m" for two months, or "5y" for five years), or an
5663 absolute date in the form YYYY-MM-DD. Defaults to "0".
5666 '--no-ask-cert-expire'
5667 When making a key signature, prompt for an expiration time. If
5668 this option is not specified, the expiration time set via
5669 '--default-cert-expire' is used. '--no-ask-cert-expire' disables
5672 '--default-cert-expire'
5673 The default expiration time to use for key signature expiration.
5674 Valid values are "0" for no expiration, a number followed by the
5675 letter d (for days), w (for weeks), m (for months), or y (for
5676 years) (for example "2m" for two months, or "5y" for five years),
5677 or an absolute date in the form YYYY-MM-DD. Defaults to "0".
5679 '--default-new-key-algo STRING'
5680 This option can be used to change the default algorithms for key
5681 generation. The STRING is similar to the arguments required for
5682 the command '--quick-add-key' but slightly different. For example
5683 the current default of '"rsa2048/cert,sign+rsa2048/encr"' (or
5684 '"rsa3072"') can be changed to the value of what we currently call
5685 future default, which is '"ed25519/cert,sign+cv25519/encr"'. You
5686 need to consult the source code to learn the details. Note that
5687 the advanced key generation commands can always be used to specify
5688 a key algorithm directly.
5690 '--no-auto-trust-new-key'
5691 When creating a new key the ownertrust of the new key is set to
5692 ultimate. This option disables this and the user needs to manually
5693 assign an ownertrust value.
5696 This option modifies the behaviour of the commands
5697 '--quick-sign-key', '--quick-lsign-key', and the "sign"
5698 sub-commands of '--edit-key' by forcing the creation of a key
5699 signature, even if one already exists.
5702 This option is intended for use in the global config file to
5703 disallow the use of generate key commands. Those commands will
5704 then fail with the error code for Not Enabled.
5706 '--allow-secret-key-import'
5707 This is an obsolete option and is not used anywhere.
5709 '--allow-multiple-messages'
5710 '--no-allow-multiple-messages'
5711 These are obsolete options; they have no more effect since GnuPG
5714 '--enable-special-filenames'
5715 This option enables a mode in which filenames of the form '-&n',
5716 where n is a non-negative decimal number, refer to the file
5717 descriptor n and not to a file with that name.
5719 '--no-expensive-trust-checks'
5720 Experimental use only.
5722 '--preserve-permissions'
5723 Don't change the permissions of a secret keyring back to user
5724 read/write only. Use this option only if you really know what you
5727 '--default-preference-list STRING'
5728 Set the list of default preferences to STRING. This preference
5729 list is used for new keys and becomes the default for "setpref" in
5730 the '--edit-key' menu.
5732 '--default-keyserver-url NAME'
5733 Set the default keyserver URL to NAME. This keyserver will be used
5734 as the keyserver URL when writing a new self-signature on a key,
5735 which includes key generation and changing preferences.
5738 Display various internal configuration parameters of GnuPG. This
5739 option is intended for external programs that call GnuPG to perform
5740 tasks, and is thus not generally useful. See the file
5741 'doc/DETAILS' in the source distribution for the details of which
5742 configuration items may be listed. '--list-config' is only usable
5743 with '--with-colons' set.
5745 '--list-gcrypt-config'
5746 Display various internal configuration parameters of Libgcrypt.
5749 This command is similar to '--list-config' but in general only
5750 internally used by the 'gpgconf' tool.
5753 This is more or less dummy action. However it parses the
5754 configuration file and returns with failure if the configuration
5755 file would prevent 'gpg' from startup. Thus it may be used to run
5756 a syntax check on the configuration file.
5759 Change the current user to UID which may either be a number or a
5760 name. This can be used from the root account to run gpg for
5761 another user. If UID is not the current UID a standard PATH is set
5762 and the envvar GNUPGHOME is unset. To override the latter the
5763 option '--homedir' can be used. This option has only an effect
5764 when used on the command line. This option has currently no effect
5767 ---------- Footnotes ----------
5769 (1) Using a little social engineering anyone who is able to decrypt
5770 the message can check whether one of the other recipients is the one he
5774 File: gnupg.info, Node: Deprecated Options, Prev: GPG Esoteric Options, Up: GPG Options
5776 4.2.7 Deprecated options
5777 ------------------------
5781 Causes '--list-keys', '--list-signatures', '--list-public-keys',
5782 '--list-secret-keys', and verifying a signature to also display the
5783 photo ID attached to the key, if any. See also '--photo-viewer'.
5784 These options are deprecated. Use '--list-options
5785 [no-]show-photos' and/or '--verify-options [no-]show-photos'
5789 Display the keyring name at the head of key listings to show which
5790 keyring a given key resides on. This option is deprecated: use
5791 '--list-options [no-]show-keyring' instead.
5794 '--no-show-notation'
5795 Show signature notations in the '--list-signatures' or
5796 '--check-signatures' listings as well as when verifying a signature
5797 with a notation in it. These options are deprecated. Use
5798 '--list-options [no-]show-notation' and/or '--verify-options
5799 [no-]show-notation' instead.
5802 '--no-show-policy-url'
5803 Show policy URLs in the '--list-signatures' or '--check-signatures'
5804 listings as well as when verifying a signature with a policy URL in
5805 it. These options are deprecated. Use '--list-options
5806 [no-]show-policy-url' and/or '--verify-options
5807 [no-]show-policy-url' instead.
5809 '--personal-aead-preferences STRING'
5810 This option is deprecated and has no more effect since version
5814 This option is deprecated and has no more effect since version
5818 File: gnupg.info, Node: GPG Configuration, Next: GPG Examples, Prev: GPG Options, Up: Invoking GPG
5820 4.3 Configuration files
5821 =======================
5823 There are a few configuration files to control certain aspects of
5824 'gpg''s operation. Unless noted, they are expected in the current home
5825 directory (*note option --homedir::).
5828 This is the standard configuration file read by 'gpg' on startup.
5829 It may contain any valid long option; the leading two dashes may
5830 not be entered and the option may not be abbreviated. This default
5831 name may be changed on the command line (*note gpg-option
5832 --options::). You should backup this file.
5835 This is an optional configuration file read by 'gpg' on startup.
5836 It may contain options pertaining to all components of GnuPG. Its
5837 current main use is for the "use-keyboxd" option. If the default
5838 home directory '~/.gnupg' does not exist, GnuPG creates this
5839 directory and a 'common.conf' file with "use_keyboxd".
5841 Note that on larger installations, it is useful to put predefined
5842 files into the directory '/usr/local/etc/skel/.gnupg' so that newly
5843 created users start up with a working configuration. For existing users
5844 a small helper script is provided to create these files (*note
5847 For internal purposes 'gpg' creates and maintains a few other files;
5848 They all live in the current home directory (*note option --homedir::).
5849 Only the 'gpg' program may modify these files.
5852 This is the default home directory which is used if neither the
5853 environment variable 'GNUPGHOME' nor the option '--homedir' is
5856 '~/.gnupg/pubring.gpg'
5857 The public keyring using a legacy format. You should backup this
5860 If this file is not available, 'gpg' defaults to the new keybox
5861 format and creates a file 'pubring.kbx' unless that file already
5862 exists in which case that file will also be used for OpenPGP keys.
5864 Note that in the case that both files, 'pubring.gpg' and
5865 'pubring.kbx' exists but the latter has no OpenPGP keys, the legacy
5866 file 'pubring.gpg' will be used. Take care: GnuPG versions before
5867 2.1 will always use the file 'pubring.gpg' because they do not know
5868 about the new keybox format. In the case that you have to use
5869 GnuPG 1.4 to decrypt archived data you should keep this file.
5871 '~/.gnupg/pubring.gpg.lock'
5872 The lock file for the public keyring.
5874 '~/.gnupg/pubring.kbx'
5875 The public keyring using the new keybox format. This file is
5876 shared with 'gpgsm'. You should backup this file. See above for
5877 the relation between this file and it predecessor.
5879 To convert an existing 'pubring.gpg' file to the keybox format, you
5880 first backup the ownertrust values, then rename 'pubring.gpg' to
5881 'publickeys.backup', so it won’t be recognized by any GnuPG
5882 version, run import, and finally restore the ownertrust values:
5885 $ gpg --export-ownertrust >otrust.lst
5886 $ mv pubring.gpg publickeys.backup
5887 $ gpg --import-options restore --import publickeys.backup
5888 $ gpg --import-ownertrust otrust.lst
5890 '~/.gnupg/pubring.kbx.lock'
5891 The lock file for 'pubring.kbx'.
5893 '~/.gnupg/secring.gpg'
5894 The legacy secret keyring as used by GnuPG versions before 2.1. It
5895 is not used by GnuPG 2.1 and later. You may want to keep it in
5896 case you have to use GnuPG 1.4 to decrypt archived data.
5898 '~/.gnupg/secring.gpg.lock'
5899 The lock file for the legacy secret keyring.
5901 '~/.gnupg/.gpg-v21-migrated'
5902 File indicating that a migration to GnuPG 2.1 has been done.
5904 '~/.gnupg/trustdb.gpg'
5905 The trust database. There is no need to backup this file; it is
5906 better to backup the ownertrust values (*note option
5907 --export-ownertrust::).
5909 '~/.gnupg/trustdb.gpg.lock'
5910 The lock file for the trust database.
5912 '~/.gnupg/random_seed'
5913 A file used to preserve the state of the internal random pool.
5915 '~/.gnupg/openpgp-revocs.d/'
5916 This is the directory where gpg stores pre-generated revocation
5917 certificates. The file name corresponds to the OpenPGP fingerprint
5918 of the respective key. It is suggested to backup those
5919 certificates and if the primary private key is not stored on the
5920 disk to move them to an external storage device. Anyone who can
5921 access these files is able to revoke the corresponding key. You
5922 may want to print them out. You should backup all files in this
5923 directory and take care to keep this backup closed away.
5925 Operation is further controlled by a few environment variables:
5928 Used to locate the default home directory.
5931 If set directory used instead of "~/.gnupg".
5934 This variable is obsolete; it was used by GnuPG versions before
5938 This value is passed via gpg-agent to pinentry. It is useful to
5939 convey extra information to a custom pinentry.
5943 Used to size some displays to the full size of the screen.
5946 Apart from its use by GNU, it is used in the W32 version to
5947 override the language selection done through the Registry. If used
5948 and set to a valid and available language name (LANGID), the file
5949 with the translation is loaded from 'GPGDIR/gnupg.nls/LANGID.mo'.
5950 Here GPGDIR is the directory out of which the gpg binary has been
5951 loaded. If it can't be loaded the Registry is tried and as last
5952 resort the native Windows locale system is used.
5955 This variable is only used by the regression test suite as a helper
5956 under operating systems without proper support to figure out the
5957 name of a process' text file.
5959 GNUPG_EXEC_DEBUG_FLAGS
5960 This variable allows to enable diagnostics for process management.
5961 A numeric decimal value is expected. Bit 0 enables general
5962 diagnostics, bit 1 enables certain warnings on Windows.
5964 When calling the gpg-agent component 'gpg' sends a set of environment
5965 variables to gpg-agent. The names of these variables can be listed
5968 gpg-connect-agent 'getinfo std_env_names' /bye | awk '$1=="D" {print $2}'
5971 File: gnupg.info, Node: GPG Examples, Next: Unattended Usage of GPG, Prev: GPG Configuration, Up: Invoking GPG
5976 gpg -se -r 'Bob' 'file'
5977 sign and encrypt for user Bob
5979 gpg -clear-sign 'file'
5980 make a cleartext signature
5983 make a detached signature
5985 gpg -u 0x12345678 -sb 'file'
5986 make a detached signature with the key 0x12345678
5988 gpg -list-keys 'user_ID'
5991 gpg -fingerprint 'user_ID'
5994 gpg -verify 'pgpfile'
5995 gpg -verify 'sigfile' ['datafile']
5996 Verify the signature of the file but do not output the data unless
5997 requested. The second form is used for detached signatures, where
5998 'sigfile' is the detached signature (either ASCII armored or
5999 binary) and 'datafile' are the signed data; if this is not given,
6000 the name of the file holding the signed data is constructed by
6001 cutting off the extension (".asc" or ".sig") of 'sigfile' or by
6002 asking the user for the filename. If the option '--output' is also
6003 used the signed data is written to the file specified by that
6004 option; use '-' to write the signed data to stdout.
6009 The options '--import-filter' and '--export-filter' use expressions with
6010 this syntax (square brackets indicate an optional part and curly braces
6011 a repetition, white space between the elements are allowed):
6013 [lc] {[{flag}] PROPNAME op VALUE [lc]}
6015 The name of a property (PROPNAME) may only consist of letters, digits
6016 and underscores. The description for the filter type describes which
6017 properties are defined. If an undefined property is used it evaluates
6018 to the empty string. Unless otherwise noted, the VALUE must always be
6019 given and may not be the empty string. No quoting is defined for the
6020 value, thus the value may not contain the strings '&&' or '||', which
6021 are used as logical connection operators. The flag '--' can be used to
6022 remove this restriction.
6024 Numerical values are computed as long int; standard C notation
6025 applies. LC is the logical connection operator; either '&&' for a
6026 conjunction or '||' for a disjunction. A conjunction is assumed at the
6027 begin of an expression. Conjunctions have higher precedence than
6028 disjunctions. If VALUE starts with one of the characters used in any OP
6029 a space after the OP is required.
6031 The supported operators (OP) are:
6034 Substring must match.
6037 Substring must not match.
6040 The full string must match.
6043 The full string must not match.
6046 The numerical value must match.
6049 The numerical value must not match.
6052 The numerical value of the field must be LE than the value.
6055 The numerical value of the field must be LT than the value.
6058 The numerical value of the field must be GT than the value.
6061 The numerical value of the field must be GE than the value.
6064 The string value of the field must be less or equal than the value.
6067 The string value of the field must be less than the value.
6070 The string value of the field must be greater than the value.
6073 The string value of the field must be greater or equal than the
6077 True if value is not empty (no value allowed).
6080 True if value is empty (no value allowed).
6083 Alias for "PROPNAME != 0" (no value allowed).
6086 Alias for "PROPNAME == 0" (no value allowed).
6088 Values for FLAG must be space separated. The supported flags are:
6091 VALUE spans to the end of the expression.
6093 The string match in this part is done case-sensitive.
6095 Leading and trailing spaces are not removed from VALUE. The
6096 optional single space after OP is here required.
6098 The filter options concatenate several specifications for a filter of
6099 the same type. For example the four options in this example:
6101 --import-filter keep-uid="uid =~ Alfa"
6102 --import-filter keep-uid="&& uid !~ Test"
6103 --import-filter keep-uid="|| uid =~ Alpha"
6104 --import-filter keep-uid="uid !~ Test"
6106 which is equivalent to
6109 keep-uid="uid =~ Alfa" && uid !~ Test" || uid =~ Alpha" && "uid !~ Test"
6111 imports only the user ids of a key containing the strings "Alfa" or
6112 "Alpha" but not the string "test".
6117 The program returns 0 if there are no severe errors, 1 if at least a
6118 signature was bad, and other error codes for fatal errors.
6120 Note that signature verification requires exact knowledge of what has
6121 been signed and by whom it has been signed. Using only the return code
6122 is thus not an appropriate way to verify a signature by a script.
6123 Either make proper use or the status codes or use the 'gpgv' tool which
6124 has been designed to make signature verification easy for scripts.
6129 Use a good password for your user account and make sure that all
6130 security issues are always fixed on your machine. Also employ diligent
6131 physical protection to your machine. Consider to use a good passphrase
6132 as a last resort protection to your secret key in the case your machine
6133 gets stolen. It is important that your secret key is never leaked.
6134 Using an easy to carry around token or smartcard with the secret key is
6137 If you are going to verify detached signatures, make sure that the
6138 program knows about it; either give both filenames on the command line
6139 or use '-' to specify STDIN.
6141 For scripted or other unattended use of 'gpg' make sure to use the
6142 machine-parseable interface and not the default interface which is
6143 intended for direct use by humans. The machine-parseable interface
6144 provides a stable and well documented API independent of the locale or
6145 future changes of 'gpg'. To enable this interface use the options
6146 '--with-colons' and '--status-fd'. For certain operations the option
6147 '--command-fd' may come handy too. See this man page and the file
6148 'DETAILS' for the specification of the interface. Note that the GnuPG
6149 "info" pages as well as the PDF version of the GnuPG manual features a
6150 chapter on unattended use of GnuPG. As an alternative the library
6151 'GPGME' can be used as a high-level abstraction on top of that
6154 INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS
6155 ********************************************
6157 GnuPG tries to be a very flexible implementation of the OpenPGP
6158 standard. In particular, GnuPG implements many of the optional parts of
6159 the standard, such as the SHA-512 hash, and the ZLIB and BZIP2
6160 compression algorithms. It is important to be aware that not all
6161 OpenPGP programs implement these optional algorithms and that by forcing
6162 their use via the '--cipher-algo', '--digest-algo',
6163 '--cert-digest-algo', or '--compress-algo' options in GnuPG, it is
6164 possible to create a perfectly valid OpenPGP message, but one that
6165 cannot be read by the intended recipient.
6167 There are dozens of variations of OpenPGP programs available, and
6168 each supports a slightly different subset of these optional algorithms.
6169 For example, until recently, no (unhacked) version of PGP supported the
6170 BLOWFISH cipher algorithm. A message using BLOWFISH simply could not be
6171 read by a PGP user. By default, GnuPG uses the standard OpenPGP
6172 preferences system that will always do the right thing and create
6173 messages that are usable by all recipients, regardless of which OpenPGP
6174 program they use. Only override this safe default if you really know
6177 If you absolutely must override the safe default, or if the
6178 preferences on a given key are invalid for some reason, you are far
6179 better off using the '--pgp6', '--pgp7', or '--pgp8' options. These
6180 options are safe as they do not force any particular algorithms in
6181 violation of OpenPGP, but rather reduce the available algorithms to a
6187 On older systems this program should be installed as setuid(root). This
6188 is necessary to lock memory pages. Locking memory pages prevents the
6189 operating system from writing memory pages (which may contain
6190 passphrases or other sensitive material) to disk. If you get no warning
6191 message about insecure memory your operating system supports locking
6192 without being root. The program drops root privileges as soon as locked
6193 memory is allocated.
6195 Note also that some systems (especially laptops) have the ability to
6196 "suspend to disk" (also known as "safe sleep" or "hibernate"). This
6197 writes all memory to disk before going into a low power or even powered
6198 off mode. Unless measures are taken in the operating system to protect
6199 the saved memory, passphrases or other sensitive material may be
6200 recoverable from it later.
6202 Before you report a bug you should first search the mailing list
6203 archives for similar problems and second check whether such a bug has
6204 already been reported to our bug tracker at <https://bugs.gnupg.org>.
6207 File: gnupg.info, Node: Unattended Usage of GPG, Prev: GPG Examples, Up: Invoking GPG
6209 4.5 Unattended Usage
6210 ====================
6212 'gpg' is often used as a backend engine by other software. To help with
6213 this a machine interface has been defined to have an unambiguous way to
6214 do this. The options '--status-fd' and '--batch' are almost always
6219 * Programmatic use of GnuPG:: Programmatic use of GnuPG
6220 * Ephemeral home directories:: Ephemeral home directories
6221 * The quick key manipulation interface:: The quick key manipulation interface
6222 * Unattended GPG key generation:: Unattended key generation
6225 File: gnupg.info, Node: Programmatic use of GnuPG, Next: Ephemeral home directories, Up: Unattended Usage of GPG
6227 4.5.1 Programmatic use of GnuPG
6228 -------------------------------
6230 Please consider using GPGME instead of calling 'gpg' directly. GPGME
6231 offers a stable, backend-independent interface for many cryptographic
6232 operations. It supports OpenPGP and S/MIME, and also allows interaction
6233 with various GnuPG components.
6235 GPGME provides a C-API, and comes with bindings for C++, Qt, and
6236 Python. Bindings for other languages are available.
6239 File: gnupg.info, Node: Ephemeral home directories, Next: The quick key manipulation interface, Prev: Programmatic use of GnuPG, Up: Unattended Usage of GPG
6241 4.5.2 Ephemeral home directories
6242 --------------------------------
6244 Sometimes you want to contain effects of some operation, for example you
6245 want to import a key to inspect it, but you do not want this key to be
6246 added to your keyring. In earlier versions of GnuPG, it was possible to
6247 specify alternate keyring files for both public and secret keys. In
6248 modern GnuPG versions, however, we changed how secret keys are stored in
6249 order to better protect secret key material, and it was not possible to
6250 preserve this interface.
6252 The preferred way to do this is to use ephemeral home directories.
6253 This technique works across all versions of GnuPG.
6255 Create a temporary directory, create (or copy) a configuration that
6256 meets your needs, make 'gpg' use this directory either using the
6257 environment variable GNUPGHOME, or the option '--homedir'. GPGME
6258 supports this too on a per-context basis, by modifying the engine info
6259 of contexts. Now execute whatever operation you like, import and export
6260 key material as necessary. Once finished, you can delete the directory.
6261 All GnuPG backend services that were started will detect this and shut
6265 File: gnupg.info, Node: The quick key manipulation interface, Next: Unattended GPG key generation, Prev: Ephemeral home directories, Up: Unattended Usage of GPG
6267 4.5.3 The quick key manipulation interface
6268 ------------------------------------------
6270 Recent versions of GnuPG have an interface to manipulate keys without
6271 using the interactive command '--edit-key'. This interface was added
6272 mainly for the benefit of GPGME (please consider using GPGME, see the
6273 manual subsection "Programmatic use of GnuPG"). This interface is
6274 described in the subsection "How to manage your keys".
6277 File: gnupg.info, Node: Unattended GPG key generation, Prev: The quick key manipulation interface, Up: Unattended Usage of GPG
6279 4.5.4 Unattended key generation
6280 -------------------------------
6282 The command '--generate-key' may be used along with the option '--batch'
6283 for unattended key generation. This is the most flexible way of
6284 generating keys, but it is also the most complex one. Consider using
6285 the quick key manipulation interface described in the previous
6286 subsection "The quick key manipulation interface".
6288 The parameters for the key are either read from stdin or given as a
6289 file on the command line. The format of the parameter file is as
6290 follows: Text only, line length is limited to about 1000 characters.
6291 UTF-8 encoding must be used to specify non-ASCII characters. Empty
6292 lines are ignored. Leading and trailing white space is ignored. A hash
6293 sign as the first non white space character indicates a comment line.
6294 Control statements are indicated by a leading percent sign, their
6295 arguments are separated by white space from the keyword. Parameters are
6296 specified by a keyword, followed by a colon; arguments are separated by
6297 white space. The first parameter must be 'Key-Type' but control
6298 statements may be placed anywhere. The order of the parameters does not
6299 matter except for 'Key-Type'. The parameters are only used for the
6300 generated keyblock (primary and subkeys); parameters from previous sets
6301 are not used. Some syntax checks may be performed. Key commences when
6302 either the end of the parameter file is reached, the next 'Key-Type'
6303 parameter is encountered, or the control statement '%commit' is
6309 Print TEXT as diagnostic.
6312 Suppress actual key generation (useful for syntax checking).
6315 Perform the key generation. Note that an implicit commit is done
6316 at the next Key-Type parameter.
6319 Do not write the key to the default or commandline given keyring
6320 but to FILENAME. This must be given before the first commit to
6321 take place, duplicate specification of the same filename is
6322 ignored, the last filename before a commit is used. The filename
6323 is used until a new filename is used (at commit points) and all
6324 keys are written to that file. If a new filename is given, this
6325 file is created (and overwrites an existing one).
6327 See the previous subsection "Ephemeral home directories" for a more
6328 robust way to contain side-effects.
6331 This option is a no-op for GnuPG 2.1 and later.
6333 See the previous subsection "Ephemeral home directories".
6337 This option is a no-op since GnuPG version 2.1.
6340 Using this option allows the creation of keys without any
6341 passphrase protection. This option is mainly intended for
6345 If given the keys are created using a faster and a somewhat less
6346 secure random number generator. This option may be used for keys
6347 which are only used for a short time and do not require full
6348 cryptographic strength. It takes only effect if used together with
6349 the control statement '%no-protection'.
6354 Starts a new parameter block by giving the type of the primary key.
6355 The algorithm must be capable of signing. This is a required
6356 parameter. ALGO may either be an OpenPGP algorithm number or a
6357 string with the algorithm name. The special value 'default' may be
6358 used for ALGO to create the default key type; in this case a
6359 'Key-Usage' shall not be given and 'default' also be used for
6363 The requested length of the generated key in bits. The default is
6364 returned by running the command 'gpg --gpgconf-list'. For ECC keys
6365 this parameter is ignored.
6368 The requested elliptic curve of the generated key. This is a
6369 required parameter for ECC keys. It is ignored for non-ECC keys.
6372 This is optional and used to generate a CSR or certificate for an
6373 already existing key. Key-Length will be ignored when given.
6375 Key-Usage: USAGE-LIST
6376 Space or comma delimited list of key usages. Allowed values are
6377 'encrypt', 'sign', and 'auth'. This is used to generate the key
6378 flags. Please make sure that the algorithm is capable of this
6379 usage. Note that OpenPGP requires that all primary keys are
6380 capable of certification, so no matter what usage is given here,
6381 the 'cert' flag will be on. If no 'Key-Usage' is specified and the
6382 'Key-Type' is not 'default', all allowed usages for that particular
6383 algorithm are used; if it is not given but 'default' is used the
6384 usage will be 'sign'.
6387 This generates a secondary key (subkey). Currently only one subkey
6388 can be handled. See also 'Key-Type' above.
6390 Subkey-Length: NBITS
6391 Length of the secondary key (subkey) in bits. The default is
6392 returned by running the command 'gpg --gpgconf-list'.
6395 Key curve for a subkey; similar to 'Key-Curve'.
6397 Subkey-Usage: USAGE-LIST
6398 Key usage lists for a subkey; similar to 'Key-Usage'.
6401 If you want to specify a passphrase for the secret key, enter it
6402 here. Default is to use the Pinentry dialog to ask for a
6406 Name-Comment: COMMENT
6408 The three parts of a user name. Remember to use UTF-8 encoding
6409 here. If you don't give any of them, no user ID is created.
6411 Expire-Date: ISO-DATE|(NUMBER[d|w|m|y])
6412 Set the expiration date for the key (and the subkey). It may
6413 either be entered in ISO date format (e.g. "20000815T145012") or
6414 as number of days, weeks, month or years after the creation date.
6415 The special notation "seconds=N" is also allowed to specify a
6416 number of seconds since creation. Without a letter days are
6417 assumed. Note that there is no check done on the overflow of the
6418 type used by OpenPGP for timestamps. Thus you better make sure
6419 that the given value make sense. Although OpenPGP works with time
6420 intervals, GnuPG uses an absolute value internally and thus the
6421 last year we can represent is 2105.
6423 Creation-Date: ISO-DATE
6424 Set the creation date of the key as stored in the key information
6425 and which is also part of the fingerprint calculation. Either a
6426 date like "1986-04-26" or a full timestamp like "19860426T042640"
6427 may be used. The time is considered to be UTC. The special
6428 notation "seconds=N" may be used to directly specify a the number
6429 of seconds since Epoch (Unix time). If it is not given the current
6433 Set the cipher, hash, and compression preference values for this
6434 key. This expects the same type of string as the sub-command
6435 'setpref' in the '--edit-key' menu.
6437 Revoker: ALGO:FPR [sensitive]
6438 Add a designated revoker to the generated key. Algo is the public
6439 key algorithm of the designated revoker (i.e. RSA=1, DSA=17, etc.)
6440 FPR is the fingerprint of the designated revoker. The optional
6441 'sensitive' flag marks the designated revoker as sensitive
6442 information. Only v4 keys may be designated revokers.
6445 This is an optional parameter that specifies the preferred
6446 keyserver URL for the key.
6449 This is an optional parameter only used with the status lines
6450 KEY_CREATED and KEY_NOT_CREATED. STRING may be up to 100 characters
6451 and should not contain spaces. It is useful for batch key
6452 generation to associate a key parameter block with a status line.
6454 Here is an example on how to create a key in an ephemeral home
6456 $ export GNUPGHOME="$(mktemp -d)"
6458 %echo Generating a basic OpenPGP key
6463 Name-Real: Joe Tester
6464 Name-Comment: with stupid passphrase
6465 Name-Email: joe@foo.bar
6468 # Do a commit here, so that we can later print "done" :-)
6472 $ gpg --batch --generate-key foo
6474 $ gpg --list-secret-keys
6475 /tmp/tmp.0NQxB74PEf/pubring.kbx
6476 -------------------------------
6477 sec dsa1024 2016-12-16 [SCA]
6478 768E895903FC1C44045C8CB95EEBDB71E9E849D0
6479 uid [ultimate] Joe Tester (with stupid passphrase) <joe@foo.bar>
6480 ssb elg1024 2016-12-16 [E]
6482 If you want to create a key with the default algorithms you would use
6484 %echo Generating a default key
6486 Subkey-Type: default
6487 Name-Real: Joe Tester
6488 Name-Comment: with stupid passphrase
6489 Name-Email: joe@foo.bar
6492 # Do a commit here, so that we can later print "done" :-)
6497 File: gnupg.info, Node: Invoking GPGSM, Next: Invoking SCDAEMON, Prev: Invoking GPG, Up: Top
6502 'gpgsm' is a tool similar to 'gpg' to provide digital encryption and
6503 signing services on X.509 certificates and the CMS protocol. It is
6504 mainly used as a backend for S/MIME mail processing. 'gpgsm' includes a
6505 full featured certificate management and complies with all rules defined
6506 for the German Sphinx project.
6508 *Note Option Index::, for an index to 'GPGSM''s commands and options.
6512 * GPGSM Commands:: List of all commands.
6513 * GPGSM Options:: List of all options.
6514 * GPGSM Configuration:: Configuration files.
6515 * GPGSM Examples:: Some usage examples.
6517 Developer information:
6518 * Unattended Usage:: Using 'gpgsm' from other programs.
6519 * GPGSM Protocol:: The protocol the server mode uses.
6522 File: gnupg.info, Node: GPGSM Commands, Next: GPGSM Options, Up: Invoking GPGSM
6527 Commands are not distinguished from options except for the fact that
6528 only one command is allowed.
6532 * General GPGSM Commands:: Commands not specific to the functionality.
6533 * Operational GPGSM Commands:: Commands to select the type of operation.
6534 * Certificate Management:: How to manage certificates.
6537 File: gnupg.info, Node: General GPGSM Commands, Next: Operational GPGSM Commands, Up: GPGSM Commands
6539 5.1.1 Commands not specific to the function
6540 -------------------------------------------
6543 Print the program version and licensing information. Note that you
6544 cannot abbreviate this command.
6547 Print a usage message summarizing the most useful command-line
6548 options. Note that you cannot abbreviate this command.
6551 Print warranty information. Note that you cannot abbreviate this
6555 Print a list of all available options and commands. Note that you
6556 cannot abbreviate this command.
6559 File: gnupg.info, Node: Operational GPGSM Commands, Next: Certificate Management, Prev: General GPGSM Commands, Up: GPGSM Commands
6561 5.1.2 Commands to select the type of operation
6562 ----------------------------------------------
6565 Perform an encryption. The keys the data is encrypted to must be
6566 set using the option '--recipient'.
6569 Perform a decryption; the type of input is automatically
6570 determined. It may either be in binary form or PEM encoded;
6571 automatic determination of base-64 encoding is not done.
6574 Create a digital signature. The key used is either the fist one
6575 found in the keybox or those set with the '--local-user' option.
6578 Check a signature file for validity. Depending on the arguments a
6579 detached signature may also be checked.
6582 Run in server mode and wait for commands on the 'stdin'.
6584 '--call-dirmngr COMMAND [ARGS]'
6585 Behave as a Dirmngr client issuing the request COMMAND with the
6586 optional list of ARGS. The output of the Dirmngr is printed
6587 stdout. Please note that file names given as arguments should have
6588 an absolute file name (i.e. commencing with '/') because they are
6589 passed verbatim to the Dirmngr and the working directory of the
6590 Dirmngr might not be the same as the one of this client. Currently
6591 it is not possible to pass data via stdin to the Dirmngr. COMMAND
6592 should not contain spaces.
6594 This is command is required for certain maintaining tasks of the
6595 dirmngr where a dirmngr must be able to call back to 'gpgsm'. See
6596 the Dirmngr manual for details.
6598 '--call-protect-tool ARGUMENTS'
6599 Certain maintenance operations are done by an external program call
6600 'gpg-protect-tool'; this is usually not installed in a directory
6601 listed in the PATH variable. This command provides a simple
6602 wrapper to access this tool. ARGUMENTS are passed verbatim to this
6603 command; use '--help' to get a list of supported operations.
6606 File: gnupg.info, Node: Certificate Management, Prev: Operational GPGSM Commands, Up: GPGSM Commands
6608 5.1.3 How to manage the certificates and keys
6609 ---------------------------------------------
6613 This command allows the creation of a certificate signing request
6614 or a self-signed certificate. It is commonly used along with the
6615 '--output' option to save the created CSR or certificate into a
6616 file. If used with the '--batch' a parameter file is used to
6617 create the CSR or certificate and it is further possible to create
6618 non-self-signed certificates.
6622 List all available certificates stored in the local key database.
6623 Note that the displayed data might be reformatted for better human
6624 readability and illegal characters are replaced by safe
6627 '--list-secret-keys'
6629 List all available certificates for which a corresponding a secret
6632 '--list-external-keys PATTERN'
6633 List certificates matching PATTERN using an external server. This
6634 utilizes the 'dirmngr' service.
6637 Same as '--list-keys' but also prints all keys making up the chain.
6641 List all available certificates stored in the local key database
6642 using a format useful mainly for debugging.
6645 Same as '--dump-keys' but also prints all keys making up the chain.
6647 '--dump-secret-keys'
6648 List all available certificates for which a corresponding a secret
6649 key is available using a format useful mainly for debugging.
6651 '--dump-external-keys PATTERN'
6652 List certificates matching PATTERN using an external server. This
6653 utilizes the 'dirmngr' service. It uses a format useful mainly for
6656 '--show-certs [FILES]'
6657 This command takes certificate files as input and prints
6658 information about them in the same format as '--dump-cert' does.
6659 Each file may either contain a single binary certificate or several
6660 PEM encoded certificates. If no files are given, the input is
6663 Please note that the listing format may be changed in future
6664 releases and that the option '--with-colons' has currently no
6667 '--keydb-clear-some-cert-flags'
6668 This is a debugging aid to reset certain flags in the key database
6669 which are used to cache certain certificate statuses. It is
6670 especially useful if a bad CRL or a weird running OCSP responder
6671 did accidentally revoke certificate. There is no security issue
6672 with this command because 'gpgsm' always make sure that the
6673 validity of a certificate is checked right before it is used.
6675 '--delete-keys PATTERN'
6676 Delete the keys matching PATTERN. Note that there is no command to
6677 delete the secret part of the key directly. In case you need to do
6678 this, you should run the command 'gpgsm --dump-secret-keys KEYID'
6679 before you delete the key, copy the string of hex-digits in the
6680 "keygrip" line and delete the file consisting of these hex-digits
6681 and the suffix '.key' from the 'private-keys-v1.d' directory below
6682 our GnuPG home directory (usually '~/.gnupg').
6684 '--export [PATTERN]'
6685 Export all certificates stored in the Keybox or those specified by
6686 the optional PATTERN. Those pattern consist of a list of user ids
6687 (*note how-to-specify-a-user-id::). When used along with the
6688 '--armor' option a few informational lines are prepended before
6689 each block. There is one limitation: As there is no commonly
6690 agreed upon way to pack more than one certificate into an ASN.1
6691 structure, the binary export (i.e. without using 'armor') works
6692 only for the export of one certificate. Thus it is required to
6693 specify a PATTERN which yields exactly one certificate. Ephemeral
6694 certificate are only exported if all PATTERN are given as
6695 fingerprints or keygrips.
6697 '--export-secret-key-p12 KEY-ID'
6698 Export the private key and the certificate identified by KEY-ID
6699 using the PKCS#12 format. When used with the '--armor' option a
6700 few informational lines are prepended to the output. Note, that
6701 the PKCS#12 format is not very secure and proper transport security
6702 should be used to convey the exported key. (*Note option
6705 '--export-secret-key-p8 KEY-ID'
6706 '--export-secret-key-raw KEY-ID'
6707 Export the private key of the certificate identified by KEY-ID with
6708 any encryption stripped. The '...-raw' command exports in PKCS#1
6709 format; the '...-p8' command exports in PKCS#8 format. When used
6710 with the '--armor' option a few informational lines are prepended
6711 to the output. These commands are useful to prepare a key for use
6715 Import the certificates from the PEM or binary encoded files as
6716 well as from signed-only messages. This command may also be used
6717 to import a secret key from a PKCS#12 file.
6720 Read information about the private keys from the smartcard and
6721 import the certificates from there. This command utilizes the
6722 'gpg-agent' and in turn the 'scdaemon'.
6724 '--change-passphrase USER_ID'
6726 Change the passphrase of the private key belonging to the
6727 certificate specified as USER_ID. Note, that changing the
6728 passphrase/PIN of a smartcard is not yet supported.
6731 File: gnupg.info, Node: GPGSM Options, Next: GPGSM Configuration, Prev: GPGSM Commands, Up: Invoking GPGSM
6736 'GPGSM' features a bunch of options to control the exact behaviour and
6737 to change the default configuration.
6741 * Configuration Options:: How to change the configuration.
6742 * Certificate Options:: Certificate related options.
6743 * Input and Output:: Input and Output.
6744 * CMS Options:: How to change how the CMS is created.
6745 * Esoteric Options:: Doing things one usually do not want to do.
6748 File: gnupg.info, Node: Configuration Options, Next: Certificate Options, Up: GPGSM Options
6750 5.2.1 How to change the configuration
6751 -------------------------------------
6753 These options are used to change the configuration and are usually found
6757 Reads configuration from FILE instead of from the default per-user
6758 configuration file. The default configuration file is named
6759 'gpgsm.conf' and expected in the '.gnupg' directory directly below
6760 the home directory of the user.
6763 Set the name of the home directory to DIR. If this option is not
6764 used, the home directory defaults to '~/.gnupg'. It is only
6765 recognized when given on the command line. It also overrides any
6766 home directory stated through the environment variable 'GNUPGHOME'
6767 or (on Windows systems) by means of the Registry entry
6768 HKCU\SOFTWARE\GNU\GNUPG:HOMEDIR.
6770 On Windows systems it is possible to install GnuPG as a portable
6771 application. In this case only this command line option is
6772 considered, all other ways to set a home directory are ignored.
6774 To install GnuPG as a portable application under Windows, create an
6775 empty file named 'gpgconf.ctl' in the same directory as the tool
6776 'gpgconf.exe'. The root of the installation is then that
6777 directory; or, if 'gpgconf.exe' has been installed directly below a
6778 directory named 'bin', its parent directory. You also need to make
6779 sure that the following directories exist and are writable:
6780 'ROOT/home' for the GnuPG home and 'ROOT/usr/local/var/cache/gnupg'
6781 for internal cache files.
6785 Outputs additional information while running. You can increase the
6786 verbosity by giving several verbose commands to 'gpgsm', such as
6789 '--keyserver STRING'
6790 This is a deprecated option. It was used to add an LDAP server to
6791 use for X.509 certificate and CRL lookup. The alias '--ldapserver'
6792 existed from version 2.2.28 to 2.2.33 and 2.3.2 to 2.3.4 but is now
6795 LDAP servers must be given in the configuration for 'dirmngr'.
6797 '--policy-file FILENAME'
6798 Change the default name of the policy file to FILENAME. The
6799 default name is 'policies.txt'.
6801 '--agent-program FILE'
6802 Specify an agent program to be used for secret key operations. The
6803 default value is determined by running the command 'gpgconf'. Note
6804 that the pipe symbol ('|') is used for a regression test suite hack
6805 and may thus not be used in the file name.
6807 '--dirmngr-program FILE'
6808 Specify a dirmngr program to be used for CRL checks. The default
6809 value is '/usr/local/bin/dirmngr'.
6811 '--prefer-system-dirmngr'
6812 This option is obsolete and ignored.
6815 Entirely disable the use of the Dirmngr.
6818 Do not start the gpg-agent or the dirmngr if it has not yet been
6819 started and its service is required. This option is mostly useful
6820 on machines where the connection to gpg-agent has been redirected
6821 to another machines. If dirmngr is required on the remote machine,
6822 it may be started manually using 'gpgconf --launch dirmngr'.
6824 '--no-secmem-warning'
6825 Do not print a warning when the so called "secure memory" cannot be
6829 When running in server mode, append all logging output to FILE.
6830 Use 'socket://' to log to socket.
6833 Prefix all log output with a timestamp even if no log file is used.
6836 File: gnupg.info, Node: Certificate Options, Next: Input and Output, Prev: Configuration Options, Up: GPGSM Options
6838 5.2.2 Certificate related options
6839 ---------------------------------
6841 '--enable-policy-checks'
6842 '--disable-policy-checks'
6843 By default policy checks are enabled. These options may be used to
6846 '--enable-crl-checks'
6847 '--disable-crl-checks'
6848 By default the CRL checks are enabled and the DirMngr is used to
6849 check for revoked certificates. The disable option is most useful
6850 with an off-line network connection to suppress this check and also
6851 to avoid that new certificates introduce a web bug by including a
6852 certificate specific CRL DP. The disable option also disables an
6853 issuer certificate lookup via the authorityInfoAccess property of
6854 the certificate; the '--enable-issuer-key-retrieve' can be used to
6855 make use of that property anyway.
6857 '--enable-trusted-cert-crl-check'
6858 '--disable-trusted-cert-crl-check'
6859 By default the CRL for trusted root certificates are checked like
6860 for any other certificates. This allows a CA to revoke its own
6861 certificates voluntary without the need of putting all ever issued
6862 certificates into a CRL. The disable option may be used to switch
6863 this extra check off. Due to the caching done by the Dirmngr,
6864 there will not be any noticeable performance gain. Note, that this
6865 also disables possible OCSP checks for trusted root certificates.
6866 A more specific way of disabling this check is by adding the
6867 "relax" keyword to the root CA line of the 'trustlist.txt'
6869 '--force-crl-refresh'
6870 Tell the dirmngr to reload the CRL for each request. For better
6871 performance, the dirmngr will actually optimize this by suppressing
6872 the loading for short time intervals (e.g. 30 minutes). This
6873 option is useful to make sure that a fresh CRL is available for
6874 certificates hold in the keybox. The suggested way of doing this
6875 is by using it along with the option '--with-validation' for a key
6876 listing command. This option should not be used in a configuration
6879 '--enable-issuer-based-crl-check'
6880 Run a CRL check even for certificates which do not have any CRL
6881 distribution point. This requires that a suitable LDAP server has
6882 been configured in Dirmngr and that the CRL can be found using the
6883 issuer. This option reverts to what GnuPG did up to version
6884 2.2.20. This option is in general not useful.
6888 By default OCSP checks are disabled. The enable option may be used
6889 to enable OCSP checks via Dirmngr. If CRL checks are also enabled,
6890 CRLs will be used as a fallback if for some reason an OCSP request
6891 will not succeed. Note, that you have to allow OCSP requests in
6892 Dirmngr's configuration too (option '--allow-ocsp') and configure
6893 Dirmngr properly. If you do not do so you will get the error code
6896 '--auto-issuer-key-retrieve'
6897 If a required certificate is missing while validating the chain of
6898 certificates, try to load that certificate from an external
6899 location. This usually means that Dirmngr is employed to search
6900 for the certificate. Note that this option makes a "web bug" like
6901 behavior possible. LDAP server operators can see which keys you
6902 request, so by sending you a message signed by a brand new key
6903 (which you naturally will not have on your local keybox), the
6904 operator can tell both your IP address and the time when you
6905 verified the signature. Note that if CRL checking is not disabled
6906 issuer certificates are retrieved in any case using the caIssuers
6907 authorityInfoAccess method.
6909 '--validation-model NAME'
6910 This option changes the default validation model. The only
6911 possible values are "shell" (which is the default), "chain" which
6912 forces the use of the chain model and "steed" for a new simplified
6913 model. The chain model is also used if an option in the
6914 'trustlist.txt' or an attribute of the certificate requests it.
6915 However the standard model (shell) is in that case always tried
6918 '--ignore-cert-extension OID'
6919 Add OID to the list of ignored certificate extensions. The OID is
6920 expected to be in dotted decimal form, like '2.5.29.3'. This
6921 option may be used more than once. Critical flagged certificate
6922 extensions matching one of the OIDs in the list are treated as if
6923 they are actually handled and thus the certificate will not be
6924 rejected due to an unknown critical extension. Use this option
6925 with care because extensions are usually flagged as critical for a
6929 File: gnupg.info, Node: Input and Output, Next: CMS Options, Prev: Certificate Options, Up: GPGSM Options
6931 5.2.3 Input and Output
6932 ----------------------
6936 Create PEM encoded output. Default is binary output.
6939 Create Base-64 encoded output; i.e. PEM without the header lines.
6942 Assume the input data is PEM encoded. Default is to autodetect the
6943 encoding but this is may fail.
6946 Assume the input data is plain base-64 encoded.
6949 Assume the input data is binary encoded.
6951 '--input-size-hint N'
6952 This option can be used to tell GPGSM the size of the input data in
6953 bytes. N must be a positive base-10 number. It is used by the
6954 '--status-fd' line "PROGRESS" to provide a value for "total" if
6955 that is not available by other means.
6957 '--p12-charset NAME'
6958 'gpgsm' uses the UTF-8 encoding when encoding passphrases for
6959 PKCS#12 files. This option may be used to force the passphrase to
6960 be encoded in the specified encoding NAME. This is useful if the
6961 application used to import the key uses a different encoding and
6962 thus will not be able to import a file generated by 'gpgsm'.
6963 Commonly used values for NAME are 'Latin1' and 'CP850'. Note that
6964 'gpgsm' itself automagically imports any file with a passphrase
6965 encoded to the most commonly used encodings.
6967 '--default-key USER_ID'
6968 Use USER_ID as the standard key for signing. This key is used if
6969 no other key has been defined as a signing key. Note, that the
6970 first '--local-users' option also sets this key if it has not yet
6971 been set; however '--default-key' always overrides this.
6973 '--local-user USER_ID'
6975 Set the user(s) to be used for signing. The default is the first
6976 secret key found in the database.
6980 Encrypt to the user id NAME. There are several ways a user id may
6981 be given (*note how-to-specify-a-user-id::).
6985 Write output to FILE. The default is to write it to stdout.
6988 Displays extra information with the '--list-keys' commands.
6989 Especially a line tagged 'grp' is printed which tells you the
6990 keygrip of a key. This string is for example used as the file name
6991 of the secret key. Implies '--with-colons'.
6994 When doing a key listing, do a full validation check for each key
6995 and print the result. This is usually a slow operation because it
6996 requires a CRL lookup and other operations.
6998 When used along with '--import', a validation of the certificate to
6999 import is done and only imported if it succeeds the test. Note
7000 that this does not affect an already available certificate in the
7001 DB. This option is therefore useful to simply verify a certificate.
7003 '--with-md5-fingerprint'
7004 For standard key listings, also print the MD5 fingerprint of the
7008 Include the keygrip in standard key listings. Note that the
7009 keygrip is always listed in '--with-colons' mode.
7012 Include info about the presence of a secret key in public key
7013 listings done with '--with-colons'.
7016 By default gpgsm prints distinguished names (DNs) like the Issuer
7017 or Subject in a more readable format (e.g. using a well defined
7018 order of the parts). However, this format can't be used as input
7019 strings. This option reverts printing to standard RFC-2253 format
7020 and thus avoids the need to use -dump-cert or -with-colons to get