.
[gnupg.git] / doc / gpg-agent.texi
index aad0fbb..066f8e9 100644 (file)
 
 @c man begin DESCRIPTION
 
-@sc{gpg-agent} is a daemon to manage secret (private) keys independelty
-from any protocol.  It is used as a backend for @sc{gpg} and @sc{gpgsm}
-as well as for a couple of other utilities.
+@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.
 
 @noindent
 The usual way to run the agent is from the @code{~/.xsession} file:
@@ -24,11 +25,11 @@ eval `gpg-agent --daemon`
 @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 gpg-agent, so you should make sure that
-only is running:  @sc{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.  This short script may do the job:
 
 @smallexample
 if test -f $HOME/.gpg-agent-info && \
@@ -42,27 +43,39 @@ fi
 @end smallexample
 
 @noindent
-If you want to use a curses based pinentry (which is usually also the
-fallback mode for a GUI based pinentry), you should add these lines to
-your @code{.bashrc} or whatever initialization file is used for all shell
-invocations:
+Note that the new option @option{--write-env-file} may be used instead.
+
+@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`
 export GPG_TTY
 @end smallexample
 
+@noindent
 It is important that this environment variable always reflects the
-output of the @code{tty} command.
+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 dependant) or use the
+option @code{pinentry-pgm} 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
 
 @noindent
-@xref{Option Index}, for an index to GPG-AGENTS's commands and options.
+@xref{Option Index}, for an index to @command{GPG-AGENT}'s commands and options.
 
 @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.
@@ -115,6 +128,7 @@ $ eval `gpg-agent --daemon`
 
 @table @gnupgtabopt
 
+@anchor{option --options}
 @item --options @var{file}
 @opindex options
 Reads configuration from @var{file} instead of from the default
@@ -122,6 +136,16 @@ 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.
 
+@anchor{option --homedir}
+@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}.
+
 @item -v
 @item --verbose
 @opindex v
@@ -223,6 +247,23 @@ 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.
 
+@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
@@ -233,20 +274,16 @@ should in general not be used to avaoid X-sniffing attacks.
 Append all logging output to @var{file}.  This is very helpful in
 seeing what the agent actually does.
 
-@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
+@file{trustlist.txt} file.  This is by default not allowed to make it
 harder for users to inadvertly accept Root-CA keys.
 
 @item --ignore-cache-for-signing
 @opindex ignore-cache-for-signing
-This option will let gpg-agent bypass the passphrase cache for all
+This option will let @command{gpg-agent} bypass the passphrase cache for all
 signing operation.  Note that there is also a per-session option to
 control this behaviour but this command line option takes precedence.
 
@@ -255,6 +292,23 @@ control this behaviour but this command line option takes precedence.
 Set the time a cache entry is valid to @var{n} seconds.  The default are
 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 are 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).
+
+@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 get expired even if it has
+been accessed recently.  The default are 2 hours (7200 seconds).
+
 @item --pinentry-program @var{filename}
 @opindex pinentry-program
 Use program @var{filename} as the PIN entry.  The default is installation
@@ -266,6 +320,27 @@ Use program @var{filename} as the Smartcard daemon.  The default is
 installation dependend and can be shown with the @code{--version}
 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
+@opindex no-use-standard-socket
+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.
+
 
 @item --display @var{string}
 @itemx --ttyname @var{string}
@@ -276,7 +351,7 @@ command.
 @opindex ttyname 
 @opindex ttytype 
 @opindex lc-type 
-@opindex lc-messa
+@opindex lc-messages
 These options are used with the server mode to pass localization
 information.
 
@@ -288,12 +363,128 @@ 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.
 
+@anchor{option --enable-ssh-support}
+@item --enable-ssh-support
+@opindex enable-ssh-support
+
+Enable emulation of 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
+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
+follwing command may be used:
+
+@smallexample
+echo UPDATESTARTUPTTY | gpg-connect-agent
+@end smallexample
+
+
 
 @end table
 
 All the long options may also be given in the configuration file after
 stripping off the two leading dashes.
 
+
+@c man begin 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}).
+
+@item trustlist.txt
+  This is the list of trusted keys.  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 fingeperint from a key
+  listing output.
+  
+  Here is an example where two keys are marked as ultimately 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 
+  @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.
+  
+  @item 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.  The @command{ssh-add} tool y 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 white spaces, 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 @code{!} may be prepended to the keygrip to disable this
+  entry.
+    
+  The follwoing example lists exactly one key.  Note that keys available
+  through a OpenPGP smartcard in the active smartcard reader are implictly
+  added to this list; i.e. there is no need to list them.
+  
+  @example
+  # Key added on 2005-02-25 15:08:29
+  5A6592BF45DC73BD876874A28FD4639282E29B52 0
+  @end example
+@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 provied to create these files (@pxref{addgnupghome}).
+
+
+
 @c
 @c Agent Signals
 @c
@@ -308,14 +499,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 chached 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
@@ -328,12 +520,13 @@ 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
 
@@ -345,12 +538,44 @@ These signals are used for internal purposes.
 
 @c man begin EXAMPLES
 
+The usual way to invoke @command{gpg-agent} is
+
 @example
 $ 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 intialization 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
+    export SSH_AGENT_PID
+  fi
+@end example
+@end cartouche
+
+@noindent
+to your shell initialization file (e.g. @file{~/.bashrc}).
 
 @c 
 @c  Assuan Protocol
@@ -358,13 +583,16 @@ $ eval `gpg-agent --daemon`
 @node Agent Protocol
 @section Agent's Assuan Protocol
 
-The gpg-agent should be started by the login shell and set an
+Note: this section does only document the protocol, which is used by
+GnuPG components; it does not deal with the ssh-agent protocol.
+
+The @command{gpg-agent} should be started by the login shell and set an
 environment variable to tell clients about the socket to be used.
 Clients should deny to access an agent with a socket name which does
 not match its own configuration.  An application may choose to start
 an instance of the gpgagent if it does not figure that any has been
 started; it should not do this if a gpgagent is running but not
-usable.  Because gpg-agent can only be used in background mode, no
+usable.  Because @command{gpg-agent} can only be used in background mode, no
 special command line option is required to activate the use of the
 protocol.
 
@@ -388,6 +616,7 @@ 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
 @end menu
 
 @node Agent PKDECRYPT
@@ -402,7 +631,7 @@ appropriate secret key or to delegate it to a smartcard.
 @end example
 
 Tell the server about the key to be used for decryption.  If this is
-not used, gpg-agent may try to figure out the key by trying to
+not used, @command{gpg-agent} may try to figure out the key by trying to
 decrypt the message with each key available.
 
 @example
@@ -514,8 +743,8 @@ The operation is affected by the option
 @end example
 
 The default of @code{1} uses the cache.  Setting this option to @code{0}
-will lead gpg-agent to ignore the passphrase cache.  Note, that there is
-also a global command line option for gpg-agent to globally disable the
+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.
 
 
@@ -788,4 +1017,16 @@ This command is used to interactively change the passphrase of the key
 indentified 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.
+