EJBCA is the most popular open-sourced and enterprise-ready certification authority. It’s build on J2EE technology and scales well from small corporate installations to national PKIs with millions of issued certificates. Since version 6 it has a great UI to manage keys in a HSM.
EJBCA uses the SUN provider for accessing hardware security modules via the PKCS#11 interface. As the SmartCard-HSM supports PKCS#11 via sc-hsm-embedded and OpenSC, integrating with EJBCA is just a matter of adding the PKCS#11 module to EJBCA’s configuration.
Update Note 2024: There is an updated integration example available using Docker. This should work as well for local installations.
Creating the Crypto Token
Crypto Tokens in EJBCA are key containers that can be shared amongst multiple CAs or other services like OCSP. They can be a software keystore or a hardware keystore accessible via PKCS#11.
When you open the Administration page in EJBCA, then you should see Crypto Token in the CA Functions menu.
Click on Create new… and complete the following dialog. Authentication Code is the PIN you assigned to your SmartCard-HSM during initialization. The Slot ID is typically 1 for sc-hsm-pkcs11 and 0 for OpenSC.
If all goes well, then EJBCA should create a new crypto token bound to your SmartCard-HSM. In the following example 4 keys already stored on the device were recognized by EJBCA:
Using the Remove, Test and Generate new pair button you can manage keys on the device.
Please remember, that not all key types available in the drop-down are supported by the SmartCard-HSM. You can choose from
- RSA with 1536, 2048, 3072 or 4096 bit
- ECDSA with secp and Brainpool Curves
Troubleshooting
If things go wrong, please try the following to isolate the issue:
Enter
$ sc-hsm-tool
Using reader with a card: SCM SCR 355 [CCID Interface] 00 00
Version : 1.2
User PIN tries left : 3
to see if the PC/SC stack is working.
Try
$ pkcs11-tool --module /usr/local/lib/opensc-pkcs11.so -L
Available slots:
Slot 0 (0xffffffffffffffff): Virtual hotplug slot
(empty)
Slot 1 (0x1): SCM SCR 355 [CCID Interface] 00 00
token label : SmartCard-HSM (UserPIN)
token manufacturer : www.CardContact.de
token model : PKCS#15 emulated
token flags : rng, login required, PIN initialized, token initialized
hardware version : 24.13
firmware version : 1.2
serial num : UTTMRN08223
to see if the PKCS#11 module loads and find the attached SmartCard-HSM.
If you can not select PKCS11 als token type, please check if opensc-pkcs11.so was added to web.properties and is found by EJBCA (see the log for details).
If you are getting an error when creating the token, a good resource is the log generated by OpenSC:
To enable logging, start JBoss with
$ OPENSC_DEBUG=9 ./standalone.sh
You can also specify the debug level and debug file in /etc/opensc.conf. To make sure that opensc.conf is used start JBoss with
$ OPENSC_CONF=/etc/opensc.conf ./standalone.sh
If you experiencing stability issues (CKR_ARGUMENT_INVALID or SEGV), then those are most likely caused by a bug in OpenSC 0.14.
If you see a CKR_GENERAL_ERROR when deleting keys, then most likely a bug in the SmartCard-HSM driver is causing the problem.
The latest version of the OpenSC source has those patches integrated already.