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.

Enabling load-sharing mode also enables high-availability mode. When in high-availability mode, the nShield PKCS #11 library will detect modules being added to, or removed from, the current Security World and, provided that at least one module remains available, applications will not require restarting to adapt to changes in module availability.

The minimum interval that modules are checked when in high-availability mode can be configured by setting CKNFAST_HA_MINIMUM_INTERVAL.
High-availability mode is disabled if preload is used.
If operating within a FIPS Security World, it is necessary to ensure at least one operator card is available to provide FIPS authorization.

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.