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:
+@c From dkg on gnupg-devel on 2016-04-21:
+@c
+@c Here's an attempt at writing a short description of the goals of an
+@c isolated cryptographic agent:
+@c
+@c A cryptographic agent should control access to secret key material.
+@c The agent permits use of the secret key material by a supplicant
+@c without providing a copy of the secret key material to the supplicant.
+@c
+@c An isolated cryptographic agent separates the request for use of
+@c secret key material from permission for use of secret key material.
+@c That is, the system or process requesting use of the key (the
+@c "supplicant") can be denied use of the key by the owner/operator of
+@c the agent (the "owner"), which the supplicant has no control over.
+@c
+@c One way of enforcing this split is a per-key or per-session
+@c passphrase, known only by the owner, which must be supplied to the
+@c agent to permit the use of the secret key material. Another way is
+@c with an out-of-band permission mechanism (e.g. a button or GUI
+@c interface that the owner has access to, but the supplicant does not).
+@c
+@c The rationale for this separation is that it allows access to the
+@c secret key to be tightly controled and audited, and it doesn't permit
+@c the the supplicant to either copy the key or to override the owner's
+@c intentions.
+
@example
gpg-connect-agent /bye
@end example
@noindent
+@efindex GPG_TTY
You should always add the following lines to your @code{.bashrc} or
whatever initialization file is used for all shell invocations:
This option inhibits the use of the very secure random quality level
(Libgcrypt’s @code{GCRY_VERY_STRONG_RANDOM}) and degrades all request
down to standard random quality. It is only used for testing and
-shall not be used for any production quality keys. This option is
+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
+@command{rngd} to fill the kernel's entropy pool with lower quality
+random data. @command{rngd} is typically provided by the
+@command{rng-tools} package. It can be run as follows: @samp{sudo
+rngd -f -r /dev/urandom}.
+
@item --debug-pinentry
@opindex debug-pinentry
This option enables extra debug information pertaining to the
@itemx --csh
@opindex sh
@opindex csh
+@efindex SHELL
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 @code{SHELL} which is correct in almost all
@anchor{option --log-file}
@item --log-file @var{file}
@opindex log-file
+@efindex HKCU\Software\GNU\GnuPG:DefaultLogFile
Append all logging output to @var{file}. This is very helpful in seeing
what the agent actually does. If neither a log file nor a log file
descriptor has been set on a Windows platform, the Registry entry
This option allows the use of @command{gpg-preset-passphrase} to seed the
internal cache of @command{gpg-agent} with passphrases.
-@anchor{option --allow-loopback-pinentry}
+@anchor{option --no-allow-loopback-pinentry}
+@item --no-allow-loopback-pinentry
@item --allow-loopback-pinentry
+@opindex no-allow-loopback-pinentry
@opindex allow-loopback-pinentry
-Allow clients to use the loopback pinentry features; see the option
-@option{pinentry-mode} for details.
+Disallow or allow clients to use the loopback pinentry features; see
+the option @option{pinentry-mode} for details. Allow is the default.
+
+The @option{--force} option of the Assuan command @command{DELETE_KEY}
+is also controlled by this option: The option is ignored if a loopback
+pinentry is disallowed.
@item --no-allow-external-cache
@opindex no-allow-external-cache
characters. @var{char} must be one character UTF-8 string. A
Pinentry may or may not honor this request.
+@item --pinentry-timeout @var{n}
+@opindex pinentry-timeout
+This option asks the Pinentry to timeout after @var{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.
+
@item --pinentry-program @var{filename}
@opindex pinentry-program
Use program @var{filename} as the PIN entry. The default is
@table @file
@item gpg-agent.conf
-@cindex gpg-agent.conf
+@efindex gpg-agent.conf
This is the standard configuration file read by @command{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.
You should backup this file.
@item trustlist.txt
+@efindex 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
@item sshcontrol
-@cindex sshcontrol
+@efindex sshcontrol
This file is used when support for the secure shell agent protocol has
been enabled (@pxref{option --enable-ssh-support}). Only keys present in
this file are used in the SSH protocol. You should backup this file.
@end cartouche
@item private-keys-v1.d/
+@efindex 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
@node Agent Examples
@section Examples
-It is important to set the GPG_TTY environment variable in
+It is important to set the environment variable @code{GPG_TTY} in
your login shell, for example in the @file{~/.bashrc} init script:
@cartouche
@example
unset SSH_AGENT_PID
if [ "$@{gnupg_SSH_AUTH_SOCK_by:-0@}" -ne $$ ]; then
- export SSH_AUTH_SOCK="$@{HOME@}/.gnupg/S.gpg-agent.ssh"
+ export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"
fi
@end example
@end cartouche
@section 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.
+GnuPG components; it does not deal with the ssh-agent protocol. To
+see the full specification of each command, use
+
+@example
+ gpg-connect-agent 'help COMMAND' /bye
+@end example
+@noindent
+or just 'help' to list all available commands.
+
+@noindent
The @command{gpg-agent} daemon is started on demand by the GnuPG
components.
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.
- Use the @xref{option --allow-loopback-pinentry}.
+ To disable this feature use @xref{option --no-allow-loopback-pinentry}.
@end table