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
@item --default-cache-ttl @var{n}
@opindex default-cache-ttl
-Set the time a cache entry is valid to @var{n} seconds. The default is
-600 seconds.
+Set the time a cache entry is valid to @var{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
+@command{max-cache-ttl}.
@item --default-cache-ttl-ssh @var{n}
@opindex default-cache-ttl
Set the time a cache entry used for SSH keys is valid to @var{n}
-seconds. The default is 1800 seconds.
+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 @command{max-cache-ttl-ssh}.
@item --max-cache-ttl @var{n}
@opindex max-cache-ttl
@opindex enable-passphrase-history
This option does nothing yet.
+@item --pinentry-invisible-char @var{char}
+@opindex pinentry-invisible-char
+This option asks the Pinentry to use @var{char} for displaying hidden
+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
the default pinentry is @file{pinentry}; if that file does not exist
but a @file{pinentry-basic} exist the latter is used.
+On a Windows platform the default is to use the first existing program
+from this list:
+@file{bin\pinentry.exe},
+@file{..\Gpg4win\bin\pinentry.exe},
+@file{..\Gpg4win\pinentry.exe},
+@file{..\GNU\GnuPG\pinentry.exe},
+@file{..\GNU\bin\pinentry.exe},
+@file{bin\pinentry-basic.exe}
+where the file names are relative to the GnuPG installation directory.
+
+
@item --pinentry-touch-file @var{filename}
@opindex pinentry-touch-file
By default the filename of the socket gpg-agent is listening for
@anchor{option --enable-ssh-support}
@item --enable-ssh-support
+@itemx --enable-putty-support
@opindex enable-ssh-support
+@opindex enable-putty-support
Enable the OpenSSH Agent protocol.
Adding the @option{--verbose} shows the progress of starting the agent.
+The @option{--enable-putty-support} is only available under Windows
+and allows the use of gpg-agent with the ssh implementation
+@command{putty}. This is similar to the regular ssh-agent support but
+makes use of Windows message queue as required by @command{putty}.
+
+
@end table
All the long options may also be given in the configuration file after
@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
again. Only certain options are honored: @code{quiet},
@code{verbose}, @code{debug}, @code{debug-all}, @code{debug-level},
@code{debug-pinentry},
-@code{no-grab}, @code{pinentry-program}, @code{default-cache-ttl},
+@code{no-grab},
+@code{pinentry-program},
+@code{pinentry-invisible-char},
+@code{default-cache-ttl},
@code{max-cache-ttl}, @code{ignore-cache-for-signing},
@code{no-allow-external-cache}, @code{allow-emacs-pinentry},
@code{no-allow-mark-trusted}, @code{disable-scdaemon}, and
@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
projects / platform / upstream / gpg2.git / blobdiff