CKR_BUFFER_TOO_SMALL: the two-call idiom, and what breaks it

PKCS#11 asks the caller to provide output space, and it tells you how much by having you make the call twice: once with no buffer to learn the length, then again with one. Nearly every appearance of this code is that idiom going wrong somewhere, and the interesting failures are the ones where it was followed correctly and the answer still changed underneath.

What the token is reporting

The output would not fit in the space you provided. The operation has not been consumed, so the same call can be repeated with a larger buffer, and the library has written the required length back into the length argument.

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 length was never asked for

A fixed buffer sized from what the algorithm produces in theory works until it meets a token that pads, or a signature format that varies, or a key larger than the one used in testing.

Check it: Check whether the first call passes a null output pointer. If your code only ever makes one call, this is the whole problem.

Fix: Call once with no buffer, read the length the library writes back, allocate that, then call again. Do not round it or reuse it.

The length was reused from an earlier call

Caching a size that was correct for one key or one input and applying it to another is the version of this that survives testing. Signature lengths in particular are not constant across keys, and some encodings vary by a byte or two between signatures with the same key.

Check it: Log the requested length and the supplied length together. If the requested one moves between calls and the supplied one does not, the cache is the fault.

The length argument was not reset between the two calls

The same variable carries the buffer size in and the required size out. A loop that measures once and then calls repeatedly without resetting that variable will work the first time and fail afterwards, which makes it look intermittent.

Check it: Set the length to the buffer’s actual capacity immediately before every call, not once outside the loop.

A binding layer that hides the idiom

Wrappers in higher level languages usually implement the two calls for you, and some of them guess a size instead. When one guesses too small the error surfaces from inside code you did not write.

Check it: Check whether the binding exposes the sizing call at all. If it does not and the failure is size-dependent, the wrapper is the place to look rather than your own code.

Which calls return it

C_Sign, C_Encrypt, C_Decrypt, C_GetAttributeValue, C_WrapKey

What it is not

It is not a failed operation. Nothing has been consumed and no state has changed, so repeating the call with more space is correct and safe, which is not true of most codes in this specification.

Sources

PKCS #11 Specification Version 3.2, OASIS. Read 2026-09-10. Used for constant name and numeric value.

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.