FIDO2 Authenticator

Overview

The FIDO2 authenticator subsystem implements the FIDO2 CTAP2 Specification (Client to Authenticator Protocol), allowing a Zephyr device to act as a hardware security key for passwordless authentication. The subsystem can be enabled with the CONFIG_FIDO2 option.

FIDO2 security keys are used with the WebAuthn Specification web standard. A relying party (website or service) interacts with the authenticator through a client (browser or OS platform) to register and verify user credentials. The authenticator performs cryptographic operations using on-device keys that never leave the hardware.

The subsystem currently supports the following CTAP2 commands:

authenticatorMakeCredential
authenticatorGetAssertion
authenticatorGetInfo
authenticatorGetNextAssertion
authenticatorSelection

Architecture

The subsystem is organized into pluggable backend components, each selectable at build time via Kconfig:

Transport

Handles wire-protocol communication between the host and the authenticator. Transports are registered using the FIDO2_TRANSPORT_DEFINE macro and are iterated at startup. Available transports:

USB HID (CTAPHID) — CONFIG_FIDO2_TRANSPORT_USB_HID

User Presence (UP)

Confirms that a human is physically present. Backends are selected via CONFIG_FIDO2_UP_BACKEND:

Input device — CONFIG_FIDO2_UP_INPUT
Always approve — CONFIG_FIDO2_UP_ALWAYS
Custom — CONFIG_FIDO2_UP_CUSTOM (application-provided)

Credential Storage

Persists discoverable (resident) credentials. Backends are selected via CONFIG_FIDO2_STORAGE_BACKEND:

Settings subsystem — CONFIG_FIDO2_STORAGE_SETTINGS
None — CONFIG_FIDO2_STORAGE_NONE (non-discoverable credentials only)

Attestation

Signs newly created credentials to prove their origin. Backends are selected via CONFIG_FIDO2_ATTESTATION_BACKEND:

Self attestation — CONFIG_FIDO2_ATTESTATION_SELF (default)
None — CONFIG_FIDO2_ATTESTATION_NONE
Custom — CONFIG_FIDO2_ATTESTATION_CUSTOM (application-provided)

Usage

To use the FIDO2 subsystem, include the main header:

#include <zephyr/authentication/fido2/fido2.h>

Basic Initialization

At least one transport must be enabled for the authenticator to communicate with a host.

See FIDO2 Authenticator for a complete initialization sequence.

Runtime State Monitoring

The subsystem exposes a runtime state callback that applications can use to drive status indicators such as LEDs:

#include <zephyr/authentication/fido2/fido2.h>

static void on_state_change(enum fido2_runtime_state state, void *user_data)
{
    switch (state) {
    case FIDO2_RUNTIME_STATE_IDLE:
        /* LED off */
        break;
    case FIDO2_RUNTIME_STATE_WAITING_USER_PRESENCE:
        /* Blink LED */
        break;
    case FIDO2_RUNTIME_STATE_PROCESSING:
        /* LED on solid */
        break;
    default:
        break;
    }
}

fido2_set_state_callback(on_state_change, NULL);