808bits

CKR_PIN_INCORRECT

PKCS#11 return value · 0x000000A0 · decimal 160
hex 0x000000A0 decimal 160 name CKR_PIN_INCORRECT

There is nothing ambiguous about this one. What makes it worth a page is that it is the last recoverable step before a state that is often not recoverable at all, and most PKCS#11 code treats it like any other failure. A token counts these, the counter survives restarts, and it does not care that the three failures came from a loop rather than from a person.

What the token is reporting

The credential presented for that role did not match. The token has almost certainly incremented a failure counter, and the remaining attempts before a lockout are usually small.

Likely causes

Ordered by how often they turn out to be the answer. That ordering is a judgement from experience, not a measured frequency.

The credential is genuinely wrong

Rotated in one place and not another, copied with a trailing newline, or read from an environment variable that was never set so the library received an empty string.

Check it: Check the length of what you passed rather than its content. An empty or whitespace-padded value is the single most common cause, and it is visible without ever logging the secret itself.

The right credential for the wrong role

Tokens have at least two roles, and the login call takes the role as an argument. A perfectly correct administrator credential presented as the normal user is simply wrong, and the token says so in exactly these terms.

Check it: Check the role argument at the login call before you doubt the credential.

The right credential for a different token

On a machine with several slots, the slot you got is not always the slot you meant, especially where slot numbering is not stable across restarts.

Check it: Read the token label of the slot you opened and confirm it is the one you meant. Address tokens by label rather than by slot number wherever the library allows it.

Which calls return it

C_Login, C_SetPIN

What it is not

It is not a reason to retry. This is the code that separates an inconvenience from an outage, and the only correct automatic response is to stop.

Often confused with

  • CKR_PIN_LOCKED: What comes next if the code retries. The two should never share an error handler.

See also

By library

SoftHSMv2

Returned by [Token::loginUser](https://github.com/softhsm/SoftHSMv2/ blob/884cb38f3d2012a0447bd5f50dbd29c429987c41/src/lib/slot_mgr/Token.c pp#L150-L184) with the CKF_USER_PIN_COUNT_LOW token flag set, and that flag is the only consequence. No counter runs behind it and the next correct PIN is accepted. Convenient for tests, and misleading about what the same loop does to hardware.

OpenSC

The direct translation of SC_ERROR_PIN_CODE_INCORRECT, which is what the card’s status word became inside libopensc. The remaining tries are counted on the card, not in the library, and pkcs11-tool --login prints the code as rv = CKR_PIN_INCORRECT (0xa0).

Sources

Every description, cause and check on this page is written from scratch. The specification is cited for the constant's name and its number, which are facts, and for nothing else.