libfido2 / Operation composition

Operation composition

Four stages: construct host objects; execute CTAP command; inspect result; verify or persist in the application. Constructors and accessors are local.

  1. 01 Open a device
  2. 02 Create a credential
  3. 03 Obtain an assertion
  4. 04 Use an extension
  5. 05 Manage authenticator state
  6. 06 Handle failures and cleanup

01. Identify and open an authenticator

Inputs / state

Initialize library; discover device paths.

Device path.

Conditions

No device path

Enumerate and choose a device.

Feature-dependent operation

Query options, algorithms and extensions after opening.

Calls

Preparefido_init · fido_dev_info_manifest · fido_dev_new
Device operationfido_dev_open

Open first; then query capabilities.

Result

Open device handle; optional capability data.

Next: Credential creation · Authentication · Device management

Failures

Discovery and open fail independently; close the handle afterward.

Sequence and contract

fido_init → fido_dev_info_new → fido_dev_info_manifest → fido_dev_info_ptr → fido_dev_info_path → fido_dev_new → fido_dev_open → fido_dev_get_cbor_info.

Inspect versions, options, extensions, algorithms, and limits. Reported support does not guarantee that an extension works with every credential or transport.

ContractHost

Preconditions

Initialized library; transport access permission.

Inputs

Device path; optional selection filter.

Outputs

Open `fido_dev_t`; optional capability data.

Failures

Discovery/open may fail; device may disappear.

Dependencies

Required
fido_init before relying on library operations; enumerate and select a path before fido_dev_open.
Conditional
fido_dev_get_cbor_info when later behavior depends on advertised algorithms, limits, options or extensions.
Boundary
Enumeration is host-side discovery; fido_dev_open accesses a device; capability query communicates with the authenticator.

02. Make and store a credential

Inputs / state

Open device; RP and user IDs; client-data hash; supported algorithm.

Configured credential request.

Conditions

Resident key, UV or extensions required

Set request policy; check device support.

Attestation trust policy enabled

Verify signature and certificate trust separately.

Calls

Preparefido_cred_new · fido_cred_set_type · fido_cred_set_clientdata_hash · fido_cred_set_rp · fido_cred_set_user
Device operationfido_dev_make_cred

Create credential; read response through accessors.

Result

Credential ID, public key, attestation, and authenticator data.

Next: Attestation verification · Authenticate later

Failures

Unsupported policy/algorithm, PIN/UV, interaction or transport.

Sequence and contract

fido_cred_new → fido_cred_set_type → fido_cred_set_clientdata_hash → fido_cred_set_rp → fido_cred_set_user → optional policy setters → fido_dev_make_cred → examine fido_cred_id_ptr, fido_cred_pubkey_ptr and attestation data → fido_cred_verify.

Persist the credential ID, RP identifier, public key, algorithm, and counter policy. Attestation signature validation and attestation trust-chain validation are separate decisions.

ContractDevice + application

Preconditions

Open device; RP/user IDs; client-data hash; acceptable COSE algorithm.

Inputs

Configured `fido_cred_t`; resident-key/UV policy.

Outputs

Credential ID, public key, attestation/authenticator data.

Failures

Unsupported algorithm/policy, PIN/UV, interaction, transport.

Dependencies

Required
Allocate/configure fido_cred_t before fido_dev_make_cred; retain a verifiable public key and credential identifier afterward.
Conditional
Device capabilities and local policy determine whether PIN/UV, extensions or additional options are needed.
Afterward
fido_cred_verify is local attestation-signature verification; separately decide whether to validate attestation trust.

03. Obtain and verify an assertion

Inputs / state

Open device; RP; client-data hash; registered public key.

Assertion request and trusted verification key.

Conditions

Permitted credential IDs known

Pass an allow-list.

Discoverable credentials used

Allow-list can be omitted.

After assertion retrieval

Verify with stored key; check flags and counter policy separately.

Calls

Preparefido_assert_new · fido_assert_set_rp · fido_assert_set_clientdata_hash · optional fido_assert_allow_cred
Device operationfido_dev_get_assert

Fetch assertions; verify locally.

Result

Authenticator data, signature, credential ID and count.

Next: Assertion verification · Inspect extensions

Failures

No credential, rejected interaction, PIN/UV or verification.

Sequence and contract

fido_assert_new → fido_assert_set_rp → fido_assert_set_clientdata_hash → optional fido_assert_allow_cred → fido_dev_get_assert → inspect fido_assert_count, ID, authenticator data and signature → fido_assert_verify.

Use the stored credential public key for local verification. Apply RP binding, flags, user verification requirements and counter policy as application checks.

ContractDevice + stored state

Preconditions

Open device; RP; client-data hash; registered trusted public key.

Inputs

Configured `fido_assert_t`; optional allow-list and UV policy.

Outputs

Assertions: authenticator data, signature, credential ID.

Failures

No credential, denied interaction, PIN/UV, failed verification.

Dependencies

Required
fido_dev_get_assert produces the result consumed by assertion accessors and fido_assert_verify.
Conditional
Use fido_assert_allow_cred to constrain selection; discoverable-credential flows can omit an allow-list.
External
Signature verification depends on the credential public key stored by the application, not merely on data returned with the assertion.

04. Use an extension

Inputs / state

Open device; parent operation; required extension inputs.

Authenticator support and compatible operation.

Conditions

Support unknown

Inspect capabilities before requesting.

Assertion hmac-secret

Set one/two salts; read returned secret and length.

Extension advertised by device

Support also depends on the credential and request.

Calls

Preparefido_cred_set_extensions / fido_assert_set_extensions · extension-specific setters
Device operationfido_dev_make_cred / fido_dev_get_assert

Extension data is part of the parent command.

Result

Extension data in the parent response.

Next: Credential workflow · Assertion workflow

Failures

Unsupported extension/protocol, missing input or UV mismatch.

Sequence and contract

Read fido_cbor_info_extensions_ptr → configure fido_cred_set_extensions or fido_assert_set_extensions → pass extension-specific inputs → run a credential or assertion operation → inspect its extension output. For HMAC-secret on assertions, supply fido_assert_set_hmac_salt before fido_dev_get_assert, then read fido_assert_hmac_secret_ptr and fido_assert_hmac_secret_len.

ContractRequest-specific

Preconditions

Device support and compatible parent operation.

Inputs

Extension flags/inputs; hmac-secret requires one/two salts.

Outputs

Extension output attached to credential/assertion.

Failures

Unsupported extension/protocol, missing input, PIN/UV mismatch.

Dependencies

Required
Attach the extension to a credential/assertion request; execute that request before reading output.
Conditional
For assertion HMAC-secret, call fido_assert_set_hmac_salt before fido_dev_get_assert and inspect the returned secret and length afterward.
Boundary
Advertising an extension is capability information, not proof that a particular credential and invocation will succeed.

05. Manage authenticator state

Inputs / state

Compatible open device; appropriate authorization.

Supported management capability and target resource.

Conditions

Resident credential management

Read metadata/RPs/credentials before modification.

Biometric enrollment

Begin, then continue to completion.

Operation changes persistent state

Writes may partially complete; verify state before retry.

Calls

Preparefido_credman_get_dev_metadata / fido_bio_dev_get_info
Device operationfido_credman_* / fido_bio_dev_enroll_* / configuration operations

Use separate commands for each management operation.

Result

Metadata, state change or enrollment progress.

Next: Credential operations · Device error handling

Failures

Authorization, unsupported operation, interruption or partial enrollment.

Sequence and contract

fido_credman_get_dev_metadata → fido_credman_get_dev_rp → fido_credman_get_dev_rk → optionally fido_credman_set_dev_rk / fido_credman_del_dev_rk. Biometric enrollment uses fido_bio_dev_get_info → fido_bio_dev_enroll_begin → fido_bio_dev_enroll_continue until complete. Configuration calls are distinct from routine credential operations.

ContractDevice administration

Preconditions

Open compatible device; required authorization.

Inputs

Management request and target RP/credential/template.

Outputs

Metadata, credential/configuration changes, enrollment progress.

Failures

Permission/UV, unsupported operations, incomplete/interrupted changes.

Dependencies

Required
Discover the relevant management capability and read state before modifying or deleting entries.
Conditional
Resident-credential operations require the credential-management path; biometric enrollment proceeds through repeated continuation calls until completion.
Effect
These operations can change persistent authenticator state; unlike assertion verification, they are not read-only.

06. Handle errors and cleanup

Inputs / state

Return code and allocated-resource inventory.

Return code, phase and possible state change.

Conditions

Host I/O error

Separate transport failure from CTAP status.

Retry repeats mutation or PIN entry

Establish retry safety first.

Early exit

Release every owned handle/object.

Calls

PrepareCheck every return code · retain operation context
Local error formattingfido_strerr

Format error; retry policy remains in the application.

Result

Classified error and resource cleanup.

Next: Error reference · Device lifecycle

Failures

Repeated writes, leaked objects, or missing error context.

Sequence and contract

Preserve the integer return code from each operation, render with fido_strerr, distinguish host I/O errors from CTAP status codes, and release objects on every exit path. Retry decisions depend on error class; PIN failures and state-changing operations require special care.

ContractEvery operation

Preconditions

Return code and ownership of allocated objects.

Inputs

Original return code; operation/phase context.

Outputs

Error classification and resource cleanup.

Failures

Lost context, unsafe retries, leaks, repeated non-idempotent operations.

Dependencies

Required
Check returned status at each operation boundary; release allocated objects even after failures.
Conditional
Distinguish host/transport failures from CTAP status; choose retry behavior only after identifying the failure class.
External
fido_strerr formats an error. It does not resolve a failure or establish that retrying is safe.