Add mksamplekeys script.
[gnupg.git] / doc / gpg-agent.texi
index 01b4227..4c7f13f 100644 (file)
 @c This is part of the GnuPG manual.
 @c For copying conditions, see the file gnupg.texi.
 
+@c Note that we use this texinfo file for all versions of GnuPG:
+@c 2.0 and 2.1.  The macro "gpgtwoone" controls parts which are only
+@c valid for GnuPG 2.1 and later.
+
+
 @node Invoking GPG-AGENT
 @chapter Invoking GPG-AGENT
 @cindex GPG-AGENT command options
 @cindex command options
 @cindex options, GPG-AGENT command
 
-@c man begin DESCRIPTION
-
+@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
-independelty from any protocol.  It is used as a backend for
+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.
 
+@ifset gpgtwoone
+The agent is usualy 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:
+
+@example
+gpg-connect-agent /bye
+@end example
+@end ifset
+
+@ifclear gpgtwoone
 @noindent
 The usual way to run the agent is from the @code{~/.xsession} file:
 
 @example
-eval `gpg-agent --daemon`
+eval $(gpg-agent --daemon)
 @end example
-
 @noindent
 If you don't use an X server, you can also put this into your regular
 startup file @code{~/.profile} or @code{.bash_profile}.  It is best not
-to run multiple instance of the @command{gpg-agent}, so you should make sure that
-only is running:  @command{gpg-agent} uses an environment variable to inform
-clients about the communication parameters. You can write the
-content of this environment variable to a file so that you can test for
-a running agent.  This short script may do the job:
+to run multiple instance of the @command{gpg-agent}, so you should make
+sure that only one is running: @command{gpg-agent} uses an environment
+variable to inform clients about the communication parameters. You can
+write the content of this environment variable to a file so that you can
+test for a running agent.  Here is an example using Bourne shell syntax:
 
 @smallexample
-if test -f $HOME/.gpg-agent-info && \
-   kill -0 `cut -d: -f 2 $HOME/.gpg-agent-info` 2>/dev/null; then
-     GPG_AGENT_INFO=`cat $HOME/.gpg-agent-info`
-     export GPG_AGENT_INFO   
-else
-     eval `gpg-agent --daemon`
-     echo $GPG_AGENT_INFO >$HOME/.gpg-agent-info
+gpg-agent --daemon --enable-ssh-support \
+          --write-env-file "$@{HOME@}/.gpg-agent-info"
+@end smallexample
+
+This code should only be run once per user session to initially fire up
+the agent.  In the example the optional support for the included Secure
+Shell agent is enabled and the information about the agent is written to
+a file in the HOME directory.  Note that by running gpg-agent without
+arguments you may test whether an agent is already running; however such
+a test may lead to a race condition, thus it is not suggested.
+
+@noindent
+The second script needs to be run for each interactive session:
+
+@smallexample
+if [ -f "$@{HOME@}/.gpg-agent-info" ]; then
+  . "$@{HOME@}/.gpg-agent-info"
+  export GPG_AGENT_INFO
+  export SSH_AUTH_SOCK
 fi
 @end smallexample
 
 @noindent
+It reads the data out of the file and exports the variables.  If you
+don't use Secure Shell, you don't need the last two export statements.
+@end ifclear
+
+@noindent
 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`
+GPG_TTY=$(tty)
 export GPG_TTY
 @end smallexample
 
@@ -58,46 +123,47 @@ required.
 
 Please make sure that a proper pinentry program has been installed
 under the default filename (which is system dependant) or use the
-option @code{pinentry-pgm} to specify the full name of that program.
+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{/usr/bin/pinentry-gtk}) to the expected
 one (e.g. @file{/usr/bin/pinentry}).
 
-@c man end
-
+@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
 * 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
 
-@c man begin COMMANDS
-
+@mansect commands
 @node Agent Commands
 @section Commands
 
-Commands are not distinguished from options execpt for the fact that
-only one one command is allowed.
+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.  Not that you can
+Print the program version and licensing information.  Note that you cannot
 abbreviate this command.
 
-@item --help, -h
+@item --help
+@itemx -h
 @opindex help
-Print a usage message summarizing the most usefule command-line options.
-Not that you can abbreviate this command.
+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.  Not that you can
+Print a list of all available options and commands.  Note that you cannot
 abbreviate this command.
 
 @item --server
@@ -105,24 +171,26 @@ abbreviate this command.
 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
+@item --daemon [@var{command line}]
 @opindex daemon
-Run the program in the background.  This option is required to prevent
-it from being accidently running in the background.  A common way to do
-this is:
-@example
-@end example
-$ eval `gpg-agent --daemon`
+Start the gpg-agent as a daemon; that is, detach it from the console
+and run it in the background.  Because @command{gpg-agent} prints out
+important information required for further use, a common way of
+invoking gpg-agent is: @code{eval $(gpg-agent --daemon)} to setup the
+environment variables.  The option @option{--write-env-file} is
+another way commonly used to do this.  Yet another way is creating
+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; if you exit from this shell, gpg-agent terminates as well.
 @end table
 
-
-@c man begin OPTIONS
-
+@mansect options
 @node Agent Options
 @section Option Summary
 
 @table @gnupgtabopt
 
+@anchor{option --options}
 @item --options @var{file}
 @opindex options
 Reads configuration from @var{file} instead of from the default
@@ -130,26 +198,19 @@ 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.
 
-@item --homedir @var{dir}
-@opindex homedir
-Set the name of the home directory to @var{dir}. If his option is not
-used, the home directory defaults to @file{~/.gnupg}.  It is only
-recognized when given on the command line.  It also overrides any home
-directory stated through the environment variable @env{GNUPGHOME} or
-(on W32 systems) by means on the Registry entry
-@var{HKCU\Software\GNU\GnuPG:HomeDir}.
+@anchor{option --homedir}
+@include opt-homedir.texi
+
 
 @item -v
 @item --verbose
-@opindex v
 @opindex verbose
 Outputs additional information while running.
 You can increase the verbosity by giving several
-verbose commands to @sc{gpgsm}, such as @samp{-vv}.
+verbose commands to @command{gpgsm}, such as @samp{-vv}.
 
 @item -q
 @item --quiet
-@opindex q
 @opindex quiet
 Try to be as quiet as possible.
 
@@ -166,23 +227,29 @@ forth to @var{epoch} which is the number of seconds elapsed since the year
 @item --debug-level @var{level}
 @opindex debug-level
 Select the debug level for investigating problems. @var{level} may be
-one of:
-
-   @table @code
-   @item none
-   no debugging at all.
-   @item basic  
-   some basic debug messages
-   @item advanced
-   more verbose debug messages
-   @item expert
-   even more detailed messages
-   @item guru
-   all of the debug messages you can get
-   @end table
+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 releaes of this program. They are
+specified and may change with newer releases of this program. They are
 however carefully selected to best aid in debugging.
 
 @item --debug @var{flags}
@@ -191,26 +258,26 @@ This option is only useful for debugging and the behaviour 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
+@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
@@ -224,42 +291,66 @@ debugger.
 
 @item --no-detach
 @opindex no-detach
-Don't detach the process from the console.  This is manly usefule for
+Don't detach the process from the console.  This is mainly useful for
 debugging.
 
 @item -s
 @itemx --sh
 @itemx -c
 @itemx --csh
-@opindex s
 @opindex sh
-@opindex c
 @opindex csh
 Format the info output in daemon mode for use with the standard Bourne
-shell respective the C-shell . The default ist to guess it based on the
-environment variable @code{SHELL} which is in almost all cases
-sufficient.
+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 --write-env-file @var{file}
+@opindex write-env-file
+Often it is required to connect to the agent from a process not being an
+inferior of @command{gpg-agent} and thus the environment variable with
+the socket name is not available.  To help setting up those variables in
+other sessions, this option may be used to write the information into
+@var{file}.  If @var{file} is not specified the default name
+@file{$@{HOME@}/.gpg-agent-info} will be used.  The format is suitable
+to be evaluated by a Bourne shell like in this simple example:
+
+@example
+eval $(cat @var{file})
+eval $(cut -d= -f 1 < @var{file} | xargs echo export)
+@end example
+
+
 
 @item --no-grab
 @opindex no-grab
-Tell the pinentryo not to grab the keyboard and mouse.  This option
-should in general not be used to avaoid X-sniffing attacks.
+Tell the pinentry not to grab the keyboard and mouse.  This option
+should in general not be used to avoid X-sniffing attacks.
 
+@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.
+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.
 
-@item --disable-pth
-@opindex disable-pth
-Don't allow multiple connections.  This option is in general not very
-useful. 
 
+@anchor{option --allow-mark-trusted}
 @item --allow-mark-trusted
 @opindex allow-mark-trusted
 Allow clients to mark keys as trusted, i.e. put them into the
-@code{trustlist.txt} file.  This is by default not allowed to make it
-harder for users to inadvertly accept Root-CA keys.
+@file{trustlist.txt} file.  This is by default not allowed to make it
+harder for users to inadvertently accept Root-CA keys.
+
+@ifset gpgtwoone
+@anchor{option --allow-loopback-pinentry}
+@item --allow-loopback-pinentry
+@opindex allow-loopback-pinentry
+Allow clients to use the loopback pinentry features; see the option
+@option{pinentry-mode} for details.
+@end ifset
 
 @item --ignore-cache-for-signing
 @opindex ignore-cache-for-signing
@@ -269,26 +360,95 @@ control this behaviour 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 are
+Set the time a cache entry is valid to @var{n} seconds.  The default is
 600 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.
+
 @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 get expired even if it has been accessed
-recently.  The default are 2 hours (7200 seconds).
+this time a cache entry will be expired even if it has been accessed
+recently.  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.  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}
+@opindex check-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. @var{file} should be an absolute filename.  The default is
+not to use any pattern file.
+
+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-program @var{filename}
 @opindex pinentry-program
 Use program @var{filename} as the PIN entry.  The default is installation
-dependend and can be shown with the @code{--version} command.
+dependent.
+
+@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 dependend and can be shown with the @code{--version}
+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 --use-standard-socket
 @itemx --no-use-standard-socket
 @opindex use-standard-socket
@@ -297,24 +457,36 @@ By enabling this option @command{gpg-agent} will listen on the socket
 named @file{S.gpg-agent}, located in the home directory, and not create
 a random socket below a temporary directory.  Tools connecting to
 @command{gpg-agent} should first try to connect to the socket given in
-environment variable @var{GPG_AGENT_INFO} and the fall back to this
-socket.  This option may not be used if the home directory is mounted as
-a remote file system.  
-
-@noindent
-Note, that as of now, W32 systems default to this option.
-
+environment variable @var{GPG_AGENT_INFO} and then fall back to this
+socket.  This option may not be used if the home directory is mounted on
+a remote file system which does not support special files like fifos or
+sockets.
+@ifset gpgtwoone
+Note, that @option{--use-standard-socket} is the default on all
+systems since GnuPG 2.1.
+@end ifset
+@ifclear gpgtwoone
+Note, that @option{--use-standard-socket} is the default on
+Windows systems.
+@end ifclear
+The default may be changed at build time.  It is
+possible to test at runtime whether the agent has been configured for
+use with the standard socket by issuing the command @command{gpg-agent
+--use-standard-socket-p} which returns success if the standard socket
+option has been enabled.
 
 @item --display @var{string}
 @itemx --ttyname @var{string}
 @itemx --ttytype @var{string}
-@itemx --lc-type @var{string}
+@itemx --lc-ctype @var{string}
 @itemx --lc-messages @var{string}
-@opindex display 
-@opindex ttyname 
-@opindex ttytype 
-@opindex lc-type 
+@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.
 
@@ -322,20 +494,19 @@ information.
 @itemx --keep-display
 @opindex keep-tty
 @opindex keep-display
-Ignore requests to change change the current @sc{tty} respective the X
-window system's @code{DISPLAY} variable.  This is useful to lock the
-pinentry to pop up at the @sc{tty} or display you started the agent.
+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 --ssh-support
-@itemx --ssh-support
-@opindex ssh-support
-@opindex ssh
+@anchor{option --enable-ssh-support}
+@item --enable-ssh-support
+@opindex enable-ssh-support
 
-Enable emulation of the OpenSSH Agent protocol.
+Enable the OpenSSH Agent protocol.
 
 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 seperate socket).  Consequently, it should possible to use
+(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
@@ -346,30 +517,176 @@ 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
+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 passphrased, 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 switch implies --keep-display
-and --keep-tty.  This strategy causes the gpg-agent to open a pinentry
-on the display or on the terminal, on which it (the gpg-agent) was
-started.
+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 abale 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.
 
 @end table
 
 All the long options may also be given in the configuration file after
 stripping off the two leading dashes.
 
+
+@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
+@cindex 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
+  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
+  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:
+
+  @example
+  # 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 example
+
+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 allowing interactive
+updates of this file by using the @xref{option --allow-mark-trusted}.
+This is however not as secure as maintaining this file manually.  It is
+even 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{/etc/gnupg/trustlist.txt}).
+This global list is also used if the local list is not available.
+
+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
+@cindex 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 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.
+
+  @example
+  # 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 example
+
+@item 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{/etc/skel/.gnupg/} 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. 
+the @command{kill} command to send a signal to the process.
 
 Here is a list of supported signals:
 
@@ -377,14 +694,15 @@ Here is a list of supported signals:
 
 @item SIGHUP
 @cpindex SIGHUP
-This signals flushes all chached passphrases and when the program was
+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{no-grab}, @code{pinentry-program},
-@code{default-cache-ttl} and @code{ignore-cache-for-signing}.
-@code{scdaemon-program} is also supported but due to the current
-implementation, which calls the scdaemon only once, it is not of much
-use.
+@code{debug}, @code{debug-all}, @code{debug-level}, @code{no-grab},
+@code{pinentry-program}, @code{default-cache-ttl}, @code{max-cache-ttl},
+@code{ignore-cache-for-signing}, @code{allow-mark-trusted} and
+@code{disable-scdaemon}.  @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
@@ -397,33 +715,63 @@ are still pending, a shutdown is forced.
 @cpindex SIGINT
 Shuts down the process immediately.
 
-
 @item SIGUSR1
-@itemx SIGUSR2
 @cpindex SIGUSR1
+Dump internal information to the log file.
+
+@item SIGUSR2
 @cpindex SIGUSR2
-These signals are used for internal purposes.
+This signal is used for internal purposes.
 
 @end table
 
-@c 
+@c
 @c  Examples
 @c
+@mansect examples
 @node Agent Examples
 @section Examples
 
-@c man begin EXAMPLES
+The usual way to invoke @command{gpg-agent} is
 
 @example
-$ eval `gpg-agent --daemon`
+$ eval $(gpg-agent --daemon)
 @end example
 
-@c man end
+An alternative way is by replacing @command{ssh-agent} with
+@command{gpg-agent}.  If for example @command{ssh-agent} is started as
+part of the Xsession initialization, you may simply replace
+@command{ssh-agent} by a script like:
+
+@cartouche
+@example
+#!/bin/sh
 
+exec /usr/local/bin/gpg-agent --enable-ssh-support --daemon \
+      --write-env-file $@{HOME@}/.gpg-agent-info "$@@"
+@end example
+@end cartouche
+
+@noindent
+and add something like (for Bourne shells)
+
+@cartouche
+@example
+  if [ -f "$@{HOME@}/.gpg-agent-info" ]; then
+    . "$@{HOME@}/.gpg-agent-info"
+    export GPG_AGENT_INFO
+    export SSH_AUTH_SOCK
+  fi
+@end example
+@end cartouche
+
+@noindent
+to your shell initialization file (e.g. @file{~/.bashrc}).
 
-@c 
+@c
 @c  Assuan Protocol
 @c
+@manpause
 @node Agent Protocol
 @section Agent's Assuan Protocol
 
@@ -441,7 +789,7 @@ special command line option is required to activate the use of the
 protocol.
 
 To identify a key we use a thing called keygrip which is the SHA-1 hash
-of an canoncical encoded S-Expression of the the public key as used in
+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
@@ -460,6 +808,10 @@ secret keys.
 * 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
@@ -491,13 +843,13 @@ text.
     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   
+     (enc-val
        (<algo>
          (<param_name1> <mpi>)
           ...
@@ -510,20 +862,20 @@ 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. 
+means of "D" lines.
 
 Here is an example session:
 
 @example
    C: PKDECRYPT
    S: INQUIRE CIPHERTEXT
-   C: D (enc-val elg (a 349324324) 
+   C: D (enc-val elg (a 349324324)
    C: D    (b 3F444677CA)))
    C: END
    S: # session key follows
-   S: D 1234567890ABCDEF0
+   S: D (value 1234567890ABCDEF0)
    S: OK descryption successful
-@end example         
+@end example
 
 
 @node Agent PKSIGN
@@ -543,35 +895,36 @@ test whether the key is a valid key to sign something and responds with
 okay.
 
 @example
-   SETHASH <hexstring>
+   SETHASH --hash=<name>|<algo> <hexstring>
 @end example
 
-The client can use this command to tell the server about the data
-(which usually is a hash) to be signed.  
+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
+@item sha256
+@item rmd160
+@item md5
+@item tls-md5sha1
+@end table
+
+@noindent
 The actual signing is done using
 
 @example
    PKSIGN <options>
 @end example
 
-Options are not yet defined, but my later be used to choosen among
-different algorithms (e.g. pkcs 1.5)
-
-The agent does then some checks, asks for the passphrase and
-if SETHASH has not been used asks the client for the data to sign:
+Options are not yet defined, but my 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
-   S: INQUIRE HASHVAL
-   C: D ABCDEF012345678901234
-   C: END
-@end example
-
-As a result the server returns the signature as an SPKI like S-Exp
-in "D" lines:
-
-@example  
-     (sig-val   
+     (sig-val
        (<algo>
          (<param_name1> <mpi>)
           ...
@@ -614,12 +967,12 @@ 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 -w which is in most cases a Soft-PSE.  An not yet defined
+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
 of the PSE, a special export tool has to be used.
 
 @example
-   GENKEY 
+   GENKEY
 @end example
 
 Invokes the key generation process and the server will then inquire
@@ -667,7 +1020,7 @@ Here is an example session:
 @node Agent IMPORT
 @subsection Importing a Secret Key
 
-This operation is not yet supportted by GpgAgent.  Specialized tools
+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
@@ -686,7 +1039,7 @@ Should be done by an extra tool.
 
 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 desription:
+an identifier in the PSE.  Here is the interface description:
 
 @example
     ISTRUSTED <fingerprint>
@@ -727,7 +1080,7 @@ GpgAgent returns a list of trusted keys line by line:
 @end example
 
 The first item on a line is the hexified fingerprint where MD5
-ingerprints are @code{00} padded to the left and the second item is a
+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.
@@ -754,13 +1107,13 @@ Known sequences with the pattern @@foo@@ are replaced according to this
 table:
 
 @table @code
-@item @@FPR16@@ 
+@item @@FPR16@@
 Format the fingerprint according to gpg rules for a v3 keys.
-@item @@FPR20@@ 
+@item @@FPR20@@
 Format the fingerprint according to gpg rules for a v4 keys.
 @item @@FPR@@
 Choose an appropriate format to format the fingerprint.
-@item @@@@ 
+@item @@@@
 Replaced by a single @code{@@}
 @end table
 
@@ -773,13 +1126,16 @@ special handling of passphrases.  This command uses a syntax which helps
 clients to use the agent with minimum effort.
 
 @example
-  GET_PASSPHRASE @var{cache_id} [@var{error_message} @var{prompt} @var{description}]
+  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 hex string used for caching a
+@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.
-  
+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{+}'.
@@ -791,9 +1147,23 @@ 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.
+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}
@@ -807,7 +1177,7 @@ function returns with OK even when there is no cached passphrase.
 @subsection Ask for confirmation
 
 This command may be used to ask for a simple confirmation by
-presenting a text and 2 bottonts: Okay and Cancel.
+presenting a text and 2 buttons: Okay and Cancel.
 
 @example
   GET_CONFIRMATION @var{description}
@@ -831,11 +1201,13 @@ 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{keygrip}
+  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.
+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
@@ -857,7 +1229,158 @@ option given the certificates are send back.
 @end example
 
 This command is used to interactively change the passphrase of the key
-indentified by the hex string @var{keygrip}.
+identified by the hex string @var{keygrip}.
+
+
+@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 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.
+
+@ifset gpgtwoone
+@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.
+  Use the @xref{option --allow-loopback-pinentry}.
+
+  @end table
+@end ifset
+
+@ifset gpgtwoone
+@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
+used a default value is used.
+@end ifset
+
+@ifset gpgtwoone
+@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.
+@end ifset
+
+@end table
 
 
+@mansect see also
+@ifset isman
+@command{gpg2}(1),
+@command{gpgsm}(1),
+@command{gpg-connect-agent}(1),
+@command{scdaemon}(1)
+@end ifset
+@include see-also-note.texi