diff --git a/doc/ChangeLog b/doc/ChangeLog index 07f94f338..4ad8b18c8 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,7 @@ +2005-04-20 Werner Koch + + * gpg-agent.texi (Agent Configuration): New section. + 2005-02-24 Werner Koch * tools.texi (gpg-connect-agent): New. @@ -171,7 +175,7 @@ * Makefile.am, gpgsm.texi: New. - Copyright 2002 Free Software Foundation, Inc. + Copyright 2002, 2004, 2005 Free Software Foundation, Inc. This file is free software; as a special exception the author gives unlimited permission to copy and/or distribute it, with or without diff --git a/doc/gnupg.texi b/doc/gnupg.texi index 5c6925260..4c30980b3 100644 --- a/doc/gnupg.texi +++ b/doc/gnupg.texi @@ -22,7 +22,7 @@ Published by the Free Software Foundation@* Boston, MA 02111-1307 USA @end iftex -Copyright @copyright{} 2002, 2004 Free Software Foundation, Inc. +Copyright @copyright{} 2002, 2004, 2005 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/gpg-agent.texi b/doc/gpg-agent.texi index 17bd59c7a..52f1fe0d8 100644 --- a/doc/gpg-agent.texi +++ b/doc/gpg-agent.texi @@ -11,7 +11,7 @@ @c man begin 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. @@ -71,6 +71,7 @@ one (e.g. @file{/usr/bin/pinentry}). @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. @@ -123,6 +124,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 @@ -130,6 +132,7 @@ 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 @@ -255,10 +258,11 @@ seeing what the agent actually does. 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 @@ -289,6 +293,12 @@ 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 @@ -326,6 +336,7 @@ 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 @@ -359,6 +370,87 @@ gpg-agent has been started. 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 diff --git a/doc/gpgsm.texi b/doc/gpgsm.texi index 09fd7d660..df2f71bce 100644 --- a/doc/gpgsm.texi +++ b/doc/gpgsm.texi @@ -12,7 +12,7 @@ @command{gpgsm} is a tool similar to @command{gpg} to provide digital encryption and signing servicesd on X.509 certificates and the CMS -protocoll. It is mainly used as a backend for S/MIME mail processing. +protocol. It is mainly used as a backend for S/MIME mail processing. @command{gpgsm} includes a full features certificate management and complies with all rules defined for the German Sphinx project.