4.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 (see option –homedir).
- 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 (see gpgsm-option –options).
You should backup this file.
- 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
For example, to allow only the policy 2.289.9.9, the file should look
# Allowed policies
- 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 character, 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
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 data directory
(e.g. /usr/share/gnupg/qualified.txt). GnuPG installs a suitable
file with root certificates as used in Germany. As new Root-CA
certificates may be issued over time, these entries may need to be
updated; new distributions of this software should come with an updated
list but it is still the responsibility of the Administrator to check
that this list is correct.
Everytime 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.
- 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/share/gnupg/help.de.txt)
and allows overriding of any help item by help files stored in the
system configuration directory (e.g. /etc/gnupg/help.de.txt).
For a reference of the help file's syntax, please see the installed
- 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
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 (see addgnupghome).
For internal purposes gpgsm creates and maintains a few other files;
they all live in in the current home directory (see option –homedir). Only gpgsm may modify these files.
- 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 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.
- If this file exists and the environment variable GPG_AGENT_INFO is
not set, 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.