PKCS#11 return values and mechanisms

A PKCS#11 library tells you something went wrong by returning a number. The specification names the number. It does not tell you what to do about it, and it says nothing at all about the numbers above 0x80000000, which is where every vendor puts the ones you are most likely to be stuck on.

This section is the missing half. Paste a return value into the box and it resolves, in both readings when the input is ambiguous. Follow a constant to its page and you get the causes worth checking first, the step that confirms each one, and where the vendors disagree.

Start here

• Every return value, by group and by number.
• By library, for anything above 0x80000000 and for how SoftHSMv2 and OpenSC actually pick each code.
• Every mechanism, with what each library was seen to expose.

Written up so far

• 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_GENERAL_ERROR · Not a failed call but a broken library. The specification says nothing further will work, so retrying it is wasted effort.
• CKR_FUNCTION_FAILED · A recoverable failure. The library is still usable and the token unchanged, so this one is worth investigating rather than restarting.
• CKR_ARGUMENTS_BAD · A pointer or a count the library will not accept. Sometimes a genuine bug, and sometimes a mechanism that requires an argument to be null.
• CKR_ATTRIBUTE_VALUE_INVALID · The token knows the attribute and rejects what you set it to. Usually a length, an encoding, or a boolean that arrived as the wrong width.
• CKR_DEVICE_ERROR · The PKCS#11 catch-all for a token that has gone wrong. Usually a stale handle after a reset, a dead client link, or a mechanism the firmware refuses.
• CKR_DEVICE_MEMORY · Not a fault in your call. The token has no space left for what you asked it to store, and on most HSMs that means accumulated objects rather than a big key.
• CKR_DEVICE_REMOVED · The library noticed the token disappear between one call and the next. Usually a pulled card, a USB power event, or a network HSM whose link reset under you.
• CKR_KEY_FUNCTION_NOT_PERMITTED · The key exists and works, and its attributes do not allow this operation. Decided when the key was created, and on most tokens not changeable afterwards.
• 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.
• CKR_OBJECT_HANDLE_INVALID · Often a search that returned nothing, whose empty result was used as if it were a key. Object handles are also scoped to the session that found them.
• CKR_PIN_INCORRECT · The credential was wrong. The important part is what your code does next, because automatic retries are how tokens get locked.
• CKR_PIN_LOCKED · The token has locked the PIN after too many failed attempts. On most HSMs this is not something you can wait out, and on some it destroys the partition.
• CKR_SESSION_HANDLE_INVALID · The handle is not one this library recognises. Usually it outlived a fork, a call to C_Finalize, or the token it belonged to.
• CKR_SESSION_READ_ONLY · The session cannot modify the token. Usually a missing read-write flag at open time, or a token object that did not need to be one.
• CKR_TEMPLATE_INCONSISTENT · Each attribute is valid and together they cannot be satisfied. Usually a key asked to be both extractable and sensitive in a way the token refuses.
• CKR_TOKEN_NOT_PRESENT · Better news than it looks: the slot identifier was right. On a network HSM this usually means the client cannot reach the partition rather than a missing card.
• CKR_USER_NOT_LOGGED_IN · A private object needs an authenticated session. Often a login that happened on a different session, or one that a token event quietly ended.
• CKR_BUFFER_TOO_SMALL · Almost always a length that was measured once and reused. The output size can change between the sizing call and the real one.
• CKR_CRYPTOKI_NOT_INITIALIZED · The library has no state in this process. In a process where two components share one module, the interesting case is the one that undid it.