Deploy for EJBCA

EJBCA and YubiHSM 2 work well together once suitable asymmetric keys have been generated on the YubiHSM 2. Even though the EJBCA Adminweb does provide functionality to generate keys on an HSM, this functionality cannot be used with YubiHSM 2. Instead, keys need to be generated using the YubiHSM 2 Setup Tool. Once the keys are generated, they can be used, tested and removed using the functionality provided by EJBCA.

When generating new keys on the YubiHSM 2 for use by an existing installation of EJBCA, the relevant crypto token must be reactivated before the new keys are accessible by EJBCA.

Note

A key alias on EJBCA is equivalent to a key label on the YubiHSM 2.

Prerequisites

Download the installation package suitable for the operation system from the Yubico Developers website. The following packages should be installed:

Configuring a New EJBCA Installation

While following the installation instructions provided by EJBCA, the instructions bellow need to be executed before deploying EJBCA for the first time:

  1. Decide how many keys to generate and what aliases they should have. See the documentation in EJBCA_HOME/conf/catoken.properties.sample for recommendation on what keys should be generated.
  2. Use the YubiHSM 2 Setup Tool to generate the keys on the YubiHSM 2, one at a time.
  3. Set the environment variable YUBIHSM_PKCS11_CONF to the path of the yubihsm_pkcs11.conf file. See Deploy for PKCS#11 for the content of that file.
  4. When configuring EJBCA, make sure to configure the following properties files:
  • EJBCA_HOME/conf/catoken.properties
sharedLibrary=/path/to/yubihsm_pkcs11.so
slotLabelType=SLOT_NUMBER
slotLabelValue=0
#Keys and their aliases as were created in step 2
  • EJBCA_HOME/conf/install.properties
ca.tokentype=org.cesecore.keys.token.PKCS11CryptoToken
#ca.tokenpassword=null
ca.tokenproperties=<EJBCA_HOME>/conf/catoken.properties
  • EJBCA_HOME/conf/web.properties
cryptotoken.p11.lib.255.name=<label to identify the YubiHSM 2>
cryptotoken.p11.lib.255.file=/path/to/yubihsm_pkcs11.so

Note

The number 255 is just an example. It can be any “available” number. See documentation in EJBCA_HOME/conf/web.properties.

Configuring an Existing EJBCA Installation

  1. Set the environment variable YUBIHSM_PKCS11_CONF to the path of the yubihsm_pkcs11.conf file. See Deploy for PKCS#11 for the content of that file.
  2. Configure EJBCA_HOME/conf/web.properties as follows (255 is just an example, read the documentation in the file for more details):
cryptotoken.p11.lib.255.name=<label to identify the YubiHSM 2>
cryptotoken.p11.lib.255.file=/path/to/yubihsm_pkcs11.so
  1. Re-deploy EJBCA and restart the application server.
  2. On EJBCA Adminweb, create a new CryptoToken:
  1. Go to CA Functions > Crypto Tokens.
  2. Click on Create new….
  3. Configure the new CryptoToken as follows:
  • Name: <name for this crypto token>
  • Type: PKCS#11
  • Authentication Code: <password to open a session on the YubiHSM 2. See Deploy for PKCS#11 > Logging In.
  • PKCS#11 Library: <from the drop down menu, choose the label you set in step 2.>
  • PKCS#11 Reference Type: Slot ID
  • PKCS#11 Reference: 0
  • PKCS#11 Attribute File: Default
  1. Click Save. If there already are keys on the YubiHSM 2, a list of them is displayed now (only keys created with the YubiHSM 2 Setup tool are displayed).
  1. On the command line, use the YubiHSM 2 Setup tool to generate keys on the YubiHSM 2, one at a time.
  2. On EJBCA Adminweb, deactivate and then re-activate the Crypto Token created in step 4. The new keys on the YubiHSM 2 are now ready to be used.

Important

The slot number of the shared PKCS#11 library must be 0.