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.
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/var/cache/gnupg' for
internal cache files.
'-v'
'--verbose'
Outputs additional information while running. You can increase the
verbosity by giving several verbose commands to 'gpg-agent', such
as '-vv'.
'-q'
'--quiet'
Try to be as quiet as possible.
'--batch'
Don't invoke a pinentry or do any other thing requiring human
interaction.
'--faked-system-time EPOCH'
This option is only useful for testing; it sets the system time
back or forth to EPOCH which is the number of seconds elapsed since
the year 1970.
'--debug-level LEVEL'
Select the debug level for investigating problems. LEVEL may be a
numeric value or a keyword:
'none'
No debugging at all. A value of less than 1 may be used
instead of the keyword.
'basic'
Some basic debug messages. A value between 1 and 2 may be
used instead of the keyword.
'advanced'
More verbose debug messages. A value between 3 and 5 may be
used instead of the keyword.
'expert'
Even more detailed messages. A value between 6 and 8 may be
used instead of the keyword.
'guru'
All of the debug messages you can get. A value greater than 8
may be used instead of the keyword. The creation of hash
tracing files is only enabled if the keyword is used.
How these messages are mapped to the actual debugging flags is not
specified and may change with newer releases of this program. They
are however carefully selected to best aid in debugging.
'--debug FLAGS'
This option is only useful for debugging and the behavior may
change at any time without notice. FLAGS are bit encoded and may
be given in usual C-Syntax. The currently defined bits are:
'0 (1)'
X.509 or OpenPGP protocol related data
'1 (2)'
values of big number integers
'2 (4)'
low level crypto operations
'5 (32)'
memory allocation
'6 (64)'
caching
'7 (128)'
show memory statistics
'9 (512)'
write hashed data to files named 'dbgmd-000*'
'10 (1024)'
trace Assuan protocol
'12 (4096)'
bypass all certificate validation
'--debug-all'
Same as '--debug=0xffffffff'
'--debug-wait N'
When running in server mode, wait N seconds before entering the
actual processing loop and print the pid. This gives time to
attach a debugger.
'--debug-quick-random'
This option inhibits the use of the very secure random quality
level (Libgcrypt’s 'GCRY_VERY_STRONG_RANDOM') and degrades all
request down to standard random quality. It is only used for
testing and should not be used for any production quality keys.
This option is only effective when given on the command line.
On GNU/Linux, another way to quickly generate insecure keys is to
use 'rngd' to fill the kernel's entropy pool with lower quality
random data. 'rngd' is typically provided by the 'rng-tools'
package. It can be run as follows: 'sudo rngd -f -r /dev/urandom'.
'--debug-pinentry'
This option enables extra debug information pertaining to the
Pinentry. As of now it is only useful when used along with
'--debug 1024'.
'--no-detach'
Don't detach the process from the console. This is mainly useful
for debugging.
'-s'
'--sh'
'-c'
'--csh'
Format the info output in daemon mode for use with the standard
Bourne shell or the C-shell respectively. The default is to guess
it based on the environment variable 'SHELL' which is correct in
almost all cases.
'--grab'
'--no-grab'
Tell the pinentry to grab the keyboard and mouse. This option
should be used on X-Servers to avoid X-sniffing attacks. Any use
of the option '--grab' overrides an used option '--no-grab'. The
default is '--no-grab'.
'--log-file FILE'
Append all logging output to FILE. This is very helpful in seeing
what the agent actually does. Use 'socket://' to log to socket.
If neither a log file nor a log file descriptor has been set on a
Windows platform, the Registry entry
'HKCU\Software\GNU\GnuPG:DefaultLogFile', if set, is used to
specify the logging output.
'--no-allow-mark-trusted'
Do not allow clients to mark keys as trusted, i.e. put them into
the 'trustlist.txt' file. This makes it harder for users to
inadvertently accept Root-CA keys.
'--allow-preset-passphrase'
This option allows the use of 'gpg-preset-passphrase' to seed the
internal cache of 'gpg-agent' with passphrases.
'--no-allow-loopback-pinentry'
'--allow-loopback-pinentry'
Disallow or allow clients to use the loopback pinentry features;
see the option 'pinentry-mode' for details. Allow is the default.
The '--force' option of the Assuan command 'DELETE_KEY' is also
controlled by this option: The option is ignored if a loopback
pinentry is disallowed.
'--no-allow-external-cache'
Tell Pinentry not to enable features which use an external cache
for passphrases.
Some desktop environments prefer to unlock all credentials with one
master password and may have installed a Pinentry which employs an
additional external cache to implement such a policy. By using
this option the Pinentry is advised not to make use of such a cache
and instead always ask the user for the requested passphrase.
'--allow-emacs-pinentry'
Tell Pinentry to allow features to divert the passphrase entry to a
running Emacs instance. How this is exactly handled depends on the
version of the used Pinentry.
'--ignore-cache-for-signing'
This option will let 'gpg-agent' bypass the passphrase cache for
all signing operation. Note that there is also a per-session
option to control this behavior but this command line option takes
precedence.
'--default-cache-ttl N'
Set the time a cache entry is valid to N seconds. The default is
600 seconds. Each time a cache entry is accessed, the entry's
timer is reset. To set an entry's maximum lifetime, use
'max-cache-ttl'. Note that a cached passphrase may not be evicted
immediately from memory if no client requests a cache operation.
This is due to an internal housekeeping function which is only run
every few seconds.
'--default-cache-ttl-ssh N'
Set the time a cache entry used for SSH keys is valid to N seconds.
The default is 1800 seconds. Each time a cache entry is accessed,
the entry's timer is reset. To set an entry's maximum lifetime,
use 'max-cache-ttl-ssh'.
'--max-cache-ttl N'
Set the maximum time a cache entry is valid to N seconds. After
this time a cache entry will be expired even if it has been
accessed recently or has been set using 'gpg-preset-passphrase'.
The default is 2 hours (7200 seconds).
'--max-cache-ttl-ssh N'
Set the maximum time a cache entry used for SSH keys is valid to N
seconds. After this time a cache entry will be expired even if it
has been accessed recently or has been set using
'gpg-preset-passphrase'. The default is 2 hours (7200 seconds).
'--enforce-passphrase-constraints'
Enforce the passphrase constraints by not allowing the user to
bypass them using the "Take it anyway" button.
'--min-passphrase-len N'
Set the minimal length of a passphrase. When entering a new
passphrase shorter than this value a warning will be displayed.
Defaults to 8.
'--min-passphrase-nonalpha N'
Set the minimal number of digits or special characters required in
a passphrase. When entering a new passphrase with less than this
number of digits or special characters a warning will be displayed.
Defaults to 1.
'--check-passphrase-pattern FILE'
Check the passphrase against the pattern given in FILE. When
entering a new passphrase matching one of these pattern a warning
will be displayed. FILE should be an absolute filename. The
default is not to use any pattern file.
Security note: It is known that checking a passphrase against a
list of pattern or even against a complete dictionary is not very
effective to enforce good passphrases. Users will soon figure up
ways to bypass such a policy. A better policy is to educate users
on good security behavior and optionally to run a passphrase
cracker regularly on all users passphrases to catch the very simple
ones.
'--max-passphrase-days N'
Ask the user to change the passphrase if N days have passed since
the last change. With '--enforce-passphrase-constraints' set the
user may not bypass this check.
'--enable-passphrase-history'
This option does nothing yet.
'--pinentry-invisible-char CHAR'
This option asks the Pinentry to use CHAR for displaying hidden
characters. CHAR must be one character UTF-8 string. A Pinentry
may or may not honor this request.
'--pinentry-timeout N'
This option asks the Pinentry to timeout after N seconds with no
user input. The default value of 0 does not ask the pinentry to
timeout, however a Pinentry may use its own default timeout value
in this case. A Pinentry may or may not honor this request.
'--pinentry-program FILENAME'
Use program FILENAME as the PIN entry. The default is installation
dependent. With the default configuration the name of the default
pinentry is 'pinentry'; if that file does not exist but a
'pinentry-basic' exist the latter is used.
On a Windows platform the default is to use the first existing
program from this list: 'bin\pinentry.exe',
'..\Gpg4win\bin\pinentry.exe', '..\Gpg4win\pinentry.exe',
'..\GNU\GnuPG\pinentry.exe', '..\GNU\bin\pinentry.exe',
'bin\pinentry-basic.exe' where the file names are relative to the
GnuPG installation directory.
'--pinentry-touch-file FILENAME'
By default the filename of the socket gpg-agent is listening for
requests is passed to Pinentry, so that it can touch that file
before exiting (it does this only in curses mode). This option
changes the file passed to Pinentry to FILENAME. The special name
'/dev/null' may be used to completely disable this feature. Note
that Pinentry will not create that file, it will only change the
modification and access time.
'--scdaemon-program FILENAME'
Use program FILENAME as the Smartcard daemon. The default is
installation dependent and can be shown with the 'gpgconf' command.
'--disable-scdaemon'
Do not make use of the scdaemon tool. This option has the effect
of disabling the ability to do smartcard operations. Note, that
enabling this option at runtime does not kill an already forked
scdaemon.
'--disable-check-own-socket'
'gpg-agent' employs a periodic self-test to detect a stolen socket.
This usually means a second instance of 'gpg-agent' has taken over
the socket and 'gpg-agent' will then terminate itself. This option
may be used to disable this self-test for debugging purposes.
'--use-standard-socket'
'--no-use-standard-socket'
'--use-standard-socket-p'
Since GnuPG 2.1 the standard socket is always used. These options
have no more effect. The command 'gpg-agent
--use-standard-socket-p' will thus always return success.
'--display STRING'
'--ttyname STRING'
'--ttytype STRING'
'--lc-ctype STRING'
'--lc-messages STRING'
'--xauthority STRING'
These options are used with the server mode to pass localization
information.
'--keep-tty'
'--keep-display'
Ignore requests to change the current 'tty' or X window system's
'DISPLAY' variable respectively. This is useful to lock the
pinentry to pop up at the 'tty' or display you started the agent.
'--listen-backlog N'
Set the size of the queue for pending connections. The default is
64.
'--extra-socket NAME'
The extra socket is created by default, you may use this option to
change the name of the socket. To disable the creation of the
socket use "none" or "/dev/null" for NAME.
Also listen on native gpg-agent connections on the given socket.
The intended use for this extra socket is to setup a Unix domain
socket forwarding from a remote machine to this socket on the local
machine. A 'gpg' running on the remote machine may then connect to
the local gpg-agent and use its private keys. This enables
decrypting or signing data on a remote machine without exposing the
private keys to the remote machine.
'--enable-extended-key-format'
'--disable-extended-key-format'
Since version 2.2.22 keys are created in the extended private key
format by default. Changing the passphrase of a key will also
convert the key to that new format. This key format is supported
since GnuPG version 2.1.12 and thus there should be no need to
disable it. Anyway, the disable option still allows to revert to
the old behavior for new keys; be aware that keys are never
migrated back to the old format. If the enable option has been
used the disable option won't have an effect. The advantage of the
extended private key format is that it is text based and can carry
additional meta data. In extended key format the OCB mode is used
for key protection.
'--enable-ssh-support'
'--enable-putty-support'
The OpenSSH Agent protocol is always enabled, but 'gpg-agent' will
only set the 'SSH_AUTH_SOCK' variable if this flag is given.
In this mode of operation, the agent does not only implement the
gpg-agent protocol, but also the agent protocol used by OpenSSH
(through a separate socket). Consequently, it should be possible
to use the gpg-agent as a drop-in replacement for the well known
ssh-agent.
SSH Keys, which are to be used through the agent, need to be added
to the gpg-agent initially through the ssh-add utility. When a key
is added, ssh-add will ask for the password of the provided key
file and send the unprotected key material to the agent; this
causes the gpg-agent to ask for a passphrase, which is to be used
for encrypting the newly received key and storing it in a gpg-agent
specific directory.
Once a key has been added to the gpg-agent this way, the gpg-agent
will be ready to use the key.
Note: in case the gpg-agent receives a signature request, the user
might need to be prompted for a passphrase, which is necessary for
decrypting the stored key. Since the ssh-agent protocol does not
contain a mechanism for telling the agent on which display/terminal
it is running, gpg-agent's ssh-support will use the TTY or X
display where gpg-agent has been started. To switch this display
to the current one, the following command may be used:
gpg-connect-agent updatestartuptty /bye
Although all GnuPG components try to start the gpg-agent as needed,
this is not possible for the ssh support because ssh does not know
about it. Thus if no GnuPG tool which accesses the agent has been
run, there is no guarantee that ssh is able to use gpg-agent for
authentication. To fix this you may start gpg-agent if needed
using this simple command:
gpg-connect-agent /bye
Adding the '--verbose' shows the progress of starting the agent.
The '--enable-putty-support' is only available under Windows and
allows the use of gpg-agent with the ssh implementation 'putty'.
This is similar to the regular ssh-agent support but makes use of
Windows message queue as required by 'putty'.
'--ssh-fingerprint-digest'
Select the digest algorithm used to compute ssh fingerprints that
are communicated to the user, e.g. in pinentry dialogs. OpenSSH
has transitioned from using MD5 to the more secure SHA256.
'--auto-expand-secmem N'
Allow Libgcrypt to expand its secure memory area as required. The
optional value N is a non-negative integer with a suggested size in
bytes of each additionally allocated secure memory area. The value
is rounded up to the next 32 KiB; usual C style prefixes are
allowed. For an heavy loaded gpg-agent with many concurrent
connection this option avoids sign or decrypt errors due to out of
secure memory error returns.
'--s2k-calibration MILLISECONDS'
Change the default calibration time to MILLISECONDS. The given
value is capped at 60 seconds; a value of 0 resets to the
compiled-in default. This option is re-read on a SIGHUP (or
'gpgconf --reload gpg-agent') and the S2K count is then
re-calibrated.
'--s2k-count N'
Specify the iteration count used to protect the passphrase. This
option can be used to override the auto-calibration done by
default. The auto-calibration computes a count which requires by
default 100ms to mangle a given passphrase. See also
'--s2k-calibration'.
To view the actually used iteration count and the milliseconds
required for an S2K operation use:
gpg-connect-agent 'GETINFO s2k_count' /bye
gpg-connect-agent 'GETINFO s2k_time' /bye
To view the auto-calibrated count use:
gpg-connect-agent 'GETINFO s2k_count_cal' /bye
Info Catalog
gnupg: Agent Commands
gnupg: Invoking GPG-AGENT
gnupg: Agent Configuration