Adding upstream version 2.2.40.upstream/2.2.40

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1672 insertions, 0 deletions

diff --git a/doc/gpg-agent.texi b/doc/gpg-agent.texi
new file mode 100644
index 0000000..8766250
--- /dev/null
+++ b/doc/gpg-agent.texi
@@ -0,0 +1,1672 @@
+@c Copyright (C) 2002 Free Software Foundation, Inc.
+@c This is part of the GnuPG manual.
+@c For copying conditions, see the file gnupg.texi.
+
+@include defs.inc
+
+@node Invoking GPG-AGENT
+@chapter Invoking GPG-AGENT
+@cindex GPG-AGENT command options
+@cindex command options
+@cindex options, GPG-AGENT command
+
+@manpage gpg-agent.1
+@ifset manverb
+.B gpg-agent
+\- Secret key management for GnuPG
+@end ifset
+
+@mansect synopsis
+@ifset manverb
+.B  gpg-agent
+.RB [ \-\-homedir
+.IR dir ]
+.RB [ \-\-options
+.IR file ]
+.RI [ options ]
+.br
+.B  gpg-agent
+.RB [ \-\-homedir
+.IR dir ]
+.RB [ \-\-options
+.IR file ]
+.RI [ options ]
+.B  \-\-server
+.br
+.B  gpg-agent
+.RB [ \-\-homedir
+.IR dir ]
+.RB [ \-\-options
+.IR file ]
+.RI [ options ]
+.B  \-\-daemon
+.RI [ command_line ]
+@end ifset
+
+@mansect description
+@command{gpg-agent} is a daemon to manage secret (private) keys
+independently from any protocol.  It is used as a backend for
+@command{gpg} and @command{gpgsm} as well as for a couple of other
+utilities.
+
+The agent is automatically started on demand by @command{gpg},
+@command{gpgsm}, @command{gpgconf}, or @command{gpg-connect-agent}.
+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:
+
+@smallexample
+GPG_TTY=$(tty)
+export GPG_TTY
+@end smallexample
+
+@noindent
+It is important that this environment variable always reflects the
+output of the @code{tty} command.  For W32 systems this option is not
+required.
+
+Please make sure that a proper pinentry program has been installed
+under the default filename (which is system dependent) or use the
+option @option{pinentry-program} to specify the full name of that program.
+It is often useful to install a symbolic link from the actual used
+pinentry (e.g. @file{@value{BINDIR}/pinentry-gtk}) to the expected
+one (e.g. @file{@value{BINDIR}/pinentry}).
+
+@manpause
+@noindent
+@xref{Option Index}, for an index to @command{GPG-AGENT}'s commands and options.
+@mancont
+
+@menu
+* Agent Commands::      List of all commands.
+* Agent Options::       List of all options.
+* Agent Configuration:: Configuration files.
+* Agent Signals::       Use of some signals.
+* Agent Examples::      Some usage examples.
+* Agent Protocol::      The protocol the agent uses.
+@end menu
+
+@mansect commands
+@node Agent Commands
+@section Commands
+
+Commands are not distinguished from options except for the fact that
+only one command is allowed.
+
+@table @gnupgtabopt
+@item --version
+@opindex version
+Print the program version and licensing information.  Note that you cannot
+abbreviate this command.
+
+@item --help
+@itemx -h
+@opindex help
+Print a usage message summarizing the most useful command-line options.
+Note that you cannot abbreviate this command.
+
+@item --dump-options
+@opindex dump-options
+Print a list of all available options and commands.  Note that you cannot
+abbreviate this command.
+
+@item --server
+@opindex server
+Run in server mode and wait for commands on the @code{stdin}.  The
+default mode is to create a socket and listen for commands there.
+
+@item --daemon [@var{command line}]
+@opindex daemon
+Start the gpg-agent as a daemon; that is, detach it from the console
+and run it in the background.
+
+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}
+@item --options @var{file}
+@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.  This option is ignored
+if used in an options file.
+
+@anchor{option --homedir}
+@include opt-homedir.texi
+
+
+@item -v
+@itemx --verbose
+@opindex verbose
+Outputs additional information while running.
+You can increase the verbosity by giving several
+verbose commands to @command{gpg-agent}, such as @samp{-vv}.
+
+@item -q
+@itemx --quiet
+@opindex quiet
+Try to be as quiet as possible.
+
+@item --batch
+@opindex batch
+Don't invoke a pinentry or do any other thing requiring human interaction.
+
+@item --faked-system-time @var{epoch}
+@opindex faked-system-time
+This option is only useful for testing; it sets the system time back or
+forth to @var{epoch} which is the number of seconds elapsed since the year
+1970.
+
+@item --debug-level @var{level}
+@opindex debug-level
+Select the debug level for investigating problems. @var{level} may be
+a numeric value or a keyword:
+
+@table @code
+@item none
+No debugging at all.  A value of less than 1 may be used instead of
+the keyword.
+@item basic
+Some basic debug messages.  A value between 1 and 2 may be used
+instead of the keyword.
+@item advanced
+More verbose debug messages.  A value between 3 and 5 may be used
+instead of the keyword.
+@item expert
+Even more detailed messages.  A value between 6 and 8 may be used
+instead of the keyword.
+@item guru
+All of the debug messages you can get. A value greater than 8 may be
+used instead of the keyword.  The creation of hash tracing files is
+only enabled if the keyword is used.
+@end table
+
+How these messages are mapped to the actual debugging flags is not
+specified and may change with newer releases of this program. They are
+however carefully selected to best aid in debugging.
+
+@item --debug @var{flags}
+@opindex debug
+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:
+
+@table @code
+@item 0  (1)
+X.509 or OpenPGP protocol related data
+@item 1  (2)
+values of big number integers
+@item 2  (4)
+low level crypto operations
+@item 5  (32)
+memory allocation
+@item 6  (64)
+caching
+@item 7  (128)
+show memory statistics
+@item 9  (512)
+write hashed data to files named @code{dbgmd-000*}
+@item 10 (1024)
+trace Assuan protocol
+@item 12 (4096)
+bypass all certificate validation
+@end table
+
+@item --debug-all
+@opindex debug-all
+Same as @code{--debug=0xffffffff}
+
+@item --debug-wait @var{n}
+@opindex debug-wait
+When running in server mode, wait @var{n} seconds before entering the
+actual processing loop and print the pid.  This gives time to attach a
+debugger.
+
+@item --debug-quick-random
+@opindex debug-quick-random
+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
+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
+Pinentry.  As of now it is only useful when used along with
+@code{--debug 1024}.
+
+@item --no-detach
+@opindex no-detach
+Don't detach the process from the console.  This is mainly useful for
+debugging.
+
+@item --steal-socket
+@opindex steal-socket
+In @option{--daemon} mode, gpg-agent detects an already running
+gpg-agent and does not allow to start a new instance. This option can
+be used to override this check: the new gpg-agent process will try to
+take over the communication sockets from the already running process
+and start anyway.  This option should in general not be used.
+
+
+@item -s
+@itemx --sh
+@itemx -c
+@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 --grab
+@itemx --no-grab
+@opindex grab
+@opindex no-grab
+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
+@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}
+@item --no-allow-mark-trusted
+@opindex no-allow-mark-trusted
+Do not allow clients to mark keys as trusted, i.e. put them into the
+@file{trustlist.txt} file.  This makes it harder for users to inadvertently
+accept Root-CA keys.
+
+
+@anchor{option --no-user-trustlist}
+@item --no-user-trustlist
+@opindex no-user-trustlist
+Entirely ignore the user trust list and consider only the global
+trustlist (@file{@value{SYSCONFDIR}/trustlist.txt}).  This
+implies the @ref{option --no-allow-mark-trusted}.
+
+@item --sys-trustlist-name @var{file}
+@opindex sys-trustlist-name
+Changes the default name for the global trustlist from "trustlist.txt"
+to @var{file}.  If @var{file} does not contain any slashes and does
+not start with "~/" it is searched in the system configuration
+directory (@file{@value{SYSCONFDIR}}).
+
+@anchor{option --allow-preset-passphrase}
+@item --allow-preset-passphrase
+@opindex allow-preset-passphrase
+This option allows the use of @command{gpg-preset-passphrase} to seed the
+internal cache of @command{gpg-agent} with passphrases.
+
+@anchor{option --no-allow-loopback-pinentry}
+@item --no-allow-loopback-pinentry
+@item --allow-loopback-pinentry
+@opindex no-allow-loopback-pinentry
+@opindex allow-loopback-pinentry
+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
+Tell Pinentry not to enable features which use an external cache for
+passphrases.
+
+Some desktop environments prefer to unlock all
+credentials with one master password and may have installed a Pinentry
+which employs an additional external cache to implement such a policy.
+By using this option the Pinentry is advised not to make use of such a
+cache and instead always ask the user for the requested passphrase.
+
+@item --allow-emacs-pinentry
+@opindex allow-emacs-pinentry
+Tell Pinentry to allow features to divert the passphrase entry to a
+running Emacs instance.  How this is exactly handled depends on the
+version of the used Pinentry.
+
+@item --ignore-cache-for-signing
+@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 behavior but this command line option takes precedence.
+
+@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.  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}.  Note that a cached passphrase may not be
+evicted immediately from memory if no client requests a cache
+operation.  This is due to an internal housekeeping function which is
+only run every few seconds.
+
+@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.  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
+Set the maximum time a cache entry is valid to @var{n} seconds.  After
+this time a cache entry will be expired even if it has been accessed
+recently or has been set using @command{gpg-preset-passphrase}.  The
+default is 2 hours (7200 seconds).
+
+@item --max-cache-ttl-ssh @var{n}
+@opindex max-cache-ttl-ssh
+Set the maximum time a cache entry used for SSH keys is valid to
+@var{n} seconds.  After this time a cache entry will be expired even
+if it has been accessed recently or has been set using
+@command{gpg-preset-passphrase}.  The default is 2 hours (7200
+seconds).
+
+@item --enforce-passphrase-constraints
+@opindex enforce-passphrase-constraints
+Enforce the passphrase constraints by not allowing the user to bypass
+them using the ``Take it anyway'' button.
+
+@item --min-passphrase-len @var{n}
+@opindex min-passphrase-len
+Set the minimal length of a passphrase.  When entering a new passphrase
+shorter than this value a warning will be displayed.  Defaults to 8.
+
+@item --min-passphrase-nonalpha @var{n}
+@opindex min-passphrase-nonalpha
+Set the minimal number of digits or special characters required in a
+passphrase.  When entering a new passphrase with less than this number
+of digits or special characters a warning will be displayed.  Defaults
+to 1.
+
+@item --check-passphrase-pattern @var{file}
+@itemx --check-sym-passphrase-pattern @var{file}
+@opindex check-passphrase-pattern
+@opindex check-sym-passphrase-pattern
+Check the passphrase against the pattern given in @var{file}.  When
+entering a new passphrase matching one of these pattern a warning will
+be displayed.  If @var{file} does not contain any slashes and does not
+start with "~/" it is searched in the system configuration directory
+(@file{@value{SYSCONFDIR}}).  The default is not to use any
+pattern file.  The second version of this option is only used when
+creating a new symmetric key to allow the use of different patterns
+for such passphrases.
+
+Security note: It is known that checking a passphrase against a list of
+pattern or even against a complete dictionary is not very effective to
+enforce good passphrases.  Users will soon figure up ways to bypass such
+a policy.  A better policy is to educate users on good security
+behavior and optionally to run a passphrase cracker regularly on all
+users passphrases to catch the very simple ones.
+
+@item --max-passphrase-days @var{n}
+@opindex max-passphrase-days
+Ask the user to change the passphrase if @var{n} days have passed since
+the last change.  With @option{--enforce-passphrase-constraints} set the
+user may not bypass this check.
+
+@item --enable-passphrase-history
+@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-formatted-passphrase
+@opindex pinentry-formatted-passphrase
+This option asks the Pinentry to enable passphrase formatting when asking the
+user for a new passphrase and masking of the passphrase is turned off.
+
+If passphrase formatting is enabled, then all non-breaking space characters
+are stripped from the entered passphrase.  Passphrase formatting is mostly
+useful in combination with passphrases generated with the GENPIN
+feature of some Pinentries.  Note that such a generated
+passphrase, if not modified by the user, skips all passphrase
+constraints checking because such constraints would actually weaken
+the generated passphrase.
+
+@item --pinentry-program @var{filename}
+@opindex pinentry-program
+Use program @var{filename} as the PIN entry.  The default is
+installation dependent.  With the default configuration the name of
+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
+requests is passed to Pinentry, so that it can touch that file before
+exiting (it does this only in curses mode).  This option changes the
+file passed to Pinentry to @var{filename}.  The special name
+@code{/dev/null} may be used to completely disable this feature.  Note
+that Pinentry will not create that file, it will only change the
+modification and access time.
+
+
+@item --scdaemon-program @var{filename}
+@opindex scdaemon-program
+Use program @var{filename} as the Smartcard daemon.  The default is
+installation dependent and can be shown with the @command{gpgconf}
+command.
+
+@item --disable-scdaemon
+@opindex disable-scdaemon
+Do not make use of the scdaemon tool.  This option has the effect of
+disabling the ability to do smartcard operations.  Note, that enabling
+this option at runtime does not kill an already forked scdaemon.
+
+@item --disable-check-own-socket
+@opindex disable-check-own-socket
+@command{gpg-agent} employs a periodic self-test to detect a stolen
+socket.  This usually means a second instance of @command{gpg-agent}
+has taken over the socket and @command{gpg-agent} will then terminate
+itself.  This option may be used to disable this self-test for
+debugging purposes.
+
+@item --use-standard-socket
+@itemx --no-use-standard-socket
+@itemx --use-standard-socket-p
+@opindex use-standard-socket
+@opindex no-use-standard-socket
+@opindex use-standard-socket-p
+Since GnuPG 2.1 the standard socket is always used.  These options
+have no more effect.  The command @code{gpg-agent
+--use-standard-socket-p} will thus always return success.
+
+@item --display @var{string}
+@itemx --ttyname @var{string}
+@itemx --ttytype @var{string}
+@itemx --lc-ctype @var{string}
+@itemx --lc-messages @var{string}
+@itemx --xauthority @var{string}
+@opindex display
+@opindex ttyname
+@opindex ttytype
+@opindex lc-ctype
+@opindex lc-messages
+@opindex xauthority
+These options are used with the server mode to pass localization
+information.
+
+@item --keep-tty
+@itemx --keep-display
+@opindex keep-tty
+@opindex keep-display
+Ignore requests to change the current @code{tty} or X window system's
+@code{DISPLAY} variable respectively.  This is useful to lock the
+pinentry to pop up at the @code{tty} or display you started the agent.
+
+@item --listen-backlog @var{n}
+@opindex listen-backlog
+Set the size of the queue for pending connections.  The default is 64.
+
+@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 enables decrypting or
+signing data on a remote machine without exposing the private keys to the
+remote machine.
+
+@item --enable-extended-key-format
+@itemx --disable-extended-key-format
+@opindex enable-extended-key-format
+@opindex disable-extended-key-format
+Since version 2.2.22 keys are created in the extended private key
+format by default.  Changing the passphrase of a key will also convert
+the key to that new format.  This key format is supported since GnuPG
+version 2.1.12 and thus there should be no need to disable it.
+Anyway, the disable option still allows to revert to the old behavior
+for new keys; be aware that keys are never migrated back to the old
+format.  If the enable option has been used the disable option won't
+have an effect.  The advantage of the extended private key format is
+that it is text based and can carry additional meta data.  In extended
+key format the OCB mode is used for key protection.
+
+@anchor{option --enable-ssh-support}
+@item --enable-ssh-support
+@itemx --enable-putty-support
+@opindex enable-ssh-support
+@opindex enable-putty-support
+
+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
+(through a separate socket).  Consequently, it should be possible to use
+the gpg-agent as a drop-in replacement for the well known ssh-agent.
+
+SSH Keys, which are to be used through the agent, need to be added to
+the gpg-agent initially through the ssh-add utility.  When a key is
+added, ssh-add will ask for the password of the provided key file and
+send the unprotected key material to the agent; this causes the
+gpg-agent to ask for a passphrase, which is to be used for encrypting
+the newly received key and storing it in a gpg-agent specific
+directory.
+
+Once a key has been added to the gpg-agent this way, the gpg-agent
+will be ready to use the key.
+
+Note: in case the gpg-agent receives a signature request, the user might
+need to be prompted for a passphrase, which is necessary for decrypting
+the stored key.  Since the ssh-agent protocol does not contain a
+mechanism for telling the agent on which display/terminal it is running,
+gpg-agent's ssh-support will use the TTY or X display where gpg-agent
+has been started.  To switch this display to the current one, the
+following command may be used:
+
+@smallexample
+gpg-connect-agent updatestartuptty /bye
+@end smallexample
+
+Although all GnuPG components try to start the gpg-agent as needed, this
+is not possible for the ssh support because ssh does not know about it.
+Thus if no GnuPG tool which accesses the agent has been run, there is no
+guarantee that ssh is able to use gpg-agent for authentication.  To fix
+this you may start gpg-agent if needed using this simple command:
+
+@smallexample
+gpg-connect-agent /bye
+@end smallexample
+
+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}.
+
+@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.
+
+
+@item --auto-expand-secmem @var{n}
+@opindex auto-expand-secmem
+Allow Libgcrypt to expand its secure memory area as required.  The
+optional value @var{n} is a non-negative integer with a suggested size
+in bytes of each additionally allocated secure memory area.  The value
+is rounded up to the next 32 KiB; usual C style prefixes are allowed.
+For an heavy loaded gpg-agent with many concurrent connection this
+option avoids sign or decrypt errors due to out of secure memory error
+returns.
+
+@item --s2k-calibration @var{milliseconds}
+@opindex s2k-calibration
+Change the default calibration time to @var{milliseconds}.  The given
+value is capped at 60 seconds; a value of 0 resets to the compiled-in
+default.  This option is re-read on a SIGHUP (or @code{gpgconf
+--reload gpg-agent}) and the S2K count is then re-calibrated.
+
+@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 by default 100ms
+to mangle a given passphrase.  See also @option{--s2k-calibration}.
+
+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
+@node Agent Configuration
+@section Configuration
+
+There are a few configuration files needed for the operation of the
+agent. By default they may all be found in the current home directory
+(@pxref{option --homedir}).
+
+@table @file
+
+@item 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.
+  This file is also read after a @code{SIGHUP} however only a few
+  options will actually have an effect.  This default name may be
+  changed on the command line (@pxref{option --options}).
+  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
+  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.
+
+  Here is an example where two keys are marked as ultimately trusted
+  and one as not trusted:
+
+  @cartouche
+  @smallexample
+  # CN=Wurzel ZS 3,O=Intevation GmbH,C=DE
+  A6935DD34EF3087973C706FC311AA2CCF733765B S
+
+  # CN=PCA-1-Verwaltung-02/O=PKI-1-Verwaltung/C=DE
+  DC:BD:69:25:48:BD:BB:7E:31:6E:BB:80:D3:00:80:35:D4:F8:A6:CD S
+
+  # CN=Root-CA/O=Schlapphuete/L=Pullach/C=DE
+  !14:56:98:D3:FE:9C:CA:5A:31:6E:BC:81:D3:11:4E:00:90:A3:44:C2 S
+  @end smallexample
+  @end cartouche
+
+Before entering a key into this file, you need to ensure its
+authenticity.  How to do this depends on your organisation; your
+administrator might have already entered those keys which are deemed
+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 @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.
+
+As a special feature a line @code{include-default} will include a global
+list of trusted certificates (e.g. @file{@value{SYSCONFDIR}/trustlist.txt}).
+This global list is also used if the local list is not available;
+the @ref{option --no-user-trustlist} enforces the use of only
+this global list.
+
+It is possible to add further flags after the @code{S} for use by the
+caller:
+
+@table @code
+
+@item relax
+@cindex relax
+Relax checking of some root certificate requirements.  As of now this
+flag allows the use of root certificates with a missing basicConstraints
+attribute (despite that it is a MUST for CA certificates) and disables
+CRL checking for the root certificate.
+
+@item cm
+If validation of a certificate finally issued by a CA with this flag set
+fails, try again using the chain validation model.
+
+@end table
+
+
+@item 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.
+
+The @command{ssh-add} tool may be used to add new entries to this file;
+you may also add them manually.  Comment lines, indicated by a leading
+hash mark, as well as empty lines are ignored.  An entry starts with
+optional whitespace, followed by the keygrip of the key given as 40 hex
+digits, optionally followed by the caching TTL in seconds and another
+optional field for arbitrary flags.  A non-zero TTL overrides the global
+default as set by @option{--default-cache-ttl-ssh}.
+
+The only flag support is @code{confirm}.  If this flag is found for a
+key, each use of the key will pop up a pinentry to confirm the use of
+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.
+
+The following example lists exactly one key.  Note that keys available
+through a OpenPGP smartcard in the active smartcard reader are
+implicitly added to this list; i.e. there is no need to list them.
+
+@cartouche
+@smallexample
+       # Key added on: 2011-07-20 20:38:46
+       # Fingerprint:  5e:8d:c4:ad:e7:af:6e:27:8a:d6:13:e4:79:ad:0b:81
+       34B62F25E277CF13D3C6BCEBFD3F85D08F0A864B 0 confirm
+@end smallexample
+@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
+  suffix @file{key}.  You should backup all files in this directory
+  and take great care to keep this backup closed away.
+
+
+@end table
+
+Note that on larger installations, it is useful to put predefined
+files into the directory @file{@value{SYSCONFSKELDIR}} so that newly created
+users start up with a working configuration.  For existing users the
+a small helper script is provided to create these files (@pxref{addgnupghome}).
+
+
+
+@c
+@c Agent Signals
+@c
+@mansect signals
+@node Agent 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.
+
+Here is a list of supported signals:
+
+@table @gnupgtabopt
+
+@item SIGHUP
+@cpindex SIGHUP
+This signal flushes all cached passphrases and if the program has been
+started with a configuration file, the configuration file is read
+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{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
+supported but due to the current implementation, which calls the
+scdaemon only once, it is not of much use unless you manually kill the
+scdaemon.
+
+
+@item SIGTERM
+@cpindex SIGTERM
+Shuts down the process but waits until all current requests are
+fulfilled.  If the process has received 3 of these signals and requests
+are still pending, a shutdown is forced.
+
+@item SIGINT
+@cpindex SIGINT
+Shuts down the process immediately.
+
+@item SIGUSR1
+@cpindex SIGUSR1
+Dump internal information to the log file.
+
+@item SIGUSR2
+@cpindex SIGUSR2
+This signal is used for internal purposes.
+
+@end table
+
+@c
+@c  Examples
+@c
+@mansect examples
+@node Agent Examples
+@section Examples
+
+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
+  export GPG_TTY=$(tty)
+@end example
+@end cartouche
+
+If you enabled the Ssh Agent Support, you also need to tell ssh about
+it by adding this to your init script:
+
+@cartouche
+@example
+unset SSH_AGENT_PID
+if [ "$@{gnupg_SSH_AUTH_SOCK_by:-0@}" -ne $$ ]; then
+  export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"
+fi
+@end example
+@end cartouche
+
+
+@c
+@c  Assuan Protocol
+@c
+@manpause
+@node Agent Protocol
+@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.  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.
+
+To identify a key we use a thing called keygrip which is the SHA-1 hash
+of an canonical encoded S-Expression of the public key as used in
+Libgcrypt.  For the purpose of this interface the keygrip is given as a
+hex string.  The advantage of using this and not the hash of a
+certificate is that it will be possible to use the same keypair for
+different protocols, thereby saving space on the token used to keep the
+secret keys.
+
+The @command{gpg-agent} may send status messages during a command or when
+returning from a command to inform a client about the progress or result of an
+operation.  For example, the @var{INQUIRE_MAXLEN} status message may be sent
+during a server inquire to inform the client of the maximum usable length of
+the inquired data (which should not be exceeded).
+
+@menu
+* Agent PKDECRYPT::       Decrypting a session key
+* Agent PKSIGN::          Signing a Hash
+* Agent GENKEY::          Generating a Key
+* Agent IMPORT::          Importing a Secret Key
+* Agent EXPORT::          Exporting a Secret Key
+* Agent ISTRUSTED::       Importing a Root Certificate
+* Agent GET_PASSPHRASE::  Ask for a passphrase
+* Agent CLEAR_PASSPHRASE:: Expire a cached passphrase
+* Agent PRESET_PASSPHRASE:: Set a passphrase for a keygrip
+* Agent GET_CONFIRMATION:: Ask for confirmation
+* Agent HAVEKEY::         Check whether a key is available
+* Agent LEARN::           Register a smartcard
+* Agent PASSWD::          Change a Passphrase
+* Agent UPDATESTARTUPTTY:: Change the Standard Display
+* Agent GETEVENTCOUNTER:: Get the Event Counters
+* Agent GETINFO::         Return information about the process
+* Agent OPTION::          Set options for the session
+@end menu
+
+@node Agent PKDECRYPT
+@subsection Decrypting a session key
+
+The client asks the server to decrypt a session key.  The encrypted
+session key should have all information needed to select the
+appropriate secret key or to delegate it to a smartcard.
+
+@example
+  SETKEY <keyGrip>
+@end example
+
+Tell the server about the key to be used for decryption.  If this is
+not used, @command{gpg-agent} may try to figure out the key by trying to
+decrypt the message with each key available.
+
+@example
+  PKDECRYPT
+@end example
+
+The agent checks whether this command is allowed and then does an
+INQUIRY to get the ciphertext the client should then send the cipher
+text.
+
+@example
+    S: INQUIRE CIPHERTEXT
+    C: D (xxxxxx
+    C: D xxxx)
+    C: END
+@end example
+
+Please note that the server may send status info lines while reading the
+data lines from the client.  The data send is a SPKI like S-Exp with
+this structure:
+
+@example
+     (enc-val
+       (<algo>
+         (<param_name1> <mpi>)
+ 	   ...
+         (<param_namen> <mpi>)))
+@end example
+
+Where algo is a string with the name of the algorithm; see the libgcrypt
+documentation for a list of valid algorithms.  The number and names of
+the parameters depend on the algorithm.  The agent does return an error
+if there is an inconsistency.
+
+If the decryption was successful the decrypted data is returned by
+means of "D" lines.
+
+Here is an example session:
+@cartouche
+@smallexample
+   C: PKDECRYPT
+   S: INQUIRE CIPHERTEXT
+   C: D (enc-val elg (a 349324324)
+   C: D    (b 3F444677CA)))
+   C: END
+   S: # session key follows
+   S: S PADDING 0
+   S: D (value 1234567890ABCDEF0)
+   S: OK decryption successful
+@end smallexample
+@end cartouche
+
+The “PADDING” status line is only send if gpg-agent can tell what kind
+of padding is used.  As of now only the value 0 is used to indicate
+that the padding has been removed.
+
+
+@node Agent PKSIGN
+@subsection Signing a Hash
+
+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:
+
+@example
+   SIGKEY <keyGrip>
+@end example
+
+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
+tests whether the key is a valid key to sign something and responds with
+okay.
+
+@example
+   SETHASH --hash=<name>|<algo> <hexstring>
+@end example
+
+The client can use this command to tell the server about the data <hexstring>
+(which usually is a hash) to be signed. <algo> is the decimal encoded hash
+algorithm number as used by Libgcrypt.  Either <algo> or --hash=<name>
+must be given.  Valid names for <name> are:
+
+@table @code
+@item sha1
+The SHA-1 hash algorithm
+@item sha256
+The SHA-256 hash algorithm
+@item rmd160
+The RIPE-MD160 hash algorithm
+@item md5
+The old and broken MD5 hash algorithm
+@item tls-md5sha1
+A combined hash algorithm as used by the TLS protocol.
+@end table
+
+@noindent
+The actual signing is done using
+
+@example
+   PKSIGN <options>
+@end example
+
+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:
+
+@example
+     (sig-val
+       (<algo>
+         (<param_name1> <mpi>)
+ 	   ...
+         (<param_namen> <mpi>)))
+@end example
+
+
+The operation is affected by the option
+
+@example
+   OPTION use-cache-for-signing=0|1
+@end example
+
+The default of @code{1} uses the cache.  Setting this option to @code{0}
+will lead @command{gpg-agent} to ignore the passphrase cache.  Note, that there is
+also a global command line option for @command{gpg-agent} to globally disable the
+caching.
+
+
+Here is an example session:
+@cartouche
+@smallexample
+   C: SIGKEY <keyGrip>
+   S: OK key available
+   C: SIGKEY <keyGrip>
+   S: OK key available
+   C: PKSIGN
+   S: # I did ask the user whether he really wants to sign
+   S: # I did ask the user for the passphrase
+   S: INQUIRE HASHVAL
+   C: D ABCDEF012345678901234
+   C: END
+   S: # signature follows
+   S: D (sig-val rsa (s 45435453654612121212))
+   S: OK
+@end smallexample
+@end cartouche
+
+@node Agent GENKEY
+@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.  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
+   GENKEY [--no-protection] [--preset] [<cache_nonce>]
+@end example
+
+Invokes the key generation process and the server will then inquire
+on the generation parameters, like:
+
+@example
+   S: INQUIRE KEYPARM
+   C: D (genkey (rsa (nbits  1024)))
+   C: END
+@end example
+
+The format of the key parameters which depends on the algorithm is of
+the form:
+
+@example
+    (genkey
+      (algo
+        (parameter_name_1 ....)
+          ....
+        (parameter_name_n ....)))
+@end example
+
+If everything succeeds, the server returns the *public key* in a SPKI
+like S-Expression like this:
+
+@example
+     (public-key
+       (rsa
+ 	 (n <mpi>)
+ 	 (e <mpi>)))
+@end example
+
+Here is an example session:
+@cartouche
+@smallexample
+   C: GENKEY
+   S: INQUIRE KEYPARM
+   C: D (genkey (rsa (nbits  1024)))
+   C: END
+   S: D (public-key
+   S: D   (rsa (n 326487324683264) (e 10001)))
+   S  OK key created
+@end smallexample
+@end cartouche
+
+The @option{--no-protection} option may be used to prevent prompting for a
+passphrase to protect the secret key while leaving the secret key unprotected.
+The @option{--preset} option may be used to add the passphrase to the cache
+using the default cache parameters.
+
+The @option{--inq-passwd} option may be used to create the key with a
+supplied passphrase.  When used the agent does an inquiry with the
+keyword @code{NEWPASSWD} to retrieve that passphrase.  This option
+takes precedence over @option{--no-protection}; however if the client
+sends a empty (zero-length) passphrase, this is identical to
+@option{--no-protection}.
+
+@node Agent IMPORT
+@subsection Importing a Secret Key
+
+This operation is not yet supported by GpgAgent.  Specialized tools
+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 ourselves, we do not need to import it.
+
+@node Agent EXPORT
+@subsection Export a Secret Key
+
+Not implemented.
+
+Should be done by an extra tool.
+
+@node Agent ISTRUSTED
+@subsection Importing a Root Certificate
+
+Actually we do not import a Root Cert but provide a way to validate
+any piece of data by storing its Hash along with a description and
+an identifier in the PSE.  Here is the interface description:
+
+@example
+    ISTRUSTED <fingerprint>
+@end example
+
+Check whether the OpenPGP primary key or the X.509 certificate with the
+given fingerprint is an ultimately trusted key or a trusted Root CA
+certificate.  The fingerprint should be given as a hexstring (without
+any blanks or colons or whatever in between) and may be left padded with
+00 in case of an MD5 fingerprint.  GPGAgent will answer with:
+
+@example
+    OK
+@end example
+
+The key is in the table of trusted keys.
+
+@example
+    ERR 304 (Not Trusted)
+@end example
+
+The key is not in this table.
+
+Gpg needs the entire list of trusted keys to maintain the web of
+trust; the following command is therefore quite helpful:
+
+@example
+    LISTTRUSTED
+@end example
+
+GpgAgent returns a list of trusted keys line by line:
+
+@example
+    S: D 000000001234454556565656677878AF2F1ECCFF P
+    S: D 340387563485634856435645634856438576457A P
+    S: D FEDC6532453745367FD83474357495743757435D S
+    S: OK
+@end example
+
+The first item on a line is the hexified fingerprint where MD5
+fingerprints are @code{00} padded to the left and the second item is a
+flag to indicate the type of key (so that gpg is able to only take care
+of PGP keys).  P = OpenPGP, S = S/MIME.  A client should ignore the rest
+of the line, so that we can extend the format in the future.
+
+Finally a client should be able to mark a key as trusted:
+
+@example
+   MARKTRUSTED @var{fingerprint} "P"|"S"
+@end example
+
+The server will then pop up a window to ask the user whether she
+really trusts this key. For this it will probably ask for a text to
+be displayed like this:
+
+@example
+   S: INQUIRE TRUSTDESC
+   C: D Do you trust the key with the fingerprint @@FPR@@
+   C: D bla fasel blurb.
+   C: END
+   S: OK
+@end example
+
+Known sequences with the pattern @@foo@@ are replaced according to this
+table:
+
+@table @code
+@item @@FPR16@@
+Format the fingerprint according to gpg rules for a v3 keys.
+@item @@FPR20@@
+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{@@}.
+@end table
+
+@node Agent GET_PASSPHRASE
+@subsection Ask for a passphrase
+
+This function is usually used to ask for a passphrase to be used for
+symmetric encryption, but may also be used by programs which need
+special handling of passphrases.  This command uses a syntax which helps
+clients to use the agent with minimum effort.
+
+@example
+  GET_PASSPHRASE [--data] [--check] [--no-ask] [--repeat[=N]] \
+                 [--qualitybar] @var{cache_id}                \
+                 [@var{error_message} @var{prompt} @var{description}]
+@end example
+
+@var{cache_id} is expected to be a string used to identify a cached
+passphrase.  Use a @code{X} to bypass the cache.  With no other
+arguments the agent returns a cached passphrase or an error.  By
+convention either the hexified fingerprint of the key shall be used for
+@var{cache_id} or an arbitrary string prefixed with the name of the
+calling application and a colon: Like @code{gpg:somestring}.
+
+@var{error_message} is either a single @code{X} for no error message or
+a string to be shown as an error message like (e.g. "invalid
+passphrase").  Blanks must be percent escaped or replaced by @code{+}'.
+
+@var{prompt} is either a single @code{X} for a default prompt or the
+text to be shown as the prompt.  Blanks must be percent escaped or
+replaced by @code{+}.
+
+@var{description} is a text shown above the entry field.  Blanks must be
+percent escaped or replaced by @code{+}.
+
+The agent either returns with an error or with a OK followed by the hex
+encoded passphrase.  Note that the length of the strings is implicitly
+limited by the maximum length of a command.  If the option
+@option{--data} is used, the passphrase is not returned on the OK line
+but by regular data lines; this is the preferred method.
+
+If the option @option{--check} is used, the standard passphrase
+constraints checks are applied.  A check is not done if the passphrase
+has been found in the cache.
+
+If the option @option{--no-ask} is used and the passphrase is not in the
+cache the user will not be asked to enter a passphrase but the error
+code @code{GPG_ERR_NO_DATA} is returned.
+
+If the option @option{--qualitybar} is used and a minimum passphrase
+length has been configured, a visual indication of the entered
+passphrase quality is shown.
+
+@example
+  CLEAR_PASSPHRASE @var{cache_id}
+@end example
+
+may be used to invalidate the cache entry for a passphrase.  The
+function returns with OK even when there is no cached passphrase.
+
+
+
+@node Agent CLEAR_PASSPHRASE
+@subsection Remove a cached passphrase
+
+Use this command to remove a cached passphrase.
+
+@example
+  CLEAR_PASSPHRASE [--mode=normal] <cache_id>
+@end example
+
+The @option{--mode=normal} option can be used to clear a @var{cache_id} that
+was set by gpg-agent.
+
+
+@node Agent PRESET_PASSPHRASE
+@subsection Set a passphrase for a keygrip
+
+This command adds a passphrase to the cache for the specified @var{keygrip}.
+
+@example
+  PRESET_PASSPHRASE [--inquire] <string_or_keygrip> <timeout> [<hexstring>]
+@end example
+
+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 infinite while @code{0} means
+the default (currently only a timeout of -1 is allowed, which means to never
+expire it).
+
+
+@node Agent GET_CONFIRMATION
+@subsection Ask for confirmation
+
+This command may be used to ask for a simple confirmation by
+presenting a text and 2 buttons: Okay and Cancel.
+
+@example
+  GET_CONFIRMATION @var{description}
+@end example
+
+@var{description}is displayed along with a Okay and Cancel
+button. Blanks must be percent escaped or replaced by @code{+}.  A
+@code{X} may be used to display confirmation dialog with a default
+text.
+
+The agent either returns with an error or with a OK.  Note, that the
+length of @var{description} is implicitly limited by the maximum
+length of a command.
+
+
+
+@node Agent HAVEKEY
+@subsection Check whether a key is available
+
+This can be used to see whether a secret key is available.  It does
+not return any information on whether the key is somehow protected.
+
+@example
+  HAVEKEY @var{keygrips}
+@end example
+
+The agent answers either with OK or @code{No_Secret_Key} (208).  The
+caller may want to check for other error codes as well.  More than one
+keygrip may be given.  In this case the command returns success if at
+least one of the keygrips corresponds to an available secret key.
+
+
+@node Agent LEARN
+@subsection Register a smartcard
+
+@example
+  LEARN [--send]
+@end example
+
+This command is used to register a smartcard.  With the @option{--send}
+option given the certificates are sent back.
+
+
+@node Agent PASSWD
+@subsection Change a Passphrase
+
+@example
+  PASSWD [--cache-nonce=<c>] [--passwd-nonce=<s>] [--preset] @var{keygrip}
+@end example
+
+This command is used to interactively change the passphrase of the key
+identified by the hex string @var{keygrip}.  The @option{--preset}
+option may be used to add the new passphrase to the cache using the
+default cache parameters.
+
+
+@node Agent UPDATESTARTUPTTY
+@subsection Change the standard display
+
+@example
+  UPDATESTARTUPTTY
+@end example
+
+Set the startup TTY and X-DISPLAY variables to the values of this
+session.  This command is useful to direct future pinentry invocations
+to another screen.  It is only required because there is no way in the
+ssh-agent protocol to convey this information.
+
+
+@node Agent GETEVENTCOUNTER
+@subsection Get the Event Counters
+
+@example
+  GETEVENTCOUNTER
+@end example
+
+This function return one status line with the current values of the
+event counters.  The event counters are useful to avoid polling by
+delaying a poll until something has changed.  The values are decimal
+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:
+@table @code
+@item ANY
+Incremented with any change of any of the other counters.
+@item KEY
+Incremented for added or removed private keys.
+@item CARD
+Incremented for changes of the card readers stati.
+@end table
+
+@node Agent GETINFO
+@subsection  Return information about the process
+
+This is a multipurpose function to return a variety of information.
+
+@example
+GETINFO @var{what}
+@end example
+
+The value of @var{what} specifies the kind of information returned:
+@table @code
+@item version
+Return the version of the program.
+@item pid
+Return the process id of the process.
+@item socket_name
+Return the name of the socket used to connect the agent.
+@item ssh_socket_name
+Return the name of the socket used for SSH connections.  If SSH support
+has not been enabled the error @code{GPG_ERR_NO_DATA} will be returned.
+@end table
+
+@node Agent OPTION
+@subsection Set options for the session
+
+Here is a list of session options which are not yet described with
+other commands.  The general syntax for an Assuan option is:
+
+@smallexample
+OPTION  @var{key}=@var{value}
+@end smallexample
+
+@noindent
+Supported @var{key}s are:
+
+@table @code
+@item agent-awareness
+This may be used to tell gpg-agent of which gpg-agent version the
+client is aware of.  gpg-agent uses this information to enable
+features which might break older clients.
+
+@item putenv
+Change the session's environment to be used for the
+Pinentry.  Valid values are:
+
+  @table @code
+  @item @var{name}
+  Delete envvar @var{name}
+  @item @var{name}=
+  Set envvar @var{name} to the empty string
+  @item @var{name}=@var{value}
+  Set envvar @var{name} to the string @var{value}.
+  @end table
+
+@item use-cache-for-signing
+See Assuan command @code{PKSIGN}.
+
+@item allow-pinentry-notify
+This does not need any value.  It is used to enable the
+PINENTRY_LAUNCHED inquiry.
+
+@item pinentry-mode
+This option is used to change the operation mode of the pinentry.  The
+following values are defined:
+
+  @table @code
+  @item ask
+  This is the default mode which pops up a pinentry as needed.
+
+  @item cancel
+  Instead of popping up a pinentry, return the error code
+  @code{GPG_ERR_CANCELED}.
+
+  @item error
+  Instead of popping up a pinentry, return the error code
+  @code{GPG_ERR_NO_PIN_ENTRY}.
+
+  @item loopback
+  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.
+  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 is not
+used a default value is used.
+
+@item s2k-count
+Instead of using the standard S2K count (which is computed on the
+fly), the given S2K count is used for new keys or when changing the
+passphrase of a key.  Values below 65536 are considered to be 0.  This
+option is valid for the entire session or until reset to 0.  This
+option is useful if the key is later used on boxes which are either
+much slower or faster than the actual box.
+
+@item pretend-request-origin
+This option switches the connection into a restricted mode which
+handles all further commands in the same way as they would be handled
+when originating from the extra or browser socket.  Note that this
+option is not available in the restricted mode.  Valid values for this
+option are:
+
+  @table @code
+  @item none
+  @itemx local
+  This is a NOP and leaves the connection in the standard way.
+
+  @item remote
+  Pretend to come from a remote origin in the same way as connections
+  from the @option{--extra-socket}.
+
+  @item browser
+  Pretend to come from a local web browser in the same way as connections
+  from the @option{--browser-socket}.
+  @end table
+
+@end table
+
+
+@mansect see also
+@ifset isman
+@command{@gpgname}(1),
+@command{gpgsm}(1),
+@command{gpgconf}(1),
+@command{gpg-connect-agent}(1),
+@command{scdaemon}(1)
+@end ifset
+@include see-also-note.texi