Skip to main content
Skip table of contents

Utimaco CryptoServer CP5

EIDAS This is an EJBCA eIDAS feature.

The Utimaco CryptoServer CP5 is Common Criteria-certified according to the eIDAS Protection Profile (PP) EN 419 221-5 “Cryptographic Module for Trust Services”.

Configuration

The following sections cover information on configuring the Utimaco CryptoServer CP5.

HSM Authentication Key

The HSM Authentication Key, short HSMAuthKey, is used by the CryptoServer CP5 to authenticate itself to a user in the initialization phase of a Secure Messaging session (secure channel). You need to retrieve the public part of the HSM authentication key using the command csadm GetHSMAuthKey and export the key into a text file named <serial number>.key. The environment variable CS_AUTH_KEYS must be set up to point to the serial number key file. This file may contain multiple entries separated by a blank line, for example if a CryptoServer CP5 cluster is deployed.

CODE
csadm GetHSMAuthKey > /opt/utimaco/auth/cs0000.key
echo 'export CS_AUTH_KEYS=/opt/utimaco/auth/cs0000.key' >> ~/.bashrc
source ~/.bashrc

Make sure to export the environment "CS_AUTH_KEYS" to web application systemd service.

Configuration File

The CryptoServer PKCS#11 configuration file cs_pkcs11_R2.cfg should be copied to /etc/utimaco/cs_pkcs11_R2.cfg.

Open the configuration file /etc/utimaco/cs_pkcs11_R2.cfg with a text editor and update the "SlotMultiSession" parameter according to the following example. Optionally logging level, log output path and timeouts may be modified as well.

[Global]
Logpath = /tmp
Logging = 0
Logsize = 10mb
RandomizeKeyHandles = false
SlotMultiSession = false
SlotCount = 10
KeepLeadZeros = false
FallbackInterval = 0
KeepAlive = false
ConnectionTimeout = 5000
CommandTimeout = 60000

[CryptoServer]
Device = TCP:3001@172.16.175.128

Generating Keys

When using a PKCS#11 CP5 token, first create keys using the following P11Ng CLI command:

CODE
$EJBCA_HOME/dist/p11ng-cli/p11ng-cli.sh generatekeypair

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, generating and associating a "Key Authorization Key" with each HSM key and authorizing usage. Initilizing the slot with the first two p11tool2 command will create the HSM user USR_0000 used in later commands. You can list users with 'csadm ListUsers', refer to the CryptoServerCP5_Manual for more information.

BASH
./p11tool2 Slot=0 Label=RootCA Login=ADMIN,/opt/utimaco/ADMIN.key InitToken=officer1
./p11tool2 Slot=0 LoginSO=officer1 InitPin=user1

$EJBCA_HOME/dist/p11ng-cli/p11ng-cli.sh generatekeypair --lib-file ./libcs_pkcs11_R2.so --slot-ref SLOT_INDEX --slot 0 --alias signKey --key-spec RSA2048 --key-usage SIGN
Enter slot login password:
Generated key pair with alias signKey
$EJBCA_HOME/dist/p11ng-cli/p11ng-cli.sh initializekey --lib-file ./libcs_pkcs11_R2.so --slot-ref SLOT_INDEX --slot 0 --alias signKey --user USR_0000 --padding-scheme PKCS1 --kak-size 2048 --kak-file-path ~/kak
Enter slot login password:
Successfully initialized the key on the HSM!
$EJBCA_HOME/dist/p11ng-cli/p11ng-cli.sh authorizekey --lib-file ./libcs_pkcs11_R2.so --slot-ref SLOT_INDEX --slot 0 --alias signKey --user USR_0000 --padding-scheme PKCS1 --kak-file-path ~/kak
Enter slot login password:
Successfully authorized the key on the HSM!

$EJBCA_HOME/dist/p11ng-cli/p11ng-cli.sh generatekeypair --lib-file ./libcs_pkcs11_R2.so --slot-ref SLOT_INDEX --slot 0 --alias defaultKey --key-spec RSA2048 --key-usage SIGN 
Enter slot login password: 
Generated key pair with alias defaultKey
$EJBCA_HOME/dist/p11ng-cli/p11ng-cli.sh initializekey --lib-file ./libcs_pkcs11_R2.so --slot-ref SLOT_INDEX --slot 0 --alias defaultKey --user USR_0000 --padding-scheme PKCS1 --kak-size 2048 --kak-file-path ~/kak
Enter slot login password:
Successfully initialized the key on the HSM!
$EJBCA_HOME/dist/p11ng-cli/p11ng-cli.sh authorizekey --lib-file ./libcs_pkcs11_R2.so --slot-ref SLOT_INDEX --slot 0 --alias defaultKey --user USR_0000 --padding-scheme PKCS1 --kak-file-path ~/kak
Enter slot login password:
Successfully authorized the key on the HSM!

$EJBCA_HOME/dist/p11ng-cli/p11ng-cli.sh generatekeypair --lib-file ./libcs_pkcs11_R2.so --slot-ref SLOT_INDEX --slot 0 --alias testKey --key-spec RSA2048 --key-usage SIGN
Enter slot login password:
Generated key pair with alias testKey
$EJBCA_HOME/dist/p11ng-cli/p11ng-cli.sh initializekey --lib-file ./libcs_pkcs11_R2.so --slot-ref SLOT_INDEX --slot 0 --alias testKey --user USR_0000 --padding-scheme PKCS1 --kak-size 2048 --kak-file-path ~/kak
Enter slot login password:
Successfully initialized the key on the HSM!
$EJBCA_HOME/dist/p11ng-cli/p11ng-cli.sh authorizekey --lib-file ./libcs_pkcs11_R2.so --slot-ref SLOT_INDEX --slot 0 --alias testKey --user USR_0000 --padding-scheme PKCS1 --kak-file-path ~/kak
Enter slot login password:
Successfully authorized the key on the HSM!

List Objects

To view the PKCS#11 objects created, run the following:

BASH
$EJBCA_HOME/dist/p11ng-cli/p11ng-cli.sh listobjects --lib-file ./libcs_pkcs11_R2.so --slot-ref SLOT_INDEX --slot 0

Example Properties

The following displays an example of the properties (catoken.properties) for the PKCS#11 token when creating a new CA using the CLI:

sharedLibrary /opt/utimaco/p11/libcs2_pkcs11.so
slotLabelType=SLOT_NUMBER
slotLabelValue=0
pin user1

defaultKey defaultKey
certSignKey signKey
crlSignKey signKey
testKey testKey

You can also create Crypto Tokens in the Admin UI, ensure that 'CS_AUTH_KEYS' are set for the running application server.

CryptoServer LAN Emulator

The Utimaco emulator for their CryptoServer LAN HSM can be used for test and development. If you have the emulation kit, refer to information in doc/howto/cryptoserver-lan-emulator.txt with instructions on using the emulator kit with EJBCA.

To check the status of a CryptoServer LAN device, run the emulator with a command according to the following example:

BASH
./csadm Device=TCP:3001@172.16.175.128 GetState
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.