808bits

Entrust nShield

documented by name · Security World v13.9.6 documentation

nShield is the other HSM most enterprises have, and its PKCS#11 library is documented in public and in detail, with one gap that matters for a site like this one. The reference guide names every mechanism and every vendor extension, and it says outright that the numbers are in a header file that ships with the software. So a vendor-range value from an nShield log cannot be decoded from anything public, and this page is about what the guide does say instead.

Slots are a configuration, not a reader

Nothing in the specification prepares a reader for how nShield numbers slots. With no special mode set, each module appears as two or more slots, the first for the module itself and the second for its smart card reader, and the first one has the login-required flag unset, so C_Login on it always fails. Set CKNFAST_LOADSHARING and the library instead creates one virtual slot per operator card set, plus softcards as further virtual slots, plus an accelerator slot unless CKNFAST_NO_ACCELERATOR_SLOTS says otherwise. Set CKNFAST_HSM_POOL and there is a single accelerator slot for the whole pool and no token-protected keys at all. The same application sees a different slot list on three machines with three environments, and CKR_SLOT_ID_INVALID is how it finds out.

Names, not numbers

The mechanisms page lists 159 mechanisms with the functions each supports, and the vendor-defined extensions page adds twenty CKM_NC_ mechanisms, mostly for the Milenage and TUAK telecom algorithms, plus HMAC key generation and an ECIES variant, along with vendor key types and attributes. The extensions page then says that the numeric values are in the supplied pkcs11extra.h. That header comes with the client software, which is not public, so none of those values appear here. The same page marks which mechanisms are restricted in a FIPS 140 Level 3 Security World, which is a policy layer the specification has no vocabulary for.

Where the guide does talk about return values

The reference guide does not publish a vendor return code list, and I found no CKR_ above the vendor base anywhere in it. What it does is annotate the standard codes. The mechanism annotations page says an OAEP hash and mask function of different sizes fail with CKR_MECHANISM_PARAM_INVALID, and the extensions page says a derive template with a key type of no fixed length is CKR_TEMPLATE_INCOMPLETE while an incompatible length is CKR_TEMPLATE_INCONSISTENT. Debugging past the code means CKNFAST_DEBUG, one of 31 CKNFAST_ environment variables the guide lists.

Return values with a note for this library

  • CKR_SLOT_ID_INVALID · The library does not have that slot. Usually a number hard-coded from a machine where the enumeration came out differently.
  • CKR_MECHANISM_INVALID · The mechanism is unknown here, or not valid for the operation you used it in. Check the slot's own list rather than the header you compiled against.

How this page was made

Documented by name only. Read from the public nShield Security World PKCS#11 reference pages, mechanisms, vendor-defined extensions, the three slot mode pages and the environment variables page, on the date below. No nShield software was available and no header was read, so no constant on this page has a number.

Scope. What the v13.9.6 documentation says, which is the current Security World release at the time of reading. Mechanism availability also depends on the Security World's FIPS setting and on the module's firmware, and the guide says so.

Sources