Migrate from SunPKCS11 to P11NG

enterprise

This covers the steps needed to migrate from the PKCS#11 implementation Java SunPKCS11 provider to the newer P11NG provider and includes reconfiguring existing crypto tokens using PKCS#11 to instead use the new P11NG provider. The P11NG crypto token was first introduced in SignServer 4.3 to provide certain functionality not supported by the Java SunPKCS11 provider. As the P11NG provider has evolved over time, it now includes key wrapping functionaliteis, support for EdDSA algorithms, and various Cloud HSM options. As of SignServer 5.11, P11NG is the recommended crypto token for new deployments of all use cases.

Background

The PKCS#11 standard has been around since 1995 and is a platform-independent API to access and use cryptographic functions in hardware security modules (HSMs), smart cards, and the like. PKCS#11 is standardized in the Oasis standardization organization.

SignServer has traditionally used PKCS#11 through the PKCS11CryptoToken that utilizes the Java provider SunPKCS11. In addition, we have implemented our own P11NG provider with additional features and improved performance, which allows us to further control and improve future HSM interactions. The new P11NG provider is used through the SignServer P11NGCryptoToken.

Both implementations should not be used simultaneously in a SignServer instance. There are a number of reasons for this, including:

Both implementations would load and potentially initialize the PKCS#11 driver.
Both implementations could be opening and holding PKCS#11 sessions which could lead to sessions running out for one or both of the implementations.
SignServer is tested with either of the implementations, not both at the same time.

Not using the different PKCS#11 implementations simultaneously means that the crypto tokens in SignServer using PKCS#11 must use the same PKCS#11 provider implementation. The same type of PKCS#11 provider implementation should also be set in databaseprotection.properties if audit log signing is enabled.

Migrate to P11NG Provider

To migrate from the legacy Java provider SunPKCS11 to the P11NG provider, you need to reconfigure all crypto tokens that previously used the PKCS11CryptoToken to instead use the corresponding P11NG*CryptoToken, and then restart the instance in order to not load the old implementation.

It is recommended to perform the migration by exporting and setting up a new crypto token, thus leaving the old crypto token disabled. For database log signing, a new "keyid" is set up and verified to be working before switching the old "keyid" to use the P11NG implementation.

Set up Crypto Workers using P11NG for each PKCS11 Crypto Worker

To set up new crypto workers using P11NG for each existing crypto worker that is using the legacy Java provider SunPKCS11, perform the following steps.

Step 1 - Export crypto worker configuration

To export the crypto worker configuration, do the following:

Go to the SignServer Administration Web Workers page.
Note down the worker ID of the P11 crypto worker.
To export the crypto worker configuration, select the crypto worker and click Export.
Click Download and save the file locally on your workstation.

Step 2 - Update crypto worker configuration

To edit the crypto worker configuration, do the following:

Copy the downloaded crypto worker configuration file to a new file, such as dump-<timestamp>.properties → dump-<timestamp>-p11ng.properties.
Open the newly created P11NG copy file in a text editor and edit the configuration according to the following:
- To update the worker ID:
  - Change the WORKER<ID>. (of the crypto worker as noted in Step 1) to the generic WORKERGENID1. at the beginning of every (non-comment) line.
  - Alternatively, use a static unused ID instead of GENID1.
- To update the crypto token implementation class, update the line:
  - WORKERGENID1.CRYPTOTOKEN_IMPLEMENTATION_CLASS=org.signserver.server.cryptotokens.PKCS11CryptoToken
    to
  - WORKERGEN1.CRYPTOTOKEN_IMPLEMENTATION_CLASS=org.signserver.p11ng.common.cryptotoken.P11NGCryptoToken
- To specify a name for the new P11NG crypto token, edit the line starting with WORKERGEN1.NAME= to use a new name such as CryptoTokenP11NG.
- If the old PKCS11 crypto worker was configured using the ATTRIBUTES property (to specify PKCS11 attributes according to the SunP11), these attribute settings need to be converted to separate ATTRIBUTE.x.y.z-style properties. For more information, see P11NGCryptoToken.
Save the file.

Step 3 - Import P11NG crypto worker configuration

To import the new P11NG crypto worker configuration, do the following:

On the SignServer Administration Web Workers page, click Add.
Click From file and then click Browse and select the updated worker configuration file from the file system.
Click Apply.
Select the new crypto worker from the Workers list, and if not auto-activated (no PIN is set), activate the token using the PIN.
Click the Crypto Token tab and verify that the existing keys are shown, thus the same keys as for the old crypto worker.

Step 4 - Update workers using the P11 crypto token

Next, to update the workers using the P11 crypto token, do the following:

For each worker using the old PKCS11CryptoToken type of crypto token, change the CRYPTOTOKEN worker property to point to the new crypto worker.
Ensure that the worker status is shown as ACTIVE after changing the CRYPTOTOKEN property.

Step 5 - Disable old crypto worker

To disable the old crypto worker, do the following:

Select the old crypto worker and click Disable.
On the disable worker page, click Disable.
The old crypto worker should now be displayed in the workers list as "Disabled".

The migration is now completed and the old crypto token is left disabled.

Reconfigure Audit Log Signing

If you are using signed audit log using PKCS11, perform the following steps to reconfigure Audit Log signing:

Update databaseprotection.properties to use P11NG:
Edit $SIGNSERVER_HOME/conf/databaseprotection.properties
Copy the section containing the configuration for the PKCS11 crypto token, for example:

# Definition of a third Crypto Token using a PKCS#11 HSM, suitable for digital signature

# Do not forget to generate keys on the HSM though, keys usable by Java PKCS#11.

# The PKCS11CryptoToken in CESeCore is very good at that.

databaseprotection.keyid.1 = 401

databaseprotection.keylabel.1 = dbProtKey

databaseprotection.classname.1 = org.cesecore.keys.token.PKCS11CryptoToken

databaseprotection.properties.1 = sharedLibrary=/usr/lib/softhsm/libsofthsm2.so, slotLabelType=SLOT_INDEX, slotLabelValue=0

databaseprotection.data.1 =

databaseprotection.tokenpin.1 = foo123

databaseprotection.version.1 = 2
Change the index of the properties, for example from 1 to 2, edit the keyid and token classname, and also change the slot properties to all caps. This would result in a crypto token configuration for P11NG that looks like the following:

databaseprotection.keyid.2 = 402

databaseprotection.keylabel.2 = dbProtKey

databaseprotection.classname.2 = org.signserver.p11ng.common.cryptotoken.P11NGDatabaseProtectionCryptoToken

databaseprotection.properties.2 = sharedLibrary=/usr/lib/softhsm/libsofthsm2.so, SLOTLABELTYPE=SLOT_INDEX, SLOTLABELVALUE=0

databaseprotection.data.2 =

databaseprotection.tokenpin.2 = foo123

databaseprotection.version.2 = 2
To change the keyid used to sign new and updated rows, update the row according to the following example:
From:

databaseprotection.keyid = 401

To:

databaseprotection.keyid = 402
Next, redeploy:

$ ./bin/ant deploy
Finally, verify that the startup event is logged and that there are no audit log failures (thus ensure that both the new and the old signing tokens are still working).
Once verified, either:
- Edit the old token to also use the P11NGDatabaseProtectionCryptoToken and the redeploy.
- Or, instead of re-using the same signing key, generate a new key for the new rows after the migration.

The database log signing is now set up to use the P11NG implementation.