Revamped the W32 gettext implementation.
[gnupg.git] / doc / gpg-agent.texi
index c9a89b9..39f5fad 100644 (file)
@@ -94,7 +94,7 @@ 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}).
@@ -117,8 +117,8 @@ one (e.g. @file{/usr/bin/pinentry}).
 @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
@@ -214,7 +214,7 @@ one of:
    @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}
@@ -256,7 +256,7 @@ 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
@@ -268,9 +268,9 @@ debugging.
 @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
@@ -291,8 +291,8 @@ eval `cut -d= -f 1 < @var{file} | xargs echo export`
 
 @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.
 
 @item --log-file @var{file}
 @opindex log-file
@@ -304,7 +304,7 @@ seeing what the agent actually does.
 @opindex allow-mark-trusted
 Allow clients to mark keys as trusted, i.e. put them into the
 @file{trustlist.txt} file.  This is by default not allowed to make it
-harder for users to inadvertly accept Root-CA keys.
+harder for users to inadvertently accept Root-CA keys.
 
 @item --ignore-cache-for-signing
 @opindex ignore-cache-for-signing
@@ -314,35 +314,87 @@ 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 are 1800 seconds.
+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 get expired even if it has
-been accessed recently.  The default are 2 hours (7200 seconds).
+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 and can be shown with the @code{--version} command.
+
+@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 @code{--version}
 command.
 
 @item --disable-scdaemon
@@ -359,12 +411,10 @@ 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
+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 as
-a remote file system.  
-
-@noindent
-Note, that as of now, W32 systems default to this option.
+a remote file system.  Note, that @option{--use-standard-socket} is the
+default on Windows systems.
 
 
 @item --display @var{string}
@@ -372,11 +422,13 @@ Note, that as of now, W32 systems default to this option.
 @itemx --ttytype @var{string}
 @itemx --lc-type @var{string}
 @itemx --lc-messages @var{string}
+@itemx --xauthority @var{string}
 @opindex display 
 @opindex ttyname 
 @opindex ttytype 
 @opindex lc-type 
 @opindex lc-messages
+@opindex xauthority
 These options are used with the server mode to pass localization
 information.
 
@@ -384,8 +436,8 @@ information.
 @itemx --keep-display
 @opindex keep-tty
 @opindex keep-display
-Ignore requests to change change the current @code{tty} respective the X
-window system's @code{DISPLAY} variable.  This is useful to lock the
+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.
 
 @anchor{option --enable-ssh-support}
@@ -396,7 +448,7 @@ 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
+(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
@@ -407,7 +459,7 @@ 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
@@ -416,7 +468,7 @@ 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:
+following command may be used:
 
 @smallexample
 echo UPDATESTARTUPTTY | gpg-connect-agent
@@ -467,34 +519,54 @@ agent. By default they may all be found in the current home directory
   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.
+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
+Relax checking of some root certificate requirements.  This is for
+example required if the certificate is missing the basicConstraints
+attribute (despite that it is a MUST for CA certificates).
+
+@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
 
-  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.
+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
+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.  The keygrip may be prefixed with a @code{!} 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.
+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 2005-02-25 15:08:29
@@ -513,7 +585,7 @@ agent. By default they may all be found in the current home directory
 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}).
+a small helper script is provided to create these files (@pxref{addgnupghome}).
 
 
 
@@ -532,7 +604,7 @@ Here is a list of supported signals:
 
 @item SIGHUP
 @cpindex SIGHUP
-This signal flushes all chached passphrases and if the program has been
+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{no-grab},
@@ -578,7 +650,7 @@ $ eval `gpg-agent --daemon`
 
 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
+part of the Xsession initialization, you may simply replace
 @command{ssh-agent} by a script like:
 
 @cartouche
@@ -648,6 +720,8 @@ secret keys.
 * 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
 @end menu
 
 @node Agent PKDECRYPT
@@ -731,12 +805,23 @@ 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
@@ -744,19 +829,9 @@ The actual signing is done using
 @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:
+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   
@@ -802,7 +877,7 @@ 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.
 
@@ -961,12 +1036,15 @@ 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] @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
@@ -979,9 +1057,15 @@ 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.
 
 @example
   CLEAR_PASSPHRASE @var{cache_id}
@@ -1061,6 +1145,53 @@ 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
+
+
 @mansect see also
 @ifset isman
 @command{gpg2}(1),