The following sections provide information on the Utimaco CryptoServer.

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:

$EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate
CODE

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.

./p11tool Slot=1 InitToken=sopassword123
./p11tool Slot=1 Label=CVCA LoginSO=sopassword123 InitPin=userpassword123
BASH

The following displays an example for generating keys on a slot using the password is user1, using the Java PKCS#11 provider:

$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.
BASH

Or with P11NG, where you can use additional algorithms:

$./p11ng-cli.sh generatekeypair --lib-file /etc/utimaco/libcs_pkcs11_R3.so --slot-ref SLOT_NUMBER --slot 0 --alias ec1 --key-spec P-256
Enter slot login password: 
Generated key pair with alias ec1
$./p11ng-cli.sh generatekeypair --lib-file /etc/utimaco/libcs_pkcs11_R3.so --slot-ref SLOT_NUMBER --slot 0 --alias ed1 --key-spec Ed25519
Enter slot login password: 
Generated key pair with alias ed1
./p11ng-cli.sh generatekeypair --lib-file /etc/utimaco/libcs_pkcs11_R3.so --slot-ref SLOT_NUMBER --slot 0 --alias rsa1 --key-spec RSA2048
Enter slot login password: 
Generated key pair with alias rsa1
BASH

You can test the keys with P11NG as well:

$./p11ng-cli.sh signperformancetest --lib-file /etc/utimaco/libcs_pkcs11_R3.so --slot 0 --alias ed1 --time-limit 1000 --signature-algorithm Ed25519 --password userpassword123
Running signing test with 1 threads using signature algorithm Ed25519.
Using cache for reading keys.
Starting thread 0
Number of operations for thread 0: 980
Total number of signings: 980
Signings per second: 831.2128922815946
$./p11ng-cli.sh signperformancetest --lib-file /etc/utimaco/libcs_pkcs11_R3.so --slot 0 --alias ec1 --time-limit 1000 --signature-algorithm SHA256WithECDSA --password userpassword123
Running signing test with 1 threads using signature algorithm SHA256WithECDSA.
Using cache for reading keys.
Starting thread 0
Number of operations for thread 0: 1113
Total number of signings: 1113
Signings per second: 790.4829545454546
BASH

You can view the PKCS11 objects created with the HSM command:

./p11tool Slot=1 Login=userpassword123 ListObjects 
BASH

This is a example of a property field when creating a CA using the CLI, the easier way is to use the Admin UI of course:

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

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
BASH

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
CODE

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.

Note that, whenever there is a key generation or renewal procedure, for example, renewing the private key of a CA, this sequence of action needs to be repeated. This allows a standalone HSM to generate the key material and then safely transfer it to other HSMs during synchronization. Hence fall back to the standalone mode of operation before the key generation or renewal operation, and then repeat steps 2 to 4.

The reason for this is that when a key is opened (which includes the creation of a key) in PKCS#11, the key is retrieved as an external blob to be able to switch to a different node in case of a failover (Store::getInternalObject). Although C_SetAttributeValue reopens a key, it also uses this function and, thus, works on the external blob and changes the attribute only there and not on the HSM.