agent: Make digest algorithms for ssh fingerprints configurable.
[gnupg.git] / doc / gpg-agent.texi
index 7aacb7b..d61dc85 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:
@@ -164,12 +172,14 @@ shell, gpg-agent terminates within a few seconds.
 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.
+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 $LISTEN_FDNAMES (see
-sd_listen_fds(3) for more information on this convention).
+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
@@ -195,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
@@ -561,6 +571,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
@@ -616,6 +636,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
 
@@ -1303,7 +1330,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.
@@ -1402,7 +1429,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.
@@ -1498,7 +1525,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
@@ -1514,8 +1541,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