gnupg/doc/gpg-agent.texi

@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.

@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

@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.

@noindent
The usual way to run the agent is from the @code{~/.xsession} file:

@example
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 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:

@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
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:

@smallexample
GPG_TTY=`tty`
export GPG_TTY
@end smallexample

It is important that this environment variable always reflects the
output of the @code{tty} command.

@c man end

@noindent
@xref{Option Index}, for an index to GPG-AGENTS's commands and options.

@menu
* Agent Commands::      List of all commands.
* Agent Options::       List of all options.
* Agent Signals::       Use of some signals.
* Agent Examples::      Some usage examples.
* Agent Protocol::      The protocol the agent uses.
@end menu

@c man begin COMMANDS

@node Agent Commands
@section Commands

Commands are not distinguished from options execpt for the fact that
only one one command is allowed.

@table @gnupgtabopt
@item --version
@opindex version
Print the program version and licensing information.  Not that you can
abbreviate this command.

@item --help, -h
@opindex help
Print a usage message summarizing the most usefule command-line options.
Not that you can abbreviate this command.

@item --dump-options
@opindex dump-options
Print a list of all available options and commands.  Not that you can
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
@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`
@end table


@c man begin OPTIONS

@node Agent Options
@section Option Summary

@table @gnupgtabopt

@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.

@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}.

@item -q
@item --quiet
@opindex q
@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
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

How these messages are mapped to the actual debugging flags is not
specified and may change with newer releaes 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 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

@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 --no-detach
@opindex no-detach
Don't detach the process from the console.  This is manly usefule 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.

@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.

@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.

@item --disable-pth
@opindex disable-pth
Don't allow multiple connections.  This option is in general not very
useful. 

@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.

@item --ignore-cache-for-signing
@opindex ignore-cache-for-signing
This option will let 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.

@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
600 seconds.

@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.

@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}
command.


@item --display @var{string}
@itemx --ttyname @var{string}
@itemx --ttytype @var{string}
@itemx --lc-type @var{string}
@itemx --lc-messages @var{string}
@opindex display 
@opindex ttyname 
@opindex ttytype 
@opindex lc-type 
@opindex lc-messa
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 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.


@end table

All the long options may also be given in the configuration file after
stripping off the two leading dashes.

@c
@c Agent Signals
@c
@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 signals flushes all chached passphrases and when the program was
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.


@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
@itemx SIGUSR2
@cpindex SIGUSR1
@cpindex SIGUSR2
These signals are used for internal purposes.

@end table

@c 
@c  Examples
@c
@node Agent Examples
@section Examples

@c man begin EXAMPLES

@example
$ eval `gpg-agent --daemon`
@end example

@c man end


@c 
@c  Assuan Protocol
@c
@node Agent Protocol
@section Agent's Assuan Protocol

The 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
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
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.

@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 GET_CONFIRMATION:: Ask for confirmation
* Agent HAVEKEY::         Check whether a key is available
* Agent LEARN::           Register a smartcard
* Agent PASSWD::          Change a Passphrase
@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, 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:

@example
   C: PKDECRYPT
   S: INQUIRE CIPHERTEXT
   C: D (enc-val elg (a 349324324) 
   C: D    (b 3F444677CA)))
   C: END
   S: # session key follows
   S: D 1234567890ABCDEF0
   S: OK descryption successful
@end example         


@node Agent PKSIGN
@subsection Signing a Hash

The client ask 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
test whether the key is a valid key to sign something and responds with
okay.

@example
   SETHASH <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 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:

@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   
       (<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 gpg-agent to ignore the passphrase cache.  Note, that there is
also a global command line option for gpg-agent to globally disable the
caching.


Here is an example session:

@example
   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 example


@node Agent GENKEY
@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
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 
@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:

@example
   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 example

@node Agent IMPORT
@subsection Importing a Secret Key

This operation is not yet supportted 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 ourself, 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 desription:

@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
ingerprints 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
conventional 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 @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
passphrase.  Use a @code{X} to bypass the cache.  With no other
arguments the agent returns a cached passphrase or an error.
  
@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.

@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 GET_CONFIRMATION
@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.

@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{keygrip}
@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.


@node Agent LEARN
@subsection Register a smartcard

@example
  LEARN [--send]
@end example

This command is used to register a smartcard.  With the --send
option given the certificates are send back.


@node Agent PASSWD
@subsection Change a Passphrase

@example
  PASSWD @var{keygrip}
@end example

This command is used to interactively change the passphrase of the key
indentified by the hex string @var{keygrip}.