PKCS#11 with key reloading

The nShield PKCS #11 library is capable of reloading keys to nShield HSMs after a PKCS #11 application has started. The PKCS #11 library will attempt to reload the keys to all HSMs from which keys have been unloaded after the application was started, for example, if the HSM was cleared. This also means that if an application uses HSMs that became unusable during runtime, the PKCS #11 library will re-add these HSMs into the group of HSMs in a single Security World when they become usable again. The PKCS #11 library will also attempt to reload the keys on new HSMs that become usable after the application has started, for example if you enroll a new HSM into the Security World. The application can then use the HSM for key operations.

The default behavior without PKCS #11 key reloading is that when an HSM is removed from the group of HSMs in a Security World, it is not re-added for PKCS #11 until the user’s application is restarted.

The CKNFAST_RELOAD_KEYS environment variable determines whether key reloading mode is enabled.

Load-sharing mode must be enabled in PKCS #11 to use key reloading mode. If load-sharing is not enabled, it is enabled automatically if CKNFAST_RELOAD_KEYS is enabled.

Key reloading is not supported for session keys.

Usage under preload

PKCS #11 key reloading only reloads keys. It must also operate under a preload session during which preload is reloading tokens that protect the keys used by PKCS #11, in high availability mode. When the PKCS #11 application is using a token-protected key, preload should first be run to reload the token while PKCS #11 is reloading the key. For information on running preload for PKCS #11 key reloading, see PKCS#11 library with the preload utility and Preload Utility.

PKCS #11 key reloading is also supported for module-protected keys, but the PKCS #11 application must still be run under a preload application which is reloading tokens for another key.

Either run the PKCS #11 application as a subprocess of preload, or in a separate command window ensuring the preload file set for preload matches the one set for PKCS #11. See PKCS#11 library with the preload utility and Preload Utility

The application will attempt to reload keys when supported functions are called, see Supported function calls.

Persistent preload files

The preload file persists on disk after the preload process has terminated. Therefore, a PKCS #11 application in key reloading mode should not be run with an NFAST_NFKM_TOKENSFILE that points to a preload file from an old (non-running) preload process.

Supported function calls

Key reloading is attempted whenever a key is used for a cryptographic operation. For signing, verifying, encrypting, and decrypting, the functions are as follows:

  • C_SignInit

  • C_VerifyInit

  • C_EncryptInit

  • C_DecryptInit

On a call to any of these functions, the PKCS #11 library will do the following:

  1. Checks if preload has reloaded any token objects on any HSMs since the last time one of the above functions was called. This is done by checking if the preload file has been modified. If not, there is nothing to reload.

  2. If reload is required, reloads any keys that are protected by the newly-loaded tokens on all usable HSMs in the group.

Retrying key reloads

PKCS #11 can fail to reload a key due to transient or genuine errors. An example for a transient error is when an HSM has not finished reinitializing in time for a key to be reloaded. An example for a genuine error is when the key is invalid. In case of a failure, PKCS #11 will attempt to reload the key every time one of the functions in Supported function calls is called for a further 5 minutes before abandoning the key reload on that HSM.

Adding new HSMs

With key reloading enabled using the CKNFAST_RELOAD_KEYS environment variable, the PKCS #11 library can add new HSMs to its internal list of usable modules. HSMs are new if they were not present when PKCS #11 applications were initialized. When key reloading is not enabled, PKCS #11 applications must be restarted before the new HSMs can be used.

The PKCS #11 library supports a maximum of 32 HSMs. If you have already reached 32 HSMs and you add a new HSM, then the PKCS #11 library will not be able to add this module. If an HSM is removed from the Security World or otherwise becomes unusable, it is still counted towards this limit. The application must be restarted to remove the removed or unusable HSM from the list.