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.

While EJBCA safeguards against accidental changes to the crypto token type stored in the database while editing a migrated crypto token, due to the above-mentioned reasons, it is not recommended to generate new keys on, or otherwise edit, migrated tokens unless the migration is intended to be irreversible.

How to migrate PKCS11CryptoTokens to Pkcs11NgCryptoTokens

To migrate PKCS11CryptoTokens:

1. Set the EJBCA Enterprise environment variable:

   CODE

       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.