Configuration File

The CryptoServer PKCS#11 configuration file cs2_pkcs11.ini should be copied to /etc/utimaco/cs2_pkcs11.ini.

Note that the Utimaco PKCS11 module has a configurable timeout (AppTimeout) that clears all session information if you do not use the keys for some time. The default time-out is 30 minutes, which is generally too low if your CA is not very active. We recommend increasing the timeout to, for example, 172800 seconds (2 days), allowing your CA to idle for an extended time.

Open the configuration file /etc/utimaco/cs2_pkcs11.ini with a text editor and update the AppTimeout parameter according to the following example:

[Global]
Timeout = 5000
Logging = 0
Logpath = /tmp

[CryptoServer]
Device     = TCP:3001@172.16.175.128
Timeout    = 600000
AppTimeout = 172800
SlotCount  = 100

Generating Keys

When using a PKCS#11 token, first create keys with the command:

Note that each CA should have its own slot and each slot must be initialized before keys can be generated. The initialization includes setting a user PIN for the slot, which also must require login. Tools for slot initialization should be provided by the HSM vendor and are not provided by PrimeKey.

The following displays an example for generating keys on a slot using the password is user1:

You can view the PKCS11 objects created with the command:

This is a example of a property field when creating the CA:

Utimaco have an emulator for their CryptoServer LAN HSM that can be used for test and development. If you have the emulation kit there is a howto in doc/howto/cryptoserver-lan-emulator.txt with steps to follow in order to use it with EJBCA.

You can check the status of a CryptoServer LAN device, for example the emulator with:

Import a PKCS#12 file in Utimaco CryptoServer

Although not recommended it is possible to import keys from a p12 file to CryptoServer. These steps were contributed by Philipp Vogt and Helmut Edlhaimb-Rexeis. The tools used are a combination of p11tool that ships with Utimaco HSMs and ejbcaClientToolBox.sh PKCS11HSMKeyTool.

• Import the .p12 file with p11Tool from Utimaco (into slot 20 in this example). p11tool Slot=22 AuthRSASign=GenPKIAd,:cs2:cyb:/dev/ttyS0 Login=123456 ID=TestCA2XYID ImportP12=mycert.p12,1234 It is absolutely necessary to set an unique id (ID=...) at import time. The key alias for the imported key is set to X509 Certificate (taken from the imported certificate) and cannot be change at import time.

• Rename the key alias to an unique key alias with PKCS11HSMKeyTool rename from ejbcaClientToolbox. ejbcaClientToolBox.sh PKCS11HSMKeyTool rename /etc/utimaco/libcs2_pkcs11.so 20 X509 Certificate TestCA2Key The new key alias is set to the label and the id of the CKO_CERTIFICATE and the id of the CKO_PRIVATE_KEY.

• Optional: Delete the public key with p11Tool using Label="RSA Public Key". p11tool Slot=20 Login=123456 Label="RSA Public Key" DeleteObject

• Test the keys, to make sure they are usable from EJBCA. ejbcaClientToolBox.sh PKCS11HSMKeyTool test ./libcs2_pkcs11.so 20 1

Make sure no other public keys using this label are present in the HSM. Even if more than one .p12 file needs to be imported only one at a time can be imported and renamed. The import and the rename process are tied together and cannot be separated.

Clustering

The Utimaco PKCS#11 driver has built in clustering capabilities for network attached HSMs. Primarily clustering works by configuring two (or more) HSM IP adresses, and if there are issues with the connection to the first HSM it fails over to the second. A pre-requisite is that the HSM contents are identical and that slots and authentication are the same.

You can also use the cluster configuration to a single HSM, causing a "fail over" (to the same HSM) if there is an intermittent network issue. This guards against PKCS#11 failures in Java so you don't have to restart EJBCA/Application server if there is a network glitch.

Example cluster configuration in the Utimaco configuration file:

In a clustered configuration with failover mode, all the HSMs need to have the necessary key material. Thus, the HSMs must be synchronized before the failover mode is enabled according to the following sequence of procedure:

1. Use the primary HSM standalone mode.

2. Generate all keys in the primary HSM.

3. Manual synchronization from primary HSM to all other HSMs (backup/restore).

4. Enable HSM failover mode.