808bits

CKR_PIN_LEN_RANGE

PKCS#11 return value · 0x000000A2 · decimal 162
hex 0x000000A2 decimal 162 name CKR_PIN_LEN_RANGE

Tokens publish a minimum and maximum PIN length in their token information, and this is the code for a PIN outside them. The length is checked before the PIN is, so a rejected length says nothing about whether the PIN was right, and a correct PIN of the wrong length for a new token behaves as though it were wrong. The surprises are in what counts as the PIN.

What the token is reporting

The length of the PIN, or of the new PIN on a change, is outside the range the token reports. The PIN’s value was not checked and, on the libraries looked at here, was not sent to the token.

Likely causes

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

A PIN that fits one token and not the next

A software token may take anything from four to hundreds of bytes, a card four to eight, an HSM whatever its policy says. A PIN chosen for one and carried to another through a migration or a test-to-production move fails on length alone.

Check it: Read the minimum and maximum from C_GetTokenInfo on the token that failed.

The PIN is not only the PIN

Some libraries expect an identifier in front of the password, and a password on its own is short by the identifier’s length. A passphrase with characters outside ASCII is longer in bytes than in characters, which matters because the limit is in bytes.

Check it: Count the bytes you are passing, not the characters, and read the library’s documentation for the PIN format before assuming it is the bare password.

An empty PIN on a token without a protected path

A null pointer and zero length are how a caller asks for the PIN to be entered on a reader’s keypad, and that is only valid when the token advertises the protected authentication path flag. Without the flag the empty PIN is simply too short.

Check it: Check the token flags for the protected authentication path bit.

A new PIN that fails the token's policy on change

Init and change calls check the new PIN against the same limits, and some tokens fold other policy failures into the length code rather than the dedicated weak-PIN one.

Check it: If the failing call is a set or an init, the new PIN is the one to measure.

Which calls return it

C_Login, C_InitPIN, C_SetPIN, C_InitToken

What it is not

It is not a wrong PIN, which is pin incorrect, and not a lockout. Since the PIN was never sent, it does not count against the retry counter on the libraries looked at here.

Often confused with

  • CKR_PIN_INCORRECT: The next check along, once the length passes.
  • CKR_PIN_INVALID: A PIN containing characters the token does not allow. Content rather than length.
  • CKR_ARGUMENTS_BAD: A null PIN pointer with a non-zero length, which some libraries report as a bad argument before the length is considered.

By library

SoftHSMv2

The init and change calls check the new PIN’s length before touching the token (SoftHSM.cpp). The login call does not check length at all, so a PIN of the wrong length there is reported as incorrect.

IBM opencryptoki

The limits are four to eight bytes (defs.h), checked on init and change ([new_host.c](h ttps://github.com/opencryptoki/opencryptoki/blob/430a47d7478236891ff17 4d096b55e04026981a8/usr/lib/common/new_host.c#L601-L603)). Eight is short by current habits and is the first thing to check when a PIN that works elsewhere fails here.

OpenSC

The card’s own invalid-length error maps to this code ([misc.c](https:/ /github.com/OpenSC/OpenSC/blob/4fab8b57301f035432191d582922d95d7d42680 2/src/pkcs11/misc.c#L94-L95)), and a change is checked against the PIN object’s minimum and maximum on the card ([framework-pkcs15.c](https:/ /github.com/OpenSC/OpenSC/blob/4fab8b57301f035432191d582922d95d7d42680 2/src/pkcs11/framework-pkcs15.c#L2029-L2030)). The limits are the card’s, per PIN object, not the library’s.

YubiHSM 2

The PIN string is the four hex digit authentication key identifier followed by the password (yubihsm_pkcs11.c). A password of the right length with the identifier missing is short by four, and nothing in the return code says so.

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.