gnupg: Agent Configuration
2.3 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
(⇒option --homedir).
'gpg-agent.conf'
This is the standard configuration file read by '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 'SIGHUP' however only a few options
will actually have an effect. This default name may be changed on
the command line (⇒option --options). You should backup
this file.
'trustlist.txt'
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 'S'. Colons
may optionally be used to separate the bytes of a fingerprint; this
enables cutting and pasting the fingerprint from a key listing
output. If the line is prefixed with a '!' the key is explicitly
marked as not trusted.
Here is an example where two keys are marked as ultimately trusted
and one as not trusted:
# 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
# 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
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
disallowing interactive updates of this file by using the ⇒
option --no-allow-mark-trusted. It might even be advisable to
change the permissions to read-only so that this file can't be
changed inadvertently.
As a special feature a line 'include-default' will include a global
list of trusted certificates (e.g. '/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 'S' for use by the
caller:
'relax'
Relax checking of some root certificate requirements. As of
now this flag allows the use of root certificates with a
missing basicConstraints attribute (despite that it is a MUST
for CA certificates) and disables CRL checking for the root
certificate.
'cm'
If validation of a certificate finally issued by a CA with
this flag set fails, try again using the chain validation
model.
'sshcontrol'
This file is used when support for the secure shell agent protocol
has been enabled (⇒option --enable-ssh-support). Only keys
present in this file are used in the SSH protocol. You should
backup this file.
The '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 '--default-cache-ttl-ssh'.
The only flag support is 'confirm'. If this flag is found for a
key, each use of the key will pop up a pinentry to confirm the use
of that key. The flag is automatically set if a new key was loaded
into 'gpg-agent' using the option '-c' of the 'ssh-add' command.
The keygrip may be prefixed with a '!' to disable an entry.
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.
# Key added on: 2011-07-20 20:38:46
# Fingerprint: 5e:8d:c4:ad:e7:af:6e:27:8a:d6:13:e4:79:ad:0b:81
34B62F25E277CF13D3C6BCEBFD3F85D08F0A864B 0 confirm
'private-keys-v1.d/'
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 'key'. You should backup all files in this
directory and take great care to keep this backup closed away.
Note that on larger installations, it is useful to put predefined
files into the directory '/etc/skel/.gnupg' so that newly created users
start up with a working configuration. For existing users the a small
helper script is provided to create these files (⇒addgnupghome).