dirmngr: Reduce default LDAP timeout to 15 seconds.
[gnupg.git] / doc / gpg-agent.texi
index 3177af4..afe2804 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
@@ -186,6 +186,9 @@ this convention).
 @node Agent Options
 @section Option Summary
 
+Options may either be used on the command line or, after stripping off
+the two leading dashes, in the configuration file.
+
 @table @gnupgtabopt
 
 @anchor{option --options}
@@ -193,8 +196,9 @@ this convention).
 @opindex options
 Reads configuration from @var{file} instead of from the default
 per-user configuration file.  The default configuration file is named
-@file{gpg-agent.conf} and expected in the @file{.gnupg} directory directly
-below the home directory of the user.
+@file{gpg-agent.conf} and expected in the @file{.gnupg} directory
+directly below the home directory of the user.  This option is ignored
+if used in an options file.
 
 @anchor{option --homedir}
 @include opt-homedir.texi
@@ -205,7 +209,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
@@ -325,10 +329,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}
@@ -571,6 +579,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
@@ -626,11 +644,37 @@ 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
 
-@end table
+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.
+
+@item --s2k-count @var{n}
+@opindex s2k-count
+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 100ms to mangle
+a given passphrase.
+
+To view the actually used iteration count and the milliseconds
+required for an S2K operation use:
+
+@example
+gpg-connect-agent 'GETINFO s2k_count' /bye
+gpg-connect-agent 'GETINFO s2k_time' /bye
+@end example
 
-All the long options may also be given in the configuration file after
-stripping off the two leading dashes.
+To view the auto-calibrated count use:
+
+@example
+gpg-connect-agent 'GETINFO s2k_count_cal' /bye
+@end example
+
+
+@end table
 
 
 @mansect files
@@ -792,6 +836,7 @@ again.  Only certain options are honored: @code{quiet},
 @code{pinentry-invisible-char},
 @code{default-cache-ttl},
 @code{max-cache-ttl}, @code{ignore-cache-for-signing},
+@code{s2k-count},
 @code{no-allow-external-cache}, @code{allow-emacs-pinentry},
 @code{no-allow-mark-trusted}, @code{disable-scdaemon}, and
 @code{disable-check-own-socket}.  @code{scdaemon-program} is also
@@ -1313,7 +1358,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.
@@ -1412,7 +1457,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.
@@ -1508,7 +1553,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