libfido2 / Errors and ownership

Errors and ownership

Keep numeric return codes and fido_strerr() labels. Error classes do not prescribe recovery; never auto-retry PINs.

Most operations return FIDO_OK on success and another error code otherwise. The library exposes readable messages through fido_strerr()[library].

Concern	Behavior
Blocking calls	Registration and assertion calls may wait on user interaction.
Timeout	Use `fido_dev_set_timeout()` for device transaction timeout policy.
Cancellation	Consult `fido_dev_cancel()` and platform support before relying on it.
Borrowed pointers	Pointer accessors refer to library-managed memory; copy data that must outlive the object.
Object cleanup	Pair `_new` with the matching `_free`; close device handles before freeing.

Classify discovery/I/O, capability, PIN/UV, interaction, and verification failures separately.

Error codes

Symbol	Interpretation
`FIDO_ERR_TX`	Transmit failed; inspect device connectivity and transport.
`FIDO_ERR_RX`	Receive failed; inspect connectivity and transport.
`FIDO_ERR_RX_NOT_CBOR`	Response did not contain the expected CBOR framing.
`FIDO_ERR_RX_INVALID_CBOR`	Response CBOR could not be decoded.
`FIDO_ERR_INVALID_PARAM`	libfido2 rejected an argument or validated value.
`FIDO_ERR_INVALID_ARGUMENT`	Caller supplied an invalid argument or incomplete object.
`FIDO_ERR_INVALID_SIG`	Local cryptographic signature verification failed.
`FIDO_ERR_USER_PRESENCE_REQUIRED`	A required presence check was not satisfied.
`FIDO_ERR_NOTFOUND`	Requested item was not found by the library.
`FIDO_ERR_COMPRESS`	Compression or decompression failed.
`FIDO_ERR_INTERNAL`	Internal library failure; preserve context and diagnostics.

Symbol	Interpretation
`FIDO_ERR_INVALID_COMMAND`	Authenticator does not accept the command.
`FIDO_ERR_INVALID_PARAMETER`	CTAP request parameter invalid.
`FIDO_ERR_INVALID_LENGTH`	CTAP payload length invalid.
`FIDO_ERR_INVALID_SEQ`	Transport sequence invalid.
`FIDO_ERR_TIMEOUT`	Transport timeout.
`FIDO_ERR_CHANNEL_BUSY`	Channel busy; distinguish contention from device failure.
`FIDO_ERR_LOCK_REQUIRED`	Transport lock required.
`FIDO_ERR_INVALID_CHANNEL`	Transport channel invalid.
`FIDO_ERR_CBOR_UNEXPECTED_TYPE`	CBOR item has the wrong type.
`FIDO_ERR_INVALID_CBOR`	Request CBOR invalid.
`FIDO_ERR_MISSING_PARAMETER`	Required request field missing.
`FIDO_ERR_LIMIT_EXCEEDED`	Request exceeds authenticator limit.
`FIDO_ERR_REQUEST_TOO_LARGE`	Request size too large.
`FIDO_ERR_UNSUPPORTED_ALGORITHM`	Requested credential algorithm unsupported.
`FIDO_ERR_UNSUPPORTED_EXTENSION`	Requested extension unsupported.
`FIDO_ERR_UNSUPPORTED_OPTION`	Requested authenticator option unsupported.
`FIDO_ERR_INVALID_OPTION`	Authenticator option invalid.

Symbol	Interpretation
`FIDO_ERR_CREDENTIAL_EXCLUDED`	Credential already exists in the exclusion list.
`FIDO_ERR_INVALID_CREDENTIAL`	Credential rejected by authenticator.
`FIDO_ERR_NO_CREDENTIALS`	No matching credential available.
`FIDO_ERR_KEY_STORE_FULL`	Authenticator credential storage full.
`FIDO_ERR_FP_DATABASE_FULL`	Fingerprint template storage full.
`FIDO_ERR_LARGEBLOB_STORAGE_FULL`	Large-blob storage full.
`FIDO_ERR_PROCESSING`	Authenticator processing status.
`FIDO_ERR_USER_ACTION_PENDING`	Waiting for user action.
`FIDO_ERR_OPERATION_PENDING`	Operation pending.
`FIDO_ERR_NO_OPERATIONS`	No operations available.
`FIDO_ERR_OPERATION_DENIED`	Authenticator denied operation.
`FIDO_ERR_NOT_BUSY`	Authenticator is not busy.
`FIDO_ERR_NO_OPERATION_PENDING`	No pending operation.
`FIDO_ERR_KEEPALIVE_CANCEL`	Operation cancelled.
`FIDO_ERR_USER_ACTION_TIMEOUT`	Timed out waiting for user action.
`FIDO_ERR_ACTION_TIMEOUT`	Authenticator action timeout.
`FIDO_ERR_NOT_ALLOWED`	Operation disallowed by policy or state.
`FIDO_ERR_UP_REQUIRED`	User presence required.

Symbol	Interpretation
`FIDO_ERR_PIN_INVALID`	Incorrect PIN; retry count can decrease.
`FIDO_ERR_PIN_BLOCKED`	PIN blocked. Do not retry in a loop.
`FIDO_ERR_PIN_AUTH_INVALID`	PIN/UV authorization value rejected.
`FIDO_ERR_PIN_AUTH_BLOCKED`	PIN/UV authorization blocked.
`FIDO_ERR_PIN_NOT_SET`	PIN not configured.
`FIDO_ERR_PIN_REQUIRED`	PIN required for this operation.
`FIDO_ERR_PIN_POLICY_VIOLATION`	PIN violates authenticator policy.
`FIDO_ERR_PIN_TOKEN_EXPIRED`	PIN/UV token expired; obtain fresh authorization.
`FIDO_ERR_UV_BLOCKED`	Built-in user verification blocked.
`FIDO_ERR_UV_INVALID`	User verification unsuccessful.
`FIDO_ERR_UNAUTHORIZED_PERM`	Authorization token lacks required permission.

Symbol	Interpretation
`FIDO_ERR_ERR_OTHER`	Authenticator returned other/unspecified error.
`FIDO_ERR_SPEC_LAST`	Specification range sentinel; not a normal application outcome.

For PIN failures, read fido_dev_get_retry_count() or fido_dev_get_uv_retry_count() only where supported. Never silently repeat a failed PIN.

For transport failures, preserve whether the operation may have completed on the authenticator before attempting a duplicate registration or write.

For verification failures, treat the assertion or credential as unverified. A transport success is not a successful authentication.

fido_strerr() returns a static symbolic string, not an explanatory message. Check the original integer return value and function context.