Managing Crypto Tokens

The following provides information on managing crypto tokens, with instructions on how to create, edit, and activate crypto tokens.

The EJBCA Administration menu option Crypto Tokens displays the Manage Crypto Tokens page. In addition, crypto tokens can be activated from the CA Activation page.

Managing Crypto Tokens from the CA UI 

Creating a Crypto Token 

To create a crypto token, select the Crypto Tokens menu option to display the Manage Crypto Tokens page, and click Create new at the bottom of the page. 

In the appearing creation screen, select the token type and specify the password and other options. For a list of available crypto token fields, see Crypto Tokens Overview.

In EJBCA Enterprise Edition, you can also 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

This view is similar to the creation of a token except for showing the ID and activation status. The view allows changing values such as the name or auto-activation status. 

Key management

While viewing an active Crypto Token, you can 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, key usage (when Type is Pkcs11NgCryptoToken), and clicking Generate.

  • Crypto Token Type is Note that the shown key specifications might not be supported by underlying PKCS#11 modules. If attempting to use such a key specification, an error will be shown. is an EJBCA Enterprise only feature

  • When Crypto Token Type is Pkcs11NgCryptoToken, there are 3 options to choose from for Key Usage:

    • Sign / Verify

    • Encrypt / Decrypt

    • Sign and Encrypt

• 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.

When using Pkcs11NgCryptoToken for the crypto token type, the mapping between key usage and PKCS11 attributes (see the Oasis PKCS#11 base specification) set on the keys is broken down in the table below:

In EJBCA Enterprise Edition, you can also generate new keys by using the WS API call generateCryptoTokenKeys in your application, with the Web Services CLI, or by using the REST API for crypto token management.

Activation and Deactivation 

The following actions are available in the Crypto Token list:

Managing Crypto Tokens from the CLI

Nearly all functionality concerning crypto tokens is mirrored in the command line using the following command:

To create a crypto token, use the create command:

To update the pin, use the setpin command:

The setpin command automatically sets the autoactivate property to true.

Soft Migration to P11NG Crypto Token

enterprise

EJBCA will phase out PKCS11CryptoToken for Enterprise customers in a future release and transition fully to the Pkcs11NgCryptoToken implementation. The following provides information about the soft migration of Crypto Tokens from PKCS11CryptoToken to Pkcs11NgCryptoToken.

To facilitate a smooth migration, EJBCA provides an option to test the migration of existing PKCS11CryptoTokens without forcefully upgrading them. This is achieved by initializing all existing PKCS11CryptoTokens as Pkcs11NgCryptoTokens at runtime, but without changing the crypto token type in the database. In theory, this makes the decision to migrate the crypto tokens reversible.

However, there are some differences in behavior between the two token types. When generating keys on a PKCS11CryptoToken, a dummy certificate is created as an object on the HSM slot. Without this object, a PKCS11CryptoToken cannot see the keys on the slot where they reside. EJBCA Pkcs11NgCryptoTokens, on the other hand, do not create such an object when generating keys. In practice, this means that for a migrated token, if new keys are generated, no dummy certificate object will be created on the slot. If the migration is later reversed, the PKCS11CryptoToken will not be able to see the keys generated by the at the time migrated Pkcs11NgCryptoToken.

The use of Attribute files is a configuration that only works with PKCS11CryptoTokens. While it is possible to set key attributes using the p11ng-cli tool, the Attribute files that can be added as part of a configuration option in the EJBCA Administration GUI are never used by the Pkcs11NgCryptoTokens. Any PKCS11CryptoToken that has been migrated will still retain its Attribute file, but the file will not be used as long as the crypto token is interpreted by EJBCA as a Pkcs11NgCryptoToken.

How to migrate PKCS11CryptoTokens to Pkcs11NgCryptoTokens

To migrate PKCS11CryptoTokens:

1. Set the EJBCA Enterprise environment variable:

   USE_P11NG_AS_P11=true

2. After setting the variable, restart the application server.

The behavior will be as follows:

• If USE_P11NG_AS_P11=true, EJBCA will treat all existing PKCS11CryptoToken instances as Pkcs11NgCryptoToken at runtime, without modifying the database.

• If the variable is unset, set to false, or set to any value other than true, EJBCA will not migrate any crypto tokens.

• If the variable is removed or disabled after restart, EJBCA will handle all crypto tokens as they are stored in the database. In effect, a crypto token created as a PKCS11CryptoToken will be used by EJBCA as a PKCS11CryptoToken.

• New keys created in Pkcs11NgCryptoTokens cannot be accessed in PKCS11CryptoTokens.