In order for multiple applications on the user's desktop to use PKCS#11 modules in a consistent manner, there must be a configuration or registry to specify which modules to load and how to use them. The PKCS#11 specification does not specify such a configuration standard. Because of the multi-library module initialization problem, use of PKCS#11 modules must be coordinated within an application. p11-kit provides that coordination. Since coordination is required, it follows that p11-kit can also implement a consistent module configuration.

The following sections describe the config format in detail. But first an example which shows the various features. The configuration below, loads two modules called 'my-module' and 'nss'. The user settings override some aspects of the system settings. Global configuration file: /etc/pkcs11/pkcs11.conf # This setting controls whether to load user configuration from the # ~/.pkcs11 directory. Possible values: # none: No user configuration (default) # merge: Merge the user configuration over the system configuration # only: Only user configuration, ignore system configuration user-config: merge One module configuration file per module: /etc/pkcs11/modules/my-module # This setting controls the actual module library to load. This config file might # be installed by the package that installs this module library. module: /usr/lib/my-pkcs11-module.so User configuration file: ~/.pkcs11/pkcs11.conf # This is an empty file. Files that do not exist are treated as empty. User configuration file: ~/.pkcs11/modules/my-module # Merge with the settings in the system my-module config file. In this case # a developer has overridden to load a different module for my-module instead. module: /home/user/src/custom-module/my-module.so User configuration file: ~/.pkcs11/modules/nss # Load the NSS libsoftokn.so.3 PKCS#11 library as a module. Note that we pass # some custom non-standard initialization arguments, as NSS expects. module: /usr/lib/libsoftokn3.so x-init-reserved: configdir='sql:/home/test/.pki/nssdb' certPrefix='' keyPrefix='' secmod='socmod.db'

A complete configuration consists of several files. These files are text files. Since p11-kit is built to be used in all sorts of environments and at very low levels of the software stack, we cannot make use of high level configuration APIs that you may find on a modern desktop. Each setting in the config file is specified consists of a name and a value. The name is a simple string consisting of characters and dashes. The name consists of alpha numeric characters, dot, hyphen and underscore. The value is specified after the name on the same line, separated from it by a : (colon). White space between the name and value is ignored. Blank lines are ignored. White space at the beginning or end of lines is stripped. Lines that begin with a # character are ignored as comments. Comments are not recognized when they come after a value on a line. A fictitious sample configuration file might look like: name:value # Here is a comment setting.2: A long value with text. x-custom : text

Each configured PKCS#11 module has its own config file. The location(s) of these files are described below. Most importantly each config file specifies the location of the PKCS#11 module to load. Each module config file has the following fields: module: The absolute path to the PKCS#11 module to load. This should include an extension like .so Other fields may be present, but it is recommended that field names that are not specified in this document start with a x- prefix.

A global configuration is also present. This file contains settings that are not related to a single PKCS#11 module. The location(s) of the global configuration are described below. The global configuration file can contain the following fields: user-config: This will be equal to one of the following values: none, merge, only. Other fields may be present, but it is recommended that field names that are not specified in this document start with a x- prefix.

Each configured PKCS#11 module is has its own config file. These files are placed in a directory. In addition a global config file exists. There is a system configuration consisting of the various module config files and a file for global configuration. Optionally each user can provide additional configuration or override the system configuration. The system global configuration file is in /etc/pkcs11/pkcs11.conf and the user global configuration file is in ~/.pkcs11/pkcs11.conf in the user's home directory. The module config files are located in the /etc/pkcs11/modules directory, with one configuration file per module. In addition the ~/.pkcs11/modules directory can be used for modules installed by the user.