Soft Migration from SunPKCS11 Crypto Token to P11NG Crypto Token

ENTERPRISE

EJBCA PKCS#11 based integration with HSMs can be configured using two different Crypto Token types. The P11NG Crypto Token type offers extended functionality than the SunPKCS11 Crypto Token type including support for quantum-safe algorithms.

The SunPKCS11 Crypto Token type is deprecated since EJBCA 9.4 and customers are recommended to migrate to the P11NG Crypto Token type. The following provides information about a method for soft migration of Crypto Tokens from SunPKCS11 Crypto Token (PKCS11CryptoToken) to P11NG Crypto Token (Pkcs11NgCryptoToken).

With this migration method, EJBCA provides an option to test the migration of existing SunPKCS11 Crypto Tokens without forcefully changing the stored configuration. This is achieved by initializing all existing SunPKCS11 Crypto Tokens as P11NG Crypto Tokens at runtime, but without changing the Crypto Token Type in the database.

When using this migration method, be aware that there are some differences in behavior between the two Crypto Token types. When generating keys on a SunPKCS11 Crypto Token, a dummy certificate is created as an object on the HSM slot. Without this object, a SunPKCS11 Crypto Token cannot see the keys on the slot where they reside. P11NG Crypto Tokens, 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 SunPKCS11 Crypto Token will not be able to see the keys generated by the at the time migrated P11NG Crypto Token.

The use of Attribute files is a configuration that only works with SunPKCS11 Crypto Tokens. 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 P11NG Crypto Tokens. Any SunPKCS11 Crypto Token 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 P11NG Crypto token.

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 SunPKCS11 Crypto Tokens to P11NG Crypto Tokens

To migrate SunPKCS11 Crypto Tokens:

Set the EJBCA Enterprise environment variable:
CODE
```
    USE_P11NG_AS_P11=true
```
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 SunPKCS11 Crypto Tokens as P11NG Crypto Tokens 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 SunPKCS11 Crypto Token will be used by EJBCA as a SunPKCS11 Crypto Token.
New keys created in P11NG Crypto Tokens cannot be accessed in SunPKCS11 Crypto Tokens.