File: gnupg.info,  Node: Agent Configuration,  Next: Agent Signals,  Prev: Agent Options,  Up: Invoking GPG-AGENT

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
(*note 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 (*note 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 *note
     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.
     '/usr/local/etc/gnupg/trustlist.txt').  This global list is also
     used if the local list is not available; the *note option
     --no-user-trustlist:: enforces the use of only this global list.

     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.

     'qual'
          The CA is allowed to issue certificates for qualified
          signatures.  This flag has an effect only if used in the
          global list.  This is now the preferred way to mark such CA;
          the old way of having a separate file 'qualified.txt' is still
          supported.

     'de-vs'
          The CA is part of an approved PKI for the German
          classification level VS-NfD. It is only valid in the global
          trustlist.  As of now this is used only for documentation
          purpose.

'sshcontrol'
     This file is used when support for the secure shell agent protocol
     has been enabled (*note option --enable-ssh-support::).  Only keys
     present in this file are used in the SSH protocol.  You should
     backup this file.

     This file is deprecated in favor of the "Use-for-ssh" attribute in
     the key files.

     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 '/usr/local/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 (*note
addgnupghome::).