PKCS#11 with load sharing mode

The behavior of the nShield PKCS #11 library varies depending on which of load-sharing mode, HSM Pool mode or neither or these is enabled. If you have enabled load-sharing mode, the nShield PKCS #11 library creates one virtual slot for each OCS and, optionally, also creates one slot for the HSM or HSMs. Softcards appear as additional virtual slots once enabled. See also CKNFAST_CARDSET_HASH.

An additional virtual slot may be returned (with the label of accelerator), depending on the value given to the variable CKNFAST_NO_ACCELERATOR_SLOTS (described in CKNFAST_NO_ACCELERATOR_SLOTS). Accelerator slots can:

  • Be used to support session objects

  • Be used to create module-protected keys

  • Not be used to create private objects.

Load-sharing mode must be enabled in PKCS #11 in order to use softcards.

Whether or not load-sharing mode is enabled is determined by the state of the CKNFAST_LOADSHARING environment variable.

Load-sharing mode enables you to load a single PKCS #11 token onto several nShield HSMs to improve performance. To enable successful load-sharing with an OCS protected key:

  • You must have an Operator Card from the OCS inserted into every slot from the same 1/N card set

  • All the Operator Cards must have the same passphrase.

The PKCS #11 token is present until you remove the last card belonging to the OCS. When you remove the token, the nShield PKCS #11 library closes any open sessions.

The nShield-specific API calls, C_LoginBegin, C_LoginNext, and C_LoginEnd do not function in load-sharing mode. K/N support for card sets in load-sharing mode is only available if you first use preload to load the logical token.

Logging in

If you call C_Login without a token present, it fails (as expected) unless you are using a persistent token with preload or using only module-protected keys. Therefore, your application should prompt users to insert tokens before logging in.

The nShield PKCS #11 library removes the nShield logical token when you call C_Logout, whether or not there is a smart card in the reader.

If there are any cards from the OCS present when you call C_Logout, the PKCS #11 token remains present but not logged-in until all cards in the set are removed. If there are no cards present, the PKCS #11 token becomes not present.

If you remove a smart card that belongs to a logged-in token, the nShield PKCS #11 library closes any open sessions and marks the token as being not present (unless the OCS is persistent). Removing a card from a persistent OCS has no effect, and the PKCS #11 token remains present until you log out.

The CKNFAST_NONREMOVABLE environment variable is only available for persistent tokens. When the variable is set, the rules for recognizing new cards are overridden, and the only way to invoke a new token is to call C_Finalize or C_Initialize.

Session objects

Session objects are loaded on all modules.

Module failure

If a subset of the modules fails, the nShield PKCS #11 library handles commands using the remaining modules. If a module fails, the single cryptographic function that was running on that module will fail, and the nShield PKCS #11 library will return a PKCS #11 error. Subsequent cryptographic commands will be run on other modules.

Compatibility

Before the implementation of load-sharing, the nShield PKCS #11 library puts the electronic serial number in both the slotinfo.slotDescription and tokeninfo.serialNumber fields. If you have enabled load-sharing, the tokeninfo.serialNumber field displays the hash of the OCS.

Restrictions on function calls in load-sharing mode

The following function calls are not supported in load-sharing mode:

  • C_LoginBegin (nShield-specific call to support K/N card sets)

  • C_LoginNext (nShield-specific call to support K/N card sets)

  • C_LoginEnd (nShield-specific call to support K/N card sets).

The following function calls are supported in load-sharing mode only when using softcards:

  • C_InitToken

  • C_InitPIN

  • C_SetPIN.

To use C_InitToken, C_InitPIN, or C_SetPIN in load-sharing mode, you must have created a softcard with the command ppmk -n before selecting the corresponding slot.
The C_InitToken function is not supported for use in non-load-sharing FIPS 140 Level 3 Security Worlds.