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 list of root certificates used for qualified
     certificates.  They are defined as certificates capable of creating
     legally binding signatures in the same way as handwritten
     signatures are.  Comments 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'.