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.
- If you do not want to delete the authentication key after the operation is complete, use the
--no-delete
flag. - 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 toolyubihsm-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:
- 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. - Generate the keys on the YubiHSM 2 using either
ejbcaClientToolBox
with YubiHSM 2 Shell 2.4 or higher or YubiHSM 2 Setup Tool.
- 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.
- Set the environment variable
YUBIHSM_PKCS11_CONF
to the path of theyubihsm_pkcs11.conf
file in the same environment as the application server. See PKCS#11 for the content of that file. - 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
- Set the environment variable
YUBIHSM_PKCS11_CONF
to the path of theyubihsm_pkcs11.conf
file in the same environment as the application server. See PKCS#11 for the content of that file. - 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
- Re-deploy EJBCA and restart the application server.
- On EJBCA Adminweb, create a new CryptoToken:
- Go to CA Functions > Crypto Tokens.
- Click on Create new….
- 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
- 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).
- (Optional) On the command line, use the YubiHSM 2 Setup tool to generate keys on the YubiHSM 2, one at a time.
- If you do not want to delete the authentication key after the operation is complete, use the
--no-delete
flag. - 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.