Deploy for EJBCA

EJBCA communicates with the YubiHSM 2 via the PKCS#11 module, available as part of the YubiHSM 2 Shell software package.

For keys on the YubiHSM 2 to be accessible by EJBCA, each key has to exist as two objects: An asymmetric key object and an X509 object, both of them must be stored using the same Object ID. There are two ways to create such keys:

• Using YubiHSM 2 Setup Tool. Using this tool with the subcommand ejbca ensures that a generated asymmetric key and an X509Certificate are stored on the YubiHSM 2 with the same Object ID. Keys generated using this tool can be used, tested and removed using the functionality provided by EJBCA.

1. If you do not want to delete the authentication key after the operation is complete, use the --no-delete flag.
2. If you have an existing installation of EJBCA, the relevant crypto token must be deactivated then re-activated after new keys are generated.

• Using EJBCA Adminweb interface or ejbcaCientToolBox with YubiHSM 2 Shell 2.4 or higher. With newer versions, the PKCS#11 module creates an opaque object containing metadata that ensures that the X509Certificate can be accessed using the same Object ID as the asymmetric key. The PKCS#11 client does not need to be aware of the metadata object, however, it is visible if the contents of the YubiHSM 2 are listed using the command line tool yubihsm-shell.

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:

• YubiHSM 2 Shell
• YubiHSM 2 Connector if yubihsm_pkcs11 is configured to use the HTTP connector. See PKCS#11 for configuration guide.
• YubiHSM 2 Setup Tool if YubiHSM Shell version is older than 2.4 or if the usage of metadata objects is not desirable.

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. Generate the keys on the YubiHSM 2 using either ejbcaClientToolBox with YubiHSM 2 Shell 2.4 or higher or YubiHSM 2 Setup Tool.

1. When using YubiHSM 2 Setup Tool, if you do not want to delete the authentication key after the operation is complete, use the --no-delete flag.

3. Set the environment variable YUBIHSM_PKCS11_CONF to the path of the yubihsm_pkcs11.conf file in the same environment as the application server. See 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 in the same environment as the application server. See 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

3. Re-deploy EJBCA and restart the application server.
4. 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 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

4. Click Save. If there already are keys on the YubiHSM 2, a list of them is displayed now (only asymmetric keys with accompanying X509Certificates stored with the same ObjectID are displayed).

5. (Optional) On the command line, use the YubiHSM 2 Setup tool to generate keys on the YubiHSM 2, one at a time.

1. If you do not want to delete the authentication key after the operation is complete, use the --no-delete flag.
2. After creating the keys, deactivate and then re-activate the Crypto Token created in step 4 in EJBCA Adminweb. The new keys on the YubiHSM 2 are now accessible and ready to be used.

Important

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

Important

YUBIHSM_PKCS11_CONF must be set in the same environment as the application server. After setting YUBIHSM_PKCS11_CONF or modifying yubihsm_pkcs11.conf content, the application server must be restarted.