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 OpenSC, integrating with EJBCA is just a matter of adding the PKCS#11 module to EJBCA’s configuration.

Want to give it a test drive ? Nothing easier than that - just follow the Ubuntu quick start guide, which should work for the majority of Linux distributions. You will also need to install OpenSC, either from the repository of your distribution or from source (the recommended way to get the latest and greatest).

Enabling PKCS#11

Before you can access the SmartCard-HSM, you need to configure two things:

To add the SmartCard-HSM and OpenSC to the list of recognized PKCS#11 modules, create a file web.properties in the conf directory of the EJBCA package.

The file must contain:

# Available PKCS#11 CryptoToken libraries and their display names
# If a library file's presence is not detected it will not show up in the Admin GUI.
# Default values (see src/java/defaultvalues.properties for most up to date values):
cryptotoken.p11.lib.60.name=SmartCard-HSM
cryptotoken.p11.lib.60.file=/usr/local/lib/opensc-pkcs11.so

You might need to adapt the path to your PKCS#11 library accordingly.

Restart JBoss and re-deploy EJBCA with

$ ant build deployear

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.

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 1024
  • RSA 1536
  • RSA 2048
  • ECDSA secp256r1 / prime256v1 / P-256

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.