Adjusting the openCryptoki configuration file

Edit online

A preconfigured list of all available tokens that are ready to register to the openCryptoki slot daemon is required before the slot daemon can start. This list is provided by the global configuration file called opencryptoki.conf. Read this topic for information on how to adapt this file according to your installation.

Table 1 lists the available libraries that may be in place after you successfully installed openCryptoki. It may vary for different distributions and is dependent from the installed packages.

Also, Linux® on IBM® Z and IBM LinuxONE do not support the Trusted Platform Module (TPM) token library.

A token is only available, if the token library is installed, and the appropriate software and hardware support pertaining to the stack of the token is also installed. For example, the EP11 token is only available if all parts of the EP11 host library software are installed and a Crypto Express EP11 coprocessor is detected. For more information, read Exploiting Enterprise PKCS #11 using openCryptoki.

A token needs not be available, even if the corresponding token library is installed. Display the list of available tokens by using the command:


$ pkcsconf -t

For a sample output, see Figure 1. Table 1 shows available openCryptoki libraries:

Table 1. openCryptoki libraries
Library	Explanation
/usr/lib64/opencryptoki/libopencryptoki.so	openCryptoki base library
/usr/lib64/opencryptoki/stdll/libpkcs11_ica.so	ICA token library
/usr/lib64/opencryptoki/stdll/libpkcs11_sw.so	Soft token library
/usr/lib64/opencryptoki/stdll/libpkcs11_tpm.so	TPM token library (not supported by Linux on IBM Z and IBM LinuxONE )
/usr/lib64/opencryptoki/stdll/libpkcs11_cca.so	CCA token library
/usr/lib64/opencryptoki/stdll/libpkcs11_ep11.so	EP11 token library
/usr/lib64/opencryptoki/stdll/libpkcs11_icsf.so	ICSF token library

libopencryptoki.so is the openCryptoki shared base library. The main API for the STDLLs PKCS11_API.so (mentioned in Architecture and components of openCryptoki) is a link, or an alias. Besides the token library, an application needs to load either the libopencryptoki.so object or the PKCS11_API.so link to be able to exploit a token.

lrwxrwxrwx 1 root root     18 May 19 20:05 PKCS11_API.so -> libopencryptoki.so

The /etc/opencryptoki/opencryptoki.conf file must exist and it must contain an entry for each instance of a token to make these instances available (see the provided sample configuration from Figure 1).

You can check the current default opencryptoki.conf file on this URL:

https://github.com/opencryptoki/opencryptoki/blob/master/usr/sbin/pkcsslotd/opencryptoki.conf

Figure 1. Default opencryptoki.conf


version opencryptoki-3.22

# The following defaults are defined:
#       hwversion = "0.0"
#       firmwareversion = "0.0"
#       description = Linux
#       manufacturer = IBM
#
# The slot definitions below may be overridden and/or customized.
# For example:
#       slot 0
#       {
#          stdll = libpkcs11_cca.so
#          description = "OCK CCA Token"
#          manufacturer = "MyCompany Inc."
#          hwversion = "2.32"
#          firmwareversion = "1.0"
#       }
# See man(5) opencryptoki.conf for further information.
#

disable-event-support                    # not part of the default config file 
statistics (on,implicit,internal)        # not part of the default config file  

slot 0
{
stdll = libpkcs11_tpm.so
tokversion = 3.12
}

slot 1
{
stdll = libpkcs11_ica.so
tokversion = 3.12
}

slot 2
{
stdll = libpkcs11_cca.so
confname = ccatok.conf
tokversion = 3.12
}

slot 3
{
stdll = libpkcs11_sw.so
tokversion = 3.12
}

slot 4
{
stdll = libpkcs11_ep11.so
confname = ep11tok.conf
tokversion = 3.12
}

Note:

The standard path for slot token dynamic link libraries (STDLLs) is: /usr/lib64/opencryptoki/stdll/ see Table 1). These paths may be distribution-specific.
The standard path for the token-specific configuration file (in our example, ep11tok.conf) is /etc/opencryptoki/.

You can specify multiple tokens of any type in different slots. Each token must be specified with a unique token name in each slot. The tokens are located in different file paths in the token directory, but use the same STDLL. For example:


slot 4
{
stdll = libpkcs11_ep11.so
confname = ep11tok01.conf
tokname = ep11token01
description = "Ep11 Token"
manufacturer = "IBM"
hwversion = "4.11"
firmwareversion = "2.0"
}

slot 5
{
stdll = libpkcs11_ep11.so
confname = ep11tok02.conf
tokname = ep11token02
}

Event notification support

You can enable openCryptoki to deliver notifications about a cryptographic external event to active token instances. External events are for example configuration changes of a cryptographic coprocessor (APQNs becoming available or unavailable), events initiated by an openCryptoki administrator via a command line tool, or HSM master key changes.

Events are delivered to all active token instances. Each process using openCryptoki has access to a set of instances of the configured tokens. Multiple processes that use openCryptoki can exist in a system. Thus, events are delivered to all processes that currently use openCryptoki, and thus to all token instances owned by each of the processes.

Event notification support is enabled by default. You can disable this support by specifying keyword disable-event-support in the openCryptoki configuration file as shown in Figure 1.

Collecting statistics

You can enable or disable the collection of statistics about mechanism usage in the openCryptoki configuration file at /etc/opencryptoki/opencryptoki.conf. Use the following option (see Figure 1):

statistics (off|on[,implicit][,internal])

By default, statistics collection is enabled. A value of (off) disables all statistics collection. A value of (on) enables collection of mechanism usage. The collected statistics can be displayed using the pkcsstats utility (see Displaying usage statistics - pkcsstats utility).

In addition to enabling statistics collection for mechanisms used by PKCS #11 applications, you can specify to also enable collection of implicit mechanism usage, where additional mechanisms are specified in mechanism parameters. For example, RSA-PSS or RSA-OAEP allow to specify a hash mechanism and a mask generation function (MGF) in the mechanism parameter. ECDH allows to specify a key derivation function (KDF) in the mechanism parameter. For this purpose, use the option statistics (on,implicit). By default only explicit mechanism usage statistics from PKCS #11 applications are collected.

You can additionally enable statistics collection of mechanisms internally used by openCryptoki by specifying (on,internal). This option additionally collects usage statistics for cryptographic operations used internally for PIN handling and encryption of private token objects in the data store. You can also combine implicit and internal statistics collection: (on,implicit,internal).

Collecting statistics can be a preparation step for enabling a policy (see Supporting cryptographic policies for openCryptoki). With statistics you can see which mechanism or key strengths would be rejected by a policy, even before the policy is made active. Look for all mechanisms and key strengths that a planned policy will not allow and make sure that the corresponding usage counters are zero.

Note: Implicit or internal mechanism usage can not be distinguished from explicit mechanism usage of PKCS #11 applications in the statistics displayed by the pkcsstats utility.