diff options
Diffstat (limited to 'doc/gnupg.info-1')
| -rw-r--r-- | doc/gnupg.info-1 | 7172 |
1 files changed, 7172 insertions, 0 deletions
diff --git a/doc/gnupg.info-1 b/doc/gnupg.info-1 new file mode 100644 index 0000000..3d95d00 --- /dev/null +++ b/doc/gnupg.info-1 @@ -0,0 +1,7172 @@ +This is gnupg.info, produced by makeinfo version 6.5 from gnupg.texi. + +This is the 'The GNU Privacy Guard Manual' (version 2.2.40-beta3, +October 2022). + + (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.40-beta3, +October 2022). + + (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. + +'--steal-socket' + In '--daemon' mode, gpg-agent detects an already running gpg-agent + and does not allow to start a new instance. This option can be + used to override this check: the new gpg-agent process will try to + take over the communication sockets from the already running + process and start anyway. This option should in general not be + used. + +'-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. + +'--no-user-trustlist' + Entirely ignore the user trust list and consider only the global + trustlist ('/etc/gnupg/trustlist.txt'). This implies the *note + option --no-allow-mark-trusted::. + +'--sys-trustlist-name FILE' + Changes the default name for the global trustlist from + "trustlist.txt" to FILE. If FILE does not contain any slashes and + does not start with "~/" it is searched in the system configuration + directory ('/etc/gnupg'). + +'--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-sym-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. If FILE does not contain any slashes and does + not start with "~/" it is searched in the system configuration + directory ('/etc/gnupg'). The default is not to use any pattern + file. The second version of this option is only used when creating + a new symmetric key to allow the use of different patterns for such + passphrases. + + 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-formatted-passphrase' + This option asks the Pinentry to enable passphrase formatting when + asking the user for a new passphrase and masking of the passphrase + is turned off. + + If passphrase formatting is enabled, then all non-breaking space + characters are stripped from the entered passphrase. Passphrase + formatting is mostly useful in combination with passphrases + generated with the GENPIN feature of some Pinentries. Note that + such a generated passphrase, if not modified by the user, skips all + passphrase constraints checking because such constraints would + actually weaken the generated passphrase. + +'--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; + the *note option --no-user-trustlist:: enforces the use of only + this global list. + + 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. The test on the available of Tor is done + by trying to connects to a SOCKS proxy at either port 9050 or + 9150); if another type of proxy is listening on one of these ports, + you should use '--no-use-tor'. + +'--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. Somes keyservers use + 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 'https://keyserver.ubuntu.com'. + + Windows users with a keyserver running on their Active Directory + may use the short form '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 things are more + complicated and two methods are available: + + The modern method (since version 2.2.28) is to use the very same + syntax as used with the option '--ldapserver'. Please see over + there for details; here is an example: + + keyserver ldap:ldap.example.com::uid=USERNAME,ou=GnuPG Users, + dc=example,dc=com:PASSWORD::starttls + + The other method is to use a full URL for NAME; 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 your LDAP administrator. Note that + only simple authentication (i.e. cleartext passwords) is supported + and thus using ldaps is strongly suggested (since 2.2.28 "ldaps" + defaults to port 389 and uses STARTTLS). On Windows authentication + via AD can be requested by adding 'gpgNtds=1' after the fourth + question mark instead of the bindname and password parameter. + +'--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 [http://]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 X.509 + 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:FLAGS + + 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) + +'--ldapserver SPEC' + This is an alternative way to specify LDAP servers for CRL and + X.509 certificate retrieval. If this option is used the servers + configured in 'dirmngr_ldapservers.conf' (or the file given by + '--ldapserverlist-file') are cleared. Note that + 'dirmngr_ldapservers.conf' is not read again by a reload signal. + However, '--ldapserver' options are read again. + + SPEC is either a proper LDAP URL or a colon delimited list of the + form + + HOSTNAME:PORT:USERNAME:PASSWORD:BASE_DN:FLAGS: + + with an optional prefix of 'ldap:' (but without the two slashes + which would turn this into a proper LDAP URL). FLAGS is a list of + one or more comma delimited keywords: + 'plain' + The default: Do not use a TLS secured connection at all; the + default port is 389. + 'starttls' + Use STARTTLS to secure the connection; the default port is + 389. + 'ldaptls' + Tunnel LDAP through a TLS connection; the default port is 636. + 'ntds' + On Windows authenticate the LDAP connection using the Active + Directory with the current user. + 'areconly' + On Windows use only the A or AAAA record when resolving the + LDAP server name. + + Note that in an URL style specification the scheme 'ldaps://' + refers to STARTTLS and _not_ to LDAP-over-TLS. + +'--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. + +'--ignore-cert FPR|FILE' + Entirely ignore certificates with the fingerprint FPR. As an + alternative to the fingerprint a filename can be given in which + case all certificates described in that file are ignored. 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. The format of such a file is a list of SHA-1 + fingerprint, one per line with optional colons between the bytes. + Empty lines and lines prefixed with a hash mark are ignored. + + This option is useful as a quick workaround to exclude certain + certificates from the system store. + +'--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 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 and + may thus be used to see what keys 'gpg' might use. In particular + external methods as defined by '--auto-key-locate' are used to + locate a key if the arguments comain valid mail addresses. 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. If a fingerprint is given and and + the methods defined by -auto-key-locate define LDAP servers, the + key is fetched from these resources; defined non-LDAP keyservers + are skipped. + +'--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 keyring 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 keyring and quit. + + quit + Quit the program without updating the keyring. + + 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. If + you need to update an existing signature, for example to add or + change notation data, you need to use the option + '--force-sign-key'. + + 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 most of them 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'. Should + not be used in an option file. + +'-v, --verbose' + Give more information during processing. If used twice, the input + data is listed in detail. + +'--no-verbose' + Reset verbose level to 0. Should not be used in an option file. + +'-q, --quiet' + Try to be as quiet as possible. Should not be used in an option + file. + +'--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 + '/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'. + Should not be used in an option file. + +'--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. Should not be used in an option + file. + +'--no' + Assume "no" on most questions. Should not be used in an option + file. + +'--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" unless '--homedir' or $GNUPGHOME + is 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. + +'--primary-keyring FILE' + This is a varian of '--keyring' and designates FILE as the primary + public keyring. This means that newly imported keys (via + '--import' or keyserver '--recv-from') will go to this keyring. + +'--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. + +'--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. This option should not be used on + Windows. 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. This option should not be used in an option + file. + + This option has no effect on Windows. There the internal used + UTF-8 encoding is translated for console input and output. The + command line arguments are expected as Unicode and translated to + UTF-8. Thus when calling this program from another, make sure to + use the Unicode version of CreateProcess. + +'--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 should be given as + 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. If the given + key is not locally available but an LDAP keyserver is configured + the missing key is imported from that server. + +'--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). + This method also allows to search by fingerprint using the + command '--locate-external-key'. Note that this mechanism is + actually a shortcut for the mechanism 'keyserver' but using + "ldap:///" as the keyserver. + + keyserver + Locate a key using a keyserver. This method also allows to + search by fingerprint using the command + '--locate-external-key' if any of the configured keyservers is + an LDAP server. + + keyserver-URL + In addition, a keyserver URL as used in the 'dirmngr' + configuration may be used here to query that particular + keyserver. This method also allows to search by fingerprint + using the command '--locate-external-key' if the URL specifies + an LDAP server. + + 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"/"hkps" for the HTTP (or compatible) keyservers or + "ldap"/"ldaps" for the LDAP keyservers. Note that your particular + installation of GnuPG may have other keyserver types available as + well. Keyserver schemes are case-insensitive. + + 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". However, if the actual used source is an LDAP + server "no-self-sigs-only" is assumed unless "self-sigs-only" has + been explictly configured. + +'--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 STRING. + +'--min-rsa-length N' + This option adjusts the compliance mode "de-vs" for stricter key + size requirements. For example, a value of 3000 turns rsa2048 and + dsa2048 keys into non-VS-NfD compliant keys. + +'--require-compliance' + To check that data has been encrypted according to the rules of the + current compliance mode, a gpg user needs to evaluate the status + lines. This is allows frontends to handle compliance check in a + more flexible way. However, for scripted use the required + evaluation of the status-line requires quite some effort; this + option can be used instead to make sure that the gpg process exits + with a failure if the compliance rules are not fulfilled. Note + that this option has currently an effect only in "de-vs" mode. + + +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. + +'--override-compliance-check' + The signature verification only allows the use of keys suitable in + the current compliance mode. If the compliance mode has been + forced by a global option, there might be no way to check certain + signature. This option allows to override this and prints an extra + warning in such a case. This option is ignored in -batch mode so + that no accidental unattended verification may happen. + +'--no-default-keyring' + Do not add the default keyring to the list of keyrings. Note that + GnuPG needs for almost all operations a keyring. Thus if you use + this option and do not provide alternate keyrings via '--keyring', + then GnuPG will still use the default keyring. + +'--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. + +'--force-sign-key' + This option modifies the behaviour of the commands + '--quick-sign-key', '--quick-lsign-key', and the "sign" + sub-commands of '--edit-key' by forcing the creation of a key + signature, even if one already exists. + +'--forbid-gen-key' + This option is intended for use in the global config file to + disallow the use of generate key commands. Those commands will + then fail with the error code for Not Enabled. + +'--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. + +GNUPG_BUILD_ROOT + This variable is only used by the regression test suite as a helper + under operating systems without proper support to figure out the + name of a process' text file. + +GNUPG_EXEC_DEBUG_FLAGS + This variable allows to enable diagnostics for process management. + A numeric decimal value is expected. Bit 0 enables general + diagnostics, bit 1 enables certain warnings on Windows. + + 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. +-t + Leading and trailing spaces are not removed from VALUE. The + optional single space after OP is here required. + + 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'. + +'--keyserver STRING' + This is a deprecated option. It was used to add an LDAP server to + use for X.509 certificate and CRL lookup. The alias '--ldapserver' + existed from version 2.2.28 to 2.2.33 but is now entirely ignored. + + LDAP servers must be given in the configuration for 'dirmngr'. + +'--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. + +'--compliance STRING' + Set the compliance mode. Valid values are shown when using "help" + for STRING. + +'--min-rsa-length N' + This option adjusts the compliance mode "de-vs" for stricter key + size requirements. For example, a value of 3000 turns rsa2048 and + dsa2048 keys into non-VS-NfD compliant keys. + +'--require-compliance' + To check that data has been encrypted according to the rules of the + current compliance mode, a gpgsm user needs to evaluate the status + lines. This is allows frontends to handle compliance check in a + more flexible way. However, for scripted use the required + evaluation of the status-line requires quite some effort; this + option can be used instead to make sure that the gpgsm process + exits with a failure if the compliance rules are not fulfilled. + Note that this option has currently an effect only in "de-vs" mode. + +'--ignore-cert-with-oid OID' + Add OID to the list of OIDs to be checked while reading + certificates from smartcards. The OID is expected to be in dotted + decimal form, like '2.5.29.3'. This option may be used more than + once. As of now certificates with an extended key usage matching + one of those OIDs are ignored during a '--learn-card' operation and + not imported. This option can help to keep the local key database + clear of unneeded certificates stored on smartcards. + +'--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. + +'--compatibility-flags FLAGS' + Set compatibility flags to work around problems due to + non-compliant certificates or data. The FLAGS are given as a comma + separated list of flag names and are OR-ed together. The special + flag "none" clears the list and allows to start over with an empty + list. To get a list of available flags the sole word "help" can be + used. + +'--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'. + |