Utimaco CryptoServer

The Utimaco PKCS11 module have 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 may be way too short if your CA is not very active. We recommend that you set this timeout to a longer value, several days.  Put a configuration file in /etc/utimaco/cs2_pkcs11.ini: 

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

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

The timeout in this example of 172800 seconds will allow your CA to idle for a long time.

When using a PKCS#11 token you should first create keys with the command: $EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate

Each CA should have its own slot.

Each slot must have been initialized before keys could be generated on the them. This includes setting a user PIN for it. The slot must also require login. Tools for doing this is not provided from EJBCA. The HSM vendor should provide this tool.

Here follows an example on how to initialize a slot and generate keys to be used by EJBCA. The password is user1:

./p11tool Slot=1 InitToken=officer1
./p11tool Slot=1 Label=CVCA LoginSO=officer1 InitPin=user1
$EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate ./libcs2_pkcs11.so 4096 signKey 1
PKCS11 Token [SunPKCS11-libcs2_pkcs11.so-slot1] Password:
Creating certificate with entry signKey.
$EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate ./libcs2_pkcs11.so 2048 defaultKey 1
PKCS11 Token [SunPKCS11-libcs2_pkcs11.so-slot1] Password:
Creating certificate with entry defaultKey.
$EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate ./libcs2_pkcs11.so 512 testKey 1
PKCS11 Token [SunPKCS11-libcs2_pkcs11.so-slot1] Password:
Creating certificate with entry testKey. 

You can view the pkcs11 objects created with the command:

./p11tool Slot=1 Login=user1 ListObjects 

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

defaultKey defaultKey
certSignKey signKey
crlSignKey signKey
testKey testKey
pin user1
sharedLibrary /opt/utimaco/p11/libcs2_pkcs11.so
slotLabelType=SLOT_NUMBER
slotLabelValue=1

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:

./csadm Device=TCP:3001@172.16.175.128 GetState

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:

[Global]
Logging = 5
Logpath = /log/TEST
Logsize = 100000000
CommandTimeout = 60000
ConnectionTimeout = 10000
KeepAlive = TRUE
[CryptoServer]
Device = {TCP:288@123.123.123.123 TCP:288@123.123.123.123}
SlotCount = 100
SlotMultiSession = FALSE