Adding tokens to openCryptoki

Edit online

You can introduce one or multiple token instances of any type into the openCryptoki framework. For this purpose, you must define a slot entry for each desired token instance in the global openCryptoki configuration file called opencryptoki.conf.

Note: For CCA tokens and EP11 tokens, you can configure each token instance differently using a token-specific configuration file (CCA token configuration file or EP11 token configuration file, specified with the confname option, see Defining a CCA token configuration file or Defining an EP11 token configuration file).

With multiple tokens of a specific token type configured, you can assign dedicated adapters and domains to different tokens respectively. This ensures data isolation between multiple applications.

If you use multiple token instances of one certain token type, 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 token instance is separated from other token instances.

For example, the default EP11 token directory is /var/lib/opencryptoki/ep11tok/. You can use the default only for a single EP11 token. Examples for multiple token directories can be:


/var/lib/opencryptoki/ep11token01/
/var/lib/opencryptoki/ep11token02/
/var/lib/opencryptoki/ccatoken01/
/var/lib/opencryptoki/ccatoken02/

Note: A certain token type configuration applies to all applications that use tokens of this type.

Adding a slot entry for a token in opencryptoki.conf

The default openCryptoki configuration file opencryptoki.conf (see Figure 1) provides a slot entry for a CCA token, preconfigured to slot #2 and a slot entry for an EP11 token, preconfigured to slot #4. Each slot entry must set the stdll attribute to the appropriate slot token dynamic link library (STDLLs), for example, libpkcs11_ep11.so for an EP11 token.

You can check the entries in the default opencryptoki.conf file to find out whether you can use it as is.

For each configured EP11 token, you must create a specific token configuration file. For a CCA token, such a configuration file is optional. A default configuration file is shipped with openCryptoki for both token types. The default EP11 token configuration file is only valid if all APQNs assigned to the token are configured with the same master key. For the CCA token, the CCA adapter selected as default adapter must be configured with the desired master keys.

An EP11 token configuration file, for example, 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 for CCA and EP11 tokens must specify the name of the used token-specific configuration file (if applicable for a CCA token). For this purpose, for both token types, use the confname attribute with the unique name of the respective CCA token configuration file or EP11 token configuration file as value.

The example from Figure 1 configures two EP11 tokens in slots 4 and 5 in the openCryptoki configuration file. 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 3 shows an example of an EP11 token configuration file and Figure 1 shows an example of a CCA token configuration file.

Figure 1. Multiple CCA or EP11 token instances defined in the openCryptoki token configuration file

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

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


slot 6
  {
     stdll = libpkcs11_cca.so
     confname = ccatok01.conf
     tokname = ccatok01
     tokversion = 3.12
}

slot 7
  {
     stdll = libpkcs11_cca.so
     confname = ccatok02.conf
     tokname = ccatok02
     tokversion = 3.12
  }