Adding EP11 tokens to openCryptoki

Edit online

You need to introduce one or multiple tokens of type EP11 (EP11 tokens) into the openCryptoki library. For this purpose, you must define a slot entry for each desired token in the global openCryptoki configuration file called opencryptoki.conf.

If you want to configure multiple EP11 tokens, you can assign dedicated adapters and domains to different tokens respectively. This ensures data isolation between multiple applications.

If you use multiple EP11 tokens, you must specify a unique token directory in the slot entry for each token, using the tokname attribute. This token directory receives the token-individual information (like for example, key objects, user PIN, SO PIN, or hashes). Thus, the information for a certain EP11 token is separated from other EP11 tokens.

The default EP11 token directory is /var/lib/opencryptoki/ep11tok/. You can use the default only for a single EP11 token. Resulting examples for multiple EP11 token directories can be:


/var/lib/opencryptoki/ep11token1/
/var/lib/opencryptoki/ep11token2/

Note: A certain token configuration applies to all applications that use this EP11 token.

Adding a slot entry for each applicable EP11 token in opencryptoki.conf

As already mentioned, the default openCryptoki configuration file opencryptoki.conf provides a slot entry for the EP11 token. It is preconfigured to slot #4. Each slot entry must set the stdll attribute to libpkcs11_ep11.so. Check this default entry to find out whether you can use it as is.

For each configured EP11 token, you must create a specific EP11 token configuration file. This EP11-specific configuration file defines the target adapters and target adapter domains to which the EP11 token sends its cryptographic requests.

In turn, each slot entry in the global openCryptoki configuration file must specify this EP11 token configuration file. For this purpose, use the confname attribute with the unique name of the respective EP11 token configuration file as value.

The example from Figure 1 configures two EP11 tokens in slots 4 and 5. It defines the names of the specific token configuration files to be ep11tok01.conf and ep11tok02.conf. Per default, these files are searched in the directory where openCryptoki searches its global configuration file. Figure 2 shows an example of an EP11 token configuration file.

Figure 1. Multiple EP11 token instances

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 
}

Setting an option for a FIPS compliant token data format

Starting with openCryptoki version 3.12, you can optionally use only FIPS compliant operations for openCryptoki's login password hashing and for encrypting the stored token data. This is valid for EP11 tokens, libica tokens, CCA tokens and Soft Tokens. Being FIPS compliant, for a new token directory, the token data is stored in a format that is better protected against attacks than the previously used data format.

If you want to use the token data format that was generated with FIPS compliant operations, you must explicitly specify the tokversion option for the token's slot entry in the openCryptoki configuration file. You must do this before token initialization with the pkcsconf command, for example:

Figure 2. Slot entry for an EP11 token with FIPS compliant data format in the opencryptoki.conf file

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

You can use the pkcstok_migrate utility to transform an EP11 token, a CCA token, an ICA token, or a Soft Token created with any version of openCryptoki into a data format that was generated by FIPS compliant operations.

The pkcstok_migrate tool converts all token data produced with any openCryptoki version, including PINs, to be encrypted with a FIPS compliant method. Without this tool, switching to the new token format is only possible with an empty repository. The new FIPS compliant format can be used by specifying the tokversion keyword in the token’s slot configuration in opencryptoki.conf as shown in Figure 2. For a value of 3.12 or greater, the new format is used. Values lower than 3.12 are invalid. To ensure compatibility with key objects generated using older versions of openCryptoki, the old format is still the default. The new format is only used when the user explicitly adds the tokversion keyword to the opencryptoki.conf file.

For information on how to use this tool, see Migrating to FIPS compliance using the pkcstok_migrate tool.