Managing Crypto Tokens

A Cryptographic Token in EJBCA is where keys are stored. A Crypto Token can be either backed by a soft keystore (file in the database) or an HSM PKCS#11 slot.

The EJBCA Admin GUI menu option Crypto Tokens displays all the Crypto Token related management and Crypto Tokens can also be activated from the CA Activation page.

There is also a CLI for all the functionality available in the Admin GUI. To list available sub-commands, run:

bin/ejbca.sh cryptotoken

New Crypto Tokens

Create a new Crypto Token using the following fields:

Crypto Token

Description

Name

A user-friendly name for the Crypto Token.

Type

PKCS#11 HSM slot mapping or a Soft PKCS#12 keystore in the database.

Authentication Code

The PKCS#11 slot PIN or the password that will protect the soft keystore.

Repeat Authentication Code

Should be the same as the previous field.

Auto-activation

If the authentication code should be stored (encrypted) in the database and used to always keep the Crypto Token active.

Allow export of private keys

EJBCA will not try to prevent Soft Crypto Token keystore export if this box is checked.

If you select to use Type PKCS#11 Crypto Token, the following additional fields are displayed. Note that PKCS#11 may require additional configuration of your app server, see the EJBCA Main Installation section.

Additional field

Description

PKCS#11 Library

PKCS#11 shared library configured as available in conf/web.properties.

PKCS#11 Reference Type

The type of a slot reference that is described by the next parameter (Id, Index or Label).

PKCS#11 Reference

PKCS#11 slot number, index or label.

PCKS#11 Attribute File

If required, this is a PKCS#11 attribute file configured as available in conf/web.properties. This should only be required for non common HSMs.

For more information on the PKCS#11 properties, see Hardware Security Modules (HSM) section. A unique Crypto Token identifier will be generated when the token is created.

In EJBCA Enterprise Edition, it is also possible to create new Crypto Tokens using the WS API call createCryptoToken in your application or with the Web Service Interface.

View or Edit a Crypto Token

The view is very similar to the creation of a token except for showing the ID and activation status. It is not possible to change the Crypto Token ID or Type or to edit the authentication code of soft Crypto Tokens.

Activation and Deactivation

The following actions are available in the Crypto Token list:

Action

Description

Activate

Enter a authentication code and click Activate to activate an inactive Crypto Token.

Deactivate

Deactivates an active Crypto Token.

Reactivate

Reactivates an active Crypto Token with Auto-activation enabled.

Key management

While viewing an active Crypto Token, it is possible to also view and interact with the Crypto Token's keys. The shown SubjectKeyID column is a SHA1 over the public key.

  • A new key pair can be created by giving it an alias, a key specification and clicking generate.

  • Key pairs can be removed by clicking Remove for the specific key pair, or selecting multiple keys and clicking Remove selected.

  • A key pair can be tested by clicking Test for the specific key pair.

  • A key pair's public key can be downloaded in PEM format by clicking Download Public Key.

Please note that the shown key specifications might not be supported by underlying PKCS#11 modules and an error will be shown when trying to use such a key specification.

In EJBCA Enterprise Edition, it is also possible to generate new keys by using the WS API call generateCryptoTokenKeys in your application or with the Web Services CLI.

CryptoToken Authorization

For all authorized CA operations, authorization for underlying Crypto Token operations are implied. The minimum authorization required to create a CA is authorization to "view" and "use" (or "modify") a Crypto Token.

Since modification of PKCS#11 Crypto Tokens could change the slot mapping, we require the same authorization for creation and modification. The full list of authorization rules follow:

  • /cryptotoken/: Required for displaying the Crypto Token management in the Admin GUI.

  • /cryptotoken/view/cryptoTokenId: Required for viewing Crypto Token information and listing key pairs.

  • /cryptotoken/use/cryptoTokenId: Required for binding a Crypto Token to a CA.

  • /cryptotoken/modify/: Required for creating or modifying a Crypto Token.

  • /cryptotoken/delete/: Required for deletion of a Crypto Token.

  • /cryptotoken/activate/cryptoTokenId: Required for activation of a Crypto Token.

  • /cryptotoken/deactivate/cryptoTokenId: Required for de-activation of a Crypto Token.

  • /cryptotoken/keys/generate/cryptoTokenId: Required for key pair generation.

  • /cryptotoken/keys/remove/cryptoTokenId: Required for key pair removal.

  • /cryptotoken/keys/test/cryptoTokenId: Required for key pair testing.