dirmngr: Reduce default LDAP timeout to 15 seconds.
[gnupg.git] / doc / gpg-agent.texi
index 5a387d4..afe2804 100644 (file)
@@ -54,11 +54,46 @@ The agent is automatically started on demand by @command{gpg},
 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 controlled and audited, and it doesn't permit
+@c   the supplicant to either copy the key or to override the owner's
+@c   intentions.
+
 @example
 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:
 
@@ -81,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
@@ -131,12 +166,29 @@ 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
 @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}
@@ -144,8 +196,9 @@ shell, gpg-agent terminates within a few seconds.
 @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
@@ -156,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
@@ -203,7 +256,7 @@ however carefully selected to best aid in debugging.
 
 @item --debug @var{flags}
 @opindex debug
-This option is only useful for debugging and the behaviour may change at
+This option is only useful for debugging and the behavior may change at
 any time without notice.  FLAGS are bit encoded and may be given in
 usual C-Syntax. The currently defined bits are:
 
@@ -219,7 +272,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)
@@ -269,25 +322,32 @@ debugging.
 @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
 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}
 @opindex log-file
-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
-@code{HKCU\Software\GNU\GnuPG:DefaultLogFile}, if set, is used to specify
-the logging output.
+@efindex HKCU\Software\GNU\GnuPG:DefaultLogFile
+Append all logging output to @var{file}.  This is very helpful in
+seeing what the agent actually does. Use @file{socket://} to log to
+socket.  If neither a log file nor a log file descriptor has been set
+on a Windows platform, the Registry entry
+@code{HKCU\Software\GNU\GnuPG:DefaultLogFile}, if set, is used to
+specify the logging output.
 
 
 @anchor{option --no-allow-mark-trusted}
@@ -303,11 +363,17 @@ accept Root-CA keys.
 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
@@ -330,7 +396,7 @@ version of the used Pinentry.
 @opindex ignore-cache-for-signing
 This option will let @command{gpg-agent} bypass the passphrase cache for all
 signing operation.  Note that there is also a per-session option to
-control this behaviour but this command line option takes precedence.
+control this behavior but this command line option takes precedence.
 
 @item --default-cache-ttl @var{n}
 @opindex default-cache-ttl
@@ -501,14 +567,28 @@ 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.
 A @command{gpg} running on the remote machine may then connect to the
-local gpg-agent and use its private keys.  This allows to decrypt or
-sign data on a remote machine without exposing the private keys to the
+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
@@ -516,7 +596,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
@@ -563,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.
 
-All the long options may also be given in the configuration file after
-stripping off the two leading dashes.
+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
+
+To view the auto-calibrated count use:
+
+@example
+gpg-connect-agent 'GETINFO s2k_count_cal' /bye
+@end example
+
+
+@end table
 
 
 @mansect files
@@ -581,7 +688,7 @@ agent. By default they may all be found in the current home directory
 @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.
@@ -591,13 +698,14 @@ agent. By default they may all be found in the current home directory
   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
   lines are ignored.  To mark a key as trusted you need to enter its
   fingerprint followed by a space and a capital letter @code{S}.  Colons
   may optionally be used to separate the bytes of a fingerprint; this
-  allows to cut and paste the fingerprint from a key listing output.  If
+  enables cutting and pasting the fingerprint from a key listing output.  If
   the line is prefixed with a @code{!} the key is explicitly marked as
   not trusted.
 
@@ -624,7 +732,7 @@ trustworthy enough into this file.  Places where to look for the
 fingerprint of a root certificate are letters received from the CA or
 the website of the CA (after making 100% sure that this is indeed the
 website of that CA).  You may want to consider disallowing interactive
-updates of this file by using the @xref{option --no-allow-mark-trusted}.
+updates of this file by using the @ref{option --no-allow-mark-trusted}.
 It might even be advisable to change the permissions to read-only so
 that this file can't be changed inadvertently.
 
@@ -652,7 +760,7 @@ fails, try again using the chain validation model.
 
 
 @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.
@@ -671,7 +779,7 @@ that key.  The flag is automatically set if a new key was loaded into
 @code{gpg-agent} using the option @option{-c} of the @code{ssh-add}
 command.
 
-The keygrip may be prefixed with a @code{!} to disable an entry entry.
+The keygrip may be prefixed with a @code{!} to disable an entry.
 
 The following example lists exactly one key.  Note that keys available
 through a OpenPGP smartcard in the active smartcard reader are
@@ -686,6 +794,7 @@ implicitly added to this list; i.e. there is no need to list them.
 @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
@@ -707,7 +816,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.
 
@@ -727,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
@@ -762,7 +872,7 @@ This signal is used for internal purposes.
 @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
@@ -778,7 +888,7 @@ it by adding this to your init script:
 @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
@@ -792,8 +902,17 @@ fi
 @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.
 
@@ -892,7 +1011,7 @@ Here is an example session:
    S: # session key follows
    S: S PADDING 0
    S: D (value 1234567890ABCDEF0)
-   S: OK descryption successful
+   S: OK decryption successful
 @end smallexample
 @end cartouche
 
@@ -904,7 +1023,7 @@ that the padding has been removed.
 @node Agent PKSIGN
 @subsection Signing a Hash
 
-The client ask the agent to sign a given hash value.  A default key
+The client asks the agent to sign a given hash value.  A default key
 will be chosen if no key has been set.  To set a key a client first
 uses:
 
@@ -914,7 +1033,7 @@ uses:
 
 This can be used multiple times to create multiple signature, the list
 of keys is reset with the next PKSIGN command or a RESET.  The server
-test whether the key is a valid key to sign something and responds with
+tests whether the key is a valid key to sign something and responds with
 okay.
 
 @example
@@ -946,7 +1065,7 @@ The actual signing is done using
    PKSIGN <options>
 @end example
 
-Options are not yet defined, but my later be used to choose among
+Options are not yet defined, but may later be used to choose among
 different algorithms.  The agent does then some checks, asks for the
 passphrase and as a result the server returns the signature as an SPKI
 like S-expression in "D" lines:
@@ -995,8 +1114,8 @@ Here is an example session:
 @subsection Generating a Key
 
 This is used to create a new keypair and store the secret key inside the
-active PSE --- which is in most cases a Soft-PSE.  An not yet defined
-option allows to choose the storage location.  To get the secret key out
+active PSE --- which is in most cases a Soft-PSE.  A not-yet-defined
+option allows choosing the storage location.  To get the secret key out
 of the PSE, a special export tool has to be used.
 
 @example
@@ -1066,7 +1185,7 @@ are to be used for this.
 
 There is no actual need because we can expect that secret keys
 created by a 3rd party are stored on a smartcard.  If we have
-generated the key ourself, we do not need to import it.
+generated the key ourselves, we do not need to import it.
 
 @node Agent EXPORT
 @subsection Export a Secret Key
@@ -1155,7 +1274,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
@@ -1239,13 +1358,13 @@ 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.
 
 The @var{timeout} parameter keeps the passphrase cached for the specified
-number of seconds. A value of @code{-1} means infinate while @code{0} means
+number of seconds. A value of @code{-1} means infinite while @code{0} means
 the default (currently only a timeout of -1 is allowed, which means to never
 expire it).
 
@@ -1294,8 +1413,8 @@ 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
-option given the certificates are send back.
+This command is used to register a smartcard.  With the @option{--send}
+option given the certificates are sent back.
 
 
 @node Agent PASSWD
@@ -1338,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.
@@ -1429,13 +1548,12 @@ following values are defined:
   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 @ref{option --no-allow-loopback-pinentry}.
   @end table
 
 @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
@@ -1451,8 +1569,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