summaryrefslogtreecommitdiffstats
path: root/doc/gnupg.info-1
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--doc/gnupg.info-17119
1 files changed, 7119 insertions, 0 deletions
diff --git a/doc/gnupg.info-1 b/doc/gnupg.info-1
new file mode 100644
index 0000000..fe1fd51
--- /dev/null
+++ b/doc/gnupg.info-1
@@ -0,0 +1,7119 @@
+This is gnupg.info, produced by makeinfo version 6.5 from gnupg.texi.
+
+This is the 'The GNU Privacy Guard Manual' (version 2.2.26-beta25,
+December 2020).
+
+ (C) 2002, 2004, 2005, 2006, 2007, 2010 Free Software Foundation, Inc.
+(C) 2013, 2014, 2015 Werner Koch.
+(C) 2015, 2016, 2017 g10 Code GmbH.
+
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the GNU General Public License as
+ published by the Free Software Foundation; either version 3 of the
+ License, or (at your option) any later version. The text of the
+ license can be found in the section entitled "Copying".
+INFO-DIR-SECTION GNU Utilities
+START-INFO-DIR-ENTRY
+* gpg2: (gnupg). OpenPGP encryption and signing tool.
+* gpgsm: (gnupg). S/MIME encryption and signing tool.
+* gpg-agent: (gnupg). The secret key daemon.
+* dirmngr: (gnupg). X.509 CRL and OCSP server.
+* dirmngr-client: (gnupg). X.509 CRL and OCSP client.
+END-INFO-DIR-ENTRY
+
+
+File: gnupg.info, Node: Top, Next: Installation, Up: (dir)
+
+Using the GNU Privacy Guard
+***************************
+
+This is the 'The GNU Privacy Guard Manual' (version 2.2.26-beta25,
+December 2020).
+
+ (C) 2002, 2004, 2005, 2006, 2007, 2010 Free Software Foundation, Inc.
+(C) 2013, 2014, 2015 Werner Koch.
+(C) 2015, 2016, 2017 g10 Code GmbH.
+
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the GNU General Public License as
+ published by the Free Software Foundation; either version 3 of the
+ License, or (at your option) any later version. The text of the
+ license can be found in the section entitled "Copying".
+
+ This manual documents how to use the GNU Privacy Guard system as well
+as the administration and the architecture.
+
+* Menu:
+
+* Installation:: A short installation guide.
+
+* Invoking GPG-AGENT:: How to launch the secret key daemon.
+* Invoking DIRMNGR:: How to launch the CRL and OCSP daemon.
+* Invoking GPG:: Using the OpenPGP protocol.
+* Invoking GPGSM:: Using the S/MIME protocol.
+* Invoking SCDAEMON:: How to handle Smartcards.
+* Specify a User ID:: How to Specify a User Id.
+* Trust Values:: How GnuPG displays trust values.
+
+* Helper Tools:: Description of small helper tools
+* Web Key Service:: Tools for the Web Key Service
+
+* Howtos:: How to do certain things.
+* System Notes:: Notes pertaining to certain OSes.
+* Debugging:: How to solve problems
+
+* Copying:: GNU General Public License says
+ how you can copy and share GnuPG
+* Contributors:: People who have contributed to GnuPG.
+
+* Glossary:: Short description of terms used.
+* Option Index:: Index to command line options.
+* Environment Index:: Index to environment variables and files.
+* Index:: Index of concepts and symbol names.
+
+
+File: gnupg.info, Node: Installation, Next: Invoking GPG-AGENT, Prev: Top, Up: Top
+
+1 A short installation guide
+****************************
+
+Unfortunately the installation guide has not been finished in time.
+Instead of delaying the release of GnuPG 2.0 even further, I decided to
+release without that guide. The chapter on gpg-agent and gpgsm do
+include brief information on how to set up the whole thing. Please
+watch the GnuPG website for updates of the documentation. In the
+meantime you may search the GnuPG mailing list archives or ask on the
+gnupg-users mailing list for advise on how to solve problems or how to
+get that whole thing up and running.
+
+ ** Building the software
+
+ Building the software is described in the file 'INSTALL'. Given that
+you are already reading this documentation we can only give some extra
+hints.
+
+ To comply with the rules on GNU systems you should have build time
+configured 'gnupg' using:
+
+ ./configure --sysconfdir=/etc --localstatedir=/var
+
+ This is to make sure that system wide configuration files are
+searched in the directory '/etc' and variable data below '/var'; the
+default would be to also install them below '/usr/local' where the
+binaries get installed. If you selected to use the '--prefix=/' you
+obviously don't need those option as they are the default then.
+
+ ** Notes on setting a root CA key to trusted
+
+ X.509 is based on a hierarchical key infrastructure. At the root of
+the tree a trusted anchor (root certificate) is required. There are
+usually no other means of verifying whether this root certificate is
+trustworthy than looking it up in a list. GnuPG uses a file
+('trustlist.txt') to keep track of all root certificates it knows about.
+There are 3 ways to get certificates into this list:
+
+ * Use the list which comes with GnuPG. However this list only
+ contains a few root certificates. Most installations will need
+ more.
+
+ * Let 'gpgsm' ask you whether you want to insert a new root
+ certificate. This feature is enabled by default; you may disable
+ it using the option 'no-allow-mark-trusted' into 'gpg-agent.conf'.
+
+ * Manually maintain the list of trusted root certificates. For a
+ multi user installation this can be done once for all users on a
+ machine. Specific changes on a per-user base are also possible.
+
+
+File: gnupg.info, Node: Invoking GPG-AGENT, Next: Invoking DIRMNGR, Prev: Installation, Up: Top
+
+2 Invoking GPG-AGENT
+********************
+
+'gpg-agent' is a daemon to manage secret (private) keys independently
+from any protocol. It is used as a backend for 'gpg' and 'gpgsm' as
+well as for a couple of other utilities.
+
+ The agent is automatically started on demand by 'gpg', 'gpgsm',
+'gpgconf', or 'gpg-connect-agent'. Thus there is no reason to start it
+manually. In case you want to use the included Secure Shell Agent you
+may start the agent using:
+
+ gpg-connect-agent /bye
+
+If you want to manually terminate the currently-running agent, you can
+safely do so with:
+
+ gpgconf --kill gpg-agent
+
+You should always add the following lines to your '.bashrc' or whatever
+initialization file is used for all shell invocations:
+
+ GPG_TTY=$(tty)
+ export GPG_TTY
+
+It is important that this environment variable always reflects the
+output of the 'tty' command. For W32 systems this option is not
+required.
+
+ Please make sure that a proper pinentry program has been installed
+under the default filename (which is system dependent) or use the option
+'pinentry-program' to specify the full name of that program. It is
+often useful to install a symbolic link from the actual used pinentry
+(e.g. '/usr/local/bin/pinentry-gtk') to the expected one (e.g.
+'/usr/local/bin/pinentry').
+
+*Note Option Index::, for an index to 'GPG-AGENT''s commands and
+options.
+
+* Menu:
+
+* Agent Commands:: List of all commands.
+* Agent Options:: List of all options.
+* Agent Configuration:: Configuration files.
+* Agent Signals:: Use of some signals.
+* Agent Examples:: Some usage examples.
+* Agent Protocol:: The protocol the agent uses.
+
+
+File: gnupg.info, Node: Agent Commands, Next: Agent Options, Up: Invoking GPG-AGENT
+
+2.1 Commands
+============
+
+Commands are not distinguished from options except for the fact that
+only one command is allowed.
+
+'--version'
+ Print the program version and licensing information. Note that you
+ cannot abbreviate this command.
+
+'--help'
+'-h'
+ Print a usage message summarizing the most useful command-line
+ options. Note that you cannot abbreviate this command.
+
+'--dump-options'
+ Print a list of all available options and commands. Note that you
+ cannot abbreviate this command.
+
+'--server'
+ Run in server mode and wait for commands on the 'stdin'. The
+ default mode is to create a socket and listen for commands there.
+
+'--daemon [COMMAND LINE]'
+ Start the gpg-agent as a daemon; that is, detach it from the
+ console and run it in the background.
+
+ As an alternative you may create a new process as a child of
+ gpg-agent: 'gpg-agent --daemon /bin/sh'. This way you get a new
+ shell with the environment setup properly; after you exit from this
+ shell, gpg-agent terminates within a few seconds.
+
+'--supervised'
+ Run in the foreground, sending logs by default to stderr, and
+ listening on provided file descriptors, which must already be bound
+ to listening sockets. This command is useful when running under
+ systemd or other similar process supervision schemes. This option
+ is not supported on Windows.
+
+ In -supervised mode, different file descriptors can be provided for
+ use as different socket types (e.g. ssh, extra) as long as they
+ are identified in the environment variable 'LISTEN_FDNAMES' (see
+ sd_listen_fds(3) on some Linux distributions for more information
+ on this convention).
+
+
+File: gnupg.info, Node: Agent Options, Next: Agent Configuration, Prev: Agent Commands, Up: Invoking GPG-AGENT
+
+2.2 Option Summary
+==================
+
+Options may either be used on the command line or, after stripping off
+the two leading dashes, in the configuration file.
+
+'--options FILE'
+ Reads configuration from FILE instead of from the default per-user
+ configuration file. The default configuration file is named
+ 'gpg-agent.conf' and expected in the '.gnupg' directory directly
+ below the home directory of the user. This option is ignored if
+ used in an options file.
+
+'--homedir DIR'
+ Set the name of the home directory to DIR. If this option is not
+ used, the home directory defaults to '~/.gnupg'. It is only
+ recognized when given on the command line. It also overrides any
+ home directory stated through the environment variable 'GNUPGHOME'
+ or (on Windows systems) by means of the Registry entry
+ HKCU\SOFTWARE\GNU\GNUPG:HOMEDIR.
+
+ On Windows systems it is possible to install GnuPG as a portable
+ application. In this case only this command line option is
+ considered, all other ways to set a home directory are ignored.
+
+ To install GnuPG as a portable application under Windows, create an
+ empty file named 'gpgconf.ctl' in the same directory as the tool
+ 'gpgconf.exe'. The root of the installation is then that
+ directory; or, if 'gpgconf.exe' has been installed directly below a
+ directory named 'bin', its parent directory. You also need to make
+ sure that the following directories exist and are writable:
+ 'ROOT/home' for the GnuPG home and 'ROOT/usr/local/var/cache/gnupg'
+ for internal cache files.
+
+'-v'
+'--verbose'
+ Outputs additional information while running. You can increase the
+ verbosity by giving several verbose commands to 'gpg-agent', such
+ as '-vv'.
+
+'-q'
+'--quiet'
+ Try to be as quiet as possible.
+
+'--batch'
+ Don't invoke a pinentry or do any other thing requiring human
+ interaction.
+
+'--faked-system-time EPOCH'
+ This option is only useful for testing; it sets the system time
+ back or forth to EPOCH which is the number of seconds elapsed since
+ the year 1970.
+
+'--debug-level LEVEL'
+ Select the debug level for investigating problems. LEVEL may be a
+ numeric value or a keyword:
+
+ 'none'
+ No debugging at all. A value of less than 1 may be used
+ instead of the keyword.
+ 'basic'
+ Some basic debug messages. A value between 1 and 2 may be
+ used instead of the keyword.
+ 'advanced'
+ More verbose debug messages. A value between 3 and 5 may be
+ used instead of the keyword.
+ 'expert'
+ Even more detailed messages. A value between 6 and 8 may be
+ used instead of the keyword.
+ 'guru'
+ All of the debug messages you can get. A value greater than 8
+ may be used instead of the keyword. The creation of hash
+ tracing files is only enabled if the keyword is used.
+
+ How these messages are mapped to the actual debugging flags is not
+ specified and may change with newer releases of this program. They
+ are however carefully selected to best aid in debugging.
+
+'--debug FLAGS'
+ This option is only useful for debugging and the behavior may
+ change at any time without notice. FLAGS are bit encoded and may
+ be given in usual C-Syntax. The currently defined bits are:
+
+ '0 (1)'
+ X.509 or OpenPGP protocol related data
+ '1 (2)'
+ values of big number integers
+ '2 (4)'
+ low level crypto operations
+ '5 (32)'
+ memory allocation
+ '6 (64)'
+ caching
+ '7 (128)'
+ show memory statistics
+ '9 (512)'
+ write hashed data to files named 'dbgmd-000*'
+ '10 (1024)'
+ trace Assuan protocol
+ '12 (4096)'
+ bypass all certificate validation
+
+'--debug-all'
+ Same as '--debug=0xffffffff'
+
+'--debug-wait N'
+ When running in server mode, wait N seconds before entering the
+ actual processing loop and print the pid. This gives time to
+ attach a debugger.
+
+'--debug-quick-random'
+ This option inhibits the use of the very secure random quality
+ level (Libgcrypt’s 'GCRY_VERY_STRONG_RANDOM') and degrades all
+ request down to standard random quality. It is only used for
+ testing and should not be used for any production quality keys.
+ This option is only effective when given on the command line.
+
+ On GNU/Linux, another way to quickly generate insecure keys is to
+ use 'rngd' to fill the kernel's entropy pool with lower quality
+ random data. 'rngd' is typically provided by the 'rng-tools'
+ package. It can be run as follows: 'sudo rngd -f -r /dev/urandom'.
+
+'--debug-pinentry'
+ This option enables extra debug information pertaining to the
+ Pinentry. As of now it is only useful when used along with
+ '--debug 1024'.
+
+'--no-detach'
+ Don't detach the process from the console. This is mainly useful
+ for debugging.
+
+'-s'
+'--sh'
+'-c'
+'--csh'
+ Format the info output in daemon mode for use with the standard
+ Bourne shell or the C-shell respectively. The default is to guess
+ it based on the environment variable 'SHELL' which is correct in
+ almost all cases.
+
+'--grab'
+'--no-grab'
+ Tell the pinentry to grab the keyboard and mouse. This option
+ should be used on X-Servers to avoid X-sniffing attacks. Any use
+ of the option '--grab' overrides an used option '--no-grab'. The
+ default is '--no-grab'.
+
+'--log-file FILE'
+ Append all logging output to FILE. This is very helpful in seeing
+ what the agent actually does. Use 'socket://' to log to socket.
+ If neither a log file nor a log file descriptor has been set on a
+ Windows platform, the Registry entry
+ 'HKCU\Software\GNU\GnuPG:DefaultLogFile', if set, is used to
+ specify the logging output.
+
+'--no-allow-mark-trusted'
+ Do not allow clients to mark keys as trusted, i.e. put them into
+ the 'trustlist.txt' file. This makes it harder for users to
+ inadvertently accept Root-CA keys.
+
+'--allow-preset-passphrase'
+ This option allows the use of 'gpg-preset-passphrase' to seed the
+ internal cache of 'gpg-agent' with passphrases.
+
+'--no-allow-loopback-pinentry'
+'--allow-loopback-pinentry'
+ Disallow or allow clients to use the loopback pinentry features;
+ see the option 'pinentry-mode' for details. Allow is the default.
+
+ The '--force' option of the Assuan command 'DELETE_KEY' is also
+ controlled by this option: The option is ignored if a loopback
+ pinentry is disallowed.
+
+'--no-allow-external-cache'
+ Tell Pinentry not to enable features which use an external cache
+ for passphrases.
+
+ Some desktop environments prefer to unlock all credentials with one
+ master password and may have installed a Pinentry which employs an
+ additional external cache to implement such a policy. By using
+ this option the Pinentry is advised not to make use of such a cache
+ and instead always ask the user for the requested passphrase.
+
+'--allow-emacs-pinentry'
+ Tell Pinentry to allow features to divert the passphrase entry to a
+ running Emacs instance. How this is exactly handled depends on the
+ version of the used Pinentry.
+
+'--ignore-cache-for-signing'
+ This option will let 'gpg-agent' bypass the passphrase cache for
+ all signing operation. Note that there is also a per-session
+ option to control this behavior but this command line option takes
+ precedence.
+
+'--default-cache-ttl N'
+ Set the time a cache entry is valid to N seconds. The default is
+ 600 seconds. Each time a cache entry is accessed, the entry's
+ timer is reset. To set an entry's maximum lifetime, use
+ 'max-cache-ttl'. Note that a cached passphrase may not be evicted
+ immediately from memory if no client requests a cache operation.
+ This is due to an internal housekeeping function which is only run
+ every few seconds.
+
+'--default-cache-ttl-ssh N'
+ Set the time a cache entry used for SSH keys is valid to N seconds.
+ The default is 1800 seconds. Each time a cache entry is accessed,
+ the entry's timer is reset. To set an entry's maximum lifetime,
+ use 'max-cache-ttl-ssh'.
+
+'--max-cache-ttl N'
+ Set the maximum time a cache entry is valid to N seconds. After
+ this time a cache entry will be expired even if it has been
+ accessed recently or has been set using 'gpg-preset-passphrase'.
+ The default is 2 hours (7200 seconds).
+
+'--max-cache-ttl-ssh N'
+ Set the maximum time a cache entry used for SSH keys is valid to N
+ seconds. After this time a cache entry will be expired even if it
+ has been accessed recently or has been set using
+ 'gpg-preset-passphrase'. The default is 2 hours (7200 seconds).
+
+'--enforce-passphrase-constraints'
+ Enforce the passphrase constraints by not allowing the user to
+ bypass them using the "Take it anyway" button.
+
+'--min-passphrase-len N'
+ Set the minimal length of a passphrase. When entering a new
+ passphrase shorter than this value a warning will be displayed.
+ Defaults to 8.
+
+'--min-passphrase-nonalpha N'
+ Set the minimal number of digits or special characters required in
+ a passphrase. When entering a new passphrase with less than this
+ number of digits or special characters a warning will be displayed.
+ Defaults to 1.
+
+'--check-passphrase-pattern FILE'
+ Check the passphrase against the pattern given in FILE. When
+ entering a new passphrase matching one of these pattern a warning
+ will be displayed. FILE should be an absolute filename. The
+ default is not to use any pattern file.
+
+ Security note: It is known that checking a passphrase against a
+ list of pattern or even against a complete dictionary is not very
+ effective to enforce good passphrases. Users will soon figure up
+ ways to bypass such a policy. A better policy is to educate users
+ on good security behavior and optionally to run a passphrase
+ cracker regularly on all users passphrases to catch the very simple
+ ones.
+
+'--max-passphrase-days N'
+ Ask the user to change the passphrase if N days have passed since
+ the last change. With '--enforce-passphrase-constraints' set the
+ user may not bypass this check.
+
+'--enable-passphrase-history'
+ This option does nothing yet.
+
+'--pinentry-invisible-char CHAR'
+ This option asks the Pinentry to use CHAR for displaying hidden
+ characters. CHAR must be one character UTF-8 string. A Pinentry
+ may or may not honor this request.
+
+'--pinentry-timeout N'
+ This option asks the Pinentry to timeout after N seconds with no
+ user input. The default value of 0 does not ask the pinentry to
+ timeout, however a Pinentry may use its own default timeout value
+ in this case. A Pinentry may or may not honor this request.
+
+'--pinentry-program FILENAME'
+ Use program FILENAME as the PIN entry. The default is installation
+ dependent. With the default configuration the name of the default
+ pinentry is 'pinentry'; if that file does not exist but a
+ 'pinentry-basic' exist the latter is used.
+
+ On a Windows platform the default is to use the first existing
+ program from this list: 'bin\pinentry.exe',
+ '..\Gpg4win\bin\pinentry.exe', '..\Gpg4win\pinentry.exe',
+ '..\GNU\GnuPG\pinentry.exe', '..\GNU\bin\pinentry.exe',
+ 'bin\pinentry-basic.exe' where the file names are relative to the
+ GnuPG installation directory.
+
+'--pinentry-touch-file FILENAME'
+ By default the filename of the socket gpg-agent is listening for
+ requests is passed to Pinentry, so that it can touch that file
+ before exiting (it does this only in curses mode). This option
+ changes the file passed to Pinentry to FILENAME. The special name
+ '/dev/null' may be used to completely disable this feature. Note
+ that Pinentry will not create that file, it will only change the
+ modification and access time.
+
+'--scdaemon-program FILENAME'
+ Use program FILENAME as the Smartcard daemon. The default is
+ installation dependent and can be shown with the 'gpgconf' command.
+
+'--disable-scdaemon'
+ Do not make use of the scdaemon tool. This option has the effect
+ of disabling the ability to do smartcard operations. Note, that
+ enabling this option at runtime does not kill an already forked
+ scdaemon.
+
+'--disable-check-own-socket'
+ 'gpg-agent' employs a periodic self-test to detect a stolen socket.
+ This usually means a second instance of 'gpg-agent' has taken over
+ the socket and 'gpg-agent' will then terminate itself. This option
+ may be used to disable this self-test for debugging purposes.
+
+'--use-standard-socket'
+'--no-use-standard-socket'
+'--use-standard-socket-p'
+ Since GnuPG 2.1 the standard socket is always used. These options
+ have no more effect. The command 'gpg-agent
+ --use-standard-socket-p' will thus always return success.
+
+'--display STRING'
+'--ttyname STRING'
+'--ttytype STRING'
+'--lc-ctype STRING'
+'--lc-messages STRING'
+'--xauthority STRING'
+ These options are used with the server mode to pass localization
+ information.
+
+'--keep-tty'
+'--keep-display'
+ Ignore requests to change the current 'tty' or X window system's
+ 'DISPLAY' variable respectively. This is useful to lock the
+ pinentry to pop up at the 'tty' or display you started the agent.
+
+'--listen-backlog N'
+ Set the size of the queue for pending connections. The default is
+ 64.
+
+'--extra-socket NAME'
+ The extra socket is created by default, you may use this option to
+ change the name of the socket. To disable the creation of the
+ socket use "none" or "/dev/null" for NAME.
+
+ Also listen on native gpg-agent connections on the given socket.
+ The intended use for this extra socket is to setup a Unix domain
+ socket forwarding from a remote machine to this socket on the local
+ machine. A 'gpg' running on the remote machine may then connect to
+ the local gpg-agent and use its private keys. This enables
+ decrypting or signing data on a remote machine without exposing the
+ private keys to the remote machine.
+
+'--enable-extended-key-format'
+'--disable-extended-key-format'
+ Since version 2.2.22 keys are created in the extended private key
+ format by default. Changing the passphrase of a key will also
+ convert the key to that new format. This key format is supported
+ since GnuPG version 2.1.12 and thus there should be no need to
+ disable it. Anyway, the disable option still allows to revert to
+ the old behavior for new keys; be aware that keys are never
+ migrated back to the old format. If the enable option has been
+ used the disable option won't have an effect. The advantage of the
+ extended private key format is that it is text based and can carry
+ additional meta data. In extended key format the OCB mode is used
+ for key protection.
+
+'--enable-ssh-support'
+'--enable-putty-support'
+
+ The OpenSSH Agent protocol is always enabled, but 'gpg-agent' will
+ only set the 'SSH_AUTH_SOCK' variable if this flag is given.
+
+ In this mode of operation, the agent does not only implement the
+ gpg-agent protocol, but also the agent protocol used by OpenSSH
+ (through a separate socket). Consequently, it should be possible
+ to use the gpg-agent as a drop-in replacement for the well known
+ ssh-agent.
+
+ SSH Keys, which are to be used through the agent, need to be added
+ to the gpg-agent initially through the ssh-add utility. When a key
+ is added, ssh-add will ask for the password of the provided key
+ file and send the unprotected key material to the agent; this
+ causes the gpg-agent to ask for a passphrase, which is to be used
+ for encrypting the newly received key and storing it in a gpg-agent
+ specific directory.
+
+ Once a key has been added to the gpg-agent this way, the gpg-agent
+ will be ready to use the key.
+
+ Note: in case the gpg-agent receives a signature request, the user
+ might need to be prompted for a passphrase, which is necessary for
+ decrypting the stored key. Since the ssh-agent protocol does not
+ contain a mechanism for telling the agent on which display/terminal
+ it is running, gpg-agent's ssh-support will use the TTY or X
+ display where gpg-agent has been started. To switch this display
+ to the current one, the following command may be used:
+
+ gpg-connect-agent updatestartuptty /bye
+
+ Although all GnuPG components try to start the gpg-agent as needed,
+ this is not possible for the ssh support because ssh does not know
+ about it. Thus if no GnuPG tool which accesses the agent has been
+ run, there is no guarantee that ssh is able to use gpg-agent for
+ authentication. To fix this you may start gpg-agent if needed
+ using this simple command:
+
+ gpg-connect-agent /bye
+
+ Adding the '--verbose' shows the progress of starting the agent.
+
+ The '--enable-putty-support' is only available under Windows and
+ allows the use of gpg-agent with the ssh implementation 'putty'.
+ This is similar to the regular ssh-agent support but makes use of
+ Windows message queue as required by 'putty'.
+
+'--ssh-fingerprint-digest'
+
+ Select the digest algorithm used to compute ssh fingerprints that
+ are communicated to the user, e.g. in pinentry dialogs. OpenSSH
+ has transitioned from using MD5 to the more secure SHA256.
+
+'--auto-expand-secmem N'
+ Allow Libgcrypt to expand its secure memory area as required. The
+ optional value N is a non-negative integer with a suggested size in
+ bytes of each additionally allocated secure memory area. The value
+ is rounded up to the next 32 KiB; usual C style prefixes are
+ allowed. For an heavy loaded gpg-agent with many concurrent
+ connection this option avoids sign or decrypt errors due to out of
+ secure memory error returns.
+
+'--s2k-calibration MILLISECONDS'
+ Change the default calibration time to MILLISECONDS. The given
+ value is capped at 60 seconds; a value of 0 resets to the
+ compiled-in default. This option is re-read on a SIGHUP (or
+ 'gpgconf --reload gpg-agent') and the S2K count is then
+ re-calibrated.
+
+'--s2k-count N'
+ Specify the iteration count used to protect the passphrase. This
+ option can be used to override the auto-calibration done by
+ default. The auto-calibration computes a count which requires by
+ default 100ms to mangle a given passphrase. See also
+ '--s2k-calibration'.
+
+ To view the actually used iteration count and the milliseconds
+ required for an S2K operation use:
+
+ gpg-connect-agent 'GETINFO s2k_count' /bye
+ gpg-connect-agent 'GETINFO s2k_time' /bye
+
+ To view the auto-calibrated count use:
+
+ gpg-connect-agent 'GETINFO s2k_count_cal' /bye
+
+
+File: gnupg.info, Node: Agent Configuration, Next: Agent Signals, Prev: Agent Options, Up: Invoking GPG-AGENT
+
+2.3 Configuration
+=================
+
+There are a few configuration files needed for the operation of the
+agent. By default they may all be found in the current home directory
+(*note option --homedir::).
+
+'gpg-agent.conf'
+ This is the standard configuration file read by 'gpg-agent' on
+ startup. It may contain any valid long option; the leading two
+ dashes may not be entered and the option may not be abbreviated.
+ This file is also read after a 'SIGHUP' however only a few options
+ will actually have an effect. This default name may be changed on
+ the command line (*note option --options::). You should backup
+ this file.
+
+'trustlist.txt'
+ This is the list of trusted keys. You should backup this file.
+
+ Comment lines, indicated by a leading hash mark, as well as empty
+ lines are ignored. To mark a key as trusted you need to enter its
+ fingerprint followed by a space and a capital letter 'S'. Colons
+ may optionally be used to separate the bytes of a fingerprint; this
+ enables cutting and pasting the fingerprint from a key listing
+ output. If the line is prefixed with a '!' the key is explicitly
+ marked as not trusted.
+
+ Here is an example where two keys are marked as ultimately trusted
+ and one as not trusted:
+
+ # CN=Wurzel ZS 3,O=Intevation GmbH,C=DE
+ A6935DD34EF3087973C706FC311AA2CCF733765B S
+
+ # CN=PCA-1-Verwaltung-02/O=PKI-1-Verwaltung/C=DE
+ DC:BD:69:25:48:BD:BB:7E:31:6E:BB:80:D3:00:80:35:D4:F8:A6:CD S
+
+ # CN=Root-CA/O=Schlapphuete/L=Pullach/C=DE
+ !14:56:98:D3:FE:9C:CA:5A:31:6E:BC:81:D3:11:4E:00:90:A3:44:C2 S
+
+ Before entering a key into this file, you need to ensure its
+ authenticity. How to do this depends on your organisation; your
+ administrator might have already entered those keys which are
+ deemed trustworthy enough into this file. Places where to look for
+ the fingerprint of a root certificate are letters received from the
+ CA or the website of the CA (after making 100% sure that this is
+ indeed the website of that CA). You may want to consider
+ disallowing interactive updates of this file by using the *note
+ option --no-allow-mark-trusted::. It might even be advisable to
+ change the permissions to read-only so that this file can't be
+ changed inadvertently.
+
+ As a special feature a line 'include-default' will include a global
+ list of trusted certificates (e.g. '/etc/gnupg/trustlist.txt').
+ This global list is also used if the local list is not available.
+
+ It is possible to add further flags after the 'S' for use by the
+ caller:
+
+ 'relax'
+ Relax checking of some root certificate requirements. As of
+ now this flag allows the use of root certificates with a
+ missing basicConstraints attribute (despite that it is a MUST
+ for CA certificates) and disables CRL checking for the root
+ certificate.
+
+ 'cm'
+ If validation of a certificate finally issued by a CA with
+ this flag set fails, try again using the chain validation
+ model.
+
+'sshcontrol'
+ This file is used when support for the secure shell agent protocol
+ has been enabled (*note option --enable-ssh-support::). Only keys
+ present in this file are used in the SSH protocol. You should
+ backup this file.
+
+ The 'ssh-add' tool may be used to add new entries to this file; you
+ may also add them manually. Comment lines, indicated by a leading
+ hash mark, as well as empty lines are ignored. An entry starts
+ with optional whitespace, followed by the keygrip of the key given
+ as 40 hex digits, optionally followed by the caching TTL in seconds
+ and another optional field for arbitrary flags. A non-zero TTL
+ overrides the global default as set by '--default-cache-ttl-ssh'.
+
+ The only flag support is 'confirm'. If this flag is found for a
+ key, each use of the key will pop up a pinentry to confirm the use
+ of that key. The flag is automatically set if a new key was loaded
+ into 'gpg-agent' using the option '-c' of the 'ssh-add' command.
+
+ The keygrip may be prefixed with a '!' to disable an entry.
+
+ The following example lists exactly one key. Note that keys
+ available through a OpenPGP smartcard in the active smartcard
+ reader are implicitly added to this list; i.e. there is no need to
+ list them.
+
+ # Key added on: 2011-07-20 20:38:46
+ # Fingerprint: 5e:8d:c4:ad:e7:af:6e:27:8a:d6:13:e4:79:ad:0b:81
+ 34B62F25E277CF13D3C6BCEBFD3F85D08F0A864B 0 confirm
+
+'private-keys-v1.d/'
+
+ This is the directory where gpg-agent stores the private keys.
+ Each key is stored in a file with the name made up of the keygrip
+ and the suffix 'key'. You should backup all files in this
+ directory and take great care to keep this backup closed away.
+
+ Note that on larger installations, it is useful to put predefined
+files into the directory '/etc/skel/.gnupg' so that newly created users
+start up with a working configuration. For existing users the a small
+helper script is provided to create these files (*note addgnupghome::).
+
+
+File: gnupg.info, Node: Agent Signals, Next: Agent Examples, Prev: Agent Configuration, Up: Invoking GPG-AGENT
+
+2.4 Use of some signals
+=======================
+
+A running 'gpg-agent' may be controlled by signals, i.e. using the
+'kill' command to send a signal to the process.
+
+ Here is a list of supported signals:
+
+'SIGHUP'
+ This signal flushes all cached passphrases and if the program has
+ been started with a configuration file, the configuration file is
+ read again. Only certain options are honored: 'quiet', 'verbose',
+ 'debug', 'debug-all', 'debug-level', 'debug-pinentry', 'no-grab',
+ 'pinentry-program', 'pinentry-invisible-char', 'default-cache-ttl',
+ 'max-cache-ttl', 'ignore-cache-for-signing', 's2k-count',
+ 'no-allow-external-cache', 'allow-emacs-pinentry',
+ 'no-allow-mark-trusted', 'disable-scdaemon', and
+ 'disable-check-own-socket'. 'scdaemon-program' is also supported
+ but due to the current implementation, which calls the scdaemon
+ only once, it is not of much use unless you manually kill the
+ scdaemon.
+
+'SIGTERM'
+ Shuts down the process but waits until all current requests are
+ fulfilled. If the process has received 3 of these signals and
+ requests are still pending, a shutdown is forced.
+
+'SIGINT'
+ Shuts down the process immediately.
+
+'SIGUSR1'
+ Dump internal information to the log file.
+
+'SIGUSR2'
+ This signal is used for internal purposes.
+
+
+File: gnupg.info, Node: Agent Examples, Next: Agent Protocol, Prev: Agent Signals, Up: Invoking GPG-AGENT
+
+2.5 Examples
+============
+
+It is important to set the environment variable 'GPG_TTY' in your login
+shell, for example in the '~/.bashrc' init script:
+
+ export GPG_TTY=$(tty)
+
+ If you enabled the Ssh Agent Support, you also need to tell ssh about
+it by adding this to your init script:
+
+ unset SSH_AGENT_PID
+ if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then
+ export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"
+ fi
+
+
+File: gnupg.info, Node: Agent Protocol, Prev: Agent Examples, Up: Invoking GPG-AGENT
+
+2.6 Agent's Assuan Protocol
+===========================
+
+Note: this section does only document the protocol, which is used by
+GnuPG components; it does not deal with the ssh-agent protocol. To see
+the full specification of each command, use
+
+ gpg-connect-agent 'help COMMAND' /bye
+
+or just 'help' to list all available commands.
+
+The 'gpg-agent' daemon is started on demand by the GnuPG components.
+
+ To identify a key we use a thing called keygrip which is the SHA-1
+hash of an canonical encoded S-Expression of the public key as used in
+Libgcrypt. For the purpose of this interface the keygrip is given as a
+hex string. The advantage of using this and not the hash of a
+certificate is that it will be possible to use the same keypair for
+different protocols, thereby saving space on the token used to keep the
+secret keys.
+
+ The 'gpg-agent' may send status messages during a command or when
+returning from a command to inform a client about the progress or result
+of an operation. For example, the INQUIRE_MAXLEN status message may be
+sent during a server inquire to inform the client of the maximum usable
+length of the inquired data (which should not be exceeded).
+
+* Menu:
+
+* Agent PKDECRYPT:: Decrypting a session key
+* Agent PKSIGN:: Signing a Hash
+* Agent GENKEY:: Generating a Key
+* Agent IMPORT:: Importing a Secret Key
+* Agent EXPORT:: Exporting a Secret Key
+* Agent ISTRUSTED:: Importing a Root Certificate
+* Agent GET_PASSPHRASE:: Ask for a passphrase
+* Agent CLEAR_PASSPHRASE:: Expire a cached passphrase
+* Agent PRESET_PASSPHRASE:: Set a passphrase for a keygrip
+* Agent GET_CONFIRMATION:: Ask for confirmation
+* Agent HAVEKEY:: Check whether a key is available
+* Agent LEARN:: Register a smartcard
+* Agent PASSWD:: Change a Passphrase
+* Agent UPDATESTARTUPTTY:: Change the Standard Display
+* Agent GETEVENTCOUNTER:: Get the Event Counters
+* Agent GETINFO:: Return information about the process
+* Agent OPTION:: Set options for the session
+
+
+File: gnupg.info, Node: Agent PKDECRYPT, Next: Agent PKSIGN, Up: Agent Protocol
+
+2.6.1 Decrypting a session key
+------------------------------
+
+The client asks the server to decrypt a session key. The encrypted
+session key should have all information needed to select the appropriate
+secret key or to delegate it to a smartcard.
+
+ SETKEY <keyGrip>
+
+ Tell the server about the key to be used for decryption. If this is
+not used, 'gpg-agent' may try to figure out the key by trying to decrypt
+the message with each key available.
+
+ PKDECRYPT
+
+ The agent checks whether this command is allowed and then does an
+INQUIRY to get the ciphertext the client should then send the cipher
+text.
+
+ S: INQUIRE CIPHERTEXT
+ C: D (xxxxxx
+ C: D xxxx)
+ C: END
+
+ Please note that the server may send status info lines while reading
+the data lines from the client. The data send is a SPKI like S-Exp with
+this structure:
+
+ (enc-val
+ (<algo>
+ (<param_name1> <mpi>)
+ ...
+ (<param_namen> <mpi>)))
+
+ Where algo is a string with the name of the algorithm; see the
+libgcrypt documentation for a list of valid algorithms. The number and
+names of the parameters depend on the algorithm. The agent does return
+an error if there is an inconsistency.
+
+ If the decryption was successful the decrypted data is returned by
+means of "D" lines.
+
+ Here is an example session:
+ C: PKDECRYPT
+ S: INQUIRE CIPHERTEXT
+ C: D (enc-val elg (a 349324324)
+ C: D (b 3F444677CA)))
+ C: END
+ S: # session key follows
+ S: S PADDING 0
+ S: D (value 1234567890ABCDEF0)
+ S: OK decryption successful
+
+ The “PADDING” status line is only send if gpg-agent can tell what
+kind of padding is used. As of now only the value 0 is used to indicate
+that the padding has been removed.
+
+
+File: gnupg.info, Node: Agent PKSIGN, Next: Agent GENKEY, Prev: Agent PKDECRYPT, Up: Agent Protocol
+
+2.6.2 Signing a Hash
+--------------------
+
+The client asks the agent to sign a given hash value. A default key
+will be chosen if no key has been set. To set a key a client first
+uses:
+
+ SIGKEY <keyGrip>
+
+ This can be used multiple times to create multiple signature, the
+list of keys is reset with the next PKSIGN command or a RESET. The
+server tests whether the key is a valid key to sign something and
+responds with okay.
+
+ SETHASH --hash=<name>|<algo> <hexstring>
+
+ The client can use this command to tell the server about the data
+<hexstring> (which usually is a hash) to be signed. <algo> is the
+decimal encoded hash algorithm number as used by Libgcrypt. Either
+<algo> or -hash=<name> must be given. Valid names for <name> are:
+
+'sha1'
+ The SHA-1 hash algorithm
+'sha256'
+ The SHA-256 hash algorithm
+'rmd160'
+ The RIPE-MD160 hash algorithm
+'md5'
+ The old and broken MD5 hash algorithm
+'tls-md5sha1'
+ A combined hash algorithm as used by the TLS protocol.
+
+The actual signing is done using
+
+ PKSIGN <options>
+
+ Options are not yet defined, but may later be used to choose among
+different algorithms. The agent does then some checks, asks for the
+passphrase and as a result the server returns the signature as an SPKI
+like S-expression in "D" lines:
+
+ (sig-val
+ (<algo>
+ (<param_name1> <mpi>)
+ ...
+ (<param_namen> <mpi>)))
+
+ The operation is affected by the option
+
+ OPTION use-cache-for-signing=0|1
+
+ The default of '1' uses the cache. Setting this option to '0' will
+lead 'gpg-agent' to ignore the passphrase cache. Note, that there is
+also a global command line option for 'gpg-agent' to globally disable
+the caching.
+
+ Here is an example session:
+ C: SIGKEY <keyGrip>
+ S: OK key available
+ C: SIGKEY <keyGrip>
+ S: OK key available
+ C: PKSIGN
+ S: # I did ask the user whether he really wants to sign
+ S: # I did ask the user for the passphrase
+ S: INQUIRE HASHVAL
+ C: D ABCDEF012345678901234
+ C: END
+ S: # signature follows
+ S: D (sig-val rsa (s 45435453654612121212))
+ S: OK
+
+
+File: gnupg.info, Node: Agent GENKEY, Next: Agent IMPORT, Prev: Agent PKSIGN, Up: Agent Protocol
+
+2.6.3 Generating a Key
+----------------------
+
+This is used to create a new keypair and store the secret key inside the
+active PSE -- which is in most cases a Soft-PSE. A not-yet-defined
+option allows choosing the storage location. To get the secret key out
+of the PSE, a special export tool has to be used.
+
+ GENKEY [--no-protection] [--preset] [<cache_nonce>]
+
+ Invokes the key generation process and the server will then inquire
+on the generation parameters, like:
+
+ S: INQUIRE KEYPARM
+ C: D (genkey (rsa (nbits 1024)))
+ C: END
+
+ The format of the key parameters which depends on the algorithm is of
+the form:
+
+ (genkey
+ (algo
+ (parameter_name_1 ....)
+ ....
+ (parameter_name_n ....)))
+
+ If everything succeeds, the server returns the *public key* in a SPKI
+like S-Expression like this:
+
+ (public-key
+ (rsa
+ (n <mpi>)
+ (e <mpi>)))
+
+ Here is an example session:
+ C: GENKEY
+ S: INQUIRE KEYPARM
+ C: D (genkey (rsa (nbits 1024)))
+ C: END
+ S: D (public-key
+ S: D (rsa (n 326487324683264) (e 10001)))
+ S OK key created
+
+ The '--no-protection' option may be used to prevent prompting for a
+passphrase to protect the secret key while leaving the secret key
+unprotected. The '--preset' option may be used to add the passphrase to
+the cache using the default cache parameters.
+
+ The '--inq-passwd' option may be used to create the key with a
+supplied passphrase. When used the agent does an inquiry with the
+keyword 'NEWPASSWD' to retrieve that passphrase. This option takes
+precedence over '--no-protection'; however if the client sends a empty
+(zero-length) passphrase, this is identical to '--no-protection'.
+
+
+File: gnupg.info, Node: Agent IMPORT, Next: Agent EXPORT, Prev: Agent GENKEY, Up: Agent Protocol
+
+2.6.4 Importing a Secret Key
+----------------------------
+
+This operation is not yet supported by GpgAgent. Specialized tools are
+to be used for this.
+
+ There is no actual need because we can expect that secret keys
+created by a 3rd party are stored on a smartcard. If we have generated
+the key ourselves, we do not need to import it.
+
+
+File: gnupg.info, Node: Agent EXPORT, Next: Agent ISTRUSTED, Prev: Agent IMPORT, Up: Agent Protocol
+
+2.6.5 Export a Secret Key
+-------------------------
+
+Not implemented.
+
+ Should be done by an extra tool.
+
+
+File: gnupg.info, Node: Agent ISTRUSTED, Next: Agent GET_PASSPHRASE, Prev: Agent EXPORT, Up: Agent Protocol
+
+2.6.6 Importing a Root Certificate
+----------------------------------
+
+Actually we do not import a Root Cert but provide a way to validate any
+piece of data by storing its Hash along with a description and an
+identifier in the PSE. Here is the interface description:
+
+ ISTRUSTED <fingerprint>
+
+ Check whether the OpenPGP primary key or the X.509 certificate with
+the given fingerprint is an ultimately trusted key or a trusted Root CA
+certificate. The fingerprint should be given as a hexstring (without
+any blanks or colons or whatever in between) and may be left padded with
+00 in case of an MD5 fingerprint. GPGAgent will answer with:
+
+ OK
+
+ The key is in the table of trusted keys.
+
+ ERR 304 (Not Trusted)
+
+ The key is not in this table.
+
+ Gpg needs the entire list of trusted keys to maintain the web of
+trust; the following command is therefore quite helpful:
+
+ LISTTRUSTED
+
+ GpgAgent returns a list of trusted keys line by line:
+
+ S: D 000000001234454556565656677878AF2F1ECCFF P
+ S: D 340387563485634856435645634856438576457A P
+ S: D FEDC6532453745367FD83474357495743757435D S
+ S: OK
+
+ The first item on a line is the hexified fingerprint where MD5
+fingerprints are '00' padded to the left and the second item is a flag
+to indicate the type of key (so that gpg is able to only take care of
+PGP keys). P = OpenPGP, S = S/MIME. A client should ignore the rest of
+the line, so that we can extend the format in the future.
+
+ Finally a client should be able to mark a key as trusted:
+
+ MARKTRUSTED FINGERPRINT "P"|"S"
+
+ The server will then pop up a window to ask the user whether she
+really trusts this key. For this it will probably ask for a text to be
+displayed like this:
+
+ S: INQUIRE TRUSTDESC
+ C: D Do you trust the key with the fingerprint @FPR@
+ C: D bla fasel blurb.
+ C: END
+ S: OK
+
+ Known sequences with the pattern @foo@ are replaced according to this
+table:
+
+'@FPR16@'
+ Format the fingerprint according to gpg rules for a v3 keys.
+'@FPR20@'
+ Format the fingerprint according to gpg rules for a v4 keys.
+'@FPR@'
+ Choose an appropriate format to format the fingerprint.
+'@@'
+ Replaced by a single '@'.
+
+
+File: gnupg.info, Node: Agent GET_PASSPHRASE, Next: Agent CLEAR_PASSPHRASE, Prev: Agent ISTRUSTED, Up: Agent Protocol
+
+2.6.7 Ask for a passphrase
+--------------------------
+
+This function is usually used to ask for a passphrase to be used for
+symmetric encryption, but may also be used by programs which need
+special handling of passphrases. This command uses a syntax which helps
+clients to use the agent with minimum effort.
+
+ GET_PASSPHRASE [--data] [--check] [--no-ask] [--repeat[=N]] \
+ [--qualitybar] CACHE_ID \
+ [ERROR_MESSAGE PROMPT DESCRIPTION]
+
+ CACHE_ID is expected to be a string used to identify a cached
+passphrase. Use a 'X' to bypass the cache. With no other arguments the
+agent returns a cached passphrase or an error. By convention either the
+hexified fingerprint of the key shall be used for CACHE_ID or an
+arbitrary string prefixed with the name of the calling application and a
+colon: Like 'gpg:somestring'.
+
+ ERROR_MESSAGE is either a single 'X' for no error message or a string
+to be shown as an error message like (e.g. "invalid passphrase").
+Blanks must be percent escaped or replaced by '+''.
+
+ PROMPT is either a single 'X' for a default prompt or the text to be
+shown as the prompt. Blanks must be percent escaped or replaced by '+'.
+
+ DESCRIPTION is a text shown above the entry field. Blanks must be
+percent escaped or replaced by '+'.
+
+ The agent either returns with an error or with a OK followed by the
+hex encoded passphrase. Note that the length of the strings is
+implicitly limited by the maximum length of a command. If the option
+'--data' is used, the passphrase is not returned on the OK line but by
+regular data lines; this is the preferred method.
+
+ If the option '--check' is used, the standard passphrase constraints
+checks are applied. A check is not done if the passphrase has been
+found in the cache.
+
+ If the option '--no-ask' is used and the passphrase is not in the
+cache the user will not be asked to enter a passphrase but the error
+code 'GPG_ERR_NO_DATA' is returned.
+
+ If the option '--qualitybar' is used and a minimum passphrase length
+has been configured, a visual indication of the entered passphrase
+quality is shown.
+
+ CLEAR_PASSPHRASE CACHE_ID
+
+ may be used to invalidate the cache entry for a passphrase. The
+function returns with OK even when there is no cached passphrase.
+
+
+File: gnupg.info, Node: Agent CLEAR_PASSPHRASE, Next: Agent PRESET_PASSPHRASE, Prev: Agent GET_PASSPHRASE, Up: Agent Protocol
+
+2.6.8 Remove a cached passphrase
+--------------------------------
+
+Use this command to remove a cached passphrase.
+
+ CLEAR_PASSPHRASE [--mode=normal] <cache_id>
+
+ The '--mode=normal' option can be used to clear a CACHE_ID that was
+set by gpg-agent.
+
+
+File: gnupg.info, Node: Agent PRESET_PASSPHRASE, Next: Agent GET_CONFIRMATION, Prev: Agent CLEAR_PASSPHRASE, Up: Agent Protocol
+
+2.6.9 Set a passphrase for a keygrip
+------------------------------------
+
+This command adds a passphrase to the cache for the specified KEYGRIP.
+
+ PRESET_PASSPHRASE [--inquire] <string_or_keygrip> <timeout> [<hexstring>]
+
+ The passphrase is a hexadecimal string when specified. When not
+specified, the passphrase will be retrieved from the pinentry module
+unless the '--inquire' option was specified in which case the passphrase
+will be retrieved from the client.
+
+ The TIMEOUT parameter keeps the passphrase cached for the specified
+number of seconds. A value of '-1' means infinite while '0' means the
+default (currently only a timeout of -1 is allowed, which means to never
+expire it).
+
+
+File: gnupg.info, Node: Agent GET_CONFIRMATION, Next: Agent HAVEKEY, Prev: Agent PRESET_PASSPHRASE, Up: Agent Protocol
+
+2.6.10 Ask for confirmation
+---------------------------
+
+This command may be used to ask for a simple confirmation by presenting
+a text and 2 buttons: Okay and Cancel.
+
+ GET_CONFIRMATION DESCRIPTION
+
+ DESCRIPTIONis displayed along with a Okay and Cancel button. Blanks
+must be percent escaped or replaced by '+'. A 'X' may be used to
+display confirmation dialog with a default text.
+
+ The agent either returns with an error or with a OK. Note, that the
+length of DESCRIPTION is implicitly limited by the maximum length of a
+command.
+
+
+File: gnupg.info, Node: Agent HAVEKEY, Next: Agent LEARN, Prev: Agent GET_CONFIRMATION, Up: Agent Protocol
+
+2.6.11 Check whether a key is available
+---------------------------------------
+
+This can be used to see whether a secret key is available. It does not
+return any information on whether the key is somehow protected.
+
+ HAVEKEY KEYGRIPS
+
+ The agent answers either with OK or 'No_Secret_Key' (208). The
+caller may want to check for other error codes as well. More than one
+keygrip may be given. In this case the command returns success if at
+least one of the keygrips corresponds to an available secret key.
+
+
+File: gnupg.info, Node: Agent LEARN, Next: Agent PASSWD, Prev: Agent HAVEKEY, Up: Agent Protocol
+
+2.6.12 Register a smartcard
+---------------------------
+
+ LEARN [--send]
+
+ This command is used to register a smartcard. With the '--send'
+option given the certificates are sent back.
+
+
+File: gnupg.info, Node: Agent PASSWD, Next: Agent UPDATESTARTUPTTY, Prev: Agent LEARN, Up: Agent Protocol
+
+2.6.13 Change a Passphrase
+--------------------------
+
+ PASSWD [--cache-nonce=<c>] [--passwd-nonce=<s>] [--preset] KEYGRIP
+
+ This command is used to interactively change the passphrase of the
+key identified by the hex string KEYGRIP. The '--preset' option may be
+used to add the new passphrase to the cache using the default cache
+parameters.
+
+
+File: gnupg.info, Node: Agent UPDATESTARTUPTTY, Next: Agent GETEVENTCOUNTER, Prev: Agent PASSWD, Up: Agent Protocol
+
+2.6.14 Change the standard display
+----------------------------------
+
+ UPDATESTARTUPTTY
+
+ Set the startup TTY and X-DISPLAY variables to the values of this
+session. This command is useful to direct future pinentry invocations
+to another screen. It is only required because there is no way in the
+ssh-agent protocol to convey this information.
+
+
+File: gnupg.info, Node: Agent GETEVENTCOUNTER, Next: Agent GETINFO, Prev: Agent UPDATESTARTUPTTY, Up: Agent Protocol
+
+2.6.15 Get the Event Counters
+-----------------------------
+
+ GETEVENTCOUNTER
+
+ This function return one status line with the current values of the
+event counters. The event counters are useful to avoid polling by
+delaying a poll until something has changed. The values are decimal
+numbers in the range '0' to 'UINT_MAX' and wrapping around to 0. The
+actual values should not be relied upon; they shall only be used to
+detect a change.
+
+ The currently defined counters are:
+'ANY'
+ Incremented with any change of any of the other counters.
+'KEY'
+ Incremented for added or removed private keys.
+'CARD'
+ Incremented for changes of the card readers stati.
+
+
+File: gnupg.info, Node: Agent GETINFO, Next: Agent OPTION, Prev: Agent GETEVENTCOUNTER, Up: Agent Protocol
+
+2.6.16 Return information about the process
+-------------------------------------------
+
+This is a multipurpose function to return a variety of information.
+
+ GETINFO WHAT
+
+ The value of WHAT specifies the kind of information returned:
+'version'
+ Return the version of the program.
+'pid'
+ Return the process id of the process.
+'socket_name'
+ Return the name of the socket used to connect the agent.
+'ssh_socket_name'
+ Return the name of the socket used for SSH connections. If SSH
+ support has not been enabled the error 'GPG_ERR_NO_DATA' will be
+ returned.
+
+
+File: gnupg.info, Node: Agent OPTION, Prev: Agent GETINFO, Up: Agent Protocol
+
+2.6.17 Set options for the session
+----------------------------------
+
+Here is a list of session options which are not yet described with other
+commands. The general syntax for an Assuan option is:
+
+ OPTION KEY=VALUE
+
+Supported KEYs are:
+
+'agent-awareness'
+ This may be used to tell gpg-agent of which gpg-agent version the
+ client is aware of. gpg-agent uses this information to enable
+ features which might break older clients.
+
+'putenv'
+ Change the session's environment to be used for the Pinentry.
+ Valid values are:
+
+ 'NAME'
+ Delete envvar NAME
+ 'NAME='
+ Set envvar NAME to the empty string
+ 'NAME=VALUE'
+ Set envvar NAME to the string VALUE.
+
+'use-cache-for-signing'
+ See Assuan command 'PKSIGN'.
+
+'allow-pinentry-notify'
+ This does not need any value. It is used to enable the
+ PINENTRY_LAUNCHED inquiry.
+
+'pinentry-mode'
+ This option is used to change the operation mode of the pinentry.
+ The following values are defined:
+
+ 'ask'
+ This is the default mode which pops up a pinentry as needed.
+
+ 'cancel'
+ Instead of popping up a pinentry, return the error code
+ 'GPG_ERR_CANCELED'.
+
+ 'error'
+ Instead of popping up a pinentry, return the error code
+ 'GPG_ERR_NO_PIN_ENTRY'.
+
+ 'loopback'
+ Use a loopback pinentry. This fakes a pinentry by using
+ inquiries back to the caller to ask for a passphrase. This
+ option may only be set if the agent has been configured for
+ that. To disable this feature use *note option
+ --no-allow-loopback-pinentry::.
+
+'cache-ttl-opt-preset'
+ This option sets the cache TTL for new entries created by GENKEY
+ and PASSWD commands when using the '--preset' option. It is not
+ used a default value is used.
+
+'s2k-count'
+ Instead of using the standard S2K count (which is computed on the
+ fly), the given S2K count is used for new keys or when changing the
+ passphrase of a key. Values below 65536 are considered to be 0.
+ This option is valid for the entire session or until reset to 0.
+ This option is useful if the key is later used on boxes which are
+ either much slower or faster than the actual box.
+
+'pretend-request-origin'
+ This option switches the connection into a restricted mode which
+ handles all further commands in the same way as they would be
+ handled when originating from the extra or browser socket. Note
+ that this option is not available in the restricted mode. Valid
+ values for this option are:
+
+ 'none'
+ 'local'
+ This is a NOP and leaves the connection in the standard way.
+
+ 'remote'
+ Pretend to come from a remote origin in the same way as
+ connections from the '--extra-socket'.
+
+ 'browser'
+ Pretend to come from a local web browser in the same way as
+ connections from the '--browser-socket'.
+
+
+File: gnupg.info, Node: Invoking DIRMNGR, Next: Invoking GPG, Prev: Invoking GPG-AGENT, Up: Top
+
+3 Invoking DIRMNGR
+******************
+
+Since version 2.1 of GnuPG, 'dirmngr' takes care of accessing the
+OpenPGP keyservers. As with previous versions it is also used as a
+server for managing and downloading certificate revocation lists (CRLs)
+for X.509 certificates, downloading X.509 certificates, and providing
+access to OCSP providers. Dirmngr is invoked internally by 'gpg',
+'gpgsm', or via the 'gpg-connect-agent' tool.
+
+*Note Option Index::,for an index to 'DIRMNGR''s commands and options.
+
+* Menu:
+
+* Dirmngr Commands:: List of all commands.
+* Dirmngr Options:: List of all options.
+* Dirmngr Configuration:: Configuration files.
+* Dirmngr Signals:: Use of signals.
+* Dirmngr Examples:: Some usage examples.
+* Dirmngr Protocol:: The protocol dirmngr uses.
+
+
+File: gnupg.info, Node: Dirmngr Commands, Next: Dirmngr Options, Up: Invoking DIRMNGR
+
+3.1 Commands
+============
+
+Commands are not distinguished from options except for the fact that
+only one command is allowed.
+
+'--version'
+ Print the program version and licensing information. Note that you
+ cannot abbreviate this command.
+
+'--help, -h'
+ Print a usage message summarizing the most useful command-line
+ options. Note that you cannot abbreviate this command.
+
+'--dump-options'
+ Print a list of all available options and commands. Note that you
+ cannot abbreviate this command.
+
+'--server'
+ Run in server mode and wait for commands on the 'stdin'. The
+ default mode is to create a socket and listen for commands there.
+ This is only used for testing.
+
+'--daemon'
+ Run in background daemon mode and listen for commands on a socket.
+ This is the way 'dirmngr' is started on demand by the other GnuPG
+ components. To force starting 'dirmngr' it is in general best to
+ use 'gpgconf --launch dirmngr'.
+
+'--supervised'
+ Run in the foreground, sending logs to stderr, and listening on
+ file descriptor 3, which must already be bound to a listening
+ socket. This is useful when running under systemd or other similar
+ process supervision schemes. This option is not supported on
+ Windows.
+
+'--list-crls'
+ List the contents of the CRL cache on 'stdout'. This is probably
+ only useful for debugging purposes.
+
+'--load-crl FILE'
+ This command requires a filename as additional argument, and it
+ will make Dirmngr try to import the CRL in FILE into it's cache.
+ Note, that this is only possible if Dirmngr is able to retrieve the
+ CA's certificate directly by its own means. In general it is
+ better to use 'gpgsm''s '--call-dirmngr loadcrl filename' command
+ so that 'gpgsm' can help dirmngr.
+
+'--fetch-crl URL'
+ This command requires an URL as additional argument, and it will
+ make dirmngr try to retrieve and import the CRL from that URL into
+ it's cache. This is mainly useful for debugging purposes. The
+ 'dirmngr-client' provides the same feature for a running dirmngr.
+
+'--shutdown'
+ This commands shuts down an running instance of Dirmngr. This
+ command has currently no effect.
+
+'--flush'
+ This command removes all CRLs from Dirmngr's cache. Client
+ requests will thus trigger reading of fresh CRLs.
+
+
+File: gnupg.info, Node: Dirmngr Options, Next: Dirmngr Configuration, Prev: Dirmngr Commands, Up: Invoking DIRMNGR
+
+3.2 Option Summary
+==================
+
+Note that all long options with the exception of '--options' and
+'--homedir' may also be given in the configuration file after stripping
+off the two leading dashes.
+
+'--options FILE'
+ Reads configuration from FILE instead of from the default per-user
+ configuration file. The default configuration file is named
+ 'dirmngr.conf' and expected in the home directory.
+
+'--homedir DIR'
+ Set the name of the home directory to DIR. This option is only
+ effective when used on the command line. The default is the
+ directory named '.gnupg' directly below the home directory of the
+ user unless the environment variable 'GNUPGHOME' has been set in
+ which case its value will be used. Many kinds of data are stored
+ within this directory.
+
+'-v'
+'--verbose'
+ Outputs additional information while running. You can increase the
+ verbosity by giving several verbose commands to DIRMNGR, such as
+ '-vv'.
+
+'--log-file FILE'
+ Append all logging output to FILE. This is very helpful in seeing
+ what the agent actually does. Use 'socket://' to log to socket.
+
+'--debug-level LEVEL'
+ Select the debug level for investigating problems. LEVEL may be a
+ numeric value or by a keyword:
+
+ 'none'
+ No debugging at all. A value of less than 1 may be used
+ instead of the keyword.
+ 'basic'
+ Some basic debug messages. A value between 1 and 2 may be
+ used instead of the keyword.
+ 'advanced'
+ More verbose debug messages. A value between 3 and 5 may be
+ used instead of the keyword.
+ 'expert'
+ Even more detailed messages. A value between 6 and 8 may be
+ used instead of the keyword.
+ 'guru'
+ All of the debug messages you can get. A value greater than 8
+ may be used instead of the keyword. The creation of hash
+ tracing files is only enabled if the keyword is used.
+
+ How these messages are mapped to the actual debugging flags is not
+ specified and may change with newer releases of this program. They
+ are however carefully selected to best aid in debugging.
+
+'--debug FLAGS'
+ Set debugging flags. This option is only useful for debugging and
+ its behavior may change with a new release. All flags are or-ed
+ and may be given in C syntax (e.g. 0x0042) or as a comma separated
+ list of flag names. To get a list of all supported flags the
+ single word "help" can be used.
+
+'--debug-all'
+ Same as '--debug=0xffffffff'
+
+'--tls-debug LEVEL'
+ Enable debugging of the TLS layer at LEVEL. The details of the
+ debug level depend on the used TLS library and are not set in
+ stone.
+
+'--debug-wait N'
+ When running in server mode, wait N seconds before entering the
+ actual processing loop and print the pid. This gives time to
+ attach a debugger.
+
+'--disable-check-own-socket'
+ On some platforms 'dirmngr' is able to detect the removal of its
+ socket file and shutdown itself. This option disable this
+ self-test for debugging purposes.
+
+'-s'
+'--sh'
+'-c'
+'--csh'
+ Format the info output in daemon mode for use with the standard
+ Bourne shell respective the C-shell. The default is to guess it
+ based on the environment variable 'SHELL' which is in almost all
+ cases sufficient.
+
+'--force'
+ Enabling this option forces loading of expired CRLs; this is only
+ useful for debugging.
+
+'--use-tor'
+'--no-use-tor'
+ The option '--use-tor' switches Dirmngr and thus GnuPG into "Tor
+ mode" to route all network access via Tor (an anonymity network).
+ Certain other features are disabled in this mode. The effect of
+ '--use-tor' cannot be overridden by any other command or even by
+ reloading dirmngr. The use of '--no-use-tor' disables the use of
+ Tor. The default is to use Tor if it is available on startup or
+ after reloading dirmngr.
+
+'--standard-resolver'
+ This option forces the use of the system's standard DNS resolver
+ code. This is mainly used for debugging. Note that on Windows a
+ standard resolver is not used and all DNS access will return the
+ error "Not Implemented" if this option is used. Using this
+ together with enabled Tor mode returns the error "Not Enabled".
+
+'--recursive-resolver'
+ When possible use a recursive resolver instead of a stub resolver.
+
+'--resolver-timeout N'
+ Set the timeout for the DNS resolver to N seconds. The default are
+ 30 seconds.
+
+'--connect-timeout N'
+'--connect-quick-timeout N'
+ Set the timeout for HTTP and generic TCP connection attempts to N
+ seconds. The value set with the quick variant is used when the
+ -quick option has been given to certain Assuan commands. The quick
+ value is capped at the value of the regular connect timeout. The
+ default values are 15 and 2 seconds. Note that the timeout values
+ are for each connection attempt; the connection code will attempt
+ to connect all addresses listed for a server.
+
+'--listen-backlog N'
+ Set the size of the queue for pending connections. The default is
+ 64.
+
+'--allow-version-check'
+ Allow Dirmngr to connect to 'https://versions.gnupg.org' to get the
+ list of current software versions. If this option is enabled the
+ list is retrieved in case the local copy does not exist or is older
+ than 5 to 7 days. See the option '--query-swdb' of the command
+ 'gpgconf' for more details. Note, that regardless of this option a
+ version check can always be triggered using this command:
+
+ gpg-connect-agent --dirmngr 'loadswdb --force' /bye
+
+'--keyserver NAME'
+ Use NAME as your keyserver. This is the server that 'gpg'
+ communicates with to receive keys, send keys, and search for keys.
+ The format of the NAME is a URI: 'scheme:[//]keyservername[:port]'
+ The scheme is the type of keyserver: "hkp" for the HTTP (or
+ compatible) keyservers, "ldap" for the LDAP keyservers, or "mailto"
+ for the Graff email keyserver. Note that your particular
+ installation of GnuPG may have other keyserver types available as
+ well. Keyserver schemes are case-insensitive. After the keyserver
+ name, optional keyserver configuration options may be provided.
+ These are the same as the '--keyserver-options' of 'gpg', but apply
+ only to this particular keyserver.
+
+ Most keyservers synchronize with each other, so there is generally
+ no need to send keys to more than one server. The keyserver
+ 'hkp://keys.gnupg.net' uses round robin DNS to give a different
+ keyserver each time you use it.
+
+ If exactly two keyservers are configured and only one is a Tor
+ hidden service (.onion), Dirmngr selects the keyserver to use
+ depending on whether Tor is locally running or not. The check for
+ a running Tor is done for each new connection.
+
+ If no keyserver is explicitly configured, dirmngr will use the
+ built-in default of 'hkps://hkps.pool.sks-keyservers.net'.
+
+ Windows users with a keyserver running on their Active Directory
+ should use 'ldap:///' for NAME to access this directory.
+
+ For accessing anonymous LDAP keyservers NAME is in general just a
+ 'ldaps://ldap.example.com'. A BaseDN parameter should never be
+ specified. If authentication is required the value of NAME is for
+ example:
+
+ keyserver ldaps://ldap.example.com/????bindname=uid=USERNAME
+ %2Cou=GnuPG%20Users%2Cdc=example%2Cdc=com,password=PASSWORD
+
+ Put this all on one line without any spaces and keep the '%2C' as
+ given. Replace USERNAME, PASSWORD, and the 'dc' parts according to
+ the instructions received from the LDAP administrator. Note that
+ only simple authentication (i.e. cleartext passwords) is supported
+ and thus using ldaps is strongly suggested.
+
+'--nameserver IPADDR'
+ In "Tor mode" Dirmngr uses a public resolver via Tor to resolve DNS
+ names. If the default public resolver, which is '8.8.8.8', shall
+ not be used a different one can be given using this option. Note
+ that a numerical IP address must be given (IPv6 or IPv4) and that
+ no error checking is done for IPADDR.
+
+'--disable-ipv4'
+'--disable-ipv6'
+ Disable the use of all IPv4 or IPv6 addresses.
+
+'--disable-ldap'
+ Entirely disables the use of LDAP.
+
+'--disable-http'
+ Entirely disables the use of HTTP.
+
+'--ignore-http-dp'
+ When looking for the location of a CRL, the to be tested
+ certificate usually contains so called "CRL Distribution Point"
+ (DP) entries which are URLs describing the way to access the CRL.
+ The first found DP entry is used. With this option all entries
+ using the HTTP scheme are ignored when looking for a suitable DP.
+
+'--ignore-ldap-dp'
+ This is similar to '--ignore-http-dp' but ignores entries using the
+ LDAP scheme. Both options may be combined resulting in ignoring
+ DPs entirely.
+
+'--ignore-ocsp-service-url'
+ Ignore all OCSP URLs contained in the certificate. The effect is
+ to force the use of the default responder.
+
+'--honor-http-proxy'
+ If the environment variable 'http_proxy' has been set, use its
+ value to access HTTP servers.
+
+'--http-proxy HOST[:PORT]'
+ Use HOST and PORT to access HTTP servers. The use of this option
+ overrides the environment variable 'http_proxy' regardless whether
+ '--honor-http-proxy' has been set.
+
+'--ldap-proxy HOST[:PORT]'
+ Use HOST and PORT to connect to LDAP servers. If PORT is omitted,
+ port 389 (standard LDAP port) is used. This overrides any
+ specified host and port part in a LDAP URL and will also be used if
+ host and port have been omitted from the URL.
+
+'--only-ldap-proxy'
+ Never use anything else but the LDAP "proxy" as configured with
+ '--ldap-proxy'. Usually 'dirmngr' tries to use other configured
+ LDAP server if the connection using the "proxy" failed.
+
+'--ldapserverlist-file FILE'
+ Read the list of LDAP servers to consult for CRLs and certificates
+ from file instead of the default per-user ldap server list file.
+ The default value for FILE is 'dirmngr_ldapservers.conf'.
+
+ This server list file contains one LDAP server per line in the
+ format
+
+ HOSTNAME:PORT:USERNAME:PASSWORD:BASE_DN
+
+ Lines starting with a '#' are comments.
+
+ Note that as usual all strings entered are expected to be UTF-8
+ encoded. Obviously this will lead to problems if the password has
+ originally been encoded as Latin-1. There is no other solution
+ here than to put such a password in the binary encoding into the
+ file (i.e. non-ascii characters won't show up readable).(1)
+
+'--ldaptimeout SECS'
+ Specify the number of seconds to wait for an LDAP query before
+ timing out. The default are 15 seconds. 0 will never timeout.
+
+'--add-servers'
+ This option makes dirmngr add any servers it discovers when
+ validating certificates against CRLs to the internal list of
+ servers to consult for certificates and CRLs.
+
+ This option is useful when trying to validate a certificate that
+ has a CRL distribution point that points to a server that is not
+ already listed in the ldapserverlist. Dirmngr will always go to
+ this server and try to download the CRL, but chances are high that
+ the certificate used to sign the CRL is located on the same server.
+ So if dirmngr doesn't add that new server to list, it will often
+ not be able to verify the signature of the CRL unless the
+ '--add-servers' option is used.
+
+ Note: The current version of dirmngr has this option disabled by
+ default.
+
+'--allow-ocsp'
+ This option enables OCSP support if requested by the client.
+
+ OCSP requests are rejected by default because they may violate the
+ privacy of the user; for example it is possible to track the time
+ when a user is reading a mail.
+
+'--ocsp-responder URL'
+ Use URL as the default OCSP Responder if the certificate does not
+ contain information about an assigned responder. Note, that
+ '--ocsp-signer' must also be set to a valid certificate.
+
+'--ocsp-signer FPR|FILE'
+ Use the certificate with the fingerprint FPR to check the responses
+ of the default OCSP Responder. Alternatively a filename can be
+ given in which case the response is expected to be signed by one of
+ the certificates described in that file. Any argument which
+ contains a slash, dot or tilde is considered a filename. Usual
+ filename expansion takes place: A tilde at the start followed by a
+ slash is replaced by the content of 'HOME', no slash at start
+ describes a relative filename which will be searched at the home
+ directory. To make sure that the FILE is searched in the home
+ directory, either prepend the name with "./" or use a name which
+ contains a dot.
+
+ If a response has been signed by a certificate described by these
+ fingerprints no further check upon the validity of this certificate
+ is done.
+
+ The format of the FILE is a list of SHA-1 fingerprint, one per line
+ with optional colons between the bytes. Empty lines and lines
+ prefix with a hash mark are ignored.
+
+'--ocsp-max-clock-skew N'
+ The number of seconds a skew between the OCSP responder and them
+ local clock is accepted. Default is 600 (10 minutes).
+
+'--ocsp-max-period N'
+ Seconds a response is at maximum considered valid after the time
+ given in the thisUpdate field. Default is 7776000 (90 days).
+
+'--ocsp-current-period N'
+ The number of seconds an OCSP response is considered valid after
+ the time given in the NEXT_UPDATE datum. Default is 10800 (3
+ hours).
+
+'--max-replies N'
+ Do not return more that N items in one query. The default is 10.
+
+'--ignore-cert-extension OID'
+ Add OID to the list of ignored certificate extensions. The OID is
+ expected to be in dotted decimal form, like '2.5.29.3'. This
+ option may be used more than once. Critical flagged certificate
+ extensions matching one of the OIDs in the list are treated as if
+ they are actually handled and thus the certificate won't be
+ rejected due to an unknown critical extension. Use this option
+ with care because extensions are usually flagged as critical for a
+ reason.
+
+'--hkp-cacert FILE'
+ Use the root certificates in FILE for verification of the TLS
+ certificates used with 'hkps' (keyserver access over TLS). If the
+ file is in PEM format a suffix of '.pem' is expected for FILE.
+ This option may be given multiple times to add more root
+ certificates. Tilde expansion is supported.
+
+ If no 'hkp-cacert' directive is present, dirmngr will make a
+ reasonable choice: if the keyserver in question is the special pool
+ 'hkps.pool.sks-keyservers.net', it will use the bundled root
+ certificate for that pool. Otherwise, it will use the system CAs.
+
+ ---------- Footnotes ----------
+
+ (1) The 'gpgconf' tool might be helpful for frontends as it enables
+editing this configuration file using percent-escaped strings.
+
+
+File: gnupg.info, Node: Dirmngr Configuration, Next: Dirmngr Signals, Prev: Dirmngr Options, Up: Invoking DIRMNGR
+
+3.3 Configuration
+=================
+
+Dirmngr makes use of several directories when running in daemon mode:
+There are a few configuration files whih control the operation of
+dirmngr. By default they may all be found in the current home directory
+(*note option --homedir::).
+
+'dirmngr.conf'
+ This is the standard configuration file read by 'dirmngr' on
+ startup. It may contain any valid long option; the leading two
+ dashes may not be entered and the option may not be abbreviated.
+ This file is also read after a 'SIGHUP' however not all options
+ will actually have an effect. This default name may be changed on
+ the command line (*note option --options::). You should backup
+ this file.
+
+'/etc/gnupg/trusted-certs'
+ This directory should be filled with certificates of Root CAs you
+ are trusting in checking the CRLs and signing OCSP Responses.
+
+ Usually these are the same certificates you use with the
+ applications making use of dirmngr. It is expected that each of
+ these certificate files contain exactly one DER encoded certificate
+ in a file with the suffix '.crt' or '.der'. 'dirmngr' reads those
+ certificates on startup and when given a SIGHUP. Certificates which
+ are not readable or do not make up a proper X.509 certificate are
+ ignored; see the log file for details.
+
+ Applications using dirmngr (e.g. gpgsm) can request these
+ certificates to complete a trust chain in the same way as with the
+ extra-certs directory (see below).
+
+ Note that for OCSP responses the certificate specified using the
+ option '--ocsp-signer' is always considered valid to sign OCSP
+ requests.
+
+'/etc/gnupg/extra-certs'
+ This directory may contain extra certificates which are preloaded
+ into the internal cache on startup. Applications using dirmngr
+ (e.g. gpgsm) can request cached certificates to complete a trust
+ chain. This is convenient in cases you have a couple intermediate
+ CA certificates or certificates usually used to sign OCSP
+ responses. These certificates are first tried before going out to
+ the net to look for them. These certificates must also be DER
+ encoded and suffixed with '.crt' or '.der'.
+
+'~/.gnupg/crls.d'
+ This directory is used to store cached CRLs. The 'crls.d' part
+ will be created by dirmngr if it does not exists but you need to
+ make sure that the upper directory exists.
+
+ To be able to see what's going on you should create the configure
+file '~/gnupg/dirmngr.conf' with at least one line:
+
+ log-file ~/dirmngr.log
+
+ To be able to perform OCSP requests you probably want to add the
+line:
+
+ allow-ocsp
+
+ To make sure that new options are read and that after the
+installation of a new GnuPG versions the installed dirmngr is running,
+you may want to kill an existing dirmngr first:
+
+ gpgconf --kill dirmngr
+
+ You may check the log file to see whether all desired root
+certificates have been loaded correctly.
+
+
+File: gnupg.info, Node: Dirmngr Signals, Next: Dirmngr Examples, Prev: Dirmngr Configuration, Up: Invoking DIRMNGR
+
+3.4 Use of signals
+==================
+
+A running 'dirmngr' may be controlled by signals, i.e. using the 'kill'
+command to send a signal to the process.
+
+ Here is a list of supported signals:
+
+'SIGHUP'
+ This signal flushes all internally cached CRLs as well as any
+ cached certificates. Then the certificate cache is reinitialized
+ as on startup. Options are re-read from the configuration file.
+ Instead of sending this signal it is better to use
+ gpgconf --reload dirmngr
+
+'SIGTERM'
+ Shuts down the process but waits until all current requests are
+ fulfilled. If the process has received 3 of these signals and
+ requests are still pending, a shutdown is forced. You may also use
+ gpgconf --kill dirmngr
+ instead of this signal
+
+'SIGINT'
+ Shuts down the process immediately.
+
+'SIGUSR1'
+ This prints some caching statistics to the log file.
+
+
+File: gnupg.info, Node: Dirmngr Examples, Next: Dirmngr Protocol, Prev: Dirmngr Signals, Up: Invoking DIRMNGR
+
+3.5 Examples
+============
+
+Here is an example on how to show dirmngr's internal table of OpenPGP
+keyserver addresses. The output is intended for debugging purposes and
+not part of a defined API.
+
+ gpg-connect-agent --dirmngr 'keyserver --hosttable' /bye
+
+ To inhibit the use of a particular host you have noticed in one of
+the keyserver pools, you may use
+
+ gpg-connect-agent --dirmngr 'keyserver --dead pgpkeys.bnd.de' /bye
+
+ The description of the 'keyserver' command can be printed using
+
+ gpg-connect-agent --dirmngr 'help keyserver' /bye
+
+
+File: gnupg.info, Node: Dirmngr Protocol, Prev: Dirmngr Examples, Up: Invoking DIRMNGR
+
+3.6 Dirmngr's Assuan Protocol
+=============================
+
+Assuan is the IPC protocol used to access dirmngr. This is a
+description of the commands implemented by dirmngr.
+
+* Menu:
+
+* Dirmngr LOOKUP:: Look up a certificate via LDAP
+* Dirmngr ISVALID:: Validate a certificate using a CRL or OCSP.
+* Dirmngr CHECKCRL:: Validate a certificate using a CRL.
+* Dirmngr CHECKOCSP:: Validate a certificate using OCSP.
+* Dirmngr CACHECERT:: Put a certificate into the internal cache.
+* Dirmngr VALIDATE:: Validate a certificate for debugging.
+
+
+File: gnupg.info, Node: Dirmngr LOOKUP, Next: Dirmngr ISVALID, Up: Dirmngr Protocol
+
+3.6.1 Return the certificate(s) found
+-------------------------------------
+
+Lookup certificate. To allow multiple patterns (which are ORed) quoting
+is required: Spaces are to be translated into "+" or into "%20";
+obviously this requires that the usual escape quoting rules are applied.
+The server responds with:
+
+ S: D <DER encoded certificate>
+ S: END
+ S: D <second DER encoded certificate>
+ S: END
+ S: OK
+
+ In this example 2 certificates are returned. The server may return
+any number of certificates; OK will also be returned when no
+certificates were found. The dirmngr might return a status line
+
+ S: S TRUNCATED <n>
+
+ To indicate that the output was truncated to N items due to a
+limitation of the server or by an arbitrary set limit.
+
+ The option '--url' may be used if instead of a search pattern a
+complete URL to the certificate is known:
+
+ C: LOOKUP --url CN%3DWerner%20Koch,o%3DIntevation%20GmbH,c%3DDE?userCertificate
+
+ If the option '--cache-only' is given, no external lookup is done so
+that only certificates from the cache are returned.
+
+ With the option '--single', the first and only the first match will
+be returned. Unless option '--cache-only' is also used, no local lookup
+will be done in this case.
+
+
+File: gnupg.info, Node: Dirmngr ISVALID, Next: Dirmngr CHECKCRL, Prev: Dirmngr LOOKUP, Up: Dirmngr Protocol
+
+3.6.2 Validate a certificate using a CRL or OCSP
+------------------------------------------------
+
+ ISVALID [--only-ocsp] [--force-default-responder] CERTID|CERTFPR
+
+ Check whether the certificate described by the CERTID has been
+revoked. Due to caching, the Dirmngr is able to answer immediately in
+most cases.
+
+ The CERTID is a hex encoded string consisting of two parts, delimited
+by a single dot. The first part is the SHA-1 hash of the issuer name
+and the second part the serial number.
+
+ Alternatively the certificate's SHA-1 fingerprint CERTFPR may be
+given in which case an OCSP request is done before consulting the CRL.
+If the option '--only-ocsp' is given, no fallback to a CRL check will be
+used. If the option '--force-default-responder' is given, only the
+default OCSP responder will be used and any other methods of obtaining
+an OCSP responder URL won't be used.
+
+Common return values are:
+
+'GPG_ERR_NO_ERROR (0)'
+ This is the positive answer: The certificate is not revoked and we
+ have an up-to-date revocation list for that certificate. If OCSP
+ was used the responder confirmed that the certificate has not been
+ revoked.
+
+'GPG_ERR_CERT_REVOKED'
+ This is the negative answer: The certificate has been revoked.
+ Either it is in a CRL and that list is up to date or an OCSP
+ responder informed us that it has been revoked.
+
+'GPG_ERR_NO_CRL_KNOWN'
+ No CRL is known for this certificate or the CRL is not valid or out
+ of date.
+
+'GPG_ERR_NO_DATA'
+ The OCSP responder returned an "unknown" status. This means that
+ it is not aware of the certificate's status.
+
+'GPG_ERR_NOT_SUPPORTED'
+ This is commonly seen if OCSP support has not been enabled in the
+ configuration.
+
+ If DirMngr has not enough information about the given certificate
+(which is the case for not yet cached certificates), it will inquire the
+missing data:
+
+ S: INQUIRE SENDCERT <CertID>
+ C: D <DER encoded certificate>
+ C: END
+
+ A client should be aware that DirMngr may ask for more than one
+certificate.
+
+ If Dirmngr has a certificate but the signature of the certificate
+could not been validated because the root certificate is not known to
+dirmngr as trusted, it may ask back to see whether the client trusts
+this the root certificate:
+
+ S: INQUIRE ISTRUSTED <CertHexfpr>
+ C: D 1
+ C: END
+
+ Only this answer will let Dirmngr consider the certificate as valid.
+
+
+File: gnupg.info, Node: Dirmngr CHECKCRL, Next: Dirmngr CHECKOCSP, Prev: Dirmngr ISVALID, Up: Dirmngr Protocol
+
+3.6.3 Validate a certificate using a CRL
+----------------------------------------
+
+Check whether the certificate with FINGERPRINT (SHA-1 hash of the entire
+X.509 certificate blob) is valid or not by consulting the CRL
+responsible for this certificate. If the fingerprint has not been given
+or the certificate is not known, the function inquires the certificate
+using:
+
+ S: INQUIRE TARGETCERT
+ C: D <DER encoded certificate>
+ C: END
+
+ Thus the caller is expected to return the certificate for the request
+(which should match FINGERPRINT) as a binary blob. Processing then
+takes place without further interaction; in particular dirmngr tries to
+locate other required certificate by its own mechanism which includes a
+local certificate store as well as a list of trusted root certificates.
+
+The return code is 0 for success; i.e. the certificate has not been
+revoked or one of the usual error codes from libgpg-error.
+
+
+File: gnupg.info, Node: Dirmngr CHECKOCSP, Next: Dirmngr CACHECERT, Prev: Dirmngr CHECKCRL, Up: Dirmngr Protocol
+
+3.6.4 Validate a certificate using OCSP
+---------------------------------------
+
+ CHECKOCSP [--force-default-responder] [FINGERPRINT]
+
+ Check whether the certificate with FINGERPRINT (the SHA-1 hash of the
+entire X.509 certificate blob) is valid by consulting the appropriate
+OCSP responder. If the fingerprint has not been given or the
+certificate is not known by Dirmngr, the function inquires the
+certificate using:
+
+ S: INQUIRE TARGETCERT
+ C: D <DER encoded certificate>
+ C: END
+
+ Thus the caller is expected to return the certificate for the request
+(which should match FINGERPRINT) as a binary blob. Processing then
+takes place without further interaction; in particular dirmngr tries to
+locate other required certificates by its own mechanism which includes a
+local certificate store as well as a list of trusted root certificates.
+
+ If the option '--force-default-responder' is given, only the default
+OCSP responder is used. This option is the per-command variant of the
+global option '--ignore-ocsp-service-url'.
+
+The return code is 0 for success; i.e. the certificate has not been
+revoked or one of the usual error codes from libgpg-error.
+
+
+File: gnupg.info, Node: Dirmngr CACHECERT, Next: Dirmngr VALIDATE, Prev: Dirmngr CHECKOCSP, Up: Dirmngr Protocol
+
+3.6.5 Put a certificate into the internal cache
+-----------------------------------------------
+
+Put a certificate into the internal cache. This command might be useful
+if a client knows in advance certificates required for a test and wants
+to make sure they get added to the internal cache. It is also helpful
+for debugging. To get the actual certificate, this command immediately
+inquires it using
+
+ S: INQUIRE TARGETCERT
+ C: D <DER encoded certificate>
+ C: END
+
+ Thus the caller is expected to return the certificate for the request
+as a binary blob.
+
+The return code is 0 for success; i.e. the certificate has not been
+successfully cached or one of the usual error codes from libgpg-error.
+
+
+File: gnupg.info, Node: Dirmngr VALIDATE, Prev: Dirmngr CACHECERT, Up: Dirmngr Protocol
+
+3.6.6 Validate a certificate for debugging
+------------------------------------------
+
+Validate a certificate using the certificate validation function used
+internally by dirmngr. This command is only useful for debugging. To
+get the actual certificate, this command immediately inquires it using
+
+ S: INQUIRE TARGETCERT
+ C: D <DER encoded certificate>
+ C: END
+
+ Thus the caller is expected to return the certificate for the request
+as a binary blob.
+
+
+File: gnupg.info, Node: Invoking GPG, Next: Invoking GPGSM, Prev: Invoking DIRMNGR, Up: Top
+
+4 Invoking GPG
+**************
+
+'gpg' is the OpenPGP part of the GNU Privacy Guard (GnuPG). It is a tool
+to provide digital encryption and signing services using the OpenPGP
+standard. 'gpg' features complete key management and all the bells and
+whistles you would expect from a full OpenPGP implementation.
+
+ There are two main versions of GnuPG: GnuPG 1.x and GnuPG 2.x. GnuPG
+2.x supports modern encryption algorithms and thus should be preferred
+over GnuPG 1.x. You only need to use GnuPG 1.x if your platform doesn't
+support GnuPG 2.x, or you need support for some features that GnuPG 2.x
+has deprecated, e.g., decrypting data created with PGP-2 keys.
+
+ If you are looking for version 1 of GnuPG, you may find that version
+installed under the name 'gpg1'.
+
+ *Note Option Index::, for an index to 'gpg''s commands and options.
+
+* Menu:
+
+* GPG Commands:: List of all commands.
+* GPG Options:: List of all options.
+* GPG Configuration:: Configuration files.
+* GPG Examples:: Some usage examples.
+
+Developer information:
+* Unattended Usage of GPG:: Using 'gpg' from other programs.
+
+
+File: gnupg.info, Node: GPG Commands, Next: GPG Options, Up: Invoking GPG
+
+4.1 Commands
+============
+
+Commands are not distinguished from options except for the fact that
+only one command is allowed. Generally speaking, irrelevant options are
+silently ignored, and may not be checked for correctness.
+
+ 'gpg' may be run with no commands. In this case it will print a
+warning perform a reasonable action depending on the type of file it is
+given as input (an encrypted message is decrypted, a signature is
+verified, a file containing keys is listed, etc.).
+
+ If you run into any problems, please add the option '--verbose' to
+the invocation to see more diagnostics.
+
+* Menu:
+
+* General GPG Commands:: Commands not specific to the functionality.
+* Operational GPG Commands:: Commands to select the type of operation.
+* OpenPGP Key Management:: How to manage your keys.
+
+
+File: gnupg.info, Node: General GPG Commands, Next: Operational GPG Commands, Up: GPG Commands
+
+4.1.1 Commands not specific to the function
+-------------------------------------------
+
+'--version'
+ Print the program version and licensing information. Note that you
+ cannot abbreviate this command.
+
+'--help'
+'-h'
+ Print a usage message summarizing the most useful command-line
+ options. Note that you cannot arbitrarily abbreviate this command
+ (though you can use its short form '-h').
+
+'--warranty'
+ Print warranty information.
+
+'--dump-options'
+ Print a list of all available options and commands. Note that you
+ cannot abbreviate this command.
+
+
+File: gnupg.info, Node: Operational GPG Commands, Next: OpenPGP Key Management, Prev: General GPG Commands, Up: GPG Commands
+
+4.1.2 Commands to select the type of operation
+----------------------------------------------
+
+'--sign'
+'-s'
+ Sign a message. This command may be combined with '--encrypt' (to
+ sign and encrypt a message), '--symmetric' (to sign and
+ symmetrically encrypt a message), or both '--encrypt' and
+ '--symmetric' (to sign and encrypt a message that can be decrypted
+ using a secret key or a passphrase). The signing key is chosen by
+ default or can be set explicitly using the '--local-user' and
+ '--default-key' options.
+
+'--clear-sign'
+'--clearsign'
+ Make a cleartext signature. The content in a cleartext signature
+ is readable without any special software. OpenPGP software is only
+ needed to verify the signature. cleartext signatures may modify
+ end-of-line whitespace for platform independence and are not
+ intended to be reversible. The signing key is chosen by default or
+ can be set explicitly using the '--local-user' and '--default-key'
+ options.
+
+'--detach-sign'
+'-b'
+ Make a detached signature.
+
+'--encrypt'
+'-e'
+ Encrypt data to one or more public keys. This command may be
+ combined with '--sign' (to sign and encrypt a message),
+ '--symmetric' (to encrypt a message that can be decrypted using a
+ secret key or a passphrase), or '--sign' and '--symmetric' together
+ (for a signed message that can be decrypted using a secret key or a
+ passphrase). '--recipient' and related options specify which
+ public keys to use for encryption.
+
+'--symmetric'
+'-c'
+ Encrypt with a symmetric cipher using a passphrase. The default
+ symmetric cipher used is AES-128, but may be chosen with the
+ '--cipher-algo' option. This command may be combined with '--sign'
+ (for a signed and symmetrically encrypted message), '--encrypt'
+ (for a message that may be decrypted via a secret key or a
+ passphrase), or '--sign' and '--encrypt' together (for a signed
+ message that may be decrypted via a secret key or a passphrase).
+ 'gpg' caches the passphrase used for symmetric encryption so that a
+ decrypt operation may not require that the user needs to enter the
+ passphrase. The option '--no-symkey-cache' can be used to disable
+ this feature.
+
+'--store'
+ Store only (make a simple literal data packet).
+
+'--decrypt'
+'-d'
+ Decrypt the file given on the command line (or STDIN if no file is
+ specified) and write it to STDOUT (or the file specified with
+ '--output'). If the decrypted file is signed, the signature is
+ also verified. This command differs from the default operation, as
+ it never writes to the filename which is included in the file and
+ it rejects files that don't begin with an encrypted message.
+
+'--verify'
+ Assume that the first argument is a signed file and verify it
+ without generating any output. With no arguments, the signature
+ packet is read from STDIN. If only one argument is given, the
+ specified file is expected to include a complete signature.
+
+ With more than one argument, the first argument should specify a
+ file with a detached signature and the remaining files should
+ contain the signed data. To read the signed data from STDIN, use
+ '-' as the second filename. For security reasons, a detached
+ signature will not read the signed material from STDIN if not
+ explicitly specified.
+
+ Note: If the option '--batch' is not used, 'gpg' may assume that a
+ single argument is a file with a detached signature, and it will
+ try to find a matching data file by stripping certain suffixes.
+ Using this historical feature to verify a detached signature is
+ strongly discouraged; you should always specify the data file
+ explicitly.
+
+ Note: When verifying a cleartext signature, 'gpg' verifies only
+ what makes up the cleartext signed data and not any extra data
+ outside of the cleartext signature or the header lines directly
+ following the dash marker line. The option '--output' may be used
+ to write out the actual signed data, but there are other pitfalls
+ with this format as well. It is suggested to avoid cleartext
+ signatures in favor of detached signatures.
+
+ Note: Sometimes the use of the 'gpgv' tool is easier than using the
+ full-fledged 'gpg' with this option. 'gpgv' is designed to compare
+ signed data against a list of trusted keys and returns with success
+ only for a good signature. It has its own manual page.
+
+'--multifile'
+ This modifies certain other commands to accept multiple files for
+ processing on the command line or read from STDIN with each
+ filename on a separate line. This allows for many files to be
+ processed at once. '--multifile' may currently be used along with
+ '--verify', '--encrypt', and '--decrypt'. Note that '--multifile
+ --verify' may not be used with detached signatures.
+
+'--verify-files'
+ Identical to '--multifile --verify'.
+
+'--encrypt-files'
+ Identical to '--multifile --encrypt'.
+
+'--decrypt-files'
+ Identical to '--multifile --decrypt'.
+
+'--list-keys'
+'-k'
+'--list-public-keys'
+ List the specified keys. If no keys are specified, then all keys
+ from the configured public keyrings are listed.
+
+ Never use the output of this command in scripts or other programs.
+ The output is intended only for humans and its format is likely to
+ change. The '--with-colons' option emits the output in a stable,
+ machine-parseable format, which is intended for use by scripts and
+ other programs.
+
+'--list-secret-keys'
+'-K'
+ List the specified secret keys. If no keys are specified, then all
+ known secret keys are listed. A '#' after the initial tags 'sec'
+ or 'ssb' means that the secret key or subkey is currently not
+ usable. We also say that this key has been taken offline (for
+ example, a primary key can be taken offline by exporting the key
+ using the command '--export-secret-subkeys'). A '>' after these
+ tags indicate that the key is stored on a smartcard. See also
+ '--list-keys'.
+
+'--check-signatures'
+'--check-sigs'
+ Same as '--list-keys', but the key signatures are verified and
+ listed too. Note that for performance reasons the revocation
+ status of a signing key is not shown. This command has the same
+ effect as using '--list-keys' with '--with-sig-check'.
+
+ The status of the verification is indicated by a flag directly
+ following the "sig" tag (and thus before the flags described below.
+ A "!" indicates that the signature has been successfully verified,
+ a "-" denotes a bad signature and a "%" is used if an error
+ occurred while checking the signature (e.g. a non supported
+ algorithm). Signatures where the public key is not available are
+ not listed; to see their keyids the command '--list-sigs' can be
+ used.
+
+ For each signature listed, there are several flags in between the
+ signature status flag and keyid. These flags give additional
+ information about each key signature. From left to right, they are
+ the numbers 1-3 for certificate check level (see
+ '--ask-cert-level'), "L" for a local or non-exportable signature
+ (see '--lsign-key'), "R" for a nonRevocable signature (see the
+ '--edit-key' command "nrsign"), "P" for a signature that contains a
+ policy URL (see '--cert-policy-url'), "N" for a signature that
+ contains a notation (see '--cert-notation'), "X" for an eXpired
+ signature (see '--ask-cert-expire'), and the numbers 1-9 or "T" for
+ 10 and above to indicate trust signature levels (see the
+ '--edit-key' command "tsign").
+
+'--locate-keys'
+'--locate-external-keys'
+ Locate the keys given as arguments. This command basically uses
+ the same algorithm as used when locating keys for encryption or
+ signing and may thus be used to see what keys 'gpg' might use. In
+ particular external methods as defined by '--auto-key-locate' may
+ be used to locate a key. Only public keys are listed. The variant
+ '--locate-external-keys' does not consider a locally existing key
+ and can thus be used to force the refresh of a key via the defined
+ external methods.
+
+'--show-keys'
+ This commands takes OpenPGP keys as input and prints information
+ about them in the same way the command '--list-keys' does for
+ locally stored key. In addition the list options
+ 'show-unusable-uids', 'show-unusable-subkeys', 'show-notations' and
+ 'show-policy-urls' are also enabled. As usual for automated
+ processing, this command should be combined with the option
+ '--with-colons'.
+
+'--fingerprint'
+ List all keys (or the specified ones) along with their
+ fingerprints. This is the same output as '--list-keys' but with
+ the additional output of a line with the fingerprint. May also be
+ combined with '--check-signatures'. If this command is given
+ twice, the fingerprints of all secondary keys are listed too. This
+ command also forces pretty printing of fingerprints if the keyid
+ format has been set to "none".
+
+'--list-packets'
+ List only the sequence of packets. This command is only useful for
+ debugging. When used with option '--verbose' the actual MPI values
+ are dumped and not only their lengths. Note that the output of
+ this command may change with new releases.
+
+'--edit-card'
+'--card-edit'
+ Present a menu to work with a smartcard. The subcommand "help"
+ provides an overview on available commands. For a detailed
+ description, please see the Card HOWTO at
+ https://gnupg.org/documentation/howtos.html#GnuPG-cardHOWTO .
+
+'--card-status'
+ Show the content of the smart card.
+
+'--change-pin'
+ Present a menu to allow changing the PIN of a smartcard. This
+ functionality is also available as the subcommand "passwd" with the
+ '--edit-card' command.
+
+'--delete-keys NAME'
+ Remove key from the public keyring. In batch mode either '--yes'
+ is required or the key must be specified by fingerprint. This is a
+ safeguard against accidental deletion of multiple keys. If the
+ exclamation mark syntax is used with the fingerprint of a subkey
+ only that subkey is deleted; if the exclamation mark is used with
+ the fingerprint of the primary key the entire public key is
+ deleted.
+
+'--delete-secret-keys NAME'
+ Remove key from the secret keyring. In batch mode the key must be
+ specified by fingerprint. The option '--yes' can be used to advise
+ gpg-agent not to request a confirmation. This extra pre-caution is
+ done because 'gpg' can't be sure that the secret key (as controlled
+ by gpg-agent) is only used for the given OpenPGP public key. If
+ the exclamation mark syntax is used with the fingerprint of a
+ subkey only the secret part of that subkey is deleted; if the
+ exclamation mark is used with the fingerprint of the primary key
+ only the secret part of the primary key is deleted.
+
+'--delete-secret-and-public-key NAME'
+ Same as '--delete-key', but if a secret key exists, it will be
+ removed first. In batch mode the key must be specified by
+ fingerprint. The option '--yes' can be used to advise gpg-agent
+ not to request a confirmation.
+
+'--export'
+ Either export all keys from all keyrings (default keyrings and
+ those registered via option '--keyring'), or if at least one name
+ is given, those of the given name. The exported keys are written
+ to STDOUT or to the file given with option '--output'. Use
+ together with '--armor' to mail those keys.
+
+'--send-keys KEYIDS'
+ Similar to '--export' but sends the keys to a keyserver.
+ Fingerprints may be used instead of key IDs. Don't send your
+ complete keyring to a keyserver -- select only those keys which are
+ new or changed by you. If no KEYIDS are given, 'gpg' does nothing.
+
+ Take care: Keyservers are by design write only systems and thus it
+ is not possible to ever delete keys once they have been send to a
+ keyserver.
+
+'--export-secret-keys'
+'--export-secret-subkeys'
+ Same as '--export', but exports the secret keys instead. The
+ exported keys are written to STDOUT or to the file given with
+ option '--output'. This command is often used along with the
+ option '--armor' to allow for easy printing of the key for paper
+ backup; however the external tool 'paperkey' does a better job of
+ creating backups on paper. Note that exporting a secret key can be
+ a security risk if the exported keys are sent over an insecure
+ channel.
+
+ The second form of the command has the special property to render
+ the secret part of the primary key useless; this is a GNU extension
+ to OpenPGP and other implementations can not be expected to
+ successfully import such a key. Its intended use is in generating
+ a full key with an additional signing subkey on a dedicated
+ machine. This command then exports the key without the primary key
+ to the main machine.
+
+ GnuPG may ask you to enter the passphrase for the key. This is
+ required, because the internal protection method of the secret key
+ is different from the one specified by the OpenPGP protocol.
+
+'--export-ssh-key'
+ This command is used to export a key in the OpenSSH public key
+ format. It requires the specification of one key by the usual
+ means and exports the latest valid subkey which has an
+ authentication capability to STDOUT or to the file given with
+ option '--output'. That output can directly be added to ssh's
+ 'authorized_key' file.
+
+ By specifying the key to export using a key ID or a fingerprint
+ suffixed with an exclamation mark (!), a specific subkey or the
+ primary key can be exported. This does not even require that the
+ key has the authentication capability flag set.
+
+'--import'
+'--fast-import'
+ Import/merge keys. This adds the given keys to the keyring. The
+ fast version is currently just a synonym.
+
+ There are a few other options which control how this command works.
+ Most notable here is the '--import-options merge-only' option which
+ does not insert new keys but does only the merging of new
+ signatures, user-IDs and subkeys.
+
+'--receive-keys KEYIDS'
+'--recv-keys KEYIDS'
+ Import the keys with the given KEYIDS from a keyserver.
+
+'--refresh-keys'
+ Request updates from a keyserver for keys that already exist on the
+ local keyring. This is useful for updating a key with the latest
+ signatures, user IDs, etc. Calling this with no arguments will
+ refresh the entire keyring.
+
+'--search-keys NAMES'
+ Search the keyserver for the given NAMES. Multiple names given
+ here will be joined together to create the search string for the
+ keyserver. Note that keyservers search for NAMES in a different
+ and simpler way than gpg does. The best choice is to use a mail
+ address. Due to data privacy reasons keyservers may even not even
+ allow searching by user id or mail address and thus may only return
+ results when being used with the '--recv-key' command to search by
+ key fingerprint or keyid.
+
+'--fetch-keys URIS'
+ Retrieve keys located at the specified URIS. Note that different
+ installations of GnuPG may support different protocols (HTTP, FTP,
+ LDAP, etc.). When using HTTPS the system provided root
+ certificates are used by this command.
+
+'--update-trustdb'
+ Do trust database maintenance. This command iterates over all keys
+ and builds the Web of Trust. This is an interactive command
+ because it may have to ask for the "ownertrust" values for keys.
+ The user has to give an estimation of how far she trusts the owner
+ of the displayed key to correctly certify (sign) other keys. GnuPG
+ only asks for the ownertrust value if it has not yet been assigned
+ to a key. Using the '--edit-key' menu, the assigned value can be
+ changed at any time.
+
+'--check-trustdb'
+ Do trust database maintenance without user interaction. From time
+ to time the trust database must be updated so that expired keys or
+ signatures and the resulting changes in the Web of Trust can be
+ tracked. Normally, GnuPG will calculate when this is required and
+ do it automatically unless '--no-auto-check-trustdb' is set. This
+ command can be used to force a trust database check at any time.
+ The processing is identical to that of '--update-trustdb' but it
+ skips keys with a not yet defined "ownertrust".
+
+ For use with cron jobs, this command can be used together with
+ '--batch' in which case the trust database check is done only if a
+ check is needed. To force a run even in batch mode add the option
+ '--yes'.
+
+'--export-ownertrust'
+ Send the ownertrust values to STDOUT. This is useful for backup
+ purposes as these values are the only ones which can't be
+ re-created from a corrupted trustdb. Example:
+ gpg --export-ownertrust > otrust.txt
+
+'--import-ownertrust'
+ Update the trustdb with the ownertrust values stored in 'files' (or
+ STDIN if not given); existing values will be overwritten. In case
+ of a severely damaged trustdb and if you have a recent backup of
+ the ownertrust values (e.g. in the file 'otrust.txt'), you may
+ re-create the trustdb using these commands:
+ cd ~/.gnupg
+ rm trustdb.gpg
+ gpg --import-ownertrust < otrust.txt
+
+'--rebuild-keydb-caches'
+ When updating from version 1.0.6 to 1.0.7 this command should be
+ used to create signature caches in the keyring. It might be handy
+ in other situations too.
+
+'--print-md ALGO'
+'--print-mds'
+ Print message digest of algorithm ALGO for all given files or
+ STDIN. With the second form (or a deprecated "*" for ALGO) digests
+ for all available algorithms are printed.
+
+'--gen-random 0|1|2 COUNT'
+ Emit COUNT random bytes of the given quality level 0, 1 or 2. If
+ COUNT is not given or zero, an endless sequence of random bytes
+ will be emitted. If used with '--armor' the output will be base64
+ encoded. PLEASE, don't use this command unless you know what you
+ are doing; it may remove precious entropy from the system!
+
+'--gen-prime MODE BITS'
+ Use the source, Luke :-). The output format is subject to change
+ with ant release.
+
+'--enarmor'
+'--dearmor'
+ Pack or unpack an arbitrary input into/from an OpenPGP ASCII armor.
+ This is a GnuPG extension to OpenPGP and in general not very
+ useful.
+
+'--tofu-policy {auto|good|unknown|bad|ask} KEYS'
+ Set the TOFU policy for all the bindings associated with the
+ specified KEYS. For more information about the meaning of the
+ policies, *note trust-model-tofu::. The KEYS may be specified
+ either by their fingerprint (preferred) or their keyid.
+
+
+File: gnupg.info, Node: OpenPGP Key Management, Prev: Operational GPG Commands, Up: GPG Commands
+
+4.1.3 How to manage your keys
+-----------------------------
+
+This section explains the main commands for key management.
+
+'--quick-generate-key USER-ID [ALGO [USAGE [EXPIRE]]]'
+'--quick-gen-key'
+ This is a simple command to generate a standard key with one user
+ id. In contrast to '--generate-key' the key is generated directly
+ without the need to answer a bunch of prompts. Unless the option
+ '--yes' is given, the key creation will be canceled if the given
+ user id already exists in the keyring.
+
+ If invoked directly on the console without any special options an
+ answer to a "Continue?" style confirmation prompt is required. In
+ case the user id already exists in the keyring a second prompt to
+ force the creation of the key will show up.
+
+ If ALGO or USAGE are given, only the primary key is created and no
+ prompts are shown. To specify an expiration date but still create
+ a primary and subkey use "default" or "future-default" for ALGO and
+ "default" for USAGE. For a description of these optional arguments
+ see the command '--quick-add-key'. The USAGE accepts also the
+ value "cert" which can be used to create a certification only
+ primary key; the default is to a create certification and signing
+ key.
+
+ The EXPIRE argument can be used to specify an expiration date for
+ the key. Several formats are supported; commonly the ISO formats
+ "YYYY-MM-DD" or "YYYYMMDDThhmmss" are used. To make the key expire
+ in N seconds, N days, N weeks, N months, or N years use
+ "seconds=N", "Nd", "Nw", "Nm", or "Ny" respectively. Not
+ specifying a value, or using "-" results in a key expiring in a
+ reasonable default interval. The values "never", "none" can be
+ used for no expiration date.
+
+ If this command is used with '--batch', '--pinentry-mode' has been
+ set to 'loopback', and one of the passphrase options
+ ('--passphrase', '--passphrase-fd', or 'passphrase-file') is used,
+ the supplied passphrase is used for the new key and the agent does
+ not ask for it. To create a key without any protection
+ '--passphrase ''' may be used.
+
+ To create an OpenPGP key from the keys available on the currently
+ inserted smartcard, the special string "card" can be used for ALGO.
+ If the card features an encryption and a signing key, gpg will
+ figure them out and creates an OpenPGP key consisting of the usual
+ primary key and one subkey. This works only with certain
+ smartcards. Note that the interactive '--full-gen-key' command
+ allows to do the same but with greater flexibility in the selection
+ of the smartcard keys.
+
+ Note that it is possible to create a primary key and a subkey using
+ non-default algorithms by using "default" and changing the default
+ parameters using the option '--default-new-key-algo'.
+
+'--quick-set-expire FPR EXPIRE [*|SUBFPRS]'
+ With two arguments given, directly set the expiration time of the
+ primary key identified by FPR to EXPIRE. To remove the expiration
+ time '0' can be used. With three arguments and the third given as
+ an asterisk, the expiration time of all non-revoked and not yet
+ expired subkeys are set to EXPIRE. With more than two arguments
+ and a list of fingerprints given for SUBFPRS, all non-revoked
+ subkeys matching these fingerprints are set to EXPIRE.
+
+'--quick-add-key FPR [ALGO [USAGE [EXPIRE]]]'
+ Directly add a subkey to the key identified by the fingerprint FPR.
+ Without the optional arguments an encryption subkey is added. If
+ any of the arguments are given a more specific subkey is added.
+
+ ALGO may be any of the supported algorithms or curve names given in
+ the format as used by key listings. To use the default algorithm
+ the string "default" or "-" can be used. Supported algorithms are
+ "rsa", "dsa", "elg", "ed25519", "cv25519", and other ECC curves.
+ For example the string "rsa" adds an RSA key with the default key
+ length; a string "rsa4096" requests that the key length is 4096
+ bits. The string "future-default" is an alias for the algorithm
+ which will likely be used as default algorithm in future versions
+ of gpg. To list the supported ECC curves the command 'gpg
+ --with-colons --list-config curve' can be used.
+
+ Depending on the given ALGO the subkey may either be an encryption
+ subkey or a signing subkey. If an algorithm is capable of signing
+ and encryption and such a subkey is desired, a USAGE string must be
+ given. This string is either "default" or "-" to keep the default
+ or a comma delimited list (or space delimited list) of keywords:
+ "sign" for a signing subkey, "auth" for an authentication subkey,
+ and "encr" for an encryption subkey ("encrypt" can be used as alias
+ for "encr"). The valid combinations depend on the algorithm.
+
+ The EXPIRE argument can be used to specify an expiration date for
+ the key. Several formats are supported; commonly the ISO formats
+ "YYYY-MM-DD" or "YYYYMMDDThhmmss" are used. To make the key expire
+ in N seconds, N days, N weeks, N months, or N years use
+ "seconds=N", "Nd", "Nw", "Nm", or "Ny" respectively. Not
+ specifying a value, or using "-" results in a key expiring in a
+ reasonable default interval. The values "never", "none" can be
+ used for no expiration date.
+
+'--generate-key'
+'--gen-key'
+ Generate a new key pair using the current default parameters. This
+ is the standard command to create a new key. In addition to the
+ key a revocation certificate is created and stored in the
+ 'openpgp-revocs.d' directory below the GnuPG home directory.
+
+'--full-generate-key'
+'--full-gen-key'
+ Generate a new key pair with dialogs for all options. This is an
+ extended version of '--generate-key'.
+
+ There is also a feature which allows you to create keys in batch
+ mode. See the manual section "Unattended key generation" on how to
+ use this.
+
+'--generate-revocation NAME'
+'--gen-revoke NAME'
+ Generate a revocation certificate for the complete key. To only
+ revoke a subkey or a key signature, use the '--edit' command.
+
+ This command merely creates the revocation certificate so that it
+ can be used to revoke the key if that is ever needed. To actually
+ revoke a key the created revocation certificate needs to be merged
+ with the key to revoke. This is done by importing the revocation
+ certificate using the '--import' command. Then the revoked key
+ needs to be published, which is best done by sending the key to a
+ keyserver (command '--send-key') and by exporting ('--export') it
+ to a file which is then send to frequent communication partners.
+
+'--generate-designated-revocation NAME'
+'--desig-revoke NAME'
+ Generate a designated revocation certificate for a key. This
+ allows a user (with the permission of the keyholder) to revoke
+ someone else's key.
+
+'--edit-key'
+ Present a menu which enables you to do most of the key management
+ related tasks. It expects the specification of a key on the
+ command line.
+
+ uid N
+ Toggle selection of user ID or photographic user ID with index
+ N. Use '*' to select all and '0' to deselect all.
+
+ key N
+ Toggle selection of subkey with index N or key ID N. Use '*'
+ to select all and '0' to deselect all.
+
+ sign
+ Make a signature on key of user 'name'. If the key is not yet
+ signed by the default user (or the users given with '-u'), the
+ program displays the information of the key again, together
+ with its fingerprint and asks whether it should be signed.
+ This question is repeated for all users specified with '-u'.
+
+ lsign
+ Same as "sign" but the signature is marked as non-exportable
+ and will therefore never be used by others. This may be used
+ to make keys valid only in the local environment.
+
+ nrsign
+ Same as "sign" but the signature is marked as non-revocable
+ and can therefore never be revoked.
+
+ tsign
+ Make a trust signature. This is a signature that combines the
+ notions of certification (like a regular signature), and trust
+ (like the "trust" command). It is generally only useful in
+ distinct communities or groups. For more information please
+ read the sections "Trust Signature" and "Regular Expression"
+ in RFC-4880.
+
+ Note that "l" (for local / non-exportable), "nr" (for
+ non-revocable, and "t" (for trust) may be freely mixed and prefixed
+ to "sign" to create a signature of any type desired.
+
+ If the option '--only-sign-text-ids' is specified, then any
+ non-text based user ids (e.g., photo IDs) will not be selected for
+ signing.
+
+ delsig
+ Delete a signature. Note that it is not possible to retract a
+ signature, once it has been send to the public (i.e. to a
+ keyserver). In that case you better use 'revsig'.
+
+ revsig
+ Revoke a signature. For every signature which has been
+ generated by one of the secret keys, GnuPG asks whether a
+ revocation certificate should be generated.
+
+ check
+ Check the signatures on all selected user IDs. With the extra
+ option 'selfsig' only self-signatures are shown.
+
+ adduid
+ Create an additional user ID.
+
+ addphoto
+ Create a photographic user ID. This will prompt for a JPEG
+ file that will be embedded into the user ID. Note that a very
+ large JPEG will make for a very large key. Also note that
+ some programs will display your JPEG unchanged (GnuPG), and
+ some programs will scale it to fit in a dialog box (PGP).
+
+ showphoto
+ Display the selected photographic user ID.
+
+ deluid
+ Delete a user ID or photographic user ID. Note that it is not
+ possible to retract a user id, once it has been send to the
+ public (i.e. to a keyserver). In that case you better use
+ 'revuid'.
+
+ revuid
+ Revoke a user ID or photographic user ID.
+
+ primary
+ Flag the current user id as the primary one, removes the
+ primary user id flag from all other user ids and sets the
+ timestamp of all affected self-signatures one second ahead.
+ Note that setting a photo user ID as primary makes it primary
+ over other photo user IDs, and setting a regular user ID as
+ primary makes it primary over other regular user IDs.
+
+ keyserver
+ Set a preferred keyserver for the specified user ID(s). This
+ allows other users to know where you prefer they get your key
+ from. See '--keyserver-options honor-keyserver-url' for more
+ on how this works. Setting a value of "none" removes an
+ existing preferred keyserver.
+
+ notation
+ Set a name=value notation for the specified user ID(s). See
+ '--cert-notation' for more on how this works. Setting a value
+ of "none" removes all notations, setting a notation prefixed
+ with a minus sign (-) removes that notation, and setting a
+ notation name (without the =value) prefixed with a minus sign
+ removes all notations with that name.
+
+ pref
+ List preferences from the selected user ID. This shows the
+ actual preferences, without including any implied preferences.
+
+ showpref
+ More verbose preferences listing for the selected user ID.
+ This shows the preferences in effect by including the implied
+ preferences of 3DES (cipher), SHA-1 (digest), and Uncompressed
+ (compression) if they are not already included in the
+ preference list. In addition, the preferred keyserver and
+ signature notations (if any) are shown.
+
+ setpref STRING
+ Set the list of user ID preferences to STRING for all (or just
+ the selected) user IDs. Calling setpref with no arguments
+ sets the preference list to the default (either built-in or
+ set via '--default-preference-list'), and calling setpref with
+ "none" as the argument sets an empty preference list. Use
+ 'gpg --version' to get a list of available algorithms. Note
+ that while you can change the preferences on an attribute user
+ ID (aka "photo ID"), GnuPG does not select keys via attribute
+ user IDs so these preferences will not be used by GnuPG.
+
+ When setting preferences, you should list the algorithms in
+ the order which you'd like to see them used by someone else
+ when encrypting a message to your key. If you don't include
+ 3DES, it will be automatically added at the end. Note that
+ there are many factors that go into choosing an algorithm (for
+ example, your key may not be the only recipient), and so the
+ remote OpenPGP application being used to send to you may or
+ may not follow your exact chosen order for a given message.
+ It will, however, only choose an algorithm that is present on
+ the preference list of every recipient key. See also the
+ INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS section below.
+
+ addkey
+ Add a subkey to this key.
+
+ addcardkey
+ Generate a subkey on a card and add it to this key.
+
+ keytocard
+ Transfer the selected secret subkey (or the primary key if no
+ subkey has been selected) to a smartcard. The secret key in
+ the keyring will be replaced by a stub if the key could be
+ stored successfully on the card and you use the save command
+ later. Only certain key types may be transferred to the card.
+ A sub menu allows you to select on what card to store the key.
+ Note that it is not possible to get that key back from the
+ card - if the card gets broken your secret key will be lost
+ unless you have a backup somewhere.
+
+ bkuptocard FILE
+ Restore the given FILE to a card. This command may be used to
+ restore a backup key (as generated during card initialization)
+ to a new card. In almost all cases this will be the
+ encryption key. You should use this command only with the
+ corresponding public key and make sure that the file given as
+ argument is indeed the backup to restore. You should then
+ select 2 to restore as encryption key. You will first be
+ asked to enter the passphrase of the backup key and then for
+ the Admin PIN of the card.
+
+ delkey
+ Remove a subkey (secondary key). Note that it is not possible
+ to retract a subkey, once it has been send to the public (i.e.
+ to a keyserver). In that case you better use 'revkey'. Also
+ note that this only deletes the public part of a key.
+
+ revkey
+ Revoke a subkey.
+
+ expire
+ Change the key or subkey expiration time. If a subkey is
+ selected, the expiration time of this subkey will be changed.
+ With no selection, the key expiration of the primary key is
+ changed.
+
+ trust
+ Change the owner trust value for the key. This updates the
+ trust-db immediately and no save is required.
+
+ disable
+ enable
+ Disable or enable an entire key. A disabled key can not
+ normally be used for encryption.
+
+ addrevoker
+ Add a designated revoker to the key. This takes one optional
+ argument: "sensitive". If a designated revoker is marked as
+ sensitive, it will not be exported by default (see
+ export-options).
+
+ passwd
+ Change the passphrase of the secret key.
+
+ toggle
+ This is dummy command which exists only for backward
+ compatibility.
+
+ clean
+ Compact (by removing all signatures except the selfsig) any
+ user ID that is no longer usable (e.g. revoked, or expired).
+ Then, remove any signatures that are not usable by the trust
+ calculations. Specifically, this removes any signature that
+ does not validate, any signature that is superseded by a later
+ signature, revoked signatures, and signatures issued by keys
+ that are not present on the keyring.
+
+ minimize
+ Make the key as small as possible. This removes all
+ signatures from each user ID except for the most recent
+ self-signature.
+
+ change-usage
+ Change the usage flags (capabilities) of the primary key or of
+ subkeys. These usage flags (e.g. Certify, Sign,
+ Authenticate, Encrypt) are set during key creation. Sometimes
+ it is useful to have the opportunity to change them (for
+ example to add Authenticate) after they have been created.
+ Please take care when doing this; the allowed usage flags
+ depend on the key algorithm.
+
+ cross-certify
+ Add cross-certification signatures to signing subkeys that may
+ not currently have them. Cross-certification signatures
+ protect against a subtle attack against signing subkeys. See
+ '--require-cross-certification'. All new keys generated have
+ this signature by default, so this command is only useful to
+ bring older keys up to date.
+
+ save
+ Save all changes to the keyrings and quit.
+
+ quit
+ Quit the program without updating the keyrings.
+
+ The listing shows you the key with its secondary keys and all user
+ IDs. The primary user ID is indicated by a dot, and selected keys
+ or user IDs are indicated by an asterisk. The trust value is
+ displayed with the primary key: "trust" is the assigned owner trust
+ and "validity" is the calculated validity of the key. Validity
+ values are also displayed for all user IDs. For possible values of
+ trust, *note trust-values::.
+
+'--sign-key NAME'
+ Signs a public key with your secret key. This is a shortcut
+ version of the subcommand "sign" from '--edit'.
+
+'--lsign-key NAME'
+ Signs a public key with your secret key but marks it as
+ non-exportable. This is a shortcut version of the subcommand
+ "lsign" from '--edit-key'.
+
+'--quick-sign-key FPR [NAMES]'
+'--quick-lsign-key FPR [NAMES]'
+ Directly sign a key from the passphrase without any further user
+ interaction. The FPR must be the verified primary fingerprint of a
+ key in the local keyring. If no NAMES are given, all useful user
+ ids are signed; with given [NAMES] only useful user ids matching
+ one of theses names are signed. By default, or if a name is
+ prefixed with a '*', a case insensitive substring match is used.
+ If a name is prefixed with a '=' a case sensitive exact match is
+ done.
+
+ The command '--quick-lsign-key' marks the signatures as
+ non-exportable. If such a non-exportable signature already exists
+ the '--quick-sign-key' turns it into a exportable signature.
+
+ This command uses reasonable defaults and thus does not provide the
+ full flexibility of the "sign" subcommand from '--edit-key'. Its
+ intended use is to help unattended key signing by utilizing a list
+ of verified fingerprints.
+
+'--quick-add-uid USER-ID NEW-USER-ID'
+ This command adds a new user id to an existing key. In contrast to
+ the interactive sub-command 'adduid' of '--edit-key' the
+ NEW-USER-ID is added verbatim with only leading and trailing white
+ space removed, it is expected to be UTF-8 encoded, and no checks on
+ its form are applied.
+
+'--quick-revoke-uid USER-ID USER-ID-TO-REVOKE'
+ This command revokes a user ID on an existing key. It cannot be
+ used to revoke the last user ID on key (some non-revoked user ID
+ must remain), with revocation reason "User ID is no longer valid".
+ If you want to specify a different revocation reason, or to supply
+ supplementary revocation text, you should use the interactive
+ sub-command 'revuid' of '--edit-key'.
+
+'--quick-revoke-sig FPR SIGNING-FPR [NAMES]'
+ This command revokes the key signatures made by SIGNING-FPR from
+ the key specified by the fingerprint FPR. With NAMES given only
+ the signatures on user ids of the key matching any of the given
+ names are affected (see '--quick-sign-key'). If a revocation
+ already exists a notice is printed instead of creating a new
+ revocation; no error is returned in this case. Note that key
+ signature revocations may be superseded by a newer key signature
+ and in turn again revoked.
+
+'--quick-set-primary-uid USER-ID PRIMARY-USER-ID'
+ This command sets or updates the primary user ID flag on an
+ existing key. USER-ID specifies the key and PRIMARY-USER-ID the
+ user ID which shall be flagged as the primary user ID. The primary
+ user ID flag is removed from all other user ids and the timestamp
+ of all affected self-signatures is set one second ahead.
+
+'--change-passphrase USER-ID'
+'--passwd USER-ID'
+ Change the passphrase of the secret key belonging to the
+ certificate specified as USER-ID. This is a shortcut for the
+ sub-command 'passwd' of the edit key menu. When using together
+ with the option '--dry-run' this will not actually change the
+ passphrase but check that the current passphrase is correct.
+
+
+File: gnupg.info, Node: GPG Options, Next: GPG Configuration, Prev: GPG Commands, Up: Invoking GPG
+
+4.2 Option Summary
+==================
+
+'gpg' features a bunch of options to control the exact behaviour and to
+change the default configuration.
+
+* Menu:
+
+* GPG Configuration Options:: How to change the configuration.
+* GPG Key related Options:: Key related options.
+* GPG Input and Output:: Input and Output.
+* OpenPGP Options:: OpenPGP protocol specific options.
+* Compliance Options:: Compliance options.
+* GPG Esoteric Options:: Doing things one usually doesn't want to do.
+* Deprecated Options:: Deprecated options.
+
+ Long options can be put in an options file (default
+"~/.gnupg/gpg.conf"). Short option names will not work - for example,
+"armor" is a valid option for the options file, while "a" is not. Do
+not write the 2 dashes, but simply the name of the option and any
+required arguments. Lines with a hash ('#') as the first
+non-white-space character are ignored. Commands may be put in this file
+too, but that is not generally useful as the command will execute
+automatically with every execution of gpg.
+
+ Please remember that option parsing stops as soon as a non-option is
+encountered, you can explicitly stop parsing by using the special option
+'--'.
+
+
+File: gnupg.info, Node: GPG Configuration Options, Next: GPG Key related Options, Up: GPG Options
+
+4.2.1 How to change the configuration
+-------------------------------------
+
+These options are used to change the configuration and are usually found
+in the option file.
+
+'--default-key NAME'
+ Use NAME as the default key to sign with. If this option is not
+ used, the default key is the first key found in the secret keyring.
+ Note that '-u' or '--local-user' overrides this option. This
+ option may be given multiple times. In this case, the last key for
+ which a secret key is available is used. If there is no secret key
+ available for any of the specified values, GnuPG will not emit an
+ error message but continue as if this option wasn't given.
+
+'--default-recipient NAME'
+ Use NAME as default recipient if option '--recipient' is not used
+ and don't ask if this is a valid one. NAME must be non-empty.
+
+'--default-recipient-self'
+ Use the default key as default recipient if option '--recipient' is
+ not used and don't ask if this is a valid one. The default key is
+ the first one from the secret keyring or the one set with
+ '--default-key'.
+
+'--no-default-recipient'
+ Reset '--default-recipient' and '--default-recipient-self'.
+
+'-v, --verbose'
+ Give more information during processing. If used twice, the input
+ data is listed in detail.
+
+'--no-verbose'
+ Reset verbose level to 0.
+
+'-q, --quiet'
+ Try to be as quiet as possible.
+
+'--batch'
+'--no-batch'
+ Use batch mode. Never ask, do not allow interactive commands.
+ '--no-batch' disables this option. Note that even with a filename
+ given on the command line, gpg might still need to read from STDIN
+ (in particular if gpg figures that the input is a detached
+ signature and no data file has been specified). Thus if you do not
+ want to feed data via STDIN, you should connect STDIN to
+ g'/dev/null'.
+
+ It is highly recommended to use this option along with the options
+ '--status-fd' and '--with-colons' for any unattended use of 'gpg'.
+
+'--no-tty'
+ Make sure that the TTY (terminal) is never used for any output.
+ This option is needed in some cases because GnuPG sometimes prints
+ warnings to the TTY even if '--batch' is used.
+
+'--yes'
+ Assume "yes" on most questions.
+
+'--no'
+ Assume "no" on most questions.
+
+'--list-options PARAMETERS'
+ This is a space or comma delimited string that gives options used
+ when listing keys and signatures (that is, '--list-keys',
+ '--check-signatures', '--list-public-keys', '--list-secret-keys',
+ and the '--edit-key' functions). Options can be prepended with a
+ 'no-' (after the two dashes) to give the opposite meaning. The
+ options are:
+
+ show-photos
+ Causes '--list-keys', '--check-signatures',
+ '--list-public-keys', and '--list-secret-keys' to display any
+ photo IDs attached to the key. Defaults to no. See also
+ '--photo-viewer'. Does not work with '--with-colons': see
+ '--attribute-fd' for the appropriate way to get photo data for
+ scripts and other frontends.
+
+ show-usage
+ Show usage information for keys and subkeys in the standard
+ key listing. This is a list of letters indicating the allowed
+ usage for a key ('E'=encryption, 'S'=signing,
+ 'C'=certification, 'A'=authentication). Defaults to yes.
+
+ show-policy-urls
+ Show policy URLs in the '--check-signatures' listings.
+ Defaults to no.
+
+ show-notations
+ show-std-notations
+ show-user-notations
+ Show all, IETF standard, or user-defined signature notations
+ in the '--check-signatures' listings. Defaults to no.
+
+ show-keyserver-urls
+ Show any preferred keyserver URL in the '--check-signatures'
+ listings. Defaults to no.
+
+ show-uid-validity
+ Display the calculated validity of user IDs during key
+ listings. Defaults to yes.
+
+ show-unusable-uids
+ Show revoked and expired user IDs in key listings. Defaults
+ to no.
+
+ show-unusable-subkeys
+ Show revoked and expired subkeys in key listings. Defaults to
+ no.
+
+ show-keyring
+ Display the keyring name at the head of key listings to show
+ which keyring a given key resides on. Defaults to no.
+
+ show-sig-expire
+ Show signature expiration dates (if any) during
+ '--check-signatures' listings. Defaults to no.
+
+ show-sig-subpackets
+ Include signature subpackets in the key listing. This option
+ can take an optional argument list of the subpackets to list.
+ If no argument is passed, list all subpackets. Defaults to
+ no. This option is only meaningful when using '--with-colons'
+ along with '--check-signatures'.
+
+ show-only-fpr-mbox
+ For each user-id which has a valid mail address print only the
+ fingerprint followed by the mail address.
+
+'--verify-options PARAMETERS'
+ This is a space or comma delimited string that gives options used
+ when verifying signatures. Options can be prepended with a 'no-'
+ to give the opposite meaning. The options are:
+
+ show-photos
+ Display any photo IDs present on the key that issued the
+ signature. Defaults to no. See also '--photo-viewer'.
+
+ show-policy-urls
+ Show policy URLs in the signature being verified. Defaults to
+ yes.
+
+ show-notations
+ show-std-notations
+ show-user-notations
+ Show all, IETF standard, or user-defined signature notations
+ in the signature being verified. Defaults to IETF standard.
+
+ show-keyserver-urls
+ Show any preferred keyserver URL in the signature being
+ verified. Defaults to yes.
+
+ show-uid-validity
+ Display the calculated validity of the user IDs on the key
+ that issued the signature. Defaults to yes.
+
+ show-unusable-uids
+ Show revoked and expired user IDs during signature
+ verification. Defaults to no.
+
+ show-primary-uid-only
+ Show only the primary user ID during signature verification.
+ That is all the AKA lines as well as photo Ids are not shown
+ with the signature verification status.
+
+ pka-lookups
+ Enable PKA lookups to verify sender addresses. Note that PKA
+ is based on DNS, and so enabling this option may disclose
+ information on when and what signatures are verified or to
+ whom data is encrypted. This is similar to the "web bug"
+ described for the '--auto-key-retrieve' option.
+
+ pka-trust-increase
+ Raise the trust in a signature to full if the signature passes
+ PKA validation. This option is only meaningful if pka-lookups
+ is set.
+
+'--enable-large-rsa'
+'--disable-large-rsa'
+ With -generate-key and -batch, enable the creation of RSA secret
+ keys as large as 8192 bit. Note: 8192 bit is more than is
+ generally recommended. These large keys don't significantly
+ improve security, but they are more expensive to use, and their
+ signatures and certifications are larger. This option is only
+ available if the binary was build with large-secmem support.
+
+'--enable-dsa2'
+'--disable-dsa2'
+ Enable hash truncation for all DSA keys even for old DSA Keys up to
+ 1024 bit. This is also the default with '--openpgp'. Note that
+ older versions of GnuPG also required this flag to allow the
+ generation of DSA larger than 1024 bit.
+
+'--photo-viewer STRING'
+ This is the command line that should be run to view a photo ID.
+ "%i" will be expanded to a filename containing the photo. "%I"
+ does the same, except the file will not be deleted once the viewer
+ exits. Other flags are "%k" for the key ID, "%K" for the long key
+ ID, "%f" for the key fingerprint, "%t" for the extension of the
+ image type (e.g. "jpg"), "%T" for the MIME type of the image (e.g.
+ "image/jpeg"), "%v" for the single-character calculated validity of
+ the image being viewed (e.g. "f"), "%V" for the calculated
+ validity as a string (e.g. "full"), "%U" for a base32 encoded hash
+ of the user ID, and "%%" for an actual percent sign. If neither %i
+ or %I are present, then the photo will be supplied to the viewer on
+ standard input.
+
+ On Unix the default viewer is 'xloadimage -fork -quiet -title
+ 'KeyID 0x%k' STDIN' with a fallback to 'display -title 'KeyID 0x%k'
+ %i' and finally to 'xdg-open %i'. On Windows '!ShellExecute 400
+ %i' is used; here the command is a meta command to use that API
+ call followed by a wait time in milliseconds which is used to give
+ the viewer time to read the temporary image file before gpg deletes
+ it again. Note that if your image viewer program is not secure,
+ then executing it from gpg does not make it secure.
+
+'--exec-path STRING'
+ Sets a list of directories to search for photo viewers If not
+ provided photo viewers use the 'PATH' environment variable.
+
+'--keyring FILE'
+ Add FILE to the current list of keyrings. If FILE begins with a
+ tilde and a slash, these are replaced by the $HOME directory. If
+ the filename does not contain a slash, it is assumed to be in the
+ GnuPG home directory ("~/.gnupg" if '--homedir' or $GNUPGHOME is
+ not used).
+
+ Note that this adds a keyring to the current list. If the intent
+ is to use the specified keyring alone, use '--keyring' along with
+ '--no-default-keyring'.
+
+ If the option '--no-keyring' has been used no keyrings will be used
+ at all.
+
+'--secret-keyring FILE'
+ This is an obsolete option and ignored. All secret keys are stored
+ in the 'private-keys-v1.d' directory below the GnuPG home
+ directory.
+
+'--primary-keyring FILE'
+ Designate FILE as the primary public keyring. This means that
+ newly imported keys (via '--import' or keyserver '--recv-from')
+ will go to this keyring.
+
+'--trustdb-name FILE'
+ Use FILE instead of the default trustdb. If FILE begins with a
+ tilde and a slash, these are replaced by the $HOME directory. If
+ the filename does not contain a slash, it is assumed to be in the
+ GnuPG home directory ('~/.gnupg' if '--homedir' or $GNUPGHOME is
+ not used).
+
+'--homedir DIR'
+ Set the name of the home directory to DIR. If this option is not
+ used, the home directory defaults to '~/.gnupg'. It is only
+ recognized when given on the command line. It also overrides any
+ home directory stated through the environment variable 'GNUPGHOME'
+ or (on Windows systems) by means of the Registry entry
+ HKCU\SOFTWARE\GNU\GNUPG:HOMEDIR.
+
+ On Windows systems it is possible to install GnuPG as a portable
+ application. In this case only this command line option is
+ considered, all other ways to set a home directory are ignored.
+
+ To install GnuPG as a portable application under Windows, create an
+ empty file named 'gpgconf.ctl' in the same directory as the tool
+ 'gpgconf.exe'. The root of the installation is then that
+ directory; or, if 'gpgconf.exe' has been installed directly below a
+ directory named 'bin', its parent directory. You also need to make
+ sure that the following directories exist and are writable:
+ 'ROOT/home' for the GnuPG home and 'ROOT/usr/local/var/cache/gnupg'
+ for internal cache files.
+
+'--display-charset NAME'
+ Set the name of the native character set. This is used to convert
+ some informational strings like user IDs to the proper UTF-8
+ encoding. Note that this has nothing to do with the character set
+ of data to be encrypted or signed; GnuPG does not recode
+ user-supplied data. If this option is not used, the default
+ character set is determined from the current locale. A verbosity
+ level of 3 shows the chosen set. Valid values for NAME are:
+
+ iso-8859-1
+ This is the Latin 1 set.
+
+ iso-8859-2
+ The Latin 2 set.
+
+ iso-8859-15
+ This is currently an alias for the Latin 1 set.
+
+ koi8-r
+ The usual Russian set (RFC-1489).
+
+ utf-8
+ Bypass all translations and assume that the OS uses native
+ UTF-8 encoding.
+
+'--utf8-strings'
+'--no-utf8-strings'
+ Assume that command line arguments are given as UTF-8 strings. The
+ default ('--no-utf8-strings') is to assume that arguments are
+ encoded in the character set as specified by '--display-charset'.
+ These options affect all following arguments. Both options may be
+ used multiple times.
+
+'--options FILE'
+ Read options from FILE and do not try to read them from the default
+ options file in the homedir (see '--homedir'). This option is
+ ignored if used in an options file.
+
+'--no-options'
+ Shortcut for '--options /dev/null'. This option is detected before
+ an attempt to open an option file. Using this option will also
+ prevent the creation of a '~/.gnupg' homedir.
+
+'-z N'
+'--compress-level N'
+'--bzip2-compress-level N'
+ Set compression level to N for the ZIP and ZLIB compression
+ algorithms. The default is to use the default compression level of
+ zlib (normally 6). '--bzip2-compress-level' sets the compression
+ level for the BZIP2 compression algorithm (defaulting to 6 as
+ well). This is a different option from '--compress-level' since
+ BZIP2 uses a significant amount of memory for each additional
+ compression level. '-z' sets both. A value of 0 for N disables
+ compression.
+
+'--bzip2-decompress-lowmem'
+ Use a different decompression method for BZIP2 compressed files.
+ This alternate method uses a bit more than half the memory, but
+ also runs at half the speed. This is useful under extreme low
+ memory circumstances when the file was originally compressed at a
+ high '--bzip2-compress-level'.
+
+'--mangle-dos-filenames'
+'--no-mangle-dos-filenames'
+ Older version of Windows cannot handle filenames with more than one
+ dot. '--mangle-dos-filenames' causes GnuPG to replace (rather than
+ add to) the extension of an output filename to avoid this problem.
+ This option is off by default and has no effect on non-Windows
+ platforms.
+
+'--ask-cert-level'
+'--no-ask-cert-level'
+ When making a key signature, prompt for a certification level. If
+ this option is not specified, the certification level used is set
+ via '--default-cert-level'. See '--default-cert-level' for
+ information on the specific levels and how they are used.
+ '--no-ask-cert-level' disables this option. This option defaults
+ to no.
+
+'--default-cert-level N'
+ The default to use for the check level when signing a key.
+
+ 0 means you make no particular claim as to how carefully you
+ verified the key.
+
+ 1 means you believe the key is owned by the person who claims to
+ own it but you could not, or did not verify the key at all. This
+ is useful for a "persona" verification, where you sign the key of a
+ pseudonymous user.
+
+ 2 means you did casual verification of the key. For example, this
+ could mean that you verified the key fingerprint and checked the
+ user ID on the key against a photo ID.
+
+ 3 means you did extensive verification of the key. For example,
+ this could mean that you verified the key fingerprint with the
+ owner of the key in person, and that you checked, by means of a
+ hard to forge document with a photo ID (such as a passport) that
+ the name of the key owner matches the name in the user ID on the
+ key, and finally that you verified (by exchange of email) that the
+ email address on the key belongs to the key owner.
+
+ Note that the examples given above for levels 2 and 3 are just
+ that: examples. In the end, it is up to you to decide just what
+ "casual" and "extensive" mean to you.
+
+ This option defaults to 0 (no particular claim).
+
+'--min-cert-level'
+ When building the trust database, treat any signatures with a
+ certification level below this as invalid. Defaults to 2, which
+ disregards level 1 signatures. Note that level 0 "no particular
+ claim" signatures are always accepted.
+
+'--trusted-key LONG KEY ID OR FINGERPRINT'
+ Assume that the specified key (which must be given as a full 8 byte
+ key ID or 20 byte fingerprint) is as trustworthy as one of your own
+ secret keys. This option is useful if you don't want to keep your
+ secret keys (or one of them) online but still want to be able to
+ check the validity of a given recipient's or signator's key.
+
+'--trust-model {pgp|classic|tofu|tofu+pgp|direct|always|auto}'
+ Set what trust model GnuPG should follow. The models are:
+
+ pgp
+ This is the Web of Trust combined with trust signatures as
+ used in PGP 5.x and later. This is the default trust model
+ when creating a new trust database.
+
+ classic
+ This is the standard Web of Trust as introduced by PGP 2.
+
+ tofu
+ TOFU stands for Trust On First Use. In this trust model, the
+ first time a key is seen, it is memorized. If later another
+ key with a user id with the same email address is seen, both
+ keys are marked as suspect. In that case, the next time
+ either is used, a warning is displayed describing the
+ conflict, why it might have occurred (either the user
+ generated a new key and failed to cross sign the old and new
+ keys, the key is forgery, or a man-in-the-middle attack is
+ being attempted), and the user is prompted to manually confirm
+ the validity of the key in question.
+
+ Because a potential attacker is able to control the email
+ address and thereby circumvent the conflict detection
+ algorithm by using an email address that is similar in
+ appearance to a trusted email address, whenever a message is
+ verified, statistics about the number of messages signed with
+ the key are shown. In this way, a user can easily identify
+ attacks using fake keys for regular correspondents.
+
+ When compared with the Web of Trust, TOFU offers significantly
+ weaker security guarantees. In particular, TOFU only helps
+ ensure consistency (that is, that the binding between a key
+ and email address doesn't change). A major advantage of TOFU
+ is that it requires little maintenance to use correctly. To
+ use the web of trust properly, you need to actively sign keys
+ and mark users as trusted introducers. This is a
+ time-consuming process and anecdotal evidence suggests that
+ even security-conscious users rarely take the time to do this
+ thoroughly and instead rely on an ad-hoc TOFU process.
+
+ In the TOFU model, policies are associated with bindings
+ between keys and email addresses (which are extracted from
+ user ids and normalized). There are five policies, which can
+ be set manually using the '--tofu-policy' option. The default
+ policy can be set using the '--tofu-default-policy' option.
+
+ The TOFU policies are: 'auto', 'good', 'unknown', 'bad' and
+ 'ask'. The 'auto' policy is used by default (unless
+ overridden by '--tofu-default-policy') and marks a binding as
+ marginally trusted. The 'good', 'unknown' and 'bad' policies
+ mark a binding as fully trusted, as having unknown trust or as
+ having trust never, respectively. The 'unknown' policy is
+ useful for just using TOFU to detect conflicts, but to never
+ assign positive trust to a binding. The final policy, 'ask'
+ prompts the user to indicate the binding's trust. If batch
+ mode is enabled (or input is inappropriate in the context),
+ then the user is not prompted and the 'undefined' trust level
+ is returned.
+
+ tofu+pgp
+ This trust model combines TOFU with the Web of Trust. This is
+ done by computing the trust level for each model and then
+ taking the maximum trust level where the trust levels are
+ ordered as follows: 'unknown < undefined < marginal < fully <
+ ultimate < expired < never'.
+
+ By setting '--tofu-default-policy=unknown', this model can be
+ used to implement the web of trust with TOFU's conflict
+ detection algorithm, but without its assignment of positive
+ trust values, which some security-conscious users don't like.
+
+ direct
+ Key validity is set directly by the user and not calculated
+ via the Web of Trust. This model is solely based on the key
+ and does not distinguish user IDs. Note that when changing to
+ another trust model the trust values assigned to a key are
+ transformed into ownertrust values, which also indicate how
+ you trust the owner of the key to sign other keys.
+
+ always
+ Skip key validation and assume that used keys are always fully
+ valid. You generally won't use this unless you are using some
+ external validation scheme. This option also suppresses the
+ "[uncertain]" tag printed with signature checks when there is
+ no evidence that the user ID is bound to the key. Note that
+ this trust model still does not allow the use of expired,
+ revoked, or disabled keys.
+
+ auto
+ Select the trust model depending on whatever the internal
+ trust database says. This is the default model if such a
+ database already exists. Note that a tofu trust model is not
+ considered here and must be enabled explicitly.
+
+'--auto-key-locate MECHANISMS'
+'--no-auto-key-locate'
+ GnuPG can automatically locate and retrieve keys as needed using
+ this option. This happens when encrypting to an email address (in
+ the "user@example.com" form), and there are no "user@example.com"
+ keys on the local keyring. This option takes any number of the
+ mechanisms listed below, in the order they are to be tried.
+ Instead of listing the mechanisms as comma delimited arguments, the
+ option may also be given several times to add more mechanism. The
+ option '--no-auto-key-locate' or the mechanism "clear" resets the
+ list. The default is "local,wkd".
+
+ cert
+ Locate a key using DNS CERT, as specified in RFC-4398.
+
+ pka
+ Locate a key using DNS PKA.
+
+ dane
+ Locate a key using DANE, as specified in
+ draft-ietf-dane-openpgpkey-05.txt.
+
+ wkd
+ Locate a key using the Web Key Directory protocol.
+
+ ldap
+ Using DNS Service Discovery, check the domain in question for
+ any LDAP keyservers to use. If this fails, attempt to locate
+ the key using the PGP Universal method of checking
+ 'ldap://keys.(thedomain)'.
+
+ ntds
+ Locate the key using the Active Directory (Windows only).
+
+ keyserver
+ Locate a key using a keyserver.
+
+ keyserver-URL
+ In addition, a keyserver URL as used in the 'dirmngr'
+ configuration may be used here to query that particular
+ keyserver.
+
+ local
+ Locate the key using the local keyrings. This mechanism
+ allows the user to select the order a local key lookup is
+ done. Thus using '--auto-key-locate local' is identical to
+ '--no-auto-key-locate'.
+
+ nodefault
+ This flag disables the standard local key lookup, done before
+ any of the mechanisms defined by the '--auto-key-locate' are
+ tried. The position of this mechanism in the list does not
+ matter. It is not required if 'local' is also used.
+
+ clear
+ Clear all defined mechanisms. This is useful to override
+ mechanisms given in a config file. Note that a 'nodefault' in
+ MECHANISMS will also be cleared unless it is given after the
+ 'clear'.
+
+'--auto-key-import'
+'--no-auto-key-import'
+ This is an offline mechanism to get a missing key for signature
+ verification and for later encryption to this key. If this option
+ is enabled and a signature includes an embedded key, that key is
+ used to verify the signature and on verification success that key
+ is imported. The default is '--no-auto-key-import'.
+
+ On the sender (signing) site the option '--include-key-block' needs
+ to be used to put the public part of the signing key as “Key Block
+ subpacket” into the signature.
+
+'--auto-key-retrieve'
+'--no-auto-key-retrieve'
+ These options enable or disable the automatic retrieving of keys
+ from a keyserver when verifying signatures made by keys that are
+ not on the local keyring. The default is '--no-auto-key-retrieve'.
+
+ The order of methods tried to lookup the key is:
+
+ 1. If the option '--auto-key-import' is set and the signatures
+ includes an embedded key, that key is used to verify the signature
+ and on verification success that key is imported.
+
+ 2. If a preferred keyserver is specified in the signature and the
+ option 'honor-keyserver-url' is active (which is not the default),
+ that keyserver is tried. Note that the creator of the signature
+ uses the option '--sig-keyserver-url' to specify the preferred
+ keyserver for data signatures.
+
+ 3. If the signature has the Signer's UID set (e.g. using
+ '--sender' while creating the signature) a Web Key Directory (WKD)
+ lookup is done. This is the default configuration but can be
+ disabled by removing WKD from the auto-key-locate list or by using
+ the option '--disable-signer-uid'.
+
+ 4. If the option 'honor-pka-record' is active, the legacy PKA
+ method is used.
+
+ 5. If any keyserver is configured and the Issuer Fingerprint is
+ part of the signature (since GnuPG 2.1.16), the configured
+ keyservers are tried.
+
+ Note that this option makes a "web bug" like behavior possible.
+ Keyserver or Web Key Directory operators can see which keys you
+ request, so by sending you a message signed by a brand new key
+ (which you naturally will not have on your local keyring), the
+ operator can tell both your IP address and the time when you
+ verified the signature.
+
+'--keyid-format {none|short|0xshort|long|0xlong}'
+ Select how to display key IDs. "none" does not show the key ID at
+ all but shows the fingerprint in a separate line. "short" is the
+ traditional 8-character key ID. "long" is the more accurate (but
+ less convenient) 16-character key ID. Add an "0x" to either to
+ include an "0x" at the beginning of the key ID, as in 0x99242560.
+ Note that this option is ignored if the option '--with-colons' is
+ used.
+
+'--keyserver NAME'
+ This option is deprecated - please use the '--keyserver' in
+ 'dirmngr.conf' instead.
+
+ Use NAME as your keyserver. This is the server that
+ '--receive-keys', '--send-keys', and '--search-keys' will
+ communicate with to receive keys from, send keys to, and search for
+ keys on. The format of the NAME is a URI:
+ 'scheme:[//]keyservername[:port]' The scheme is the type of
+ keyserver: "hkp" for the HTTP (or compatible) keyservers, "ldap"
+ for the LDAP keyservers, or "mailto" for the Graff email keyserver.
+ Note that your particular installation of GnuPG may have other
+ keyserver types available as well. Keyserver schemes are
+ case-insensitive. After the keyserver name, optional keyserver
+ configuration options may be provided. These are the same as the
+ global '--keyserver-options' from below, but apply only to this
+ particular keyserver.
+
+ Most keyservers synchronize with each other, so there is generally
+ no need to send keys to more than one server. The keyserver
+ 'hkp://keys.gnupg.net' uses round robin DNS to give a different
+ keyserver each time you use it.
+
+'--keyserver-options {NAME=VALUE}'
+ This is a space or comma delimited string that gives options for
+ the keyserver. Options can be prefixed with a 'no-' to give the
+ opposite meaning. Valid import-options or export-options may be
+ used here as well to apply to importing ('--recv-key') or exporting
+ ('--send-key') a key from a keyserver. While not all options are
+ available for all keyserver types, some common options are:
+
+ include-revoked
+ When searching for a key with '--search-keys', include keys
+ that are marked on the keyserver as revoked. Note that not
+ all keyservers differentiate between revoked and unrevoked
+ keys, and for such keyservers this option is meaningless.
+ Note also that most keyservers do not have cryptographic
+ verification of key revocations, and so turning this option
+ off may result in skipping keys that are incorrectly marked as
+ revoked.
+
+ include-disabled
+ When searching for a key with '--search-keys', include keys
+ that are marked on the keyserver as disabled. Note that this
+ option is not used with HKP keyservers.
+
+ auto-key-retrieve
+ This is an obsolete alias for the option 'auto-key-retrieve'.
+ Please do not use it; it will be removed in future versions..
+
+ honor-keyserver-url
+ When using '--refresh-keys', if the key in question has a
+ preferred keyserver URL, then use that preferred keyserver to
+ refresh the key from. In addition, if auto-key-retrieve is
+ set, and the signature being verified has a preferred
+ keyserver URL, then use that preferred keyserver to fetch the
+ key from. Note that this option introduces a "web bug": The
+ creator of the key can see when the keys is refreshed. Thus
+ this option is not enabled by default.
+
+ honor-pka-record
+ If '--auto-key-retrieve' is used, and the signature being
+ verified has a PKA record, then use the PKA information to
+ fetch the key. Defaults to "yes".
+
+ include-subkeys
+ When receiving a key, include subkeys as potential targets.
+ Note that this option is not used with HKP keyservers, as they
+ do not support retrieving keys by subkey id.
+
+ timeout
+ http-proxy=VALUE
+ verbose
+ debug
+ check-cert
+ ca-cert-file
+ These options have no more function since GnuPG 2.1. Use the
+ 'dirmngr' configuration options instead.
+
+ The default list of options is: "self-sigs-only, import-clean,
+ repair-keys, repair-pks-subkey-bug, export-attributes,
+ honor-pka-record".
+
+'--completes-needed N'
+ Number of completely trusted users to introduce a new key signer
+ (defaults to 1).
+
+'--marginals-needed N'
+ Number of marginally trusted users to introduce a new key signer
+ (defaults to 3)
+
+'--tofu-default-policy {auto|good|unknown|bad|ask}'
+ The default TOFU policy (defaults to 'auto'). For more information
+ about the meaning of this option, *note trust-model-tofu::.
+
+'--max-cert-depth N'
+ Maximum depth of a certification chain (default is 5).
+
+'--no-sig-cache'
+ Do not cache the verification status of key signatures. Caching
+ gives a much better performance in key listings. However, if you
+ suspect that your public keyring is not safe against write
+ modifications, you can use this option to disable the caching. It
+ probably does not make sense to disable it because all kind of
+ damage can be done if someone else has write access to your public
+ keyring.
+
+'--auto-check-trustdb'
+'--no-auto-check-trustdb'
+ If GnuPG feels that its information about the Web of Trust has to
+ be updated, it automatically runs the '--check-trustdb' command
+ internally. This may be a time consuming process.
+ '--no-auto-check-trustdb' disables this option.
+
+'--use-agent'
+'--no-use-agent'
+ This is dummy option. 'gpg' always requires the agent.
+
+'--gpg-agent-info'
+ This is dummy option. It has no effect when used with 'gpg'.
+
+'--agent-program FILE'
+ Specify an agent program to be used for secret key operations. The
+ default value is determined by running 'gpgconf' with the option
+ '--list-dirs'. Note that the pipe symbol ('|') is used for a
+ regression test suite hack and may thus not be used in the file
+ name.
+
+'--dirmngr-program FILE'
+ Specify a dirmngr program to be used for keyserver access. The
+ default value is '/usr/local/bin/dirmngr'.
+
+'--disable-dirmngr'
+ Entirely disable the use of the Dirmngr.
+
+'--no-autostart'
+ Do not start the gpg-agent or the dirmngr if it has not yet been
+ started and its service is required. This option is mostly useful
+ on machines where the connection to gpg-agent has been redirected
+ to another machines. If dirmngr is required on the remote machine,
+ it may be started manually using 'gpgconf --launch dirmngr'.
+
+'--lock-once'
+ Lock the databases the first time a lock is requested and do not
+ release the lock until the process terminates.
+
+'--lock-multiple'
+ Release the locks every time a lock is no longer needed. Use this
+ to override a previous '--lock-once' from a config file.
+
+'--lock-never'
+ Disable locking entirely. This option should be used only in very
+ special environments, where it can be assured that only one process
+ is accessing those files. A bootable floppy with a stand-alone
+ encryption system will probably use this. Improper usage of this
+ option may lead to data and key corruption.
+
+'--exit-on-status-write-error'
+ This option will cause write errors on the status FD to immediately
+ terminate the process. That should in fact be the default but it
+ never worked this way and thus we need an option to enable this, so
+ that the change won't break applications which close their end of a
+ status fd connected pipe too early. Using this option along with
+ '--enable-progress-filter' may be used to cleanly cancel long
+ running gpg operations.
+
+'--limit-card-insert-tries N'
+ With N greater than 0 the number of prompts asking to insert a
+ smartcard gets limited to N-1. Thus with a value of 1 gpg won't at
+ all ask to insert a card if none has been inserted at startup.
+ This option is useful in the configuration file in case an
+ application does not know about the smartcard support and waits ad
+ infinitum for an inserted card.
+
+'--no-random-seed-file'
+ GnuPG uses a file to store its internal random pool over
+ invocations. This makes random generation faster; however
+ sometimes write operations are not desired. This option can be
+ used to achieve that with the cost of slower random generation.
+
+'--no-greeting'
+ Suppress the initial copyright message.
+
+'--no-secmem-warning'
+ Suppress the warning about "using insecure memory".
+
+'--no-permission-warning'
+ Suppress the warning about unsafe file and home directory
+ ('--homedir') permissions. Note that the permission checks that
+ GnuPG performs are not intended to be authoritative, but rather
+ they simply warn about certain common permission problems. Do not
+ assume that the lack of a warning means that your system is secure.
+
+ Note that the warning for unsafe '--homedir' permissions cannot be
+ suppressed in the gpg.conf file, as this would allow an attacker to
+ place an unsafe gpg.conf file in place, and use this file to
+ suppress warnings about itself. The '--homedir' permissions
+ warning may only be suppressed on the command line.
+
+'--require-secmem'
+'--no-require-secmem'
+ Refuse to run if GnuPG cannot get secure memory. Defaults to no
+ (i.e. run, but give a warning).
+
+'--require-cross-certification'
+'--no-require-cross-certification'
+ When verifying a signature made from a subkey, ensure that the
+ cross certification "back signature" on the subkey is present and
+ valid. This protects against a subtle attack against subkeys that
+ can sign. Defaults to '--require-cross-certification' for 'gpg'.
+
+'--expert'
+'--no-expert'
+ Allow the user to do certain nonsensical or "silly" things like
+ signing an expired or revoked key, or certain potentially
+ incompatible things like generating unusual key types. This also
+ disables certain warning messages about potentially incompatible
+ actions. As the name implies, this option is for experts only. If
+ you don't fully understand the implications of what it allows you
+ to do, leave this off. '--no-expert' disables this option.
+
+
+File: gnupg.info, Node: GPG Key related Options, Next: GPG Input and Output, Prev: GPG Configuration Options, Up: GPG Options
+
+4.2.2 Key related options
+-------------------------
+
+'--recipient NAME'
+'-r'
+ Encrypt for user id NAME. If this option or '--hidden-recipient'
+ is not specified, GnuPG asks for the user-id unless
+ '--default-recipient' is given.
+
+'--hidden-recipient NAME'
+'-R'
+ Encrypt for user ID NAME, but hide the key ID of this user's key.
+ This option helps to hide the receiver of the message and is a
+ limited countermeasure against traffic analysis. If this option or
+ '--recipient' is not specified, GnuPG asks for the user ID unless
+ '--default-recipient' is given.
+
+'--recipient-file FILE'
+'-f'
+ This option is similar to '--recipient' except that it encrypts to
+ a key stored in the given file. FILE must be the name of a file
+ containing exactly one key. 'gpg' assumes that the key in this
+ file is fully valid.
+
+'--hidden-recipient-file FILE'
+'-F'
+ This option is similar to '--hidden-recipient' except that it
+ encrypts to a key stored in the given file. FILE must be the name
+ of a file containing exactly one key. 'gpg' assumes that the key
+ in this file is fully valid.
+
+'--encrypt-to NAME'
+ Same as '--recipient' but this one is intended for use in the
+ options file and may be used with your own user-id as an
+ "encrypt-to-self". These keys are only used when there are other
+ recipients given either by use of '--recipient' or by the asked
+ user id. No trust checking is performed for these user ids and
+ even disabled keys can be used.
+
+'--hidden-encrypt-to NAME'
+ Same as '--hidden-recipient' but this one is intended for use in
+ the options file and may be used with your own user-id as a hidden
+ "encrypt-to-self". These keys are only used when there are other
+ recipients given either by use of '--recipient' or by the asked
+ user id. No trust checking is performed for these user ids and
+ even disabled keys can be used.
+
+'--no-encrypt-to'
+ Disable the use of all '--encrypt-to' and '--hidden-encrypt-to'
+ keys.
+
+'--group {NAME=VALUE}'
+ Sets up a named group, which is similar to aliases in email
+ programs. Any time the group name is a recipient ('-r' or
+ '--recipient'), it will be expanded to the values specified.
+ Multiple groups with the same name are automatically merged into a
+ single group.
+
+ The values are 'key IDs' or fingerprints, but any key description
+ is accepted. Note that a value with spaces in it will be treated
+ as two different values. Note also there is only one level of
+ expansion -- you cannot make an group that points to another group.
+ When used from the command line, it may be necessary to quote the
+ argument to this option to prevent the shell from treating it as
+ multiple arguments.
+
+'--ungroup NAME'
+ Remove a given entry from the '--group' list.
+
+'--no-groups'
+ Remove all entries from the '--group' list.
+
+'--local-user NAME'
+'-u'
+ Use NAME as the key to sign with. Note that this option overrides
+ '--default-key'.
+
+'--sender MBOX'
+ This option has two purposes. MBOX must either be a complete user
+ id with a proper mail address or just a mail address. When
+ creating a signature this option tells gpg the user id of a key
+ used to make a signature if the key was not directly specified by a
+ user id. When verifying a signature the MBOX is used to restrict
+ the information printed by the TOFU code to matching user ids.
+
+'--try-secret-key NAME'
+ For hidden recipients GPG needs to know the keys to use for trial
+ decryption. The key set with '--default-key' is always tried
+ first, but this is often not sufficient. This option allows
+ setting more keys to be used for trial decryption. Although any
+ valid user-id specification may be used for NAME it makes sense to
+ use at least the long keyid to avoid ambiguities. Note that
+ gpg-agent might pop up a pinentry for a lot keys to do the trial
+ decryption. If you want to stop all further trial decryption you
+ may use close-window button instead of the cancel button.
+
+'--try-all-secrets'
+ Don't look at the key ID as stored in the message but try all
+ secret keys in turn to find the right decryption key. This option
+ forces the behaviour as used by anonymous recipients (created by
+ using '--throw-keyids' or '--hidden-recipient') and might come
+ handy in case where an encrypted message contains a bogus key ID.
+
+'--skip-hidden-recipients'
+'--no-skip-hidden-recipients'
+ During decryption skip all anonymous recipients. This option helps
+ in the case that people use the hidden recipients feature to hide
+ their own encrypt-to key from others. If one has many secret keys
+ this may lead to a major annoyance because all keys are tried in
+ turn to decrypt something which was not really intended for it.
+ The drawback of this option is that it is currently not possible to
+ decrypt a message which includes real anonymous recipients.
+
+
+File: gnupg.info, Node: GPG Input and Output, Next: OpenPGP Options, Prev: GPG Key related Options, Up: GPG Options
+
+4.2.3 Input and Output
+----------------------
+
+'--armor'
+'-a'
+ Create ASCII armored output. The default is to create the binary
+ OpenPGP format.
+
+'--no-armor'
+ Assume the input data is not in ASCII armored format.
+
+'--output FILE'
+'-o FILE'
+ Write output to FILE. To write to stdout use '-' as the filename.
+
+'--max-output N'
+ This option sets a limit on the number of bytes that will be
+ generated when processing a file. Since OpenPGP supports various
+ levels of compression, it is possible that the plaintext of a given
+ message may be significantly larger than the original OpenPGP
+ message. While GnuPG works properly with such messages, there is
+ often a desire to set a maximum file size that will be generated
+ before processing is forced to stop by the OS limits. Defaults to
+ 0, which means "no limit".
+
+'--input-size-hint N'
+ This option can be used to tell GPG the size of the input data in
+ bytes. N must be a positive base-10 number. This option is only
+ useful if the input is not taken from a file. GPG may use this
+ hint to optimize its buffer allocation strategy. It is also used
+ by the '--status-fd' line "PROGRESS" to provide a value for "total"
+ if that is not available by other means.
+
+'--key-origin STRING[,URL]'
+ gpg can track the origin of a key. Certain origins are implicitly
+ known (e.g. keyserver, web key directory) and set. For a standard
+ import the origin of the keys imported can be set with this option.
+ To list the possible values use "help" for STRING. Some origins
+ can store an optional URL argument. That URL can appended to
+ STRING after a comma.
+
+'--import-options PARAMETERS'
+ This is a space or comma delimited string that gives options for
+ importing keys. Options can be prepended with a 'no-' to give the
+ opposite meaning. The options are:
+
+ import-local-sigs
+ Allow importing key signatures marked as "local". This is not
+ generally useful unless a shared keyring scheme is being used.
+ Defaults to no.
+
+ keep-ownertrust
+ Normally possible still existing ownertrust values of a key
+ are cleared if a key is imported. This is in general
+ desirable so that a formerly deleted key does not
+ automatically gain an ownertrust values merely due to import.
+ On the other hand it is sometimes necessary to re-import a
+ trusted set of keys again but keeping already assigned
+ ownertrust values. This can be achieved by using this option.
+
+ repair-pks-subkey-bug
+ During import, attempt to repair the damage caused by the PKS
+ keyserver bug (pre version 0.9.6) that mangles keys with
+ multiple subkeys. Note that this cannot completely repair the
+ damaged key as some crucial data is removed by the keyserver,
+ but it does at least give you back one subkey. Defaults to no
+ for regular '--import' and to yes for keyserver
+ '--receive-keys'.
+
+ import-show
+ show-only
+ Show a listing of the key as imported right before it is
+ stored. This can be combined with the option '--dry-run' to
+ only look at keys; the option 'show-only' is a shortcut for
+ this combination. The command '--show-keys' is another
+ shortcut for this. Note that suffixes like '#' for "sec" and
+ "sbb" lines may or may not be printed.
+
+ import-export
+ Run the entire import code but instead of storing the key to
+ the local keyring write it to the output. The export options
+ 'export-pka' and 'export-dane' affect the output. This option
+ can be used to remove all invalid parts from a key without the
+ need to store it.
+
+ merge-only
+ During import, allow key updates to existing keys, but do not
+ allow any new keys to be imported. Defaults to no.
+
+ import-clean
+ After import, compact (remove all signatures except the
+ self-signature) any user IDs from the new key that are not
+ usable. Then, remove any signatures from the new key that are
+ not usable. This includes signatures that were issued by keys
+ that are not present on the keyring. This option is the same
+ as running the '--edit-key' command "clean" after import.
+ Defaults to no.
+
+ self-sigs-only
+ Accept only self-signatures while importing a key. All other
+ key signatures are skipped at an early import stage. This
+ option can be used with 'keyserver-options' to mitigate
+ attempts to flood a key with bogus signatures from a
+ keyserver. The drawback is that all other valid key
+ signatures, as required by the Web of Trust are also not
+ imported. Note that when using this option along with
+ import-clean it suppresses the final clean step after merging
+ the imported key into the existing key.
+
+ repair-keys
+ After import, fix various problems with the keys. For
+ example, this reorders signatures, and strips duplicate
+ signatures. Defaults to yes.
+
+ import-minimal
+ Import the smallest key possible. This removes all signatures
+ except the most recent self-signature on each user ID. This
+ option is the same as running the '--edit-key' command
+ "minimize" after import. Defaults to no.
+
+ restore
+ import-restore
+ Import in key restore mode. This imports all data which is
+ usually skipped during import; including all GnuPG specific
+ data. All other contradicting options are overridden.
+
+'--import-filter {NAME=EXPR}'
+'--export-filter {NAME=EXPR}'
+ These options define an import/export filter which are applied to
+ the imported/exported keyblock right before it will be
+ stored/written. NAME defines the type of filter to use, EXPR the
+ expression to evaluate. The option can be used several times which
+ then appends more expression to the same NAME.
+
+ The available filter types are:
+
+ keep-uid
+ This filter will keep a user id packet and its dependent
+ packets in the keyblock if the expression evaluates to true.
+
+ drop-subkey
+ This filter drops the selected subkeys. Currently only
+ implemented for -export-filter.
+
+ drop-sig
+ This filter drops the selected key signatures on user ids.
+ Self-signatures are not considered. Currently only
+ implemented for -import-filter.
+
+ For the syntax of the expression see the chapter "FILTER
+ EXPRESSIONS". The property names for the expressions depend on the
+ actual filter type and are indicated in the following table.
+
+ The available properties are:
+
+ uid
+ A string with the user id. (keep-uid)
+
+ mbox
+ The addr-spec part of a user id with mailbox or the empty
+ string. (keep-uid)
+
+ key_algo
+ A number with the public key algorithm of a key or subkey
+ packet. (drop-subkey)
+
+ key_created
+ key_created_d
+ The first is the timestamp a public key or subkey packet was
+ created. The second is the same but given as an ISO string,
+ e.g. "2016-08-17". (drop-subkey)
+
+ fpr
+ The hexified fingerprint of the current subkey or primary key.
+ (drop-subkey)
+
+ primary
+ Boolean indicating whether the user id is the primary one.
+ (keep-uid)
+
+ expired
+ Boolean indicating whether a user id (keep-uid), a key
+ (drop-subkey), or a signature (drop-sig) expired.
+
+ revoked
+ Boolean indicating whether a user id (keep-uid) or a key
+ (drop-subkey) has been revoked.
+
+ disabled
+ Boolean indicating whether a primary key is disabled. (not
+ used)
+
+ secret
+ Boolean indicating whether a key or subkey is a secret one.
+ (drop-subkey)
+
+ usage
+ A string indicating the usage flags for the subkey, from the
+ sequence "ecsa?". For example, a subkey capable of just
+ signing and authentication would be an exact match for "sa".
+ (drop-subkey)
+
+ sig_created
+ sig_created_d
+ The first is the timestamp a signature packet was created.
+ The second is the same but given as an ISO date string, e.g.
+ "2016-08-17". (drop-sig)
+
+ sig_algo
+ A number with the public key algorithm of a signature packet.
+ (drop-sig)
+
+ sig_digest_algo
+ A number with the digest algorithm of a signature packet.
+ (drop-sig)
+
+'--export-options PARAMETERS'
+ This is a space or comma delimited string that gives options for
+ exporting keys. Options can be prepended with a 'no-' to give the
+ opposite meaning. The options are:
+
+ export-local-sigs
+ Allow exporting key signatures marked as "local". This is not
+ generally useful unless a shared keyring scheme is being used.
+ Defaults to no.
+
+ export-attributes
+ Include attribute user IDs (photo IDs) while exporting. Not
+ including attribute user IDs is useful to export keys that are
+ going to be used by an OpenPGP program that does not accept
+ attribute user IDs. Defaults to yes.
+
+ export-sensitive-revkeys
+ Include designated revoker information that was marked as
+ "sensitive". Defaults to no.
+
+ backup
+ export-backup
+ Export for use as a backup. The exported data includes all
+ data which is needed to restore the key or keys later with
+ GnuPG. The format is basically the OpenPGP format but enhanced
+ with GnuPG specific data. All other contradicting options are
+ overridden.
+
+ export-clean
+ Compact (remove all signatures from) user IDs on the key being
+ exported if the user IDs are not usable. Also, do not export
+ any signatures that are not usable. This includes signatures
+ that were issued by keys that are not present on the keyring.
+ This option is the same as running the '--edit-key' command
+ "clean" before export except that the local copy of the key is
+ not modified. Defaults to no.
+
+ export-minimal
+ Export the smallest key possible. This removes all signatures
+ except the most recent self-signature on each user ID. This
+ option is the same as running the '--edit-key' command
+ "minimize" before export except that the local copy of the key
+ is not modified. Defaults to no.
+
+ export-pka
+ Instead of outputting the key material output PKA records
+ suitable to put into DNS zone files. An ORIGIN line is
+ printed before each record to allow diverting the records to
+ the corresponding zone file.
+
+ export-dane
+ Instead of outputting the key material output OpenPGP DANE
+ records suitable to put into DNS zone files. An ORIGIN line
+ is printed before each record to allow diverting the records
+ to the corresponding zone file.
+
+'--with-colons'
+ Print key listings delimited by colons. Note that the output will
+ be encoded in UTF-8 regardless of any '--display-charset' setting.
+ This format is useful when GnuPG is called from scripts and other
+ programs as it is easily machine parsed. The details of this
+ format are documented in the file 'doc/DETAILS', which is included
+ in the GnuPG source distribution.
+
+'--fixed-list-mode'
+ Do not merge primary user ID and primary key in '--with-colon'
+ listing mode and print all timestamps as seconds since 1970-01-01.
+ Since GnuPG 2.0.10, this mode is always used and thus this option
+ is obsolete; it does not harm to use it though.
+
+'--legacy-list-mode'
+ Revert to the pre-2.1 public key list mode. This only affects the
+ human readable output and not the machine interface (i.e.
+ '--with-colons'). Note that the legacy format does not convey
+ suitable information for elliptic curves.
+
+'--with-fingerprint'
+ Same as the command '--fingerprint' but changes only the format of
+ the output and may be used together with another command.
+
+'--with-subkey-fingerprint'
+ If a fingerprint is printed for the primary key, this option forces
+ printing of the fingerprint for all subkeys. This could also be
+ achieved by using the '--with-fingerprint' twice but by using this
+ option along with keyid-format "none" a compact fingerprint is
+ printed.
+
+'--with-icao-spelling'
+ Print the ICAO spelling of the fingerprint in addition to the hex
+ digits.
+
+'--with-keygrip'
+ Include the keygrip in the key listings. In '--with-colons' mode
+ this is implicitly enable for secret keys.
+
+'--with-key-origin'
+ Include the locally held information on the origin and last update
+ of a key in a key listing. In '--with-colons' mode this is always
+ printed. This data is currently experimental and shall not be
+ considered part of the stable API.
+
+'--with-wkd-hash'
+ Print a Web Key Directory identifier along with each user ID in key
+ listings. This is an experimental feature and semantics may
+ change.
+
+'--with-secret'
+ Include info about the presence of a secret key in public key
+ listings done with '--with-colons'.
+
+
+File: gnupg.info, Node: OpenPGP Options, Next: Compliance Options, Prev: GPG Input and Output, Up: GPG Options
+
+4.2.4 OpenPGP protocol specific options
+---------------------------------------
+
+'-t, --textmode'
+'--no-textmode'
+ Treat input files as text and store them in the OpenPGP canonical
+ text form with standard "CRLF" line endings. This also sets the
+ necessary flags to inform the recipient that the encrypted or
+ signed data is text and may need its line endings converted back to
+ whatever the local system uses. This option is useful when
+ communicating between two platforms that have different line ending
+ conventions (UNIX-like to Mac, Mac to Windows, etc).
+ '--no-textmode' disables this option, and is the default.
+
+'--force-v3-sigs'
+'--no-force-v3-sigs'
+'--force-v4-certs'
+'--no-force-v4-certs'
+ These options are obsolete and have no effect since GnuPG 2.1.
+
+'--force-mdc'
+'--disable-mdc'
+ These options are obsolete and have no effect since GnuPG 2.2.8.
+ The MDC is always used. But note: If the creation of a legacy
+ non-MDC message is exceptionally required, the option '--rfc2440'
+ allows for this.
+
+'--disable-signer-uid'
+ By default the user ID of the signing key is embedded in the data
+ signature. As of now this is only done if the signing key has been
+ specified with 'local-user' using a mail address, or with 'sender'.
+ This information can be helpful for verifier to locate the key; see
+ option '--auto-key-retrieve'.
+
+'--include-key-block'
+ This option is used to embed the actual signing key into a data
+ signature. The embedded key is stripped down to a single user id
+ and includes only the signing subkey used to create the signature
+ as well as as valid encryption subkeys. All other info is removed
+ from the key to keep it and thus the signature small. This option
+ is the OpenPGP counterpart to the 'gpgsm' option '--include-certs'.
+
+'--personal-cipher-preferences STRING'
+ Set the list of personal cipher preferences to STRING. Use 'gpg
+ --version' to get a list of available algorithms, and use 'none' to
+ set no preference at all. This allows the user to safely override
+ the algorithm chosen by the recipient key preferences, as GPG will
+ only select an algorithm that is usable by all recipients. The
+ most highly ranked cipher in this list is also used for the
+ '--symmetric' encryption command.
+
+'--personal-digest-preferences STRING'
+ Set the list of personal digest preferences to STRING. Use 'gpg
+ --version' to get a list of available algorithms, and use 'none' to
+ set no preference at all. This allows the user to safely override
+ the algorithm chosen by the recipient key preferences, as GPG will
+ only select an algorithm that is usable by all recipients. The
+ most highly ranked digest algorithm in this list is also used when
+ signing without encryption (e.g. '--clear-sign' or '--sign').
+
+'--personal-compress-preferences STRING'
+ Set the list of personal compression preferences to STRING. Use
+ 'gpg --version' to get a list of available algorithms, and use
+ 'none' to set no preference at all. This allows the user to safely
+ override the algorithm chosen by the recipient key preferences, as
+ GPG will only select an algorithm that is usable by all recipients.
+ The most highly ranked compression algorithm in this list is also
+ used when there are no recipient keys to consider (e.g.
+ '--symmetric').
+
+'--s2k-cipher-algo NAME'
+ Use NAME as the cipher algorithm for symmetric encryption with a
+ passphrase if '--personal-cipher-preferences' and '--cipher-algo'
+ are not given. The default is AES-128.
+
+'--s2k-digest-algo NAME'
+ Use NAME as the digest algorithm used to mangle the passphrases for
+ symmetric encryption. The default is SHA-1.
+
+'--s2k-mode N'
+ Selects how passphrases for symmetric encryption are mangled. If N
+ is 0 a plain passphrase (which is in general not recommended) will
+ be used, a 1 adds a salt (which should not be used) to the
+ passphrase and a 3 (the default) iterates the whole process a
+ number of times (see '--s2k-count').
+
+'--s2k-count N'
+ Specify how many times the passphrases mangling for symmetric
+ encryption is repeated. This value may range between 1024 and
+ 65011712 inclusive. The default is inquired from gpg-agent. Note
+ that not all values in the 1024-65011712 range are legal and if an
+ illegal value is selected, GnuPG will round up to the nearest legal
+ value. This option is only meaningful if '--s2k-mode' is set to
+ the default of 3.
+
+
+File: gnupg.info, Node: Compliance Options, Next: GPG Esoteric Options, Prev: OpenPGP Options, Up: GPG Options
+
+4.2.5 Compliance options
+------------------------
+
+These options control what GnuPG is compliant to. Only one of these
+options may be active at a time. Note that the default setting of this
+is nearly always the correct one. See the INTEROPERABILITY WITH OTHER
+OPENPGP PROGRAMS section below before using one of these options.
+
+'--gnupg'
+ Use standard GnuPG behavior. This is essentially OpenPGP behavior
+ (see '--openpgp'), but with some additional workarounds for common
+ compatibility problems in different versions of PGP. This is the
+ default option, so it is not generally needed, but it may be useful
+ to override a different compliance option in the gpg.conf file.
+
+'--openpgp'
+ Reset all packet, cipher and digest options to strict OpenPGP
+ behavior. Use this option to reset all previous options like
+ '--s2k-*', '--cipher-algo', '--digest-algo' and '--compress-algo'
+ to OpenPGP compliant values. All PGP workarounds are disabled.
+
+'--rfc4880'
+ Reset all packet, cipher and digest options to strict RFC-4880
+ behavior. Note that this is currently the same thing as
+ '--openpgp'.
+
+'--rfc4880bis'
+ Enable experimental features from proposed updates to RFC-4880.
+ This option can be used in addition to the other compliance
+ options. Warning: The behavior may change with any GnuPG release
+ and created keys or data may not be usable with future GnuPG
+ versions.
+
+'--rfc2440'
+ Reset all packet, cipher and digest options to strict RFC-2440
+ behavior. Note that by using this option encryption packets are
+ created in a legacy mode without MDC protection. This is dangerous
+ and should thus only be used for experiments. See also option
+ '--ignore-mdc-error'.
+
+'--pgp6'
+ Set up all options to be as PGP 6 compliant as possible. This
+ restricts you to the ciphers IDEA (if the IDEA plugin is
+ installed), 3DES, and CAST5, the hashes MD5, SHA1 and RIPEMD160,
+ and the compression algorithms none and ZIP. This also disables
+ '--throw-keyids', and making signatures with signing subkeys as PGP
+ 6 does not understand signatures made by signing subkeys.
+
+ This option implies '--escape-from-lines'.
+
+'--pgp7'
+ Set up all options to be as PGP 7 compliant as possible. This is
+ identical to '--pgp6' except that MDCs are not disabled, and the
+ list of allowable ciphers is expanded to add AES128, AES192,
+ AES256, and TWOFISH.
+
+'--pgp8'
+ Set up all options to be as PGP 8 compliant as possible. PGP 8 is
+ a lot closer to the OpenPGP standard than previous versions of PGP,
+ so all this does is disable '--throw-keyids' and set
+ '--escape-from-lines'. All algorithms are allowed except for the
+ SHA224, SHA384, and SHA512 digests.
+
+'--compliance STRING'
+ This option can be used instead of one of the options above. Valid
+ values for STRING are the above option names (without the double
+ dash) and possibly others as shown when using "help" for VALUE.
+
+
+File: gnupg.info, Node: GPG Esoteric Options, Next: Deprecated Options, Prev: Compliance Options, Up: GPG Options
+
+4.2.6 Doing things one usually doesn't want to do
+-------------------------------------------------
+
+'-n'
+'--dry-run'
+ Don't make any changes (this is not completely implemented).
+
+'--list-only'
+ Changes the behaviour of some commands. This is like '--dry-run'
+ but different in some cases. The semantic of this option may be
+ extended in the future. Currently it only skips the actual
+ decryption pass and therefore enables a fast listing of the
+ encryption keys.
+
+'-i'
+'--interactive'
+ Prompt before overwriting any files.
+
+'--debug-level LEVEL'
+ Select the debug level for investigating problems. LEVEL may be a
+ numeric value or by a keyword:
+
+ 'none'
+ No debugging at all. A value of less than 1 may be used
+ instead of the keyword.
+ 'basic'
+ Some basic debug messages. A value between 1 and 2 may be
+ used instead of the keyword.
+ 'advanced'
+ More verbose debug messages. A value between 3 and 5 may be
+ used instead of the keyword.
+ 'expert'
+ Even more detailed messages. A value between 6 and 8 may be
+ used instead of the keyword.
+ 'guru'
+ All of the debug messages you can get. A value greater than 8
+ may be used instead of the keyword. The creation of hash
+ tracing files is only enabled if the keyword is used.
+
+ How these messages are mapped to the actual debugging flags is not
+ specified and may change with newer releases of this program. They
+ are however carefully selected to best aid in debugging.
+
+'--debug FLAGS'
+ Set debugging flags. All flags are or-ed and FLAGS may be given in
+ C syntax (e.g. 0x0042) or as a comma separated list of flag names.
+ To get a list of all supported flags the single word "help" can be
+ used.
+
+'--debug-all'
+ Set all useful debugging flags.
+
+'--debug-iolbf'
+ Set stdout into line buffered mode. This option is only honored
+ when given on the command line.
+
+'--faked-system-time EPOCH'
+ This option is only useful for testing; it sets the system time
+ back or forth to EPOCH which is the number of seconds elapsed since
+ the year 1970. Alternatively EPOCH may be given as a full ISO time
+ string (e.g. "20070924T154812").
+
+ If you suffix EPOCH with an exclamation mark (!), the system time
+ will appear to be frozen at the specified time.
+
+'--enable-progress-filter'
+ Enable certain PROGRESS status outputs. This option allows
+ frontends to display a progress indicator while gpg is processing
+ larger files. There is a slight performance overhead using it.
+
+'--status-fd N'
+ Write special status strings to the file descriptor N. See the
+ file DETAILS in the documentation for a listing of them.
+
+'--status-file FILE'
+ Same as '--status-fd', except the status data is written to file
+ FILE.
+
+'--logger-fd N'
+ Write log output to file descriptor N and not to STDERR.
+
+'--log-file FILE'
+'--logger-file FILE'
+ Same as '--logger-fd', except the logger data is written to file
+ FILE. Use 'socket://' to log to a socket. Note that in this
+ version of gpg the option has only an effect if '--batch' is also
+ used.
+
+'--attribute-fd N'
+ Write attribute subpackets to the file descriptor N. This is most
+ useful for use with '--status-fd', since the status messages are
+ needed to separate out the various subpackets from the stream
+ delivered to the file descriptor.
+
+'--attribute-file FILE'
+ Same as '--attribute-fd', except the attribute data is written to
+ file FILE.
+
+'--comment STRING'
+'--no-comments'
+ Use STRING as a comment string in cleartext signatures and ASCII
+ armored messages or keys (see '--armor'). The default behavior is
+ not to use a comment string. '--comment' may be repeated multiple
+ times to get multiple comment strings. '--no-comments' removes all
+ comments. It is a good idea to keep the length of a single comment
+ below 60 characters to avoid problems with mail programs wrapping
+ such lines. Note that comment lines, like all other header lines,
+ are not protected by the signature.
+
+'--emit-version'
+'--no-emit-version'
+ Force inclusion of the version string in ASCII armored output. If
+ given once only the name of the program and the major number is
+ emitted, given twice the minor is also emitted, given thrice the
+ micro is added, and given four times an operating system
+ identification is also emitted. '--no-emit-version' (default)
+ disables the version line.
+
+'--sig-notation {NAME=VALUE}'
+'--cert-notation {NAME=VALUE}'
+'-N, --set-notation {NAME=VALUE}'
+ Put the name value pair into the signature as notation data. NAME
+ must consist only of printable characters or spaces, and must
+ contain a '@' character in the form keyname@domain.example.com
+ (substituting the appropriate keyname and domain name, of course).
+ This is to help prevent pollution of the IETF reserved notation
+ namespace. The '--expert' flag overrides the '@' check. VALUE may
+ be any printable string; it will be encoded in UTF-8, so you should
+ check that your '--display-charset' is set correctly. If you
+ prefix NAME with an exclamation mark (!), the notation data will be
+ flagged as critical (rfc4880:5.2.3.16). '--sig-notation' sets a
+ notation for data signatures. '--cert-notation' sets a notation
+ for key signatures (certifications). '--set-notation' sets both.
+
+ There are special codes that may be used in notation names. "%k"
+ will be expanded into the key ID of the key being signed, "%K" into
+ the long key ID of the key being signed, "%f" into the fingerprint
+ of the key being signed, "%s" into the key ID of the key making the
+ signature, "%S" into the long key ID of the key making the
+ signature, "%g" into the fingerprint of the key making the
+ signature (which might be a subkey), "%p" into the fingerprint of
+ the primary key of the key making the signature, "%c" into the
+ signature count from the OpenPGP smartcard, and "%%" results in a
+ single "%". %k, %K, and %f are only meaningful when making a key
+ signature (certification), and %c is only meaningful when using the
+ OpenPGP smartcard.
+
+'--known-notation NAME'
+ Adds NAME to a list of known critical signature notations. The
+ effect of this is that gpg will not mark a signature with a
+ critical signature notation of that name as bad. Note that gpg
+ already knows by default about a few critical signatures notation
+ names.
+
+'--sig-policy-url STRING'
+'--cert-policy-url STRING'
+'--set-policy-url STRING'
+ Use STRING as a Policy URL for signatures (rfc4880:5.2.3.20). If
+ you prefix it with an exclamation mark (!), the policy URL packet
+ will be flagged as critical. '--sig-policy-url' sets a policy url
+ for data signatures. '--cert-policy-url' sets a policy url for key
+ signatures (certifications). '--set-policy-url' sets both.
+
+ The same %-expandos used for notation data are available here as
+ well.
+
+'--sig-keyserver-url STRING'
+ Use STRING as a preferred keyserver URL for data signatures. If
+ you prefix it with an exclamation mark (!), the keyserver URL
+ packet will be flagged as critical.
+
+ The same %-expandos used for notation data are available here as
+ well.
+
+'--set-filename STRING'
+ Use STRING as the filename which is stored inside messages. This
+ overrides the default, which is to use the actual filename of the
+ file being encrypted. Using the empty string for STRING
+ effectively removes the filename from the output.
+
+'--for-your-eyes-only'
+'--no-for-your-eyes-only'
+ Set the 'for your eyes only' flag in the message. This causes
+ GnuPG to refuse to save the file unless the '--output' option is
+ given, and PGP to use a "secure viewer" with a claimed
+ Tempest-resistant font to display the message. This option
+ overrides '--set-filename'. '--no-for-your-eyes-only' disables
+ this option.
+
+'--use-embedded-filename'
+'--no-use-embedded-filename'
+ Try to create a file with a name as embedded in the data. This can
+ be a dangerous option as it enables overwriting files. Defaults to
+ no. Note that the option '--output' overrides this option.
+
+'--cipher-algo NAME'
+ Use NAME as cipher algorithm. Running the program with the command
+ '--version' yields a list of supported algorithms. If this is not
+ used the cipher algorithm is selected from the preferences stored
+ with the key. In general, you do not want to use this option as it
+ allows you to violate the OpenPGP standard.
+ '--personal-cipher-preferences' is the safe way to accomplish the
+ same thing.
+
+'--digest-algo NAME'
+ Use NAME as the message digest algorithm. Running the program with
+ the command '--version' yields a list of supported algorithms. In
+ general, you do not want to use this option as it allows you to
+ violate the OpenPGP standard. '--personal-digest-preferences' is
+ the safe way to accomplish the same thing.
+
+'--compress-algo NAME'
+ Use compression algorithm NAME. "zlib" is RFC-1950 ZLIB
+ compression. "zip" is RFC-1951 ZIP compression which is used by
+ PGP. "bzip2" is a more modern compression scheme that can compress
+ some things better than zip or zlib, but at the cost of more memory
+ used during compression and decompression. "uncompressed" or
+ "none" disables compression. If this option is not used, the
+ default behavior is to examine the recipient key preferences to see
+ which algorithms the recipient supports. If all else fails, ZIP is
+ used for maximum compatibility.
+
+ ZLIB may give better compression results than ZIP, as the
+ compression window size is not limited to 8k. BZIP2 may give even
+ better compression results than that, but will use a significantly
+ larger amount of memory while compressing and decompressing. This
+ may be significant in low memory situations. Note, however, that
+ PGP (all versions) only supports ZIP compression. Using any
+ algorithm other than ZIP or "none" will make the message unreadable
+ with PGP. In general, you do not want to use this option as it
+ allows you to violate the OpenPGP standard.
+ '--personal-compress-preferences' is the safe way to accomplish the
+ same thing.
+
+'--cert-digest-algo NAME'
+ Use NAME as the message digest algorithm used when signing a key.
+ Running the program with the command '--version' yields a list of
+ supported algorithms. Be aware that if you choose an algorithm
+ that GnuPG supports but other OpenPGP implementations do not, then
+ some users will not be able to use the key signatures you make, or
+ quite possibly your entire key.
+
+'--disable-cipher-algo NAME'
+ Never allow the use of NAME as cipher algorithm. The given name
+ will not be checked so that a later loaded algorithm will still get
+ disabled.
+
+'--disable-pubkey-algo NAME'
+ Never allow the use of NAME as public key algorithm. The given
+ name will not be checked so that a later loaded algorithm will
+ still get disabled.
+
+'--throw-keyids'
+'--no-throw-keyids'
+ Do not put the recipient key IDs into encrypted messages. This
+ helps to hide the receivers of the message and is a limited
+ countermeasure against traffic analysis.(1) On the receiving side,
+ it may slow down the decryption process because all available
+ secret keys must be tried. '--no-throw-keyids' disables this
+ option. This option is essentially the same as using
+ '--hidden-recipient' for all recipients.
+
+'--not-dash-escaped'
+ This option changes the behavior of cleartext signatures so that
+ they can be used for patch files. You should not send such an
+ armored file via email because all spaces and line endings are
+ hashed too. You can not use this option for data which has 5
+ dashes at the beginning of a line, patch files don't have this. A
+ special armor header line tells GnuPG about this cleartext
+ signature option.
+
+'--escape-from-lines'
+'--no-escape-from-lines'
+ Because some mailers change lines starting with "From " to ">From "
+ it is good to handle such lines in a special way when creating
+ cleartext signatures to prevent the mail system from breaking the
+ signature. Note that all other PGP versions do it this way too.
+ Enabled by default. '--no-escape-from-lines' disables this option.
+
+'--passphrase-repeat N'
+ Specify how many times 'gpg' will request a new passphrase be
+ repeated. This is useful for helping memorize a passphrase.
+ Defaults to 1 repetition; can be set to 0 to disable any passphrase
+ repetition. Note that a N greater than 1 will pop up the pinentry
+ window N+1 times even if a modern pinentry with two entry fields is
+ used.
+
+'--passphrase-fd N'
+ Read the passphrase from file descriptor N. Only the first line
+ will be read from file descriptor N. If you use 0 for N, the
+ passphrase will be read from STDIN. This can only be used if only
+ one passphrase is supplied.
+
+ Note that since Version 2.0 this passphrase is only used if the
+ option '--batch' has also been given. Since Version 2.1 the
+ '--pinentry-mode' also needs to be set to 'loopback'.
+
+'--passphrase-file FILE'
+ Read the passphrase from file FILE. Only the first line will be
+ read from file FILE. This can only be used if only one passphrase
+ is supplied. Obviously, a passphrase stored in a file is of
+ questionable security if other users can read this file. Don't use
+ this option if you can avoid it.
+
+ Note that since Version 2.0 this passphrase is only used if the
+ option '--batch' has also been given. Since Version 2.1 the
+ '--pinentry-mode' also needs to be set to 'loopback'.
+
+'--passphrase STRING'
+ Use STRING as the passphrase. This can only be used if only one
+ passphrase is supplied. Obviously, this is of very questionable
+ security on a multi-user system. Don't use this option if you can
+ avoid it.
+
+ Note that since Version 2.0 this passphrase is only used if the
+ option '--batch' has also been given. Since Version 2.1 the
+ '--pinentry-mode' also needs to be set to 'loopback'.
+
+'--pinentry-mode MODE'
+ Set the pinentry mode to MODE. Allowed values for MODE are:
+ default
+ Use the default of the agent, which is 'ask'.
+ ask
+ Force the use of the Pinentry.
+ cancel
+ Emulate use of Pinentry's cancel button.
+ error
+ Return a Pinentry error ("No Pinentry").
+ loopback
+ Redirect Pinentry queries to the caller. Note that in
+ contrast to Pinentry the user is not prompted again if he
+ enters a bad password.
+
+'--no-symkey-cache'
+ Disable the passphrase cache used for symmetrical en- and
+ decryption. This cache is based on the message specific salt value
+ (cf. '--s2k-mode').
+
+'--request-origin ORIGIN'
+ Tell gpg to assume that the operation ultimately originated at
+ ORIGIN. Depending on the origin certain restrictions are applied
+ and the Pinentry may include an extra note on the origin.
+ Supported values for ORIGIN are: 'local' which is the default,
+ 'remote' to indicate a remote origin or 'browser' for an operation
+ requested by a web browser.
+
+'--command-fd N'
+ This is a replacement for the deprecated shared-memory IPC mode.
+ If this option is enabled, user input on questions is not expected
+ from the TTY but from the given file descriptor. It should be used
+ together with '--status-fd'. See the file doc/DETAILS in the
+ source distribution for details on how to use it.
+
+'--command-file FILE'
+ Same as '--command-fd', except the commands are read out of file
+ FILE
+
+'--allow-non-selfsigned-uid'
+'--no-allow-non-selfsigned-uid'
+ Allow the import and use of keys with user IDs which are not
+ self-signed. This is not recommended, as a non self-signed user ID
+ is trivial to forge. '--no-allow-non-selfsigned-uid' disables.
+
+'--allow-freeform-uid'
+ Disable all checks on the form of the user ID while generating a
+ new one. This option should only be used in very special
+ environments as it does not ensure the de-facto standard format of
+ user IDs.
+
+'--ignore-time-conflict'
+ GnuPG normally checks that the timestamps associated with keys and
+ signatures have plausible values. However, sometimes a signature
+ seems to be older than the key due to clock problems. This option
+ makes these checks just a warning. See also '--ignore-valid-from'
+ for timestamp issues on subkeys.
+
+'--ignore-valid-from'
+ GnuPG normally does not select and use subkeys created in the
+ future. This option allows the use of such keys and thus exhibits
+ the pre-1.0.7 behaviour. You should not use this option unless
+ there is some clock problem. See also '--ignore-time-conflict' for
+ timestamp issues with signatures.
+
+'--ignore-crc-error'
+ The ASCII armor used by OpenPGP is protected by a CRC checksum
+ against transmission errors. Occasionally the CRC gets mangled
+ somewhere on the transmission channel but the actual content (which
+ is protected by the OpenPGP protocol anyway) is still okay. This
+ option allows GnuPG to ignore CRC errors.
+
+'--ignore-mdc-error'
+ This option changes a MDC integrity protection failure into a
+ warning. It is required to decrypt old messages which did not use
+ an MDC. It may also be useful if a message is partially garbled,
+ but it is necessary to get as much data as possible out of that
+ garbled message. Be aware that a missing or failed MDC can be an
+ indication of an attack. Use with great caution; see also option
+ '--rfc2440'.
+
+'--allow-weak-digest-algos'
+ Signatures made with known-weak digest algorithms are normally
+ rejected with an "invalid digest algorithm" message. This option
+ allows the verification of signatures made with such weak
+ algorithms. MD5 is the only digest algorithm considered weak by
+ default. See also '--weak-digest' to reject other digest
+ algorithms.
+
+'--weak-digest NAME'
+ Treat the specified digest algorithm as weak. Signatures made over
+ weak digests algorithms are normally rejected. This option can be
+ supplied multiple times if multiple algorithms should be considered
+ weak. See also '--allow-weak-digest-algos' to disable rejection of
+ weak digests. MD5 is always considered weak, and does not need to
+ be listed explicitly.
+
+'--allow-weak-key-signatures'
+ To avoid a minor risk of collision attacks on third-party key
+ signatures made using SHA-1, those key signatures are considered
+ invalid. This options allows to override this restriction.
+
+'--no-default-keyring'
+ Do not add the default keyrings to the list of keyrings. Note that
+ GnuPG will not operate without any keyrings, so if you use this
+ option and do not provide alternate keyrings via '--keyring' or
+ '--secret-keyring', then GnuPG will still use the default public or
+ secret keyrings.
+
+'--no-keyring'
+ Do not use any keyring at all. This overrides the default and all
+ options which specify keyrings.
+
+'--skip-verify'
+ Skip the signature verification step. This may be used to make the
+ decryption faster if the signature verification is not needed.
+
+'--with-key-data'
+ Print key listings delimited by colons (like '--with-colons') and
+ print the public key data.
+
+'--list-signatures'
+'--list-sigs'
+ Same as '--list-keys', but the signatures are listed too. This
+ command has the same effect as using '--list-keys' with
+ '--with-sig-list'. Note that in contrast to '--check-signatures'
+ the key signatures are not verified. This command can be used to
+ create a list of signing keys missing in the local keyring; for
+ example:
+
+ gpg --list-sigs --with-colons USERID | \
+ awk -F: '$1=="sig" && $2=="?" {if($13){print $13}else{print $5}}'
+
+'--fast-list-mode'
+ Changes the output of the list commands to work faster; this is
+ achieved by leaving some parts empty. Some applications don't need
+ the user ID and the trust information given in the listings. By
+ using this options they can get a faster listing. The exact
+ behaviour of this option may change in future versions. If you are
+ missing some information, don't use this option.
+
+'--no-literal'
+ This is not for normal use. Use the source to see for what it
+ might be useful.
+
+'--set-filesize'
+ This is not for normal use. Use the source to see for what it
+ might be useful.
+
+'--show-session-key'
+ Display the session key used for one message. See
+ '--override-session-key' for the counterpart of this option.
+
+ We think that Key Escrow is a Bad Thing; however the user should
+ have the freedom to decide whether to go to prison or to reveal the
+ content of one specific message without compromising all messages
+ ever encrypted for one secret key.
+
+ You can also use this option if you receive an encrypted message
+ which is abusive or offensive, to prove to the administrators of
+ the messaging system that the ciphertext transmitted corresponds to
+ an inappropriate plaintext so they can take action against the
+ offending user.
+
+'--override-session-key STRING'
+'--override-session-key-fd FD'
+ Don't use the public key but the session key STRING respective the
+ session key taken from the first line read from file descriptor FD.
+ The format of this string is the same as the one printed by
+ '--show-session-key'. This option is normally not used but comes
+ handy in case someone forces you to reveal the content of an
+ encrypted message; using this option you can do this without
+ handing out the secret key. Note that using
+ '--override-session-key' may reveal the session key to all local
+ users via the global process table. Often it is useful to combine
+ this option with '--no-keyring'.
+
+'--ask-sig-expire'
+'--no-ask-sig-expire'
+ When making a data signature, prompt for an expiration time. If
+ this option is not specified, the expiration time set via
+ '--default-sig-expire' is used. '--no-ask-sig-expire' disables
+ this option.
+
+'--default-sig-expire'
+ The default expiration time to use for signature expiration. Valid
+ values are "0" for no expiration, a number followed by the letter d
+ (for days), w (for weeks), m (for months), or y (for years) (for
+ example "2m" for two months, or "5y" for five years), or an
+ absolute date in the form YYYY-MM-DD. Defaults to "0".
+
+'--ask-cert-expire'
+'--no-ask-cert-expire'
+ When making a key signature, prompt for an expiration time. If
+ this option is not specified, the expiration time set via
+ '--default-cert-expire' is used. '--no-ask-cert-expire' disables
+ this option.
+
+'--default-cert-expire'
+ The default expiration time to use for key signature expiration.
+ Valid values are "0" for no expiration, a number followed by the
+ letter d (for days), w (for weeks), m (for months), or y (for
+ years) (for example "2m" for two months, or "5y" for five years),
+ or an absolute date in the form YYYY-MM-DD. Defaults to "0".
+
+'--default-new-key-algo STRING'
+ This option can be used to change the default algorithms for key
+ generation. The STRING is similar to the arguments required for
+ the command '--quick-add-key' but slightly different. For example
+ the current default of '"rsa2048/cert,sign+rsa2048/encr"' (or
+ '"rsa3072"') can be changed to the value of what we currently call
+ future default, which is '"ed25519/cert,sign+cv25519/encr"'. You
+ need to consult the source code to learn the details. Note that
+ the advanced key generation commands can always be used to specify
+ a key algorithm directly.
+
+'--allow-secret-key-import'
+ This is an obsolete option and is not used anywhere.
+
+'--allow-multiple-messages'
+'--no-allow-multiple-messages'
+ Allow processing of multiple OpenPGP messages contained in a single
+ file or stream. Some programs that call GPG are not prepared to
+ deal with multiple messages being processed together, so this
+ option defaults to no. Note that versions of GPG prior to 1.4.7
+ always allowed multiple messages. Future versions of GnUPG will
+ remove this option.
+
+ Warning: Do not use this option unless you need it as a temporary
+ workaround!
+
+'--enable-special-filenames'
+ This option enables a mode in which filenames of the form '-&n',
+ where n is a non-negative decimal number, refer to the file
+ descriptor n and not to a file with that name.
+
+'--no-expensive-trust-checks'
+ Experimental use only.
+
+'--preserve-permissions'
+ Don't change the permissions of a secret keyring back to user
+ read/write only. Use this option only if you really know what you
+ are doing.
+
+'--default-preference-list STRING'
+ Set the list of default preferences to STRING. This preference
+ list is used for new keys and becomes the default for "setpref" in
+ the edit menu.
+
+'--default-keyserver-url NAME'
+ Set the default keyserver URL to NAME. This keyserver will be used
+ as the keyserver URL when writing a new self-signature on a key,
+ which includes key generation and changing preferences.
+
+'--list-config'
+ Display various internal configuration parameters of GnuPG. This
+ option is intended for external programs that call GnuPG to perform
+ tasks, and is thus not generally useful. See the file
+ 'doc/DETAILS' in the source distribution for the details of which
+ configuration items may be listed. '--list-config' is only usable
+ with '--with-colons' set.
+
+'--list-gcrypt-config'
+ Display various internal configuration parameters of Libgcrypt.
+
+'--gpgconf-list'
+ This command is similar to '--list-config' but in general only
+ internally used by the 'gpgconf' tool.
+
+'--gpgconf-test'
+ This is more or less dummy action. However it parses the
+ configuration file and returns with failure if the configuration
+ file would prevent 'gpg' from startup. Thus it may be used to run
+ a syntax check on the configuration file.
+
+ ---------- Footnotes ----------
+
+ (1) Using a little social engineering anyone who is able to decrypt
+the message can check whether one of the other recipients is the one he
+suspects.
+
+
+File: gnupg.info, Node: Deprecated Options, Prev: GPG Esoteric Options, Up: GPG Options
+
+4.2.7 Deprecated options
+------------------------
+
+'--show-photos'
+'--no-show-photos'
+ Causes '--list-keys', '--list-signatures', '--list-public-keys',
+ '--list-secret-keys', and verifying a signature to also display the
+ photo ID attached to the key, if any. See also '--photo-viewer'.
+ These options are deprecated. Use '--list-options
+ [no-]show-photos' and/or '--verify-options [no-]show-photos'
+ instead.
+
+'--show-keyring'
+ Display the keyring name at the head of key listings to show which
+ keyring a given key resides on. This option is deprecated: use
+ '--list-options [no-]show-keyring' instead.
+
+'--always-trust'
+ Identical to '--trust-model always'. This option is deprecated.
+
+'--show-notation'
+'--no-show-notation'
+ Show signature notations in the '--list-signatures' or
+ '--check-signatures' listings as well as when verifying a signature
+ with a notation in it. These options are deprecated. Use
+ '--list-options [no-]show-notation' and/or '--verify-options
+ [no-]show-notation' instead.
+
+'--show-policy-url'
+'--no-show-policy-url'
+ Show policy URLs in the '--list-signatures' or '--check-signatures'
+ listings as well as when verifying a signature with a policy URL in
+ it. These options are deprecated. Use '--list-options
+ [no-]show-policy-url' and/or '--verify-options
+ [no-]show-policy-url' instead.
+
+
+File: gnupg.info, Node: GPG Configuration, Next: GPG Examples, Prev: GPG Options, Up: Invoking GPG
+
+4.3 Configuration files
+=======================
+
+There are a few configuration files to control certain aspects of
+'gpg''s operation. Unless noted, they are expected in the current home
+directory (*note option --homedir::).
+
+'gpg.conf'
+ This is the standard configuration file read by 'gpg' on startup.
+ It may contain any valid long option; the leading two dashes may
+ not be entered and the option may not be abbreviated. This default
+ name may be changed on the command line (*note gpg-option
+ --options::). You should backup this file.
+
+ Note that on larger installations, it is useful to put predefined
+files into the directory '/etc/skel/.gnupg' so that newly created users
+start up with a working configuration. For existing users a small
+helper script is provided to create these files (*note addgnupghome::).
+
+ For internal purposes 'gpg' creates and maintains a few other files;
+They all live in the current home directory (*note option --homedir::).
+Only the 'gpg' program may modify these files.
+
+'~/.gnupg'
+ This is the default home directory which is used if neither the
+ environment variable 'GNUPGHOME' nor the option '--homedir' is
+ given.
+
+'~/.gnupg/pubring.gpg'
+ The public keyring using a legacy format. You should backup this
+ file.
+
+ If this file is not available, 'gpg' defaults to the new keybox
+ format and creates a file 'pubring.kbx' unless that file already
+ exists in which case that file will also be used for OpenPGP keys.
+
+ Note that in the case that both files, 'pubring.gpg' and
+ 'pubring.kbx' exists but the latter has no OpenPGP keys, the legacy
+ file 'pubring.gpg' will be used. Take care: GnuPG versions before
+ 2.1 will always use the file 'pubring.gpg' because they do not know
+ about the new keybox format. In the case that you have to use
+ GnuPG 1.4 to decrypt archived data you should keep this file.
+
+'~/.gnupg/pubring.gpg.lock'
+ The lock file for the public keyring.
+
+'~/.gnupg/pubring.kbx'
+ The public keyring using the new keybox format. This file is
+ shared with 'gpgsm'. You should backup this file. See above for
+ the relation between this file and it predecessor.
+
+ To convert an existing 'pubring.gpg' file to the keybox format, you
+ first backup the ownertrust values, then rename 'pubring.gpg' to
+ 'publickeys.backup', so it won’t be recognized by any GnuPG
+ version, run import, and finally restore the ownertrust values:
+
+ $ cd ~/.gnupg
+ $ gpg --export-ownertrust >otrust.lst
+ $ mv pubring.gpg publickeys.backup
+ $ gpg --import-options restore --import publickeys.backups
+ $ gpg --import-ownertrust otrust.lst
+
+'~/.gnupg/pubring.kbx.lock'
+ The lock file for 'pubring.kbx'.
+
+'~/.gnupg/secring.gpg'
+ The legacy secret keyring as used by GnuPG versions before 2.1. It
+ is not used by GnuPG 2.1 and later. You may want to keep it in
+ case you have to use GnuPG 1.4 to decrypt archived data.
+
+'~/.gnupg/secring.gpg.lock'
+ The lock file for the legacy secret keyring.
+
+'~/.gnupg/.gpg-v21-migrated'
+ File indicating that a migration to GnuPG 2.1 has been done.
+
+'~/.gnupg/trustdb.gpg'
+ The trust database. There is no need to backup this file; it is
+ better to backup the ownertrust values (*note option
+ --export-ownertrust::).
+
+'~/.gnupg/trustdb.gpg.lock'
+ The lock file for the trust database.
+
+'~/.gnupg/random_seed'
+ A file used to preserve the state of the internal random pool.
+
+'~/.gnupg/openpgp-revocs.d/'
+ This is the directory where gpg stores pre-generated revocation
+ certificates. The file name corresponds to the OpenPGP fingerprint
+ of the respective key. It is suggested to backup those
+ certificates and if the primary private key is not stored on the
+ disk to move them to an external storage device. Anyone who can
+ access theses files is able to revoke the corresponding key. You
+ may want to print them out. You should backup all files in this
+ directory and take care to keep this backup closed away.
+
+ Operation is further controlled by a few environment variables:
+
+HOME
+ Used to locate the default home directory.
+
+GNUPGHOME
+ If set directory used instead of "~/.gnupg".
+
+GPG_AGENT_INFO
+ This variable is obsolete; it was used by GnuPG versions before
+ 2.1.
+
+PINENTRY_USER_DATA
+ This value is passed via gpg-agent to pinentry. It is useful to
+ convey extra information to a custom pinentry.
+
+COLUMNS
+LINES
+ Used to size some displays to the full size of the screen.
+
+LANGUAGE
+ Apart from its use by GNU, it is used in the W32 version to
+ override the language selection done through the Registry. If used
+ and set to a valid and available language name (LANGID), the file
+ with the translation is loaded from 'GPGDIR/gnupg.nls/LANGID.mo'.
+ Here GPGDIR is the directory out of which the gpg binary has been
+ loaded. If it can't be loaded the Registry is tried and as last
+ resort the native Windows locale system is used.
+
+ When calling the gpg-agent component 'gpg' sends a set of environment
+variables to gpg-agent. The names of these variables can be listed
+using the command:
+
+ gpg-connect-agent 'getinfo std_env_names' /bye | awk '$1=="D" {print $2}'
+
+
+File: gnupg.info, Node: GPG Examples, Next: Unattended Usage of GPG, Prev: GPG Configuration, Up: Invoking GPG
+
+4.4 Examples
+============
+
+gpg -se -r 'Bob' 'file'
+ sign and encrypt for user Bob
+
+gpg -clear-sign 'file'
+ make a cleartext signature
+
+gpg -sb 'file'
+ make a detached signature
+
+gpg -u 0x12345678 -sb 'file'
+ make a detached signature with the key 0x12345678
+
+gpg -list-keys 'user_ID'
+ show keys
+
+gpg -fingerprint 'user_ID'
+ show fingerprint
+
+gpg -verify 'pgpfile'
+gpg -verify 'sigfile' ['datafile']
+ Verify the signature of the file but do not output the data unless
+ requested. The second form is used for detached signatures, where
+ 'sigfile' is the detached signature (either ASCII armored or
+ binary) and 'datafile' are the signed data; if this is not given,
+ the name of the file holding the signed data is constructed by
+ cutting off the extension (".asc" or ".sig") of 'sigfile' or by
+ asking the user for the filename. If the option '--output' is also
+ used the signed data is written to the file specified by that
+ option; use '-' to write the signed data to stdout.
+
+FILTER EXPRESSIONS
+******************
+
+The options '--import-filter' and '--export-filter' use expressions with
+this syntax (square brackets indicate an optional part and curly braces
+a repetition, white space between the elements are allowed):
+
+ [lc] {[{flag}] PROPNAME op VALUE [lc]}
+
+ The name of a property (PROPNAME) may only consist of letters, digits
+and underscores. The description for the filter type describes which
+properties are defined. If an undefined property is used it evaluates
+to the empty string. Unless otherwise noted, the VALUE must always be
+given and may not be the empty string. No quoting is defined for the
+value, thus the value may not contain the strings '&&' or '||', which
+are used as logical connection operators. The flag '--' can be used to
+remove this restriction.
+
+ Numerical values are computed as long int; standard C notation
+applies. LC is the logical connection operator; either '&&' for a
+conjunction or '||' for a disjunction. A conjunction is assumed at the
+begin of an expression. Conjunctions have higher precedence than
+disjunctions. If VALUE starts with one of the characters used in any OP
+a space after the OP is required.
+
+The supported operators (OP) are:
+
+=~
+ Substring must match.
+
+!~
+ Substring must not match.
+
+=
+ The full string must match.
+
+<>
+ The full string must not match.
+
+==
+ The numerical value must match.
+
+!=
+ The numerical value must not match.
+
+<=
+ The numerical value of the field must be LE than the value.
+
+<
+ The numerical value of the field must be LT than the value.
+
+>
+ The numerical value of the field must be GT than the value.
+
+>=
+ The numerical value of the field must be GE than the value.
+
+-le
+ The string value of the field must be less or equal than the value.
+
+-lt
+ The string value of the field must be less than the value.
+
+-gt
+ The string value of the field must be greater than the value.
+
+-ge
+ The string value of the field must be greater or equal than the
+ value.
+
+-n
+ True if value is not empty (no value allowed).
+
+-z
+ True if value is empty (no value allowed).
+
+-t
+ Alias for "PROPNAME != 0" (no value allowed).
+
+-f
+ Alias for "PROPNAME == 0" (no value allowed).
+
+Values for FLAG must be space separated. The supported flags are:
+
+-
+ VALUE spans to the end of the expression.
+-c
+ The string match in this part is done case-sensitive.
+
+ The filter options concatenate several specifications for a filter of
+the same type. For example the four options in this example:
+
+ --import-filter keep-uid="uid =~ Alfa"
+ --import-filter keep-uid="&& uid !~ Test"
+ --import-filter keep-uid="|| uid =~ Alpha"
+ --import-filter keep-uid="uid !~ Test"
+
+which is equivalent to
+
+ --import-filter \
+ keep-uid="uid =~ Alfa" && uid !~ Test" || uid =~ Alpha" && "uid !~ Test"
+
+ imports only the user ids of a key containing the strings "Alfa" or
+"Alpha" but not the string "test".
+
+RETURN VALUE
+************
+
+The program returns 0 if there are no severe errors, 1 if at least a
+signature was bad, and other error codes for fatal errors.
+
+ Note that signature verification requires exact knowledge of what has
+been signed and by whom it has beensigned. Using only the return code
+is thus not an appropriate way to verify a signature by a script.
+Either make proper use or the status codes or use the 'gpgv' tool which
+has been designed to make signature verification easy for scripts.
+
+WARNINGS
+********
+
+Use a good password for your user account and make sure that all
+security issues are always fixed on your machine. Also employ diligent
+physical protection to your machine. Consider to use a good passphrase
+as a last resort protection to your secret key in the case your machine
+gets stolen. It is important that your secret key is never leaked.
+Using an easy to carry around token or smartcard with the secret key is
+often a advisable.
+
+ If you are going to verify detached signatures, make sure that the
+program knows about it; either give both filenames on the command line
+or use '-' to specify STDIN.
+
+ For scripted or other unattended use of 'gpg' make sure to use the
+machine-parseable interface and not the default interface which is
+intended for direct use by humans. The machine-parseable interface
+provides a stable and well documented API independent of the locale or
+future changes of 'gpg'. To enable this interface use the options
+'--with-colons' and '--status-fd'. For certain operations the option
+'--command-fd' may come handy too. See this man page and the file
+'DETAILS' for the specification of the interface. Note that the GnuPG
+"info" pages as well as the PDF version of the GnuPG manual features a
+chapter on unattended use of GnuPG. As an alternative the library
+'GPGME' can be used as a high-level abstraction on top of that
+interface.
+
+INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS
+********************************************
+
+GnuPG tries to be a very flexible implementation of the OpenPGP
+standard. In particular, GnuPG implements many of the optional parts of
+the standard, such as the SHA-512 hash, and the ZLIB and BZIP2
+compression algorithms. It is important to be aware that not all
+OpenPGP programs implement these optional algorithms and that by forcing
+their use via the '--cipher-algo', '--digest-algo',
+'--cert-digest-algo', or '--compress-algo' options in GnuPG, it is
+possible to create a perfectly valid OpenPGP message, but one that
+cannot be read by the intended recipient.
+
+ There are dozens of variations of OpenPGP programs available, and
+each supports a slightly different subset of these optional algorithms.
+For example, until recently, no (unhacked) version of PGP supported the
+BLOWFISH cipher algorithm. A message using BLOWFISH simply could not be
+read by a PGP user. By default, GnuPG uses the standard OpenPGP
+preferences system that will always do the right thing and create
+messages that are usable by all recipients, regardless of which OpenPGP
+program they use. Only override this safe default if you really know
+what you are doing.
+
+ If you absolutely must override the safe default, or if the
+preferences on a given key are invalid for some reason, you are far
+better off using the '--pgp6', '--pgp7', or '--pgp8' options. These
+options are safe as they do not force any particular algorithms in
+violation of OpenPGP, but rather reduce the available algorithms to a
+"PGP-safe" list.
+
+BUGS
+****
+
+On older systems this program should be installed as setuid(root). This
+is necessary to lock memory pages. Locking memory pages prevents the
+operating system from writing memory pages (which may contain
+passphrases or other sensitive material) to disk. If you get no warning
+message about insecure memory your operating system supports locking
+without being root. The program drops root privileges as soon as locked
+memory is allocated.
+
+ Note also that some systems (especially laptops) have the ability to
+"suspend to disk" (also known as "safe sleep" or "hibernate"). This
+writes all memory to disk before going into a low power or even powered
+off mode. Unless measures are taken in the operating system to protect
+the saved memory, passphrases or other sensitive material may be
+recoverable from it later.
+
+ Before you report a bug you should first search the mailing list
+archives for similar problems and second check whether such a bug has
+already been reported to our bug tracker at <https://bugs.gnupg.org>.
+
+
+File: gnupg.info, Node: Unattended Usage of GPG, Prev: GPG Examples, Up: Invoking GPG
+
+4.5 Unattended Usage
+====================
+
+'gpg' is often used as a backend engine by other software. To help with
+this a machine interface has been defined to have an unambiguous way to
+do this. The options '--status-fd' and '--batch' are almost always
+required for this.
+
+* Menu:
+
+* Programmatic use of GnuPG:: Programmatic use of GnuPG
+* Ephemeral home directories:: Ephemeral home directories
+* The quick key manipulation interface:: The quick key manipulation interface
+* Unattended GPG key generation:: Unattended key generation
+
+
+File: gnupg.info, Node: Programmatic use of GnuPG, Next: Ephemeral home directories, Up: Unattended Usage of GPG
+
+4.5.1 Programmatic use of GnuPG
+-------------------------------
+
+Please consider using GPGME instead of calling 'gpg' directly. GPGME
+offers a stable, backend-independent interface for many cryptographic
+operations. It supports OpenPGP and S/MIME, and also allows interaction
+with various GnuPG components.
+
+ GPGME provides a C-API, and comes with bindings for C++, Qt, and
+Python. Bindings for other languages are available.
+
+
+File: gnupg.info, Node: Ephemeral home directories, Next: The quick key manipulation interface, Prev: Programmatic use of GnuPG, Up: Unattended Usage of GPG
+
+4.5.2 Ephemeral home directories
+--------------------------------
+
+Sometimes you want to contain effects of some operation, for example you
+want to import a key to inspect it, but you do not want this key to be
+added to your keyring. In earlier versions of GnuPG, it was possible to
+specify alternate keyring files for both public and secret keys. In
+modern GnuPG versions, however, we changed how secret keys are stored in
+order to better protect secret key material, and it was not possible to
+preserve this interface.
+
+ The preferred way to do this is to use ephemeral home directories.
+This technique works across all versions of GnuPG.
+
+ Create a temporary directory, create (or copy) a configuration that
+meets your needs, make 'gpg' use this directory either using the
+environment variable GNUPGHOME, or the option '--homedir'. GPGME
+supports this too on a per-context basis, by modifying the engine info
+of contexts. Now execute whatever operation you like, import and export
+key material as necessary. Once finished, you can delete the directory.
+All GnuPG backend services that were started will detect this and shut
+down.
+
+
+File: gnupg.info, Node: The quick key manipulation interface, Next: Unattended GPG key generation, Prev: Ephemeral home directories, Up: Unattended Usage of GPG
+
+4.5.3 The quick key manipulation interface
+------------------------------------------
+
+Recent versions of GnuPG have an interface to manipulate keys without
+using the interactive command '--edit-key'. This interface was added
+mainly for the benefit of GPGME (please consider using GPGME, see the
+manual subsection "Programmatic use of GnuPG"). This interface is
+described in the subsection "How to manage your keys".
+
+
+File: gnupg.info, Node: Unattended GPG key generation, Prev: The quick key manipulation interface, Up: Unattended Usage of GPG
+
+4.5.4 Unattended key generation
+-------------------------------
+
+The command '--generate-key' may be used along with the option '--batch'
+for unattended key generation. This is the most flexible way of
+generating keys, but it is also the most complex one. Consider using
+the quick key manipulation interface described in the previous
+subsection "The quick key manipulation interface".
+
+ The parameters for the key are either read from stdin or given as a
+file on the command line. The format of the parameter file is as
+follows:
+
+ * Text only, line length is limited to about 1000 characters.
+ * UTF-8 encoding must be used to specify non-ASCII characters.
+ * Empty lines are ignored.
+ * Leading and trailing white space is ignored.
+ * A hash sign as the first non white space character indicates a
+ comment line.
+ * Control statements are indicated by a leading percent sign, the
+ arguments are separated by white space from the keyword.
+ * Parameters are specified by a keyword, followed by a colon.
+ Arguments are separated by white space.
+ * The first parameter must be 'Key-Type'; control statements may be
+ placed anywhere.
+ * The order of the parameters does not matter except for 'Key-Type'
+ which must be the first parameter. The parameters are only used
+ for the generated keyblock (primary and subkeys); parameters from
+ previous sets are not used. Some syntactically checks may be
+ performed.
+ * Key generation takes place when either the end of the parameter
+ file is reached, the next 'Key-Type' parameter is encountered or at
+ the control statement '%commit' is encountered.
+
+Control statements:
+
+%echo TEXT
+ Print TEXT as diagnostic.
+
+%dry-run
+ Suppress actual key generation (useful for syntax checking).
+
+%commit
+ Perform the key generation. Note that an implicit commit is done
+ at the next Key-Type parameter.
+
+%pubring FILENAME
+ Do not write the key to the default or commandline given keyring
+ but to FILENAME. This must be given before the first commit to
+ take place, duplicate specification of the same filename is
+ ignored, the last filename before a commit is used. The filename
+ is used until a new filename is used (at commit points) and all
+ keys are written to that file. If a new filename is given, this
+ file is created (and overwrites an existing one).
+
+ See the previous subsection "Ephemeral home directories" for a more
+ robust way to contain side-effects.
+
+%secring FILENAME
+ This option is a no-op for GnuPG 2.1 and later.
+
+ See the previous subsection "Ephemeral home directories".
+
+%ask-passphrase
+%no-ask-passphrase
+ This option is a no-op for GnuPG 2.1 and later.
+
+%no-protection
+ Using this option allows the creation of keys without any
+ passphrase protection. This option is mainly intended for
+ regression tests.
+
+%transient-key
+ If given the keys are created using a faster and a somewhat less
+ secure random number generator. This option may be used for keys
+ which are only used for a short time and do not require full
+ cryptographic strength. It takes only effect if used together with
+ the control statement '%no-protection'.
+
+General Parameters:
+
+Key-Type: ALGO
+ Starts a new parameter block by giving the type of the primary key.
+ The algorithm must be capable of signing. This is a required
+ parameter. ALGO may either be an OpenPGP algorithm number or a
+ string with the algorithm name. The special value 'default' may be
+ used for ALGO to create the default key type; in this case a
+ 'Key-Usage' shall not be given and 'default' also be used for
+ 'Subkey-Type'.
+
+Key-Length: NBITS
+ The requested length of the generated key in bits. The default is
+ returned by running the command 'gpg --gpgconf-list'. For ECC keys
+ this parameter is ignored.
+
+Key-Curve: CURVE
+ The requested elliptic curve of the generated key. This is a
+ required parameter for ECC keys. It is ignored for non-ECC keys.
+
+Key-Grip: HEXSTRING
+ This is optional and used to generate a CSR or certificate for an
+ already existing key. Key-Length will be ignored when given.
+
+Key-Usage: USAGE-LIST
+ Space or comma delimited list of key usages. Allowed values are
+ 'encrypt', 'sign', and 'auth'. This is used to generate the key
+ flags. Please make sure that the algorithm is capable of this
+ usage. Note that OpenPGP requires that all primary keys are
+ capable of certification, so no matter what usage is given here,
+ the 'cert' flag will be on. If no 'Key-Usage' is specified and the
+ 'Key-Type' is not 'default', all allowed usages for that particular
+ algorithm are used; if it is not given but 'default' is used the
+ usage will be 'sign'.
+
+Subkey-Type: ALGO
+ This generates a secondary key (subkey). Currently only one subkey
+ can be handled. See also 'Key-Type' above.
+
+Subkey-Length: NBITS
+ Length of the secondary key (subkey) in bits. The default is
+ returned by running the command 'gpg --gpgconf-list'.
+
+Subkey-Curve: CURVE
+ Key curve for a subkey; similar to 'Key-Curve'.
+
+Subkey-Usage: USAGE-LIST
+ Key usage lists for a subkey; similar to 'Key-Usage'.
+
+Passphrase: STRING
+ If you want to specify a passphrase for the secret key, enter it
+ here. Default is to use the Pinentry dialog to ask for a
+ passphrase.
+
+Name-Real: NAME
+Name-Comment: COMMENT
+Name-Email: EMAIL
+ The three parts of a user name. Remember to use UTF-8 encoding
+ here. If you don't give any of them, no user ID is created.
+
+Expire-Date: ISO-DATE|(NUMBER[d|w|m|y])
+ Set the expiration date for the key (and the subkey). It may
+ either be entered in ISO date format (e.g. "20000815T145012") or
+ as number of days, weeks, month or years after the creation date.
+ The special notation "seconds=N" is also allowed to specify a
+ number of seconds since creation. Without a letter days are
+ assumed. Note that there is no check done on the overflow of the
+ type used by OpenPGP for timestamps. Thus you better make sure
+ that the given value make sense. Although OpenPGP works with time
+ intervals, GnuPG uses an absolute value internally and thus the
+ last year we can represent is 2105.
+
+Creation-Date: ISO-DATE
+ Set the creation date of the key as stored in the key information
+ and which is also part of the fingerprint calculation. Either a
+ date like "1986-04-26" or a full timestamp like "19860426T042640"
+ may be used. The time is considered to be UTC. The special
+ notation "seconds=N" may be used to directly specify a the number
+ of seconds since Epoch (Unix time). If it is not given the current
+ time is used.
+
+Preferences: STRING
+ Set the cipher, hash, and compression preference values for this
+ key. This expects the same type of string as the sub-command
+ 'setpref' in the '--edit-key' menu.
+
+Revoker: ALGO:FPR [sensitive]
+ Add a designated revoker to the generated key. Algo is the public
+ key algorithm of the designated revoker (i.e. RSA=1, DSA=17, etc.)
+ FPR is the fingerprint of the designated revoker. The optional
+ 'sensitive' flag marks the designated revoker as sensitive
+ information. Only v4 keys may be designated revokers.
+
+Keyserver: STRING
+ This is an optional parameter that specifies the preferred
+ keyserver URL for the key.
+
+Handle: STRING
+ This is an optional parameter only used with the status lines
+ KEY_CREATED and KEY_NOT_CREATED. STRING may be up to 100 characters
+ and should not contain spaces. It is useful for batch key
+ generation to associate a key parameter block with a status line.
+
+Here is an example on how to create a key in an ephemeral home
+directory:
+ $ export GNUPGHOME="$(mktemp -d)"
+ $ cat >foo <<EOF
+ %echo Generating a basic OpenPGP key
+ Key-Type: DSA
+ Key-Length: 1024
+ Subkey-Type: ELG-E
+ Subkey-Length: 1024
+ Name-Real: Joe Tester
+ Name-Comment: with stupid passphrase
+ Name-Email: joe@foo.bar
+ Expire-Date: 0
+ Passphrase: abc
+ # Do a commit here, so that we can later print "done" :-)
+ %commit
+ %echo done
+ EOF
+ $ gpg --batch --generate-key foo
+ [...]
+ $ gpg --list-secret-keys
+ /tmp/tmp.0NQxB74PEf/pubring.kbx
+ -------------------------------
+ sec dsa1024 2016-12-16 [SCA]
+ 768E895903FC1C44045C8CB95EEBDB71E9E849D0
+ uid [ultimate] Joe Tester (with stupid passphrase) <joe@foo.bar>
+ ssb elg1024 2016-12-16 [E]
+
+If you want to create a key with the default algorithms you would use
+these parameters:
+ %echo Generating a default key
+ Key-Type: default
+ Subkey-Type: default
+ Name-Real: Joe Tester
+ Name-Comment: with stupid passphrase
+ Name-Email: joe@foo.bar
+ Expire-Date: 0
+ Passphrase: abc
+ # Do a commit here, so that we can later print "done" :-)
+ %commit
+ %echo done
+
+
+File: gnupg.info, Node: Invoking GPGSM, Next: Invoking SCDAEMON, Prev: Invoking GPG, Up: Top
+
+5 Invoking GPGSM
+****************
+
+'gpgsm' is a tool similar to 'gpg' to provide digital encryption and
+signing services on X.509 certificates and the CMS protocol. It is
+mainly used as a backend for S/MIME mail processing. 'gpgsm' includes a
+full featured certificate management and complies with all rules defined
+for the German Sphinx project.
+
+ *Note Option Index::, for an index to 'GPGSM''s commands and options.
+
+* Menu:
+
+* GPGSM Commands:: List of all commands.
+* GPGSM Options:: List of all options.
+* GPGSM Configuration:: Configuration files.
+* GPGSM Examples:: Some usage examples.
+
+Developer information:
+* Unattended Usage:: Using 'gpgsm' from other programs.
+* GPGSM Protocol:: The protocol the server mode uses.
+
+
+File: gnupg.info, Node: GPGSM Commands, Next: GPGSM Options, Up: Invoking GPGSM
+
+5.1 Commands
+============
+
+Commands are not distinguished from options except for the fact that
+only one command is allowed.
+
+* Menu:
+
+* General GPGSM Commands:: Commands not specific to the functionality.
+* Operational GPGSM Commands:: Commands to select the type of operation.
+* Certificate Management:: How to manage certificates.
+
+
+File: gnupg.info, Node: General GPGSM Commands, Next: Operational GPGSM Commands, Up: GPGSM Commands
+
+5.1.1 Commands not specific to the function
+-------------------------------------------
+
+'--version'
+ Print the program version and licensing information. Note that you
+ cannot abbreviate this command.
+
+'--help, -h'
+ Print a usage message summarizing the most useful command-line
+ options. Note that you cannot abbreviate this command.
+
+'--warranty'
+ Print warranty information. Note that you cannot abbreviate this
+ command.
+
+'--dump-options'
+ Print a list of all available options and commands. Note that you
+ cannot abbreviate this command.
+
+
+File: gnupg.info, Node: Operational GPGSM Commands, Next: Certificate Management, Prev: General GPGSM Commands, Up: GPGSM Commands
+
+5.1.2 Commands to select the type of operation
+----------------------------------------------
+
+'--encrypt'
+ Perform an encryption. The keys the data is encrypted to must be
+ set using the option '--recipient'.
+
+'--decrypt'
+ Perform a decryption; the type of input is automatically
+ determined. It may either be in binary form or PEM encoded;
+ automatic determination of base-64 encoding is not done.
+
+'--sign'
+ Create a digital signature. The key used is either the fist one
+ found in the keybox or those set with the '--local-user' option.
+
+'--verify'
+ Check a signature file for validity. Depending on the arguments a
+ detached signature may also be checked.
+
+'--server'
+ Run in server mode and wait for commands on the 'stdin'.
+
+'--call-dirmngr COMMAND [ARGS]'
+ Behave as a Dirmngr client issuing the request COMMAND with the
+ optional list of ARGS. The output of the Dirmngr is printed
+ stdout. Please note that file names given as arguments should have
+ an absolute file name (i.e. commencing with '/') because they are
+ passed verbatim to the Dirmngr and the working directory of the
+ Dirmngr might not be the same as the one of this client. Currently
+ it is not possible to pass data via stdin to the Dirmngr. COMMAND
+ should not contain spaces.
+
+ This is command is required for certain maintaining tasks of the
+ dirmngr where a dirmngr must be able to call back to 'gpgsm'. See
+ the Dirmngr manual for details.
+
+'--call-protect-tool ARGUMENTS'
+ Certain maintenance operations are done by an external program call
+ 'gpg-protect-tool'; this is usually not installed in a directory
+ listed in the PATH variable. This command provides a simple
+ wrapper to access this tool. ARGUMENTS are passed verbatim to this
+ command; use '--help' to get a list of supported operations.
+
+
+File: gnupg.info, Node: Certificate Management, Prev: Operational GPGSM Commands, Up: GPGSM Commands
+
+5.1.3 How to manage the certificates and keys
+---------------------------------------------
+
+'--generate-key'
+'--gen-key'
+ This command allows the creation of a certificate signing request
+ or a self-signed certificate. It is commonly used along with the
+ '--output' option to save the created CSR or certificate into a
+ file. If used with the '--batch' a parameter file is used to
+ create the CSR or certificate and it is further possible to create
+ non-self-signed certificates.
+
+'--list-keys'
+'-k'
+ List all available certificates stored in the local key database.
+ Note that the displayed data might be reformatted for better human
+ readability and illegal characters are replaced by safe
+ substitutes.
+
+'--list-secret-keys'
+'-K'
+ List all available certificates for which a corresponding a secret
+ key is available.
+
+'--list-external-keys PATTERN'
+ List certificates matching PATTERN using an external server. This
+ utilizes the 'dirmngr' service.
+
+'--list-chain'
+ Same as '--list-keys' but also prints all keys making up the chain.
+
+'--dump-cert'
+'--dump-keys'
+ List all available certificates stored in the local key database
+ using a format useful mainly for debugging.
+
+'--dump-chain'
+ Same as '--dump-keys' but also prints all keys making up the chain.
+
+'--dump-secret-keys'
+ List all available certificates for which a corresponding a secret
+ key is available using a format useful mainly for debugging.
+
+'--dump-external-keys PATTERN'
+ List certificates matching PATTERN using an external server. This
+ utilizes the 'dirmngr' service. It uses a format useful mainly for
+ debugging.
+
+'--keydb-clear-some-cert-flags'
+ This is a debugging aid to reset certain flags in the key database
+ which are used to cache certain certificate stati. It is
+ especially useful if a bad CRL or a weird running OCSP responder
+ did accidentally revoke certificate. There is no security issue
+ with this command because 'gpgsm' always make sure that the
+ validity of a certificate is checked right before it is used.
+
+'--delete-keys PATTERN'
+ Delete the keys matching PATTERN. Note that there is no command to
+ delete the secret part of the key directly. In case you need to do
+ this, you should run the command 'gpgsm --dump-secret-keys KEYID'
+ before you delete the key, copy the string of hex-digits in the
+ "keygrip" line and delete the file consisting of these hex-digits
+ and the suffix '.key' from the 'private-keys-v1.d' directory below
+ our GnuPG home directory (usually '~/.gnupg').
+
+'--export [PATTERN]'
+ Export all certificates stored in the Keybox or those specified by
+ the optional PATTERN. Those pattern consist of a list of user ids
+ (*note how-to-specify-a-user-id::). When used along with the
+ '--armor' option a few informational lines are prepended before
+ each block. There is one limitation: As there is no commonly
+ agreed upon way to pack more than one certificate into an ASN.1
+ structure, the binary export (i.e. without using 'armor') works
+ only for the export of one certificate. Thus it is required to
+ specify a PATTERN which yields exactly one certificate. Ephemeral
+ certificate are only exported if all PATTERN are given as
+ fingerprints or keygrips.
+
+'--export-secret-key-p12 KEY-ID'
+ Export the private key and the certificate identified by KEY-ID
+ using the PKCS#12 format. When used with the '--armor' option a
+ few informational lines are prepended to the output. Note, that
+ the PKCS#12 format is not very secure and proper transport security
+ should be used to convey the exported key. (*Note option
+ --p12-charset::.)
+
+'--export-secret-key-p8 KEY-ID'
+'--export-secret-key-raw KEY-ID'
+ Export the private key of the certificate identified by KEY-ID with
+ any encryption stripped. The '...-raw' command exports in PKCS#1
+ format; the '...-p8' command exports in PKCS#8 format. When used
+ with the '--armor' option a few informational lines are prepended
+ to the output. These commands are useful to prepare a key for use
+ on a TLS server.
+
+'--import [FILES]'
+ Import the certificates from the PEM or binary encoded files as
+ well as from signed-only messages. This command may also be used
+ to import a secret key from a PKCS#12 file.
+
+'--learn-card'
+ Read information about the private keys from the smartcard and
+ import the certificates from there. This command utilizes the
+ 'gpg-agent' and in turn the 'scdaemon'.
+
+'--change-passphrase USER_ID'
+'--passwd USER_ID'
+ Change the passphrase of the private key belonging to the
+ certificate specified as USER_ID. Note, that changing the
+ passphrase/PIN of a smartcard is not yet supported.
+
+
+File: gnupg.info, Node: GPGSM Options, Next: GPGSM Configuration, Prev: GPGSM Commands, Up: Invoking GPGSM
+
+5.2 Option Summary
+==================
+
+'GPGSM' features a bunch of options to control the exact behaviour and
+to change the default configuration.
+
+* Menu:
+
+* Configuration Options:: How to change the configuration.
+* Certificate Options:: Certificate related options.
+* Input and Output:: Input and Output.
+* CMS Options:: How to change how the CMS is created.
+* Esoteric Options:: Doing things one usually do not want to do.
+
+
+File: gnupg.info, Node: Configuration Options, Next: Certificate Options, Up: GPGSM Options
+
+5.2.1 How to change the configuration
+-------------------------------------
+
+These options are used to change the configuration and are usually found
+in the option file.
+
+'--options FILE'
+ Reads configuration from FILE instead of from the default per-user
+ configuration file. The default configuration file is named
+ 'gpgsm.conf' and expected in the '.gnupg' directory directly below
+ the home directory of the user.
+
+'--homedir DIR'
+ Set the name of the home directory to DIR. If this option is not
+ used, the home directory defaults to '~/.gnupg'. It is only
+ recognized when given on the command line. It also overrides any
+ home directory stated through the environment variable 'GNUPGHOME'
+ or (on Windows systems) by means of the Registry entry
+ HKCU\SOFTWARE\GNU\GNUPG:HOMEDIR.
+
+ On Windows systems it is possible to install GnuPG as a portable
+ application. In this case only this command line option is
+ considered, all other ways to set a home directory are ignored.
+
+ To install GnuPG as a portable application under Windows, create an
+ empty file named 'gpgconf.ctl' in the same directory as the tool
+ 'gpgconf.exe'. The root of the installation is then that
+ directory; or, if 'gpgconf.exe' has been installed directly below a
+ directory named 'bin', its parent directory. You also need to make
+ sure that the following directories exist and are writable:
+ 'ROOT/home' for the GnuPG home and 'ROOT/usr/local/var/cache/gnupg'
+ for internal cache files.
+
+'-v'
+'--verbose'
+ Outputs additional information while running. You can increase the
+ verbosity by giving several verbose commands to 'gpgsm', such as
+ '-vv'.
+
+'--policy-file FILENAME'
+ Change the default name of the policy file to FILENAME.
+
+'--agent-program FILE'
+ Specify an agent program to be used for secret key operations. The
+ default value is determined by running the command 'gpgconf'. Note
+ that the pipe symbol ('|') is used for a regression test suite hack
+ and may thus not be used in the file name.
+
+'--dirmngr-program FILE'
+ Specify a dirmngr program to be used for CRL checks. The default
+ value is '/usr/local/bin/dirmngr'.
+
+'--prefer-system-dirmngr'
+ This option is obsolete and ignored.
+
+'--disable-dirmngr'
+ Entirely disable the use of the Dirmngr.
+
+'--no-autostart'
+ Do not start the gpg-agent or the dirmngr if it has not yet been
+ started and its service is required. This option is mostly useful
+ on machines where the connection to gpg-agent has been redirected
+ to another machines. If dirmngr is required on the remote machine,
+ it may be started manually using 'gpgconf --launch dirmngr'.
+
+'--no-secmem-warning'
+ Do not print a warning when the so called "secure memory" cannot be
+ used.
+
+'--log-file FILE'
+ When running in server mode, append all logging output to FILE.
+ Use 'socket://' to log to socket.
+
+
+File: gnupg.info, Node: Certificate Options, Next: Input and Output, Prev: Configuration Options, Up: GPGSM Options
+
+5.2.2 Certificate related options
+---------------------------------
+
+'--enable-policy-checks'
+'--disable-policy-checks'
+ By default policy checks are enabled. These options may be used to
+ change it.
+
+'--enable-crl-checks'
+'--disable-crl-checks'
+ By default the CRL checks are enabled and the DirMngr is used to
+ check for revoked certificates. The disable option is most useful
+ with an off-line network connection to suppress this check and also
+ to avoid that new certificates introduce a web bug by including a
+ certificate specific CRL DP. The disable option also disables an
+ issuer certificate lookup via the authorityInfoAccess property of
+ the certificate; the '--enable-issuer-key-retrieve' can be used to
+ make use of that property anyway.
+
+'--enable-trusted-cert-crl-check'
+'--disable-trusted-cert-crl-check'
+ By default the CRL for trusted root certificates are checked like
+ for any other certificates. This allows a CA to revoke its own
+ certificates voluntary without the need of putting all ever issued
+ certificates into a CRL. The disable option may be used to switch
+ this extra check off. Due to the caching done by the Dirmngr,
+ there will not be any noticeable performance gain. Note, that this
+ also disables possible OCSP checks for trusted root certificates.
+ A more specific way of disabling this check is by adding the
+ "relax" keyword to the root CA line of the 'trustlist.txt'
+
+'--force-crl-refresh'
+ Tell the dirmngr to reload the CRL for each request. For better
+ performance, the dirmngr will actually optimize this by suppressing
+ the loading for short time intervals (e.g. 30 minutes). This
+ option is useful to make sure that a fresh CRL is available for
+ certificates hold in the keybox. The suggested way of doing this
+ is by using it along with the option '--with-validation' for a key
+ listing command. This option should not be used in a configuration
+ file.
+
+'--enable-issuer-based-crl-check'
+ Run a CRL check even for certificates which do not have any CRL
+ distribution point. This requires that a suitable LDAP server has
+ been configured in Dirmngr and that the CRL can be found using the
+ issuer. This option reverts to what GnuPG did up to version
+ 2.2.20. This option is in general not useful.
+
+'--enable-ocsp'
+'--disable-ocsp'
+ By default OCSP checks are disabled. The enable option may be used
+ to enable OCSP checks via Dirmngr. If CRL checks are also enabled,
+ CRLs will be used as a fallback if for some reason an OCSP request
+ will not succeed. Note, that you have to allow OCSP requests in
+ Dirmngr's configuration too (option '--allow-ocsp') and configure
+ Dirmngr properly. If you do not do so you will get the error code
+ 'Not supported'.
+
+'--auto-issuer-key-retrieve'
+ If a required certificate is missing while validating the chain of
+ certificates, try to load that certificate from an external
+ location. This usually means that Dirmngr is employed to search
+ for the certificate. Note that this option makes a "web bug" like
+ behavior possible. LDAP server operators can see which keys you
+ request, so by sending you a message signed by a brand new key
+ (which you naturally will not have on your local keybox), the
+ operator can tell both your IP address and the time when you
+ verified the signature.
+
+'--validation-model NAME'
+ This option changes the default validation model. The only
+ possible values are "shell" (which is the default), "chain" which
+ forces the use of the chain model and "steed" for a new simplified
+ model. The chain model is also used if an option in the
+ 'trustlist.txt' or an attribute of the certificate requests it.
+ However the standard model (shell) is in that case always tried
+ first.
+
+'--ignore-cert-extension OID'
+ Add OID to the list of ignored certificate extensions. The OID is
+ expected to be in dotted decimal form, like '2.5.29.3'. This
+ option may be used more than once. Critical flagged certificate
+ extensions matching one of the OIDs in the list are treated as if
+ they are actually handled and thus the certificate will not be
+ rejected due to an unknown critical extension. Use this option
+ with care because extensions are usually flagged as critical for a
+ reason.
+
+
+File: gnupg.info, Node: Input and Output, Next: CMS Options, Prev: Certificate Options, Up: GPGSM Options
+
+5.2.3 Input and Output
+----------------------
+
+'--armor'
+'-a'
+ Create PEM encoded output. Default is binary output.
+
+'--base64'
+ Create Base-64 encoded output; i.e. PEM without the header lines.
+
+'--assume-armor'
+ Assume the input data is PEM encoded. Default is to autodetect the
+ encoding but this is may fail.
+
+'--assume-base64'
+ Assume the input data is plain base-64 encoded.
+
+'--assume-binary'
+ Assume the input data is binary encoded.
+
+'--p12-charset NAME'
+ 'gpgsm' uses the UTF-8 encoding when encoding passphrases for
+ PKCS#12 files. This option may be used to force the passphrase to
+ be encoded in the specified encoding NAME. This is useful if the
+ application used to import the key uses a different encoding and
+ thus will not be able to import a file generated by 'gpgsm'.
+ Commonly used values for NAME are 'Latin1' and 'CP850'. Note that
+ 'gpgsm' itself automagically imports any file with a passphrase
+ encoded to the most commonly used encodings.
+
+'--default-key USER_ID'
+ Use USER_ID as the standard key for signing. This key is used if
+ no other key has been defined as a signing key. Note, that the
+ first '--local-users' option also sets this key if it has not yet
+ been set; however '--default-key' always overrides this.
+
+'--local-user USER_ID'
+'-u USER_ID'
+ Set the user(s) to be used for signing. The default is the first
+ secret key found in the database.
+
+'--recipient NAME'
+'-r'
+ Encrypt to the user id NAME. There are several ways a user id may
+ be given (*note how-to-specify-a-user-id::).
+
+'--output FILE'
+'-o FILE'
+ Write output to FILE. The default is to write it to stdout.
+
+'--with-key-data'
+ Displays extra information with the '--list-keys' commands.
+ Especially a line tagged 'grp' is printed which tells you the
+ keygrip of a key. This string is for example used as the file name
+ of the secret key. Implies '--with-colons'.
+
+'--with-validation'
+ When doing a key listing, do a full validation check for each key
+ and print the result. This is usually a slow operation because it
+ requires a CRL lookup and other operations.
+
+ When used along with '--import', a validation of the certificate to
+ import is done and only imported if it succeeds the test. Note
+ that this does not affect an already available certificate in the
+ DB. This option is therefore useful to simply verify a certificate.
+
+'--with-md5-fingerprint'
+ For standard key listings, also print the MD5 fingerprint of the
+ certificate.
+
+'--with-keygrip'
+ Include the keygrip in standard key listings. Note that the
+ keygrip is always listed in '--with-colons' mode.
+
+'--with-secret'
+ Include info about the presence of a secret key in public key
+ listings done with '--with-colons'.
+
+
+File: gnupg.info, Node: CMS Options, Next: Esoteric Options, Prev: Input and Output, Up: GPGSM Options
+
+5.2.4 How to change how the CMS is created
+------------------------------------------
+
+'--include-certs N'
+ Using N of -2 includes all certificate except for the root cert, -1
+ includes all certs, 0 does not include any certs, 1 includes only
+ the signers cert and all other positive values include up to N
+ certificates starting with the signer cert. The default is -2.
+
+'--cipher-algo OID'
+ Use the cipher algorithm with the ASN.1 object identifier OID for
+ encryption. For convenience the strings '3DES', 'AES' and 'AES256'
+ may be used instead of their OIDs. The default is 'AES'
+ (2.16.840.1.101.3.4.1.2).
+
+'--digest-algo name'
+ Use 'name' as the message digest algorithm. Usually this algorithm
+ is deduced from the respective signing certificate. This option
+ forces the use of the given algorithm and may lead to severe
+ interoperability problems.
+
+
+File: gnupg.info, Node: Esoteric Options, Prev: CMS Options, Up: GPGSM Options
+
+5.2.5 Doing things one usually do not want to do
+------------------------------------------------
+
+'--extra-digest-algo NAME'
+ Sometimes signatures are broken in that they announce a different
+ digest algorithm than actually used. 'gpgsm' uses a one-pass data
+ processing model and thus needs to rely on the announced digest
+ algorithms to properly hash the data. As a workaround this option
+ may be used to tell 'gpgsm' to also hash the data using the
+ algorithm NAME; this slows processing down a little bit but allows
+ verification of such broken signatures. If 'gpgsm' prints an error
+ like "digest algo 8 has not been enabled" you may want to try this
+ option, with 'SHA256' for NAME.
+
+'--faked-system-time EPOCH'
+ This option is only useful for testing; it sets the system time
+ back or forth to EPOCH which is the number of seconds elapsed since
+ the year 1970. Alternatively EPOCH may be given as a full ISO time
+ string (e.g. "20070924T154812").
+
+'--with-ephemeral-keys'
+ Include ephemeral flagged keys in the output of key listings. Note
+ that they are included anyway if the key specification for a
+ listing is given as fingerprint or keygrip.
+
+'--debug-level LEVEL'
+ Select the debug level for investigating problems. LEVEL may be a
+ numeric value or by a keyword:
+
+ 'none'
+ No debugging at all. A value of less than 1 may be used
+ instead of the keyword.
+ 'basic'
+ Some basic debug messages. A value between 1 and 2 may be
+ used instead of the keyword.
+ 'advanced'
+ More verbose debug messages. A value between 3 and 5 may be
+ used instead of the keyword.
+ 'expert'
+ Even more detailed messages. A value between 6 and 8 may be
+ used instead of the keyword.
+ 'guru'
+ All of the debug messages you can get. A value greater than 8
+ may be used instead of the keyword. The creation of hash
+ tracing files is only enabled if the keyword is used.
+
+ How these messages are mapped to the actual debugging flags is not
+ specified and may change with newer releases of this program. They
+ are however carefully selected to best aid in debugging.
+
+'--debug FLAGS'
+ This option is only useful for debugging and the behaviour may
+ change at any time without notice; using '--debug-levels' is the
+ preferred method to select the debug verbosity. FLAGS are bit
+ encoded and may be given in usual C-Syntax. The currently defined
+ bits are:
+
+ '0 (1)'
+ X.509 or OpenPGP protocol related data
+ '1 (2)'
+ values of big number integers
+ '2 (4)'
+ low level crypto operations
+ '5 (32)'
+ memory allocation
+ '6 (64)'
+ caching
+ '7 (128)'
+ show memory statistics
+ '9 (512)'
+ write hashed data to files named 'dbgmd-000*'
+ '10 (1024)'
+ trace Assuan protocol
+
+ Note, that all flags set using this option may get overridden by
+ '--debug-level'.
+
+'--debug-all'
+ Same as '--debug=0xffffffff'
+
+'--debug-allow-core-dump'
+ Usually 'gpgsm' tries to avoid dumping core by well written code
+ and by disabling core dumps for security reasons. However, bugs
+ are pretty durable beasts and to squash them it is sometimes useful
+ to have a core dump. This option enables core dumps unless the Bad
+ Thing happened before the option parsing.
+
+'--debug-no-chain-validation'
+ This is actually not a debugging option but only useful as such.
+ It lets 'gpgsm' bypass all certificate chain validation checks.
+
+'--debug-ignore-expiration'
+ This is actually not a debugging option but only useful as such.
+ It lets 'gpgsm' ignore all notAfter dates, this is used by the
+ regression tests.
+
+'--passphrase-fd n'
+ Read the passphrase from file descriptor 'n'. Only the first line
+ will be read from file descriptor 'n'. If you use 0 for 'n', the
+ passphrase will be read from STDIN. This can only be used if only
+ one passphrase is supplied.
+
+ Note that this passphrase is only used if the option '--batch' has
+ also been given.
+
+'--pinentry-mode mode'
+ Set the pinentry mode to 'mode'. Allowed values for 'mode' are:
+ default
+ Use the default of the agent, which is 'ask'.
+ ask
+ Force the use of the Pinentry.
+ cancel
+ Emulate use of Pinentry's cancel button.
+ error
+ Return a Pinentry error ("No Pinentry").
+ loopback
+ Redirect Pinentry queries to the caller. Note that in
+ contrast to Pinentry the user is not prompted again if he
+ enters a bad password.
+
+'--request-origin ORIGIN'
+ Tell gpgsm to assume that the operation ultimately originated at
+ ORIGIN. Depending on the origin certain restrictions are applied
+ and the Pinentry may include an extra note on the origin.
+ Supported values for ORIGIN are: 'local' which is the default,
+ 'remote' to indicate a remote origin or 'browser' for an operation
+ requested by a web browser.
+
+'--no-common-certs-import'
+ Suppress the import of common certificates on keybox creation.
+
+ All the long options may also be given in the configuration file
+after stripping off the two leading dashes.
+
+
+File: gnupg.info, Node: GPGSM Configuration, Next: GPGSM Examples, Prev: GPGSM Options, Up: Invoking GPGSM
+
+5.3 Configuration files
+=======================
+
+There are a few configuration files to control certain aspects of
+'gpgsm''s operation. Unless noted, they are expected in the current
+home directory (*note option --homedir::).
+
+'gpgsm.conf'
+ This is the standard configuration file read by 'gpgsm' on startup.
+ It may contain any valid long option; the leading two dashes may
+ not be entered and the option may not be abbreviated. This default
+ name may be changed on the command line (*note gpgsm-option
+ --options::). You should backup this file.
+
+'policies.txt'
+ This is a list of allowed CA policies. This file should list the
+ object identifiers of the policies line by line. Empty lines and
+ lines starting with a hash mark are ignored. Policies missing in
+ this file and not marked as critical in the certificate will print
+ only a warning; certificates with policies marked as critical and
+ not listed in this file will fail the signature verification. You
+ should backup this file.
+
+ For example, to allow only the policy 2.289.9.9, the file should
+ look like this:
+
+ # Allowed policies
+ 2.289.9.9
+
+'qualified.txt'
+ This is the list of root certificates used for qualified
+ certificates. They are defined as certificates capable of creating
+ legally binding signatures in the same way as handwritten
+ signatures are. Comments start with a hash mark and empty lines
+ are ignored. Lines do have a length limit but this is not a
+ serious limitation as the format of the entries is fixed and
+ checked by 'gpgsm': A non-comment line starts with optional
+ whitespace, followed by exactly 40 hex characters, white space and
+ a lowercased 2 letter country code. Additional data delimited with
+ by a white space is current ignored but might late be used for
+ other purposes.
+
+ Note that even if a certificate is listed in this file, this does
+ not mean that the certificate is trusted; in general the
+ certificates listed in this file need to be listed also in
+ 'trustlist.txt'.
+
+ This is a global file an installed in the data directory (e.g.
+ '/usr/local/share/gnupg/qualified.txt'). GnuPG installs a suitable
+ file with root certificates as used in Germany. As new Root-CA
+ certificates may be issued over time, these entries may need to be
+ updated; new distributions of this software should come with an
+ updated list but it is still the responsibility of the
+ Administrator to check that this list is correct.
+
+ Every time 'gpgsm' uses a certificate for signing or verification
+ this file will be consulted to check whether the certificate under
+ question has ultimately been issued by one of these CAs. If this
+ is the case the user will be informed that the verified signature
+ represents a legally binding ("qualified") signature. When
+ creating a signature using such a certificate an extra prompt will
+ be issued to let the user confirm that such a legally binding
+ signature shall really be created.
+
+ Because this software has not yet been approved for use with such
+ certificates, appropriate notices will be shown to indicate this
+ fact.
+
+'help.txt'
+ This is plain text file with a few help entries used with
+ 'pinentry' as well as a large list of help items for 'gpg' and
+ 'gpgsm'. The standard file has English help texts; to install
+ localized versions use filenames like 'help.LL.txt' with LL
+ denoting the locale. GnuPG comes with a set of predefined help
+ files in the data directory (e.g.
+ '/usr/local/share/gnupg/gnupg/help.de.txt') and allows overriding
+ of any help item by help files stored in the system configuration
+ directory (e.g. '/etc/gnupg/help.de.txt'). For a reference of the
+ help file's syntax, please see the installed 'help.txt' file.
+
+'com-certs.pem'
+ This file is a collection of common certificates used to populated
+ a newly created 'pubring.kbx'. An administrator may replace this
+ file with a custom one. The format is a concatenation of PEM
+ encoded X.509 certificates. This global file is installed in the
+ data directory (e.g. '/usr/local/share/gnupg/com-certs.pem').
+
+ Note that on larger installations, it is useful to put predefined
+files into the directory '/etc/skel/.gnupg/' so that newly created users
+start up with a working configuration. For existing users a small
+helper script is provided to create these files (*note addgnupghome::).
+
+ For internal purposes 'gpgsm' creates and maintains a few other
+files; they all live in the current home directory (*note option
+--homedir::). Only 'gpgsm' may modify these files.
+
+'pubring.kbx'
+ This a database file storing the certificates as well as meta
+ information. For debugging purposes the tool 'kbxutil' may be used
+ to show the internal structure of this file. You should backup
+ this file.
+
+'random_seed'
+ This content of this file is used to maintain the internal state of
+ the random number generator across invocations. The same file is
+ used by other programs of this software too.
+
+'S.gpg-agent'
+ If this file exists 'gpgsm' will first try to connect to this
+ socket for accessing 'gpg-agent' before starting a new 'gpg-agent'
+ instance. Under Windows this socket (which in reality be a plain
+ file describing a regular TCP listening port) is the standard way
+ of connecting the 'gpg-agent'.
+
+
+File: gnupg.info, Node: GPGSM Examples, Next: Unattended Usage, Prev: GPGSM Configuration, Up: Invoking GPGSM
+
+5.4 Examples
+============
+
+ $ gpgsm -er goo@bar.net <plaintext >ciphertext
+
+
+File: gnupg.info, Node: Unattended Usage, Next: GPGSM Protocol, Prev: GPGSM Examples, Up: Invoking GPGSM
+
+5.5 Unattended Usage
+====================
+
+'gpgsm' is often used as a backend engine by other software. To help
+with this a machine interface has been defined to have an unambiguous
+way to do this. This is most likely used with the '--server' command
+but may also be used in the standard operation mode by using the
+'--status-fd' option.
+
+* Menu:
+
+* Automated signature checking:: Automated signature checking.
+* CSR and certificate creation:: CSR and certificate creation.
+
+
+File: gnupg.info, Node: Automated signature checking, Next: CSR and certificate creation, Up: Unattended Usage
+
+5.5.1 Automated signature checking
+----------------------------------
+
+It is very important to understand the semantics used with signature
+verification. Checking a signature is not as simple as it may sound and
+so the operation is a bit complicated. In most cases it is required to
+look at several status lines. Here is a table of all cases a signed
+message may have:
+
+The signature is valid
+ This does mean that the signature has been successfully verified,
+ the certificates are all sane. However there are two subcases with
+ important information: One of the certificates may have expired or
+ a signature of a message itself as expired. It is a sound practise
+ to consider such a signature still as valid but additional
+ information should be displayed. Depending on the subcase 'gpgsm'
+ will issue these status codes:
+ signature valid and nothing did expire
+ 'GOODSIG', 'VALIDSIG', 'TRUST_FULLY'
+ signature valid but at least one certificate has expired
+ 'EXPKEYSIG', 'VALIDSIG', 'TRUST_FULLY'
+ signature valid but expired
+ 'EXPSIG', 'VALIDSIG', 'TRUST_FULLY' Note, that this case is
+ currently not implemented.
+
+The signature is invalid
+ This means that the signature verification failed (this is an
+ indication of a transfer error, a program error or tampering with
+ the message). 'gpgsm' issues one of these status codes sequences:
+ 'BADSIG'
+ 'GOODSIG, VALIDSIG TRUST_NEVER'
+
+Error verifying a signature
+ For some reason the signature could not be verified, i.e. it
+ cannot be decided whether the signature is valid or invalid. A
+ common reason for this is a missing certificate.
+
+
+File: gnupg.info, Node: CSR and certificate creation, Prev: Automated signature checking, Up: Unattended Usage
+
+5.5.2 CSR and certificate creation
+----------------------------------
+
+The command '--generate-key' may be used along with the option '--batch'
+to either create a certificate signing request (CSR) or an X.509
+certificate. This is controlled by a parameter file; the format of this
+file is as follows:
+
+ * Text only, line length is limited to about 1000 characters.
+ * UTF-8 encoding must be used to specify non-ASCII characters.
+ * Empty lines are ignored.
+ * Leading and trailing while space is ignored.
+ * A hash sign as the first non white space character indicates a
+ comment line.
+ * Control statements are indicated by a leading percent sign, the
+ arguments are separated by white space from the keyword.
+ * Parameters are specified by a keyword, followed by a colon.
+ Arguments are separated by white space.
+ * The first parameter must be 'Key-Type', control statements may be
+ placed anywhere.
+ * The order of the parameters does not matter except for 'Key-Type'
+ which must be the first parameter. The parameters are only used
+ for the generated CSR/certificate; parameters from previous sets
+ are not used. Some syntactically checks may be performed.
+ * Key generation takes place when either the end of the parameter
+ file is reached, the next 'Key-Type' parameter is encountered or at
+ the control statement '%commit' is encountered.
+
+Control statements:
+
+%echo TEXT
+ Print TEXT as diagnostic.
+
+%dry-run
+ Suppress actual key generation (useful for syntax checking).
+
+%commit
+ Perform the key generation. Note that an implicit commit is done
+ at the next Key-Type parameter.
+
+General Parameters:
+
+Key-Type: ALGO
+ Starts a new parameter block by giving the type of the primary key.
+ The algorithm must be capable of signing. This is a required
+ parameter. The only supported value for ALGO is 'rsa'.
+
+Key-Length: NBITS
+ The requested length of a generated key in bits. Defaults to 3072.
+
+Key-Grip: HEXSTRING
+ This is optional and used to generate a CSR or certificate for an
+ already existing key. Key-Length will be ignored when given.
+
+Key-Usage: USAGE-LIST
+ Space or comma delimited list of key usage, allowed values are
+ 'encrypt', 'sign' and 'cert'. This is used to generate the
+ keyUsage extension. Please make sure that the algorithm is capable
+ of this usage. Default is to allow encrypt and sign.
+
+Name-DN: SUBJECT-NAME
+ This is the Distinguished Name (DN) of the subject in RFC-2253
+ format.
+
+Name-Email: STRING
+ This is an email address for the altSubjectName. This parameter is
+ optional but may occur several times to add several email addresses
+ to a certificate.
+
+Name-DNS: STRING
+ The is an DNS name for the altSubjectName. This parameter is
+ optional but may occur several times to add several DNS names to a
+ certificate.
+
+Name-URI: STRING
+ This is an URI for the altSubjectName. This parameter is optional
+ but may occur several times to add several URIs to a certificate.
+
+Additional parameters used to create a certificate (in contrast to a
+certificate signing request):
+
+Serial: SN
+ If this parameter is given an X.509 certificate will be generated.
+ SN is expected to be a hex string representing an unsigned integer
+ of arbitrary length. The special value 'random' can be used to
+ create a 64 bit random serial number.
+
+Issuer-DN: ISSUER-NAME
+ This is the DN name of the issuer in RFC-2253 format. If it is not
+ set it will default to the subject DN and a special GnuPG extension
+ will be included in the certificate to mark it as a standalone
+ certificate.
+
+Creation-Date: ISO-DATE
+Not-Before: ISO-DATE
+ Set the notBefore date of the certificate. Either a date like
+ '1986-04-26' or '1986-04-26 12:00' or a standard ISO timestamp like
+ '19860426T042640' may be used. The time is considered to be UTC.
+ If it is not given the current date is used.
+
+Expire-Date: ISO-DATE
+Not-After: ISO-DATE
+ Set the notAfter date of the certificate. Either a date like
+ '2063-04-05' or '2063-04-05 17:00' or a standard ISO timestamp like
+ '20630405T170000' may be used. The time is considered to be UTC.
+ If it is not given a default value in the not too far future is
+ used.
+
+Signing-Key: KEYGRIP
+ This gives the keygrip of the key used to sign the certificate. If
+ it is not given a self-signed certificate will be created. For
+ compatibility with future versions, it is suggested to prefix the
+ keygrip with a '&'.
+
+Hash-Algo: HASH-ALGO
+ Use HASH-ALGO for this CSR or certificate. The supported hash
+ algorithms are: 'sha1', 'sha256', 'sha384' and 'sha512'; they may
+ also be specified with uppercase letters. The default is 'sha256'.
+
+
+File: gnupg.info, Node: GPGSM Protocol, Prev: Unattended Usage, Up: Invoking GPGSM
+
+5.6 The Protocol the Server Mode Uses
+=====================================
+
+Description of the protocol used to access 'GPGSM'. 'GPGSM' does
+implement the Assuan protocol and in addition provides a regular command
+line interface which exhibits a full client to this protocol (but uses
+internal linking). To start 'gpgsm' as a server the command line the
+option '--server' must be used. Additional options are provided to
+select the communication method (i.e. the name of the socket).
+
+ We assume that the connection has already been established; see the
+Assuan manual for details.
+
+* Menu:
+
+* GPGSM ENCRYPT:: Encrypting a message.
+* GPGSM DECRYPT:: Decrypting a message.
+* GPGSM SIGN:: Signing a message.
+* GPGSM VERIFY:: Verifying a message.
+* GPGSM GENKEY:: Generating a key.
+* GPGSM LISTKEYS:: List available keys.
+* GPGSM EXPORT:: Export certificates.
+* GPGSM IMPORT:: Import certificates.
+* GPGSM DELETE:: Delete certificates.
+* GPGSM GETAUDITLOG:: Retrieve an audit log.
+* GPGSM GETINFO:: Information about the process
+* GPGSM OPTION:: Session options.
+
+
+File: gnupg.info, Node: GPGSM ENCRYPT, Next: GPGSM DECRYPT, Up: GPGSM Protocol
+
+5.6.1 Encrypting a Message
+--------------------------
+
+Before encryption can be done the recipient must be set using the
+command:
+
+ RECIPIENT USERID
+
+ Set the recipient for the encryption. USERID should be the internal
+representation of the key; the server may accept any other way of
+specification. If this is a valid and trusted recipient the server does
+respond with OK, otherwise the return is an ERR with the reason why the
+recipient cannot be used, the encryption will then not be done for this
+recipient. If the policy is not to encrypt at all if not all recipients
+are valid, the client has to take care of this. All 'RECIPIENT'
+commands are cumulative until a 'RESET' or an successful 'ENCRYPT'
+command.
+
+ INPUT FD[=N] [--armor|--base64|--binary]
+
+ Set the file descriptor for the message to be encrypted to N.
+Obviously the pipe must be open at that point, the server establishes
+its own end. If the server returns an error the client should consider
+this session failed. If N is not given, this commands uses the last
+file descriptor passed to the application. *Note the assuan_sendfd
+function: (assuan)fun-assuan_sendfd, on how to do descriptor passing.
+
+ The '--armor' option may be used to advise the server that the input
+data is in PEM format, '--base64' advises that a raw base-64 encoding is
+used, '--binary' advises of raw binary input (BER). If none of these
+options is used, the server tries to figure out the used encoding, but
+this may not always be correct.
+
+ OUTPUT FD[=N] [--armor|--base64]
+
+ Set the file descriptor to be used for the output (i.e. the
+encrypted message). Obviously the pipe must be open at that point, the
+server establishes its own end. If the server returns an error the
+client should consider this session failed.
+
+ The option '--armor' encodes the output in PEM format, the '--base64'
+option applies just a base-64 encoding. No option creates binary output
+(BER).
+
+ The actual encryption is done using the command
+
+ ENCRYPT
+
+ It takes the plaintext from the 'INPUT' command, writes to the
+ciphertext to the file descriptor set with the 'OUTPUT' command, take
+the recipients from all the recipients set so far. If this command
+fails the clients should try to delete all output currently done or
+otherwise mark it as invalid. 'GPGSM' does ensure that there will not
+be any security problem with leftover data on the output in this case.
+
+ This command should in general not fail, as all necessary checks have
+been done while setting the recipients. The input and output pipes are
+closed.
+
+
+File: gnupg.info, Node: GPGSM DECRYPT, Next: GPGSM SIGN, Prev: GPGSM ENCRYPT, Up: GPGSM Protocol
+
+5.6.2 Decrypting a message
+--------------------------
+
+Input and output FDs are set the same way as in encryption, but 'INPUT'
+refers to the ciphertext and 'OUTPUT' to the plaintext. There is no
+need to set recipients. 'GPGSM' automatically strips any S/MIME headers
+from the input, so it is valid to pass an entire MIME part to the INPUT
+pipe.
+
+ The decryption is done by using the command
+
+ DECRYPT
+
+ It performs the decrypt operation after doing some check on the
+internal state (e.g. that all needed data has been set). Because it
+utilizes the GPG-Agent for the session key decryption, there is no need
+to ask the client for a protecting passphrase - GpgAgent takes care of
+this by requesting this from the user.
+
+
+File: gnupg.info, Node: GPGSM SIGN, Next: GPGSM VERIFY, Prev: GPGSM DECRYPT, Up: GPGSM Protocol
+
+5.6.3 Signing a Message
+-----------------------
+
+Signing is usually done with these commands:
+
+ INPUT FD[=N] [--armor|--base64|--binary]
+
+ This tells 'GPGSM' to read the data to sign from file descriptor N.
+
+ OUTPUT FD[=M] [--armor|--base64]
+
+ Write the output to file descriptor M. If a detached signature is
+requested, only the signature is written.
+
+ SIGN [--detached]
+
+ Sign the data set with the 'INPUT' command and write it to the sink
+set by 'OUTPUT'. With '--detached', a detached signature is created
+(surprise).
+
+ The key used for signing is the default one or the one specified in
+the configuration file. To get finer control over the keys, it is
+possible to use the command
+
+ SIGNER USERID
+
+ to set the signer's key. USERID should be the internal
+representation of the key; the server may accept any other way of
+specification. If this is a valid and trusted recipient the server does
+respond with OK, otherwise the return is an ERR with the reason why the
+key cannot be used, the signature will then not be created using this
+key. If the policy is not to sign at all if not all keys are valid, the
+client has to take care of this. All 'SIGNER' commands are cumulative
+until a 'RESET' is done. Note that a 'SIGN' does not reset this list of
+signers which is in contrast to the 'RECIPIENT' command.
+
+
+File: gnupg.info, Node: GPGSM VERIFY, Next: GPGSM GENKEY, Prev: GPGSM SIGN, Up: GPGSM Protocol
+
+5.6.4 Verifying a Message
+-------------------------
+
+To verify a message the command:
+
+ VERIFY
+
+ is used. It does a verify operation on the message send to the input
+FD. The result is written out using status lines. If an output FD was
+given, the signed text will be written to that. If the signature is a
+detached one, the server will inquire about the signed material and the
+client must provide it.
+