gpg,sm: New option --with-key-screening.
[gnupg.git] / doc / gpg-agent.texi
index 8176b37..d7a562a 100644 (file)
@@ -77,7 +77,7 @@ the included Secure Shell Agent you may start the agent using:
 @c
 @c   The rationale for this separation is that it allows access to the
 @c   secret key to be tightly controlled and audited, and it doesn't permit
-@c   the the supplicant to either copy the key or to override the owner's
+@c   the supplicant to either copy the key or to override the owner's
 @c   intentions.
 
 @example
@@ -85,6 +85,14 @@ gpg-connect-agent /bye
 @end example
 
 @noindent
+If you want to manually terminate the currently-running agent, you can
+safely do so with:
+
+@example
+gpgconf --kill gpg-agent
+@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:
@@ -108,7 +116,7 @@ one (e.g. @file{@value{BINDIR}/pinentry}).
 
 @manpause
 @noindent
-@xref{Option Index},for an index to @command{GPG-AGENT}'s commands and options.
+@xref{Option Index}, for an index to @command{GPG-AGENT}'s commands and options.
 @mancont
 
 @menu
@@ -137,7 +145,7 @@ abbreviate this command.
 @itemx -h
 @opindex help
 Print a usage message summarizing the most useful command-line options.
-Note that you can abbreviate this command.
+Note that you cannot abbreviate this command.
 
 @item --dump-options
 @opindex dump-options
@@ -158,6 +166,20 @@ As an alternative you may create a new process as a child of
 gpg-agent: @code{gpg-agent --daemon /bin/sh}.  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.
+
+@item --supervised
+@opindex supervised
+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.
+
+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 @code{LISTEN_FDNAMES} (see
+sd_listen_fds(3) on some Linux distributions for more information on
+this convention).
 @end table
 
 @mansect options
@@ -183,7 +205,7 @@ below the home directory of the user.
 @opindex verbose
 Outputs additional information while running.
 You can increase the verbosity by giving several
-verbose commands to @command{gpgsm}, such as @samp{-vv}.
+verbose commands to @command{gpg-agent}, such as @samp{-vv}.
 
 @item -q
 @item --quiet
@@ -246,7 +268,7 @@ memory allocation
 @item 6  (64)
 caching
 @item 7  (128)
-show memory statistics.
+show memory statistics
 @item 9  (512)
 write hashed data to files named @code{dbgmd-000*}
 @item 10 (1024)
@@ -303,10 +325,14 @@ the environment variable @code{SHELL} which is correct in almost all
 cases.
 
 
-@item --no-grab
+@item --grab
+@itemx --no-grab
+@opindex grab
 @opindex no-grab
-Tell the pinentry not to grab the keyboard and mouse.  This option
-should in general not be used to avoid X-sniffing attacks.
+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 @option{--grab} overrides an used option @option{--no-grab}.
+The default is @option{--no-grab}.
 
 @anchor{option --log-file}
 @item --log-file @var{file}
@@ -537,6 +563,10 @@ pinentry to pop up at the @code{tty} or display you started the agent.
 @anchor{option --extra-socket}
 @item --extra-socket @var{name}
 @opindex extra-socket
+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 @var{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.
@@ -545,6 +575,16 @@ 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.
 
+@anchor{option --enable-extended-key-format}
+@item --enable-extended-key-format
+@opindex enable-extended-key-format
+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.
 
 @anchor{option --enable-ssh-support}
 @item --enable-ssh-support
@@ -552,7 +592,8 @@ remote machine.
 @opindex enable-ssh-support
 @opindex enable-putty-support
 
-Enable the OpenSSH Agent protocol.
+The OpenSSH Agent protocol is always enabled, but @command{gpg-agent}
+will only set the @code{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
@@ -599,6 +640,13 @@ 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}.
 
+@anchor{option --ssh-fingerprint-digest}
+@item --ssh-fingerprint-digest
+@opindex 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.
 
 @end table
 
@@ -745,7 +793,7 @@ a small helper script is provided to create these files (@pxref{addgnupghome}).
 @c
 @mansect signals
 @node Agent Signals
-@section Use of some signals.
+@section Use of some signals
 A running @command{gpg-agent} may be controlled by signals, i.e. using
 the @command{kill} command to send a signal to the process.
 
@@ -1202,7 +1250,7 @@ Format the fingerprint according to gpg rules for a v4 keys.
 @item @@FPR@@
 Choose an appropriate format to format the fingerprint.
 @item @@@@
-Replaced by a single @code{@@}
+Replaced by a single @code{@@}.
 @end table
 
 @node Agent GET_PASSPHRASE
@@ -1286,7 +1334,7 @@ This command adds a passphrase to the cache for the specified @var{keygrip}.
   PRESET_PASSPHRASE [--inquire] <string_or_keygrip> <timeout> [<hexstring>]
 @end example
 
-The passphrase is a hexidecimal string when specified. When not specified, the
+The passphrase is a hexadecimal string when specified. When not specified, the
 passphrase will be retrieved from the pinentry module unless the
 @option{--inquire} option was specified in which case the passphrase will be
 retrieved from the client.
@@ -1341,7 +1389,7 @@ least one of the keygrips corresponds to an available secret key.
   LEARN [--send]
 @end example
 
-This command is used to register a smartcard.  With the --send
+This command is used to register a smartcard.  With the @option{--send}
 option given the certificates are sent back.
 
 
@@ -1385,7 +1433,7 @@ numbers in the range @code{0} to @code{UINT_MAX} and wrapping around to
 0.  The actual values should not be relied upon; they shall only be used
 to detect a change.
 
-The currently defined counters are are:
+The currently defined counters are:
 @table @code
 @item ANY
 Incremented with any change of any of the other counters.
@@ -1481,7 +1529,7 @@ following values are defined:
 
 @item cache-ttl-opt-preset
 This option sets the cache TTL for new entries created by GENKEY and
-PASSWD commands when using the @option{--preset} option.  It it is not
+PASSWD commands when using the @option{--preset} option.  It is not
 used a default value is used.
 
 @item s2k-count
@@ -1497,8 +1545,9 @@ much slower or faster than the actual box.
 
 @mansect see also
 @ifset isman
-@command{gpg2}(1),
+@command{@gpgname}(1),
 @command{gpgsm}(1),
+@command{gpgconf}(1),
 @command{gpg-connect-agent}(1),
 @command{scdaemon}(1)
 @end ifset