Provide default strings for the pinentry.
[gnupg.git] / doc / gpg-agent.texi
index 2900154..344f412 100644 (file)
@@ -61,23 +61,36 @@ 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:
+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
+  export SSH_AGENT_PID
 fi
 @end smallexample
 
 @noindent
-Note that the new option @option{--write-env-file} may be used instead.
+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.
  
-
 @noindent
 You should always add the following lines to your @code{.bashrc} or
 whatever initialization file is used for all shell invocations:
@@ -144,15 +157,17 @@ default mode is to create a socket and listen for commands there.
 
 @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
 
-
 @mansect options
 @node Agent Options
 @section Option Summary
@@ -198,20 +213,26 @@ 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 releases of this program. They are
@@ -420,13 +441,13 @@ default on Windows systems.
 @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}
 @itemx --xauthority @var{string}
 @opindex display 
 @opindex ttyname 
 @opindex ttytype 
-@opindex lc-type 
+@opindex lc-ctype 
 @opindex lc-messages
 @opindex xauthority
 These options are used with the server mode to pass localization
@@ -499,17 +520,22 @@ agent. By default they may all be found in the current home directory
   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}).
+  changed on the command line (@pxref{option --options}).  
+  You should backup this file.
 
 @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 fingerprint from a key
-  listing output.
+  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:
+  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
@@ -517,6 +543,9 @@ agent. By default they may all be found in the current home directory
   
   # 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
@@ -554,15 +583,18 @@ fails, try again using the chain validation model.
 @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
-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.
+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 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
@@ -577,7 +609,8 @@ implicitly added to this list; i.e. there is no need to list them.
 
   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}.
+  suffix @file{key}.  You should backup all files in this directory
+  and take great care to keep this backup closed away.
 
 
 @end table
@@ -700,7 +733,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
@@ -828,7 +861,7 @@ The actual signing is done using
    PKSIGN <options>
 @end example
 
-Options are not yet defined, but my later be used to choosen among
+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:
@@ -930,7 +963,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
@@ -949,7 +982,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>
@@ -990,7 +1023,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.
@@ -1036,7 +1069,7 @@ special handling of passphrases.  This command uses a syntax which helps
 clients to use the agent with minimum effort.
 
 @example
-  GET_PASSPHRASE [--data] [--check] [--no-ask] @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 string used to identify a cached
@@ -1071,6 +1104,9 @@ 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}
@@ -1084,7 +1120,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}
@@ -1134,7 +1170,7 @@ 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