Defining an EP11 token-specific configuration file

One default configuration file for the EP11 token called ep11tok.conf is delivered by openCryptoki. You must adapt it according to your installation's system environment. If you use multiple EP11 tokens, you must provide an individual token configuration file for each token. Each slot entry in the global configuration file opencryptoki.conf defines these configuration file names.

In the example from Figure 1, these names are defined as ep11tok01.conf and ep11tok02.conf. If the environment variable OCK_EP11_TOKEN_DIR is set, then the EP11 token looks for the configuration file or files in the directory specified with this variable. If OCK_EP11_TOKEN_DIR is not set, then the EP11 token configuration files are searched in the global openCryptoki directory, for example: /etc/opencryptoki/ep11tok.conf.

export OCK_EP11_TOKEN_DIR=/home/user/ep11token

<root>/home/user/ep11token/ep11tok02.conf 

The following is a list of available options for an EP11 token configuration file.

APQN_WHITELIST

Because different EP11 hardware security modules (HSM) can use different wrapping keys (referred to as master keys in the TKE environment), users need to specify which HSM, in practice an adapter/domain pair, can be used by the EP11 token as a target for cryptographic requests. Therefore, an EP11 token configuration file contains a list of adapter/domain pairs to be used.

You start this list of adapter/domain pairs starting with a line containing the keyword APQN_WHITELIST. Next follows the list which can specify up to 512 adapter/domain pairs, denoted by decimal numbers in the range 0 - 255. Each pair designates an adapter (first number) and a domain (second number) accessible to the EP11 token. Close the list using the keyword END.

Alternatively, you can use the keyword APQN_ANY to define that all adapter/domain pairs with EP11 firmware, that are available to the system, can be used as target adapters. This is the default.

Notes:

• The term APQN stands for adjunct processor queue number. It designates the combination of a cryptographic coprocessor (adapter) and a domain, a so-called adapter/domain pair. At least one adapter/domain pair must be specified.
• If more than one APQN is used by a token, then these APQNs must be configured with the same master key.

An adapter/domain pair is displayed by the lszcrypt tool or in the sys file system (for example, in /sys/bus/ap/devices) in the form card .domain, where both numbers are displayed in hexadecimal format.

There are two ways to specify the cryptographic adapter:

• either as an explicit list of adapter/domain pairs:

  
   APQN_WHITELIST
    8 13
    10 13
   END

  The adapter and domain can be given in decimal, octal (with leading 0), or hexadecimal (with leading 0x) notation:

  
   APQN_WHITELIST
    8 0x0d
    0x0a 13
   END

  Valid adapter and domain values are in the range 0 to 255.

• or as any available cryptographic adapters:

  APQN_ANY

In the example from Figure 2, adapter 0 with domains 0 and 1, and adapter 2 with domain 84 are specified as target for requests from the EP11 token. In Figure 1, these adapter/domain pairs are shown in hexadecimal notation as APQNs (00,0000), (00,0001), and (02,0054).

FORCE_SENSITIVE

Specify this option to force that the default for CKA_SENSITIVE is CK_TRUE for secret keys. For more information, see Restrictions with using the EP11 library functions.

STRICT_MODE

In strict-mode, all session-keys strictly belong to the PKCS #11 session that created it. When the PKCS #11 session ends, all session keys created for this session can no longer be used.

For more information, read Controlling access to cryptographic objects.

VHSM_MODE

In VHSM-mode (virtual-HSM), all keys generated by the EP11 token strictly belong to the EP11 token that created it. Every EP11 token running in this mode requires a VHSM card-PIN which must be set using the pkcsep11_session tool.

For more information, read Controlling access to cryptographic objects and Managing EP11 sessions with the pkcsep11_session tool.

CPFILTER

The list of mechanisms returned by C_GetMechanismList is filtered using the domain or access control point (ACP) settings of the used cryptographic coprocessors. The EP11 access control point filter configuration file (ACP-filter configuration file) is used to associate certain access (domain) control points with mechanisms that are dependent on these access control points. The default ACP-filter configuration file is ep11cpfilter.conf located in the same directory as this EP11 token configuration file. You can optionally specify the name or location, or both, of the ACP-filter file:

CPFILTER /etc/opencryptoki/ep11cpfilter.conf

For more information, read Filtering mechanisms.

OPTIMIZE_SINGLE_PART_OPERATIONS

Set this option to optimize the performance of single part sign- and verify-operations, as well as of single part encrypt- or decrypt-operations. Then the init call is not passed through the EP11 library as long as there is no corresponding multi-part operation.

When this option is enabled, error handling can be slightly different, when errors from the deferred init call are presented during the first update call or during the calls to C_Sign, C_Verify, C_Encrypt, or C_Decrypt for a single part operation. That is, the first update call on a multi part operation or the mentioned calls for a single part operation may return errors, which are usually not returned by the update call. Such errors may be for example:

• CKR_OBJECT_HANDLE_INVALID
• CKR_ATTRIBUTE_VALUE_INVALID
• CKR_KEY_HANDLE_INVALID
• CKR_KEY_SIZE_RANGE
• CKR_KEY_TYPE_INCONSISTENT
• CKR_MECHANISM_INVALID
• CKR_MECHANISM_PARAM_INVALID

DIGEST_LIBICA <libica-path> | DEFAULT | OFF

To improve the performance of required hash functions, the EP11 token on initialization loads the default libica library. If required, the EP11 token invokes the libica SHA-based hash functions, because the libica library performs these hash functions on the CPACF, thus avoiding hash processing on a cryptographic coprocessor which results in I/O operations to the adapter.

libica provides an OpenSSL based software fall-back, in case CPACF or a certain hashing function of CPACF is not available. In case a libica operation fails, because neither the hardware nor the software support is available, or if libica is not available at all, then the request is passed to the EP11 library instead.

With the DIGEST_LIBICA option, you can control which libica library is loaded:

DEFAULT

The default libica library is loaded. If libica could not be found, a message is issued to syslog, and all hash based functions will use the EP11 library.

The same behavior is applied if the DIGEST_LIBICA option is not specified at all.

<libica-path>

The specified library is loaded. If it can not be found, a message is issued to syslog, and token initialization fails.

OFF

No libica is loaded, and all hash based functions use the EP11 library.

If DIGEST_LIBICA is not specified, then the default libica library is loaded (same behavior as for DIGEST_LIBICA DEFAULT).

USE_PRANDOM

Set this option to control from where the EP11 token reads random data. With USE_PRANDOM specified, the EP11 token reads random data from /dev/prandom, or from /dev/urandom if /dev/prandom is not available. The default is to read the random data using the m_GenerateRandom function from the Crypto Express EP11 coprocessor.

#
# EP11 token configuration
#
APQN_WHITELIST
0 0
0 1
2 84
END
FORCE_SENSITIVE
STRICT_MODE
VHSM_MODE
CPFILTER /etc/opencryptoki/ep11cpfilter.conf
OPTIMIZE_SINGLE_PART_OPERATIONS
DIGEST_LIBICA DEFAULT
USE_PRANDOM