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_HOST_MEMORY · The library could not allocate host memory. Rare as a real out-of-memory. More often a size computed from bad input, a leak, or a vendor error filed here.
• 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_READ_ONLY · The attribute cannot be changed on this object, or cannot be supplied at creation because the token sets it. Computed flags, identity, or a locked object.
• CKR_ATTRIBUTE_SENSITIVE · The attribute exists and the token will not disclose it. Private key material behind CKA_SENSITIVE or a false CKA_EXTRACTABLE. Not a fault.
• CKR_ATTRIBUTE_TYPE_INVALID · The object has no such attribute, or this library never stored it. Common when reading fields that only exist for another key type, and in object dumps.
• 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_DATA_INVALID · Right length, wrong content. A DigestInfo the token cannot parse, an EC point in the wrong encoding, or on a card, a status word with nowhere else to go.
• CKR_DATA_LEN_RANGE · Input length the mechanism does not accept. A block cipher without padding, RSA input longer than the modulus, or a raw signing mechanism given a message.
• 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_ENCRYPTED_DATA_INVALID · Ciphertext the token could not decrypt: bad padding, the wrong key, a failed tag. Some libraries use it for every decrypt failure, against padding oracles.
• CKR_FUNCTION_NOT_SUPPORTED · The library exports the function and will not perform it. Usually a v3.0 message call, a dual-function update, or a wrap on a token that never wraps.
• CKR_KEY_TYPE_INCONSISTENT · The key's type does not fit the mechanism. An EC key on an RSA mechanism, an Edwards key on ECDSA, or a find that returned the certificate instead.
• 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_MECHANISM_PARAM_INVALID · The mechanism is known and its parameter is wrong. A missing IV, an OAEP hash pairing the token refuses, or a GCM tag length out of range.
• 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_OPERATION_ACTIVE · An Init was called while the session already holds an operation of that kind. A multi-part operation that was never finished, or two threads on one session.
• CKR_OPERATION_NOT_INITIALIZED · Sign, Update or Final with no matching Init on this session. An Init whose failure was ignored, an operation the library reset, or a session shared by threads.
• 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_LEN_RANGE · The PIN is too short or too long for this token. The limits are in the token info and are applied before the PIN is looked at, so the PIN may also be wrong.
• 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_INCOMPLETE · The template does not fully specify the object. A missing CKA_CLASS or CKA_KEY_TYPE on create, a missing CKA_VALUE_LEN on generate, or a vendor rule.
• 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_TOKEN_NOT_RECOGNIZED · The library saw a device in the slot and has no driver for it, or the card answered in a way it could not parse. A smart card code far more than an HSM one.
• CKR_USER_ALREADY_LOGGED_IN · A login on a token that already has that user logged in through another session. Two components sharing a token, or a retry after a login that succeeded.
• 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_DOMAIN_PARAMS_INVALID · The domain parameters are not ones this token accepts. An EC curve the token lacks or in the wrong encoding, or DH parameters given where the token makes them.
• 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.
• CKR_CRYPTOKI_ALREADY_INITIALIZED · C_Initialize on a library that is already initialized in this process. Usually two components sharing one module, or a fork the library did not notice.