File: gnupg.info,  Node: GPGSM Configuration,  Next: GPGSM Examples,  Prev: GPGSM Options,  Up: Invoking GPGSM

5.3 Configuration files
=======================

There are a few configuration files to control certain aspects of
'gpgsm''s operation.  Unless noted, they are expected in the current
home directory (*note option --homedir::).

'gpgsm.conf'
     This is the standard configuration file read by 'gpgsm' 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 default
     name may be changed on the command line (*note gpgsm-option
     --options::).  You should backup this file.

'common.conf'
     This is an optional configuration file read by 'gpgsm' on startup.
     It may contain options pertaining to all components of GnuPG. Its
     current main use is for the "use-keyboxd" option.

'policies.txt'
     This is a list of allowed CA policies.  This file should list the
     object identifiers of the policies line by line.  Empty lines and
     lines starting with a hash mark are ignored.  Policies missing in
     this file and not marked as critical in the certificate will print
     only a warning; certificates with policies marked as critical and
     not listed in this file will fail the signature verification.  You
     should backup this file.

     For example, to allow only the policy 2.289.9.9, the file should
     look like this:

          # Allowed policies
          2.289.9.9

'qualified.txt'
     This is the legacy method to mark root certificates as usable for
     qualified certificates.  Qualified certificates are capable of
     creating legally binding signatures in the same way as handwritten
     signatures.  The modern method to mark such root certificates is to
     use the "qual" flag in the system trustlist.txt; see the gpg-agent
     man page for details.

     Comments int his file start with a hash mark and empty lines are
     ignored.  Lines do have a length limit but this is not a serious
     limitation as the format of the entries is fixed and checked by
     'gpgsm': A non-comment line starts with optional whitespace,
     followed by exactly 40 hex characters, white space and a lowercased
     2 letter country code.  Additional data delimited with by a white
     space is current ignored but might late be used for other purposes.

     Note that even if a certificate is listed in this file, this does
     not mean that the certificate is trusted; in general the
     certificates listed in this file need to be listed also in
     'trustlist.txt'.  This is a global file an installed in the sysconf
     directory (e.g.  '/usr/local/etc/gnupg/qualified.txt').

     Every time 'gpgsm' uses a certificate for signing or verification
     this file will be consulted to check whether the certificate under
     question has ultimately been issued by one of these CAs.  If this
     is the case the user will be informed that the verified signature
     represents a legally binding ("qualified") signature.  When
     creating a signature using such a certificate an extra prompt will
     be issued to let the user confirm that such a legally binding
     signature shall really be created.

     Because this software has not yet been approved for use with such
     certificates, appropriate notices will be shown to indicate this
     fact.

'help.txt'
     This is plain text file with a few help entries used with
     'pinentry' as well as a large list of help items for 'gpg' and
     'gpgsm'.  The standard file has English help texts; to install
     localized versions use filenames like 'help.LL.txt' with LL
     denoting the locale.  GnuPG comes with a set of predefined help
     files in the data directory (e.g.
     '/usr/local/share/gnupg/gnupg/help.de.txt') and allows overriding
     of any help item by help files stored in the system configuration
     directory (e.g.  '/usr/local/etc/gnupg/help.de.txt').  For a
     reference of the help file's syntax, please see the installed
     'help.txt' file.

'com-certs.pem'
     This file is a collection of common certificates used to populated
     a newly created 'pubring.kbx'.  An administrator may replace this
     file with a custom one.  The format is a concatenation of PEM
     encoded X.509 certificates.  This global file is installed in the
     data directory (e.g.  '/usr/local/share/gnupg/com-certs.pem').

   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 a small
helper script is provided to create these files (*note addgnupghome::).

   For internal purposes 'gpgsm' creates and maintains a few other
files; they all live in the current home directory (*note option
--homedir::).  Only 'gpgsm' may modify these files.

'pubring.kbx'
     This a database file storing the certificates as well as meta
     information.  For debugging purposes the tool 'kbxutil' may be used
     to show the internal structure of this file.  You should backup
     this file.

'random_seed'
     This content of this file is used to maintain the internal state of
     the random number generator across invocations.  The same file is
     used by other programs of this software too.

'S.gpg-agent'
     If this file exists 'gpgsm' will first try to connect to this
     socket for accessing 'gpg-agent' before starting a new 'gpg-agent'
     instance.  Under Windows this socket (which in reality be a plain
     file describing a regular TCP listening port) is the standard way
     of connecting the 'gpg-agent'.