gnupg: Agent Options
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.
‘-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’
Set debug 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. This option is only useful for debugging and the behavior
may change at any time without notice.
‘--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 one 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 ⇒
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’
These options are obsolete and have no effect. The extended key
format is used for years now and has been supported since 2.1.12.
Existing keys in the old format are migrated to the new format as
soon as they are touched.
‘--enable-ssh-support’
‘--enable-win32-openssh-support’
‘--enable-putty-support’
On Unix platforms the OpenSSH Agent protocol is always enabled, but
‘gpg-agent’ will only set the ‘SSH_AUTH_SOCK’ variable if the
option ‘enable-ssh-support’ is given. Some Linux distributions use
the presence of this option to decide whether the old ssh-agent
shall be started.
On Windows support for the native ssh implementation must be
enabled using the the option ‘enable-win32-openssh-support’. For
using gpg-agent as a replacement for PuTTY's Pageant, the option
‘enable-putty-support’ must be enabled.
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 or via Named Pipes) or the protocol used
by PuTTY. Consequently, this allows one to use the gpg-agent as a
drop-in replacement for the 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’.
The order in which keys are presented to ssh are:
‘Negative Use-for-ssh values’
If a key file has the attribute "Use-for-ssh" and its value is
negative, these keys are presented first to ssh. The negative
values are capped at -999 with -999 being lower ranked than
-1. These values can be used to prefer on-disk keys over keys
taken from active cards.
‘Active cards’
Active cards (inserted into a card reader or plugged in
tokens) are always tried; they are ordered by their serial
numbers.
‘Keys listed in the sshcontrol file’
Non-disabled keys from the sshcontrol file are presented in
the order they appear in this file. Note that the sshcontrol
file is deprecated.
‘Positive Use-for-ssh values’
If a key file has the attribute "Use-for-ssh" and its value is
"yes", "true", or any positive number the key is presented in
the order of their values. "yes" and "true" have a value of
1; other values are capped at 99999.
Editing the "Use-for-ssh" values can be done with an editor or
using ‘gpg-connect-agent’ and "KEYATTR" (Remember to append a colon
to the key; i.e. use "Use-for-ssh:").
‘--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
Info Catalog
gnupg: Agent Commands
gnupg: Invoking GPG-AGENT
gnupg: Agent Configuration