1122 lines
34 KiB
HTML
1122 lines
34 KiB
HTML
|
||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
<HTML><HEAD><TITLE>Man page of GPG-AGENT</TITLE>
|
||
</HEAD><BODY>
|
||
<H1>GPG-AGENT</H1>
|
||
Section: GNU Privacy Guard 2.2 (1)<BR>Updated: 2019-11-23<BR><A HREF="#index">Index</A>
|
||
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
||
|
||
<A NAME="lbAB"> </A>
|
||
<H2>NAME</H2>
|
||
|
||
<B>gpg-agent</B>
|
||
|
||
- Secret key management for GnuPG
|
||
<A NAME="lbAC"> </A>
|
||
<H2>SYNOPSIS</H2>
|
||
|
||
<B>gpg-agent</B>
|
||
|
||
[<B>--homedir</B>
|
||
|
||
<I>dir</I>]
|
||
|
||
[<B>--options</B>
|
||
|
||
<I>file</I>]
|
||
|
||
[<I>options</I>]
|
||
|
||
<BR>
|
||
|
||
<B>gpg-agent</B>
|
||
|
||
[<B>--homedir</B>
|
||
|
||
<I>dir</I>]
|
||
|
||
[<B>--options</B>
|
||
|
||
<I>file</I>]
|
||
|
||
[<I>options</I>]
|
||
|
||
<B>--server</B>
|
||
|
||
<BR>
|
||
|
||
<B>gpg-agent</B>
|
||
|
||
[<B>--homedir</B>
|
||
|
||
<I>dir</I>]
|
||
|
||
[<B>--options</B>
|
||
|
||
<I>file</I>]
|
||
|
||
[<I>options</I>]
|
||
|
||
<B>--daemon</B>
|
||
|
||
[<I>command_line</I>]
|
||
|
||
<P>
|
||
<A NAME="lbAD"> </A>
|
||
<H2>DESCRIPTION</H2>
|
||
|
||
<B>gpg-agent</B> is a daemon to manage secret (private) keys
|
||
independently from any protocol. It is used as a backend for
|
||
<B>gpg</B> and <B>gpgsm</B> as well as for a couple of other
|
||
utilities.
|
||
<P>
|
||
The agent is automatically started on demand by <B>gpg</B>,
|
||
<B>gpgsm</B>, <B>gpgconf</B>, or <B>gpg-connect-agent</B>.
|
||
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:
|
||
<P>
|
||
<P>
|
||
<DL COMPACT><DT id="1"><DD>
|
||
<PRE>
|
||
gpg-connect-agent /bye
|
||
</PRE>
|
||
|
||
</DL>
|
||
|
||
<P>
|
||
<P>
|
||
If you want to manually terminate the currently-running agent, you can
|
||
safely do so with:
|
||
<P>
|
||
<DL COMPACT><DT id="2"><DD>
|
||
<PRE>
|
||
gpgconf --kill gpg-agent
|
||
</PRE>
|
||
|
||
</DL>
|
||
|
||
<P>
|
||
<P>
|
||
You should always add the following lines to your <B>.bashrc</B> or
|
||
whatever initialization file is used for all shell invocations:
|
||
<P>
|
||
<DL COMPACT><DT id="3"><DD>
|
||
<PRE>
|
||
GPG_TTY=$(tty)
|
||
export GPG_TTY
|
||
</PRE>
|
||
|
||
</DL>
|
||
|
||
<P>
|
||
<P>
|
||
It is important that this environment variable always reflects the
|
||
output of the <B>tty</B> command. For W32 systems this option is not
|
||
required.
|
||
<P>
|
||
Please make sure that a proper pinentry program has been installed
|
||
under the default filename (which is system dependent) or use the
|
||
option <B>pinentry-program</B> to specify the full name of that program.
|
||
It is often useful to install a symbolic link from the actual used
|
||
pinentry (e.g. '<I>/usr/bin/pinentry-gtk</I>') to the expected
|
||
one (e.g. '<I>/usr/bin/pinentry</I>').
|
||
<P>
|
||
<P>
|
||
<P>
|
||
<A NAME="lbAE"> </A>
|
||
<H2>COMMANDS</H2>
|
||
|
||
<P>
|
||
Commands are not distinguished from options except for the fact that
|
||
only one command is allowed.
|
||
<P>
|
||
<DL COMPACT>
|
||
<DT id="4"><B>--version</B>
|
||
|
||
<DD>
|
||
Print the program version and licensing information. Note that you cannot
|
||
abbreviate this command.
|
||
<P>
|
||
<DT id="5"><B>--help</B>
|
||
|
||
<DD>
|
||
|
||
<B>-h</B>
|
||
|
||
Print a usage message summarizing the most useful command-line options.
|
||
Note that you cannot abbreviate this command.
|
||
<P>
|
||
<DT id="6"><B>--dump-options</B>
|
||
|
||
<DD>
|
||
Print a list of all available options and commands. Note that you cannot
|
||
abbreviate this command.
|
||
<P>
|
||
<DT id="7"><B>--server</B>
|
||
|
||
<DD>
|
||
Run in server mode and wait for commands on the <B>stdin</B>. The
|
||
default mode is to create a socket and listen for commands there.
|
||
<P>
|
||
<DT id="8"><B>--daemon [</B><I>command line</I>]
|
||
|
||
<DD>
|
||
Start the gpg-agent as a daemon; that is, detach it from the console
|
||
and run it in the background.
|
||
<P>
|
||
As an alternative you may create a new process as a child of
|
||
gpg-agent: <B>gpg-agent --daemon /bin/sh</B>. 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.
|
||
<P>
|
||
<DT id="9"><B>--supervised</B>
|
||
|
||
<DD>
|
||
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.
|
||
<P>
|
||
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 <B>LISTEN_FDNAMES</B> (see
|
||
<A HREF="/cgi-bin/man/man2html?3+sd_listen_fds">sd_listen_fds</A>(3) on some Linux distributions for more information on
|
||
this convention).
|
||
</DL>
|
||
<P>
|
||
|
||
<P>
|
||
<A NAME="lbAF"> </A>
|
||
<H2>OPTIONS</H2>
|
||
|
||
<P>
|
||
Options may either be used on the command line or, after stripping off
|
||
the two leading dashes, in the configuration file.
|
||
<P>
|
||
<P>
|
||
<P>
|
||
<DL COMPACT>
|
||
<DT id="10"><B>--options </B><I>file</I>
|
||
|
||
<DD>
|
||
Reads configuration from <I>file</I> instead of from the default
|
||
per-user configuration file. The default configuration file is named
|
||
'<I>gpg-agent.conf</I>' and expected in the '<I>.gnupg</I>' directory
|
||
directly below the home directory of the user. This option is ignored
|
||
if used in an options file.
|
||
<P>
|
||
<P>
|
||
<DT id="11"><B>--homedir </B><I>dir</I>
|
||
|
||
<DD>
|
||
Set the name of the home directory to <I>dir</I>. If this option is not
|
||
used, the home directory defaults to '<I>~/.gnupg</I>'. It is only
|
||
recognized when given on the command line. It also overrides any home
|
||
directory stated through the environment variable '<I>GNUPGHOME</I>' or
|
||
(on Windows systems) by means of the Registry entry
|
||
<I>HKCU\Software\GNU\GnuPG:HomeDir</I>.
|
||
<P>
|
||
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.
|
||
<P>
|
||
To install GnuPG as a portable application under Windows, create an
|
||
empty file named '<I>gpgconf.ctl</I>' in the same directory as the tool
|
||
'<I>gpgconf.exe</I>'. The root of the installation is then that
|
||
directory; or, if '<I>gpgconf.exe</I>' has been installed directly below
|
||
a directory named '<I>bin</I>', its parent directory. You also need to
|
||
make sure that the following directories exist and are writable:
|
||
'<I>ROOT/home</I>' for the GnuPG home and '<I>ROOT/var/cache/gnupg</I>'
|
||
for internal cache files.
|
||
<P>
|
||
<P>
|
||
<DT id="12"><B>-v</B>
|
||
|
||
<DD>
|
||
<DT id="13"><B>--verbose</B>
|
||
|
||
<DD>
|
||
Outputs additional information while running.
|
||
You can increase the verbosity by giving several
|
||
verbose commands to <B>gpg-agent</B>, such as '-vv'.
|
||
<P>
|
||
<DT id="14"><B>-q</B>
|
||
|
||
<DD>
|
||
<DT id="15"><B>--quiet</B>
|
||
|
||
<DD>
|
||
Try to be as quiet as possible.
|
||
<P>
|
||
<DT id="16"><B>--batch</B>
|
||
|
||
<DD>
|
||
Don't invoke a pinentry or do any other thing requiring human interaction.
|
||
<P>
|
||
<DT id="17"><B>--faked-system-time </B><I>epoch</I>
|
||
|
||
<DD>
|
||
This option is only useful for testing; it sets the system time back or
|
||
forth to <I>epoch</I> which is the number of seconds elapsed since the year
|
||
1970.
|
||
<P>
|
||
<DT id="18"><B>--debug-level </B><I>level</I>
|
||
|
||
<DD>
|
||
Select the debug level for investigating problems. <I>level</I> may be
|
||
a numeric value or a keyword:
|
||
<P>
|
||
<DL COMPACT><DT id="19"><DD>
|
||
<DL COMPACT>
|
||
<DT id="20"><B>none</B>
|
||
|
||
<DD>
|
||
No debugging at all. A value of less than 1 may be used instead of
|
||
the keyword.
|
||
<DT id="21"><B>basic</B>
|
||
|
||
<DD>
|
||
Some basic debug messages. A value between 1 and 2 may be used
|
||
instead of the keyword.
|
||
<DT id="22"><B>advanced</B>
|
||
|
||
<DD>
|
||
More verbose debug messages. A value between 3 and 5 may be used
|
||
instead of the keyword.
|
||
<DT id="23"><B>expert</B>
|
||
|
||
<DD>
|
||
Even more detailed messages. A value between 6 and 8 may be used
|
||
instead of the keyword.
|
||
<DT id="24"><B>guru</B>
|
||
|
||
<DD>
|
||
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.
|
||
</DL>
|
||
</DL>
|
||
|
||
<P>
|
||
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.
|
||
<P>
|
||
<DT id="25"><B>--debug </B><I>flags</I>
|
||
|
||
<DD>
|
||
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:
|
||
<P>
|
||
<DL COMPACT><DT id="26"><DD>
|
||
<DL COMPACT>
|
||
<DT id="27"><B>0 (1)</B>
|
||
|
||
<DD>
|
||
X.509 or OpenPGP protocol related data
|
||
<DT id="28"><B>1 (2)</B>
|
||
|
||
<DD>
|
||
values of big number integers
|
||
<DT id="29"><B>2 (4)</B>
|
||
|
||
<DD>
|
||
low level crypto operations
|
||
<DT id="30"><B>5 (32)</B>
|
||
|
||
<DD>
|
||
memory allocation
|
||
<DT id="31"><B>6 (64)</B>
|
||
|
||
<DD>
|
||
caching
|
||
<DT id="32"><B>7 (128)</B>
|
||
|
||
<DD>
|
||
show memory statistics
|
||
<DT id="33"><B>9 (512)</B>
|
||
|
||
<DD>
|
||
write hashed data to files named <B>dbgmd-000*</B>
|
||
<DT id="34"><B>10 (1024)</B>
|
||
|
||
<DD>
|
||
trace Assuan protocol
|
||
<DT id="35"><B>12 (4096)</B>
|
||
|
||
<DD>
|
||
bypass all certificate validation
|
||
</DL>
|
||
</DL>
|
||
|
||
<P>
|
||
<DT id="36"><B>--debug-all</B>
|
||
|
||
<DD>
|
||
Same as <B>--debug=0xffffffff</B>
|
||
<P>
|
||
<DT id="37"><B>--debug-wait </B><I>n</I>
|
||
|
||
<DD>
|
||
When running in server mode, wait <I>n</I> seconds before entering the
|
||
actual processing loop and print the pid. This gives time to attach a
|
||
debugger.
|
||
<P>
|
||
<DT id="38"><B>--debug-quick-random</B>
|
||
|
||
<DD>
|
||
This option inhibits the use of the very secure random quality level
|
||
(Libgcrypt’s <B>GCRY_VERY_STRONG_RANDOM</B>) 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.
|
||
<P>
|
||
On GNU/Linux, another way to quickly generate insecure keys is to use
|
||
<B>rngd</B> to fill the kernel's entropy pool with lower quality
|
||
random data. <B>rngd</B> is typically provided by the
|
||
<B>rng-tools</B> package. It can be run as follows: 'sudo
|
||
rngd -f -r /dev/urandom'.
|
||
<P>
|
||
<DT id="39"><B>--debug-pinentry</B>
|
||
|
||
<DD>
|
||
This option enables extra debug information pertaining to the
|
||
Pinentry. As of now it is only useful when used along with
|
||
<B>--debug 1024</B>.
|
||
<P>
|
||
<DT id="40"><B>--no-detach</B>
|
||
|
||
<DD>
|
||
Don't detach the process from the console. This is mainly useful for
|
||
debugging.
|
||
<P>
|
||
<DT id="41"><B>-s</B>
|
||
|
||
<DD>
|
||
|
||
<B>--sh</B>
|
||
|
||
|
||
<B>-c</B>
|
||
|
||
|
||
<B>--csh</B>
|
||
|
||
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 <B>SHELL</B> which is correct in almost all
|
||
cases.
|
||
<P>
|
||
<P>
|
||
<DT id="42"><B>--grab</B>
|
||
|
||
<DD>
|
||
|
||
<B>--no-grab</B>
|
||
|
||
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 <B>--grab</B> overrides an used option <B>--no-grab</B>.
|
||
The default is <B>--no-grab</B>.
|
||
<P>
|
||
<P>
|
||
<DT id="43"><B>--log-file </B><I>file</I>
|
||
|
||
<DD>
|
||
Append all logging output to <I>file</I>. This is very helpful in
|
||
seeing what the agent actually does. Use '<I>socket://</I>' to log to
|
||
socket. If neither a log file nor a log file descriptor has been set
|
||
on a Windows platform, the Registry entry
|
||
<B>HKCU\Software\GNU\GnuPG:DefaultLogFile</B>, if set, is used to
|
||
specify the logging output.
|
||
<P>
|
||
<P>
|
||
<P>
|
||
<DT id="44"><B>--no-allow-mark-trusted</B>
|
||
|
||
<DD>
|
||
Do not allow clients to mark keys as trusted, i.e. put them into the
|
||
'<I>trustlist.txt</I>' file. This makes it harder for users to inadvertently
|
||
accept Root-CA keys.
|
||
<P>
|
||
<P>
|
||
<DT id="45"><B>--allow-preset-passphrase</B>
|
||
|
||
<DD>
|
||
This option allows the use of <B>gpg-preset-passphrase</B> to seed the
|
||
internal cache of <B>gpg-agent</B> with passphrases.
|
||
<P>
|
||
<P>
|
||
<DT id="46"><B>--no-allow-loopback-pinentry</B>
|
||
|
||
<DD>
|
||
<DT id="47"><B>--allow-loopback-pinentry</B>
|
||
|
||
<DD>
|
||
Disallow or allow clients to use the loopback pinentry features; see
|
||
the option <B>pinentry-mode</B> for details. Allow is the default.
|
||
<P>
|
||
The <B>--force</B> option of the Assuan command <B>DELETE_KEY</B>
|
||
is also controlled by this option: The option is ignored if a loopback
|
||
pinentry is disallowed.
|
||
<P>
|
||
<DT id="48"><B>--no-allow-external-cache</B>
|
||
|
||
<DD>
|
||
Tell Pinentry not to enable features which use an external cache for
|
||
passphrases.
|
||
<P>
|
||
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.
|
||
<P>
|
||
<DT id="49"><B>--allow-emacs-pinentry</B>
|
||
|
||
<DD>
|
||
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.
|
||
<P>
|
||
<DT id="50"><B>--ignore-cache-for-signing</B>
|
||
|
||
<DD>
|
||
This option will let <B>gpg-agent</B> 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.
|
||
<P>
|
||
<DT id="51"><B>--default-cache-ttl </B><I>n</I>
|
||
|
||
<DD>
|
||
Set the time a cache entry is valid to <I>n</I> 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
|
||
<B>max-cache-ttl</B>. Note that a cached passphrase may not
|
||
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.
|
||
<P>
|
||
<DT id="52"><B>--default-cache-ttl-ssh </B><I>n</I>
|
||
|
||
<DD>
|
||
Set the time a cache entry used for SSH keys is valid to <I>n</I>
|
||
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 <B>max-cache-ttl-ssh</B>.
|
||
<P>
|
||
<DT id="53"><B>--max-cache-ttl </B><I>n</I>
|
||
|
||
<DD>
|
||
Set the maximum time a cache entry is valid to <I>n</I> seconds. After
|
||
this time a cache entry will be expired even if it has been accessed
|
||
recently or has been set using <B>gpg-preset-passphrase</B>. The
|
||
default is 2 hours (7200 seconds).
|
||
<P>
|
||
<DT id="54"><B>--max-cache-ttl-ssh </B><I>n</I>
|
||
|
||
<DD>
|
||
Set the maximum time a cache entry used for SSH keys is valid to
|
||
<I>n</I> seconds. After this time a cache entry will be expired even
|
||
if it has been accessed recently or has been set using
|
||
<B>gpg-preset-passphrase</B>. The default is 2 hours (7200
|
||
seconds).
|
||
<P>
|
||
<DT id="55"><B>--enforce-passphrase-constraints</B>
|
||
|
||
<DD>
|
||
Enforce the passphrase constraints by not allowing the user to bypass
|
||
them using the ``Take it anyway'' button.
|
||
<P>
|
||
<DT id="56"><B>--min-passphrase-len </B><I>n</I>
|
||
|
||
<DD>
|
||
Set the minimal length of a passphrase. When entering a new passphrase
|
||
shorter than this value a warning will be displayed. Defaults to 8.
|
||
<P>
|
||
<DT id="57"><B>--min-passphrase-nonalpha </B><I>n</I>
|
||
|
||
<DD>
|
||
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.
|
||
<P>
|
||
<DT id="58"><B>--check-passphrase-pattern </B><I>file</I>
|
||
|
||
<DD>
|
||
Check the passphrase against the pattern given in <I>file</I>. When
|
||
entering a new passphrase matching one of these pattern a warning will
|
||
be displayed. <I>file</I> should be an absolute filename. The default is
|
||
not to use any pattern file.
|
||
<P>
|
||
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.
|
||
<P>
|
||
<DT id="59"><B>--max-passphrase-days </B><I>n</I>
|
||
|
||
<DD>
|
||
Ask the user to change the passphrase if <I>n</I> days have passed since
|
||
the last change. With <B>--enforce-passphrase-constraints</B> set the
|
||
user may not bypass this check.
|
||
<P>
|
||
<DT id="60"><B>--enable-passphrase-history</B>
|
||
|
||
<DD>
|
||
This option does nothing yet.
|
||
<P>
|
||
<DT id="61"><B>--pinentry-invisible-char </B><I>char</I>
|
||
|
||
<DD>
|
||
This option asks the Pinentry to use <I>char</I> for displaying hidden
|
||
characters. <I>char</I> must be one character UTF-8 string. A
|
||
Pinentry may or may not honor this request.
|
||
<P>
|
||
<DT id="62"><B>--pinentry-timeout </B><I>n</I>
|
||
|
||
<DD>
|
||
This option asks the Pinentry to timeout after <I>n</I> 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.
|
||
<P>
|
||
<DT id="63"><B>--pinentry-program </B><I>filename</I>
|
||
|
||
<DD>
|
||
Use program <I>filename</I> as the PIN entry. The default is
|
||
installation dependent. With the default configuration the name of
|
||
the default pinentry is '<I>pinentry</I>'; if that file does not exist
|
||
but a '<I>pinentry-basic</I>' exist the latter is used.
|
||
<P>
|
||
On a Windows platform the default is to use the first existing program
|
||
from this list:
|
||
'<I>bin\pinentry.exe</I>',
|
||
'<I>..\Gpg4win\bin\pinentry.exe</I>',
|
||
'<I>..\Gpg4win\pinentry.exe</I>',
|
||
'<I>..\GNU\GnuPG\pinentry.exe</I>',
|
||
'<I>..\GNU\bin\pinentry.exe</I>',
|
||
'<I>bin\pinentry-basic.exe</I>'
|
||
where the file names are relative to the GnuPG installation directory.
|
||
<P>
|
||
<P>
|
||
<DT id="64"><B>--pinentry-touch-file </B><I>filename</I>
|
||
|
||
<DD>
|
||
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 <I>filename</I>. The special name
|
||
<B>/dev/null</B> 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.
|
||
<P>
|
||
<P>
|
||
<DT id="65"><B>--scdaemon-program </B><I>filename</I>
|
||
|
||
<DD>
|
||
Use program <I>filename</I> as the Smartcard daemon. The default is
|
||
installation dependent and can be shown with the <B>gpgconf</B>
|
||
command.
|
||
<P>
|
||
<DT id="66"><B>--disable-scdaemon</B>
|
||
|
||
<DD>
|
||
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.
|
||
<P>
|
||
<DT id="67"><B>--disable-check-own-socket</B>
|
||
|
||
<DD>
|
||
<B>gpg-agent</B> employs a periodic self-test to detect a stolen
|
||
socket. This usually means a second instance of <B>gpg-agent</B>
|
||
has taken over the socket and <B>gpg-agent</B> will then terminate
|
||
itself. This option may be used to disable this self-test for
|
||
debugging purposes.
|
||
<P>
|
||
<DT id="68"><B>--use-standard-socket</B>
|
||
|
||
<DD>
|
||
|
||
<B>--no-use-standard-socket</B>
|
||
|
||
|
||
<B>--use-standard-socket-p</B>
|
||
|
||
Since GnuPG 2.1 the standard socket is always used. These options
|
||
have no more effect. The command <B>gpg-agent
|
||
--use-standard-socket-p</B> will thus always return success.
|
||
<P>
|
||
<DT id="69"><B>--display </B><I>string</I>
|
||
|
||
<DD>
|
||
|
||
<B>--ttyname </B><I>string</I>
|
||
|
||
|
||
<B>--ttytype </B><I>string</I>
|
||
|
||
|
||
<B>--lc-ctype </B><I>string</I>
|
||
|
||
|
||
<B>--lc-messages </B><I>string</I>
|
||
|
||
|
||
<B>--xauthority </B><I>string</I>
|
||
|
||
These options are used with the server mode to pass localization
|
||
information.
|
||
<P>
|
||
<DT id="70"><B>--keep-tty</B>
|
||
|
||
<DD>
|
||
|
||
<B>--keep-display</B>
|
||
|
||
Ignore requests to change the current <B>tty</B> or X window system's
|
||
<B>DISPLAY</B> variable respectively. This is useful to lock the
|
||
pinentry to pop up at the <B>tty</B> or display you started the agent.
|
||
<P>
|
||
<DT id="71"><B>--listen-backlog </B><I>n</I>
|
||
|
||
<DD>
|
||
Set the size of the queue for pending connections. The default is 64.
|
||
<P>
|
||
<P>
|
||
<DT id="72"><B>--extra-socket </B><I>name</I>
|
||
|
||
<DD>
|
||
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 <I>name</I>.
|
||
<P>
|
||
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 <B>gpg</B> 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.
|
||
<P>
|
||
<P>
|
||
<DT id="73"><B>--enable-extended-key-format</B>
|
||
|
||
<DD>
|
||
This option creates keys in the extended private key format. Changing
|
||
the passphrase of a key will also convert the key to that new format.
|
||
Using this option makes the private keys unreadable for gpg-agent
|
||
versions before 2.1.12. The advantage of the extended private key
|
||
format is that it is text based and can carry additional meta data.
|
||
Note that this option also changes the key protection format to use
|
||
OCB mode.
|
||
<P>
|
||
<P>
|
||
<DT id="74"><B>--enable-ssh-support</B>
|
||
|
||
<DD>
|
||
|
||
<B>--enable-putty-support</B>
|
||
|
||
<P>
|
||
The OpenSSH Agent protocol is always enabled, but <B>gpg-agent</B>
|
||
will only set the <B>SSH_AUTH_SOCK</B> variable if this flag is given.
|
||
<P>
|
||
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.
|
||
<P>
|
||
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.
|
||
<P>
|
||
Once a key has been added to the gpg-agent this way, the gpg-agent
|
||
will be ready to use the key.
|
||
<P>
|
||
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:
|
||
<P>
|
||
<DL COMPACT><DT id="75"><DD>
|
||
<PRE>
|
||
gpg-connect-agent updatestartuptty /bye
|
||
</PRE>
|
||
|
||
</DL>
|
||
|
||
<P>
|
||
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:
|
||
<P>
|
||
<DL COMPACT><DT id="76"><DD>
|
||
<PRE>
|
||
gpg-connect-agent /bye
|
||
</PRE>
|
||
|
||
</DL>
|
||
|
||
<P>
|
||
Adding the <B>--verbose</B> shows the progress of starting the agent.
|
||
<P>
|
||
The <B>--enable-putty-support</B> is only available under Windows
|
||
and allows the use of gpg-agent with the ssh implementation
|
||
<B>putty</B>. This is similar to the regular ssh-agent support but
|
||
makes use of Windows message queue as required by <B>putty</B>.
|
||
<P>
|
||
<P>
|
||
<DT id="77"><B>--ssh-fingerprint-digest</B>
|
||
|
||
<DD>
|
||
<P>
|
||
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.
|
||
<P>
|
||
<P>
|
||
<DT id="78"><B>--auto-expand-secmem </B><I>n</I>
|
||
|
||
<DD>
|
||
Allow Libgcrypt to expand its secure memory area as required. The
|
||
optional value <I>n</I> 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.
|
||
<P>
|
||
<DT id="79"><B>--s2k-calibration </B><I>milliseconds</I>
|
||
|
||
<DD>
|
||
Change the default calibration time to <I>milliseconds</I>. 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 <B>gpgconf
|
||
--reload gpg-agent</B>) and the S2K count is then re-calibrated.
|
||
<P>
|
||
<DT id="80"><B>--s2k-count </B><I>n</I>
|
||
|
||
<DD>
|
||
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 <B>--s2k-calibration</B>.
|
||
<P>
|
||
To view the actually used iteration count and the milliseconds
|
||
required for an S2K operation use:
|
||
<P>
|
||
<DL COMPACT><DT id="81"><DD>
|
||
<PRE>
|
||
gpg-connect-agent 'GETINFO s2k_count' /bye
|
||
gpg-connect-agent 'GETINFO s2k_time' /bye
|
||
</PRE>
|
||
|
||
</DL>
|
||
|
||
<P>
|
||
To view the auto-calibrated count use:
|
||
<P>
|
||
<DL COMPACT><DT id="82"><DD>
|
||
<PRE>
|
||
gpg-connect-agent 'GETINFO s2k_count_cal' /bye
|
||
</PRE>
|
||
|
||
</DL>
|
||
|
||
<P>
|
||
<P>
|
||
</DL>
|
||
<P>
|
||
|
||
<P>
|
||
<P>
|
||
<A NAME="lbAG"> </A>
|
||
<H2>EXAMPLES</H2>
|
||
|
||
<P>
|
||
It is important to set the environment variable <B>GPG_TTY</B> in
|
||
your login shell, for example in the '<I>~/.bashrc</I>' init script:
|
||
<P>
|
||
<DL COMPACT><DT id="83"><DD>
|
||
<PRE>
|
||
export GPG_TTY=$(tty)
|
||
</PRE>
|
||
|
||
</DL>
|
||
|
||
<P>
|
||
If you enabled the Ssh Agent Support, you also need to tell ssh about
|
||
it by adding this to your init script:
|
||
<P>
|
||
<DL COMPACT><DT id="84"><DD>
|
||
<PRE>
|
||
unset SSH_AGENT_PID
|
||
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then
|
||
export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"
|
||
fi
|
||
</PRE>
|
||
|
||
</DL>
|
||
|
||
<P>
|
||
<P>
|
||
<P>
|
||
<A NAME="lbAH"> </A>
|
||
<H2>FILES</H2>
|
||
|
||
<P>
|
||
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
|
||
(see: [option --homedir]).
|
||
<P>
|
||
<P>
|
||
<DL COMPACT>
|
||
<DT id="85"><B>gpg-agent.conf</B>
|
||
|
||
<DD>
|
||
<BR> This is the standard configuration file read by <B>gpg-agent</B> on
|
||
<BR> startup. It may contain any valid long option; the leading
|
||
<BR> two dashes may not be entered and the option may not be abbreviated.
|
||
<BR> This file is also read after a <B>SIGHUP</B> however only a few
|
||
<BR> options will actually have an effect. This default name may be
|
||
<BR> changed on the command line (see: [option --options]).
|
||
<BR> You should backup this file.
|
||
<P>
|
||
<DT id="86"><B>trustlist.txt</B>
|
||
|
||
<DD>
|
||
<BR> This is the list of trusted keys. You should backup this file.
|
||
<P>
|
||
<BR> Comment lines, indicated by a leading hash mark, as well as empty
|
||
<BR> lines are ignored. To mark a key as trusted you need to enter its
|
||
<BR> fingerprint followed by a space and a capital letter <B>S</B>. Colons
|
||
<BR> may optionally be used to separate the bytes of a fingerprint; this
|
||
<BR> enables cutting and pasting the fingerprint from a key listing output. If
|
||
<BR> the line is prefixed with a <B>!</B> the key is explicitly marked as
|
||
<BR> not trusted.
|
||
<P>
|
||
<BR> Here is an example where two keys are marked as ultimately trusted
|
||
<BR> and one as not trusted:
|
||
<P>
|
||
<BR> .RS 2
|
||
<PRE>
|
||
# 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
|
||
.fi
|
||
|
||
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 [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 <B>include-default</B> will include a global
|
||
list of trusted certificates (e.g. '<I>/etc/gnupg/trustlist.txt</I>').
|
||
This global list is also used if the local list is not available.
|
||
|
||
It is possible to add further flags after the <B>S</B> for use by the
|
||
caller:
|
||
|
||
<DL COMPACT><DT id="87"><DD>
|
||
<DL COMPACT>
|
||
<DT id="88"><B>relax</B>
|
||
<DD>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.
|
||
|
||
<DT id="89"><B>cm</B>
|
||
<DD>If validation of a certificate finally issued by a CA with this flag set
|
||
fails, try again using the chain validation model.
|
||
|
||
</DL>
|
||
</DL>
|
||
|
||
|
||
<DT id="90"><B>sshcontrol</B>
|
||
<DD>This file is used when support for the secure shell agent protocol has
|
||
been enabled (see: [option --enable-ssh-support]). Only keys present in
|
||
this file are used in the SSH protocol. You should backup this file.
|
||
|
||
The <B>ssh-add</B> 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 <B>--default-cache-ttl-ssh</B>.
|
||
|
||
The only flag support is <B>confirm</B>. 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
|
||
<B>gpg-agent</B> using the option <B>-c</B> of the <B>ssh-add</B>
|
||
command.
|
||
|
||
The keygrip may be prefixed with a <B>!</B> 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.
|
||
|
||
<DL COMPACT><DT id="91"><DD> # 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
|
||
</PRE>
|
||
|
||
</DL>
|
||
|
||
<P>
|
||
<DT id="92"><B>private-keys-v1.d/</B>
|
||
|
||
<DD>
|
||
<P>
|
||
<BR> This is the directory where gpg-agent stores the private keys. Each
|
||
<BR> key is stored in a file with the name made up of the keygrip and the
|
||
<BR> suffix '<I>key</I>'. You should backup all files in this directory
|
||
<BR> and take great care to keep this backup closed away.
|
||
<P>
|
||
<P>
|
||
</DL>
|
||
<P>
|
||
|
||
<P>
|
||
Note that on larger installations, it is useful to put predefined
|
||
files into the directory '<I>/etc/skel/.gnupg</I>' 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 (see: [addgnupghome]).
|
||
<P>
|
||
<P>
|
||
<P>
|
||
<P>
|
||
<A NAME="lbAI"> </A>
|
||
<H2>SIGNALS</H2>
|
||
|
||
A running <B>gpg-agent</B> may be controlled by signals, i.e. using
|
||
the <B>kill</B> command to send a signal to the process.
|
||
<P>
|
||
Here is a list of supported signals:
|
||
<P>
|
||
<P>
|
||
<DL COMPACT>
|
||
<DT id="93"><B>SIGHUP</B>
|
||
|
||
<DD>
|
||
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: <B>quiet</B>,
|
||
<B>verbose</B>, <B>debug</B>, <B>debug-all</B>, <B>debug-level</B>,
|
||
<B>debug-pinentry</B>,
|
||
<B>no-grab</B>,
|
||
<B>pinentry-program</B>,
|
||
<B>pinentry-invisible-char</B>,
|
||
<B>default-cache-ttl</B>,
|
||
<B>max-cache-ttl</B>, <B>ignore-cache-for-signing</B>,
|
||
<B>s2k-count</B>,
|
||
<B>no-allow-external-cache</B>, <B>allow-emacs-pinentry</B>,
|
||
<B>no-allow-mark-trusted</B>, <B>disable-scdaemon</B>, and
|
||
<B>disable-check-own-socket</B>. <B>scdaemon-program</B> 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.
|
||
<P>
|
||
<P>
|
||
<DT id="94"><B>SIGTERM</B>
|
||
|
||
<DD>
|
||
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.
|
||
<P>
|
||
<DT id="95"><B>SIGINT</B>
|
||
|
||
<DD>
|
||
Shuts down the process immediately.
|
||
<P>
|
||
<DT id="96"><B>SIGUSR1</B>
|
||
|
||
<DD>
|
||
Dump internal information to the log file.
|
||
<P>
|
||
<DT id="97"><B>SIGUSR2</B>
|
||
|
||
<DD>
|
||
This signal is used for internal purposes.
|
||
<P>
|
||
</DL>
|
||
<P>
|
||
|
||
<P>
|
||
<P>
|
||
<A NAME="lbAJ"> </A>
|
||
<H2>SEE ALSO</H2>
|
||
|
||
<B><A HREF="/cgi-bin/man/man2html?1+gpg">gpg</A></B>(1),
|
||
<B><A HREF="/cgi-bin/man/man2html?1+gpgsm">gpgsm</A></B>(1),
|
||
<B><A HREF="/cgi-bin/man/man2html?1+gpgconf">gpgconf</A></B>(1),
|
||
<B><A HREF="/cgi-bin/man/man2html?1+gpg-connect-agent">gpg-connect-agent</A></B>(1),
|
||
<B><A HREF="/cgi-bin/man/man2html?1+scdaemon">scdaemon</A></B>(1)
|
||
<P>
|
||
The full documentation for this tool is maintained as a Texinfo manual.
|
||
If GnuPG and the info program are properly installed at your site, the
|
||
command
|
||
<P>
|
||
<DL COMPACT><DT id="98"><DD>
|
||
<PRE>
|
||
info gnupg
|
||
</PRE>
|
||
|
||
</DL>
|
||
|
||
<P>
|
||
should give you access to the complete manual including a menu structure
|
||
and an index.
|
||
<P>
|
||
|
||
<HR>
|
||
<A NAME="index"> </A><H2>Index</H2>
|
||
<DL>
|
||
<DT id="99"><A HREF="#lbAB">NAME</A><DD>
|
||
<DT id="100"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
||
<DT id="101"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
||
<DT id="102"><A HREF="#lbAE">COMMANDS</A><DD>
|
||
<DT id="103"><A HREF="#lbAF">OPTIONS</A><DD>
|
||
<DT id="104"><A HREF="#lbAG">EXAMPLES</A><DD>
|
||
<DT id="105"><A HREF="#lbAH">FILES</A><DD>
|
||
<DT id="106"><A HREF="#lbAI">SIGNALS</A><DD>
|
||
<DT id="107"><A HREF="#lbAJ">SEE ALSO</A><DD>
|
||
</DL>
|
||
<HR>
|
||
This document was created by
|
||
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
||
using the manual pages.<BR>
|
||
Time: 00:05:15 GMT, March 31, 2021
|
||
</BODY>
|
||
</HTML>
|