Python-FIDO2

https://github.com/yubico/python-fido2
Admin
A Python library for FIDO2 authentication, enabling secure and passwordless logins using hardware...
Tokens:163,563
Snippets:1,018
Trust Score:9.7
License:BSD-2-Clause
Update:1 week ago
Show doc for...
Tokens:
Raw
### Set up and run the WebAuthn server

Source: https://github.com/yubico/python-fido2/blob/main/examples/server/README.adoc

Set up the example environment and start the WebAuthn server. Requires `uv`. Both commands are run in the `examples/server` directory.

```shell
$ uv sync
```

```shell
$ uv run server
```

--------------------------------

### Usage Example

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/extensions.md

An example showing how to create a Fido2Client with custom extensions and use them during credential creation, including accessing extension outputs.

```APIDOC
## Usage Example

### Description
Demonstrates how to instantiate a Fido2Client with custom extensions and use them in a registration flow, including reading extension results.

### Code
```python
from fido2.client import DefaultClientDataCollector, Fido2Client, UserInteraction
from fido2.ctap2.extensions import HmacSecretExtension, LargeBlobExtension
from fido2.server import Fido2Server

client = Fido2Client(
    device,
    client_data_collector=DefaultClientDataCollector("https://example.com"),
    user_interaction=UserInteraction(),
    extensions=[HmacSecretExtension(), LargeBlobExtension()],
)

create_options, state = server.register_begin(user)
create_options["publicKey"]["extensions"] = {
    "prf": {"eval": {"first": b"salt-1"}},
    "largeBlob": {"support": "preferred"},
}
result = client.make_credential(create_options["publicKey"])

# Extension outputs are surfaced per-key
prf = result.response.client_extension_results["prf"]
print(prf["enabled"], prf["results"]["first"].hex())
```
```

--------------------------------

### Install u2f-devd on FreeBSD

Source: https://github.com/yubico/python-fido2/blob/main/README.adoc

Install the u2f-devd package on FreeBSD to automate adding device rules for FIDO support.

```bash
# pkg install u2f-devd
```

--------------------------------

### Usage example with Fido2Client and extensions

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/extensions.md

Shows how to create a Fido2Client with custom extensions and use them during registration. The example sets PRF and largeBlob extension options and prints the PRF result.

```python
from fido2.client import DefaultClientDataCollector, Fido2Client, UserInteraction
from fido2.ctap2.extensions import HmacSecretExtension, LargeBlobExtension
from fido2.server import Fido2Server

client = Fido2Client(
    device,
    client_data_collector=DefaultClientDataCollector("https://example.com"),
    user_interaction=UserInteraction(),
    extensions=[HmacSecretExtension(), LargeBlobExtension()],
)

create_options, state = server.register_begin(user)
create_options["publicKey"]["extensions"] = {
    "prf": {"eval": {"first": b"salt-1"}},
    "largeBlob": {"support": "preferred"},
}
result = client.make_credential(create_options["publicKey"])

# Extension outputs are surfaced per-key
prf = result.response.client_extension_results["prf"]
print(prf["enabled"], prf["results"]["first"].hex())
```

--------------------------------

### enroll_begin(timeout=None, event=None, on_keepalive=None)

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/bio.md

Starts the enrollment process and waits for the first fingerprint sample.

```APIDOC
## enroll_begin(timeout=None, event=None, on_keepalive=None)

### Description
Starts enrollment and waits for the first sample.

### Parameters
- `timeout` (int | None) - Optional - Timeout in milliseconds.
- `event` (threading.Event | None) - Optional - Cancellation event.
- `on_keepalive` (Callable[[int], None] | None) - Optional - Keep-alive callback.

### Returns
tuple[bytes, FPBioEnrollment.FEEDBACK, int] - `(template_id, sample_status, samples_remaining)`.
```

--------------------------------

### Install fido2 with PC/SC support

Source: https://github.com/yubico/python-fido2/blob/main/README.adoc

Install fido2 with the optional dependencies required for NFC authenticator communication via PC/SC.

```bash
pip install fido2[pcsc]
```

--------------------------------

### POST /api/authenticate/begin

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/endpoints.md

Starts the WebAuthn authentication process. It calls Fido2Server.authenticate_begin with the stored credentials and stores the state in the session.

```APIDOC
## POST /api/authenticate/begin

### Description
Starts the WebAuthn authentication process. It calls Fido2Server.authenticate_begin with the stored credentials and stores the state in the session.

### Method
POST

### Endpoint
/api/authenticate/begin

### Parameters
#### Request Body
None

### Response
#### Success Response (200)
- **publicKey** (object) - CredentialRequestOptions JSON for navigator.credentials.get()

#### Response Example
{
  "publicKey": {}
}

### Errors
- **404** - If no credentials are stored

```

--------------------------------

### Install fido2 with pip

Source: https://github.com/yubico/python-fido2/blob/main/README.adoc

Install the fido2 library using pip. Use this command to install the base package.

```bash
pip install fido2
```

--------------------------------

### POST /api/register/begin

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/endpoints.md

Starts the WebAuthn registration process. It calls Fido2Server.register_begin with a hard-coded user entity and stores the state in the session.

```APIDOC
## POST /api/register/begin

### Description
Starts the WebAuthn registration process. It calls Fido2Server.register_begin with a hard-coded user entity and stores the state in the session.

### Method
POST

### Endpoint
/api/register/begin

### Parameters
#### Request Body
None used (user is hard-coded)

### Response
#### Success Response (200)
- **publicKey** (object) - CredentialCreationOptions JSON for navigator.credentials.create()

#### Response Example
{
  "publicKey": {}
}

```

--------------------------------

### Usage example for fido2.utils functions

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/utils.md

Shows how to use websafe_encode, websafe_decode, sha256, int2bytes, and bytes2int. Demonstrates encoding/decoding round-trip and zero-padded integer conversion.

```python
from fido2.utils import sha256, int2bytes, bytes2int, websafe_encode, websafe_decode

print(websafe_encode(b"\xfb\xff"))          # "-_8"
assert websafe_decode("-_8") == b"\xfb\xff"

rp_id_hash = sha256(b"example.com")
encoded = int2bytes(rp_id_hash[0], 32)      # zero-padded to 32 bytes
assert bytes2int(encoded) == rp_id_hash[0]
```

--------------------------------

### authenticate_begin

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/server.md

Starts a WebAuthn authentication ceremony. It takes optional credentials and other parameters to generate credential request options and an opaque state dict.

```APIDOC
## authenticate_begin(credentials=None, user_verification=None, challenge=None, extensions=None) -> tuple[CredentialRequestOptions, Any]

### Description
Starts a WebAuthn authentication ceremony. It takes optional credentials and other parameters to generate credential request options and an opaque state dict.

### Method
authenticate_begin

### Parameters
- **credentials** (Sequence[AttestedCredentialData | PublicKeyCredentialDescriptor] | None) - Optional - Registered credentials → `allowCredentials`.
- **user_verification** (UserVerificationRequirement | None) - Optional - Desired UV level.
- **challenge** (bytes | None) - Optional - Custom challenge (default random 32 bytes).
- **extensions** (untyped) - Optional - Extension inputs.

### Returns
`(CredentialRequestOptions, state)`.
```

--------------------------------

### Get assertion and select response

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/client.md

Performs authentication by calling get_assertion, enumerating all returned assertions to print their credential IDs, and selecting the first response. Uses the same client as the previous example.

```python
selection = client.get_assertion(request_options["publicKey"])
for i, assertion in enumerate(selection.get_assertions()):
    print(i, assertion.credential["id"].hex())
response = selection.get_response(0)   # pick one

```

--------------------------------

### register_begin

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/server.md

Starts a WebAuthn registration ceremony. It takes user information and optional parameters to generate credential creation options and an opaque state dict for later verification.

```APIDOC
## register_begin(user, credentials=None, resident_key_requirement=None, user_verification=None, authenticator_attachment=None, challenge=None, extensions=None)

### Description
Starts a WebAuthn registration ceremony. It takes user information and optional parameters to generate credential creation options and an opaque state dict for later verification.

### Method
register_begin

### Parameters
- **user** (PublicKeyCredentialUserEntity or dict) - Required - User entity.
- **credentials** (Sequence[AttestedCredentialData | PublicKeyCredentialDescriptor] | None) - Optional - Previously registered credentials → `excludeCredentials`.
- **resident_key_requirement** (ResidentKeyRequirement | None) - Optional - Desired resident-key level.
- **user_verification** (UserVerificationRequirement | None) - Optional - Desired UV level.
- **authenticator_attachment** (AuthenticatorAttachment | None) - Optional - Desired attachment preference.
- **challenge** (bytes | None) - Optional - Custom challenge; default is `os.urandom(32)`.
- **extensions** (untyped) - Optional - Extension inputs included in the options.

### Returns
`(CredentialCreationOptions, state)` where `state` is an opaque dict (`{"challenge": websafe-encoded, "user_verification": ...}`) that must be passed unchanged to `register_complete`.

### Raises
- `ValueError("Server has no allowed algorithms.")` if `allowed_algorithms` is empty.
- `TypeError`/`ValueError` from challenge validation (bytes required, length ≥ 16).
```

--------------------------------

### Usage example

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/cbor.md

Demonstrates round-trip encoding/decoding, decoding with trailing data, canonical key ordering, and handling of unsupported types.

```python
from fido2 import cbor

# Round trip
original = {1: "rp", 2: b"\x01\x02", 3: [True, -7]}
blob = cbor.encode(original)
assert cbor.decode(blob) == original

# Decode with trailing data (used by AuthenticatorData/AttestedCredentialData)
value, rest = cbor.decode_from(blob + b"\x00\x00")
assert rest == b"\x00\x00"

# Key ordering is canonical: {"b": 1, "a": 2} sorts as a-then-b
assert cbor.encode({"b": 1, "a": 2}) < cbor.encode({"a": 1, "b": 2})

try:
    cbor.encode(object())
except ValueError as e:
    print("Unsupported type:", e)
```

--------------------------------

### PaymentClientDataCollector with Fido2Client and ThirdPartyPaymentExtension

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/payment.md

Shows how to instantiate Fido2Client with PaymentClientDataCollector and ThirdPartyPaymentExtension, then create a credential with payment extension data. The example includes setting the payment extension in create_options and printing the client data response.

```python
from fido2.client import Fido2Client, UserInteraction
from fido2.ctap2.extensions import (
    ThirdPartyPaymentExtension,
    AuthenticationExtensionsPaymentInputs,
    PaymentCurrencyAmount,
    PaymentCredentialInstrument,
)
from fido2.payment import PaymentClientDataCollector
from fido2.server import Fido2Server

server = Fido2Server({"id": "example.com", "name": "Example"})
client = Fido2Client(
    device,
    client_data_collector=PaymentClientDataCollector("https://example.com"),
    user_interaction=UserInteraction(),
    extensions=[ThirdPartyPaymentExtension()],
)

create_options, state = server.register_begin(
    user, resident_key_requirement="required", user_verification="required"
)
create_options["publicKey"]["extensions"] = {
    "payment": {
        "is_payment": True,
        "rp_id": "example.com",
        "top_origin": "https://example.com",
        "payee_name": "Merchant",
        "payee_origin": "https://merchant.example.com",
        "total": {"currency": "USD", "value": "1.00"},
        "instrument": {
            "display_name": "Visa •••• 4242",
            "icon": "https://example.com/icon.png",
            "icon_must_be_shown": True,
        },
    }
}

result = client.make_credential(create_options["publicKey"])
print(result.response.client_data)  # includes the "payment" member
```

--------------------------------

### Usage example for parse_blob

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/mds3.md

Shows how to parse an MDS3 blob, create an MdsAttestationVerifier, and configure a Fido2Server. Also demonstrates using find_entry to inspect a device after an unsuccessful verification.

```python
from fido2.mds3 import parse_blob, MdsAttestationVerifier
from fido2.server import Fido2Server

# blob_bytes from https://fidoalliance.org/metadata/ , trust root from the same page
payload = parse_blob(blob_bytes, mds_trust_root_ca_der)
print("Next update:", payload.next_update)

verifier = MdsAttestationVerifier(payload)  # defaults: revoked + compromised filters

server = Fido2Server(
    {"id": "example.com", "name": "Example"},
    attestation="direct",
    verify_attestation=verifier,
)

# or, after an unsuccessful verify, inspect which device was (not) trusted:
entry = verifier.find_entry(attestation_object, client_data_hash)  # None if untrusted
```

--------------------------------

### Usage example for verify_rp_id

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/utils.md

Shows how to use `verify_rp_id` with various RP IDs and origins, including secure and non-secure contexts, public suffixes, and localhost.

```python
from fido2.rpid import verify_rp_id

assert verify_rp_id("example.com", "https://example.com")
assert verify_rp_id("example.com", "https://login.example.com")
assert not verify_rp_id("com", "https://anything.com")           # com is a public suffix
assert not verify_rp_id("example.com", "https://evil-example.com")
assert not verify_rp_id("example.com", "http://example.com")     # not a secure context
assert verify_rp_id("localhost", "http://localhost:5000")
```

--------------------------------

### Full registration flow with Fido2Server

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/server.md

Shows the complete WebAuthn registration flow: create a Fido2Server with an RP entity and attestation type, generate registration options with register_begin, and verify the browser's response with register_complete. The example includes error handling for ValueError and storing the resulting credential.

```python
from fido2.server import Fido2Server
from fido2.webauthn import (
    PublicKeyCredentialRpEntity, PublicKeyCredentialUserEntity,
    UserVerificationRequirement,
)

server = Fido2Server(
    PublicKeyCredentialRpEntity(id="example.com", name="Example RP"),
    attestation="direct",
)

user = PublicKeyCredentialUserEntity(id=b"user-1", name="Alice")

# 1. Generate options for the client
create_options, state = server.register_begin(
    user, user_verification=UserVerificationRequirement.PREFERRED
)
# send dict(create_options) to the browser, store `state` server-side

# 2. Verify the browser's response
try:
    auth_data = server.register_complete(state, response_from_browser)
except ValueError as e:
    # The exact check that failed is in the message, e.g.:
    # "Wrong challenge in response.", "Invalid origin in CollectedClientData."
    handle_failure(e)
else:
    credential = auth_data.credential_data  # store for later authentication
```

--------------------------------

### Fido2Server.__init__(rp, attestation=None, verify_origin=None, verify_attestation=None)

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/server.md

Initializes a Fido2Server instance with relying party data and optional configuration for attestation and origin verification.

```APIDOC
## Fido2Server.__init__(rp, attestation=None, verify_origin=None, verify_attestation=None)

### Description
Initializes a Fido2Server instance with relying party data and optional configuration for attestation and origin verification.

### Method
Constructor

### Endpoint
`Fido2Server(rp: PublicKeyCredentialRpEntity, attestation: AttestationConveyancePreference | None = None, verify_origin: VerifyOrigin | None = None, verify_attestation: VerifyAttestation | None = None)`

### Parameters
- **rp** (PublicKeyCredentialRpEntity or dict) - Required - Relying party data; `id` must not be `None` (asserted).
- **attestation** (AttestationConveyancePreference | None) - Optional - Attestation requirement propagated to `register_begin`; `"none"`/`None` disables attestation verification.
- **verify_origin** (VerifyOrigin | None) - Optional - Custom origin validator; default derives from `rp.id` via the public-suffix algorithm.
- **verify_attestation** (VerifyAttestation | None) - Optional - Attestation verifier, e.g. a subclass of `AttestationVerifier` or `MdsAttestationVerifier`; default ignores attestation.

### Instance Attributes
- **rp** (PublicKeyCredentialRpEntity) - Normalized RP entity.
- **timeout** (int | None) - Applied as `timeout` in generated options (default `None`).
- **attestation** (AttestationConveyancePreference) - Coerced via the enum constructor.
- **allowed_algorithms** (list[PublicKeyCredentialParameters]) - Built from `CoseKey.supported_algorithms()` — used as `pub_key_cred_params`.
```

--------------------------------

### GET /

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/endpoints.md

Redirects to the static index page. No request parameters are required.

```APIDOC
## GET /

### Description
Redirects to the static index page.

### Method
GET

### Endpoint
/

### Response
#### Success Response (302)
Redirect to /index.html

```

--------------------------------

### WebAuthnClient.get_assertion

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/client.md

Abstract method to get an assertion using the WebAuthn client. Implemented by Fido2Client and WindowsClient.

```APIDOC
## get_assertion

### Description
Gets an assertion using the WebAuthn client. This is an abstract method implemented by concrete clients.

### Method
`get_assertion`

### Signature
`(options: PublicKeyCredentialRequestOptions, event: Event | None = None) -> AssertionSelection`

### Parameters
#### Request Body
- **options** (PublicKeyCredentialRequestOptions) - Required - The options for requesting an assertion.
- **event** (Event | None) - Optional - An event for cancellation or progress.

### Returns
- **AssertionSelection** - The assertion selection result.
```

--------------------------------

### Enumerate HID devices and use CTAP2 capabilities

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/hid.md

Lists all CTAP HID devices, prints their path and product name, and if the device supports CBOR, retrieves and prints CTAP2 info. Also winks if the device supports the WINK capability, then closes the device.

```python
from fido2.hid import CtapHidDevice, CAPABILITY
from fido2.ctap2 import Ctap2

for dev in CtapHidDevice.list_devices():
    print(dev.descriptor.path, dev.product_name)
    if dev.capabilities & CAPABILITY.CBOR:
        ctap2 = Ctap2(dev)
        print("CTAP2 info:", ctap2.info)
    if dev.capabilities & CAPABILITY.WINK:
        dev.wink()
    dev.close()
```

--------------------------------

### Aaguid

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/webauthn.md

A 16-byte binary type representing an Authenticator Attestation GUID, with parsing and string conversion.

```APIDOC
## Aaguid

### Description
A 16-byte binary type representing an Authenticator Attestation GUID (AAGUID). Provides parsing from hex strings and UUID-form string representation.

### Constructor
- **data** (bytes) - Required - Must be exactly 16 bytes, otherwise raises `ValueError`.

### Class Attributes
- **NONE** (Aaguid) - The all-zero AAGUID value (`Aaguid(b"\0" * 16)`).

### Methods
- **parse(value: str) -> Aaguid** - Class method. Parses a dashed or undashed hex string into an `Aaguid`.
- **__bool__() -> bool** - Returns `False` for `Aaguid.NONE`, `True` otherwise.
- **__str__() -> str** - Returns the UUID form string (e.g., `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`).

### Example
```python
from fido2.webauthn import Aaguid

aaguid = Aaguid.parse("00000000-0000-0000-0000-000000000000")
print(bool(aaguid))  # False
print(str(aaguid))   # "00000000-0000-0000-0000-000000000000"
```
```

--------------------------------

### Fido2Client.__init__

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/client.md

Initializes a Fido2Client instance with a CTAP device, client data collector, user interaction callbacks, and optional extensions. Selects the appropriate backend (CTAP2 or CTAP1) based on device capabilities.

```APIDOC
## Fido2Client.__init__

### Description
Initializes a Fido2Client instance with a CTAP device, client data collector, user interaction callbacks, and optional extensions. Selects the appropriate backend (CTAP2 or CTAP1) based on device capabilities.

### Method
Constructor

### Signature
```python
Fido2Client(
    device: CtapDevice,
    client_data_collector: ClientDataCollector,
    user_interaction: UserInteraction = UserInteraction(),
    extensions: Sequence[Ctap2Extension] = _DEFAULT_EXTENSIONS
)
```

### Parameters
- **device** (CtapDevice) - Required - Transport to use.
- **client_data_collector** (ClientDataCollector) - Required - Supplies client data and RP ID.
- **user_interaction** (UserInteraction) - Optional - User prompting callbacks. Default: `UserInteraction()`.
- **extensions** (Sequence[Ctap2Extension]) - Optional - Active extension processors. Default: `_DEFAULT_EXTENSIONS`.

### Description
Backend selection: tries the CTAP2 backend (which itself queries `getInfo`); on `ValueError` (no CBOR) or `CtapError` it falls back to the CTAP1/U2F backend.
```

--------------------------------

### decode_from function

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/cbor.md

Decodes a CBOR-encoded value from the start of a byte string, returning the decoded object and any remaining data.

```python
def decode_from(data: bytes) -> tuple[Any, bytes]:
    """Decodes a CBOR-encoded value from the start of a byte string.

    Additional data after a valid CBOR object is returned as well.

    :return: The decoded object, and any remaining data."""
    fb = data[0]
    return _DESERIALIZERS[fb >> 5](fb & 0b11111, data[1:])
```

--------------------------------

### WindowsClient.__init__

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/client.md

Initializes a WindowsClient instance with a client data collector, optional window handle, and optional hmac-secret support.

```APIDOC
## WindowsClient.__init__

### Description
Initializes a WindowsClient instance, which uses the Windows WebAuthn API. This class only works on Windows 10 19H1 or later.

### Method
Constructor

### Parameters
- **client_data_collector** (ClientDataCollector) - Required - As Fido2Client.
- **handle** (ctypes.wintypes.HWND) - Optional - Window handle for the WebAuthn UI. Defaults to the foreground window.
- **allow_hmac_secret** (bool) - Optional - Enable hmac-secret handling. Defaults to False.

### Request Example
```python
from fido2.client import DefaultClientDataCollector
from fido2.client.windows import WindowsClient

client = WindowsClient(
    client_data_collector=DefaultClientDataCollector("https://example.com"),
    handle=None,
    allow_hmac_secret=False,
)
```

### Response
No return value.
```

--------------------------------

### Build release with uv

Source: https://github.com/yubico/python-fido2/blob/main/RELEASE.adoc

Builds the distribution artifacts using uv.

```shell
$ uv build
```

--------------------------------

### Custom CA-only verifier

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/attestation.md

Example of subclassing AttestationVerifier to override ca_lookup and return a single trusted root CA, then using it with Fido2Server for direct attestation.

```APIDOC
## Custom CA-only verifier

### Description
This example shows how to create a custom AttestationVerifier that trusts a single CA root by overriding the `ca_lookup` method, and how to configure a Fido2Server to use it for direct attestation verification.

### Class
`fido2.attestation.AttestationVerifier`

### Method
`ca_lookup(self, result, auth_data)`

### Parameters
- **result** - The attestation statement result.
- **auth_data** - The authenticator data.

### Returns
- **bytes** - The DER-encoded trusted root CA.

### Usage Example
```python
from fido2.attestation import AttestationVerifier
from fido2.server import Fido2Server

class YubicoVerifier(AttestationVerifier):
    def ca_lookup(self, result, auth_data):
        return YUBICO_ROOT_CA_DER  # bytes: a single trusted root

server = Fido2Server(
    {"id": "example.com", "name": "Example"},
    attestation="direct",
    verify_attestation=YubicoVerifier(),
)

try:
    server.register_complete(state, response)
except Exception as e:
    # e may be InvalidSignature, InvalidData, UntrustedAttestation,
    # UnsupportedType, NotImplementedError (ECDAA), or ValueError
    if isinstance(e, UntrustedAttestation):
        print("Attestation could not be trusted:", e)
```

### Exceptions
- `InvalidSignature` - Raised when the attestation signature is invalid.
- `InvalidData` - Raised when the attestation data is malformed.
- `UntrustedAttestation` - Raised when the attestation cannot be trusted.
- `UnsupportedType` - Raised when the attestation type is unsupported.
- `NotImplementedError` - Raised for ECDAA attestation.
- `ValueError` - Raised for other validation errors.
```

--------------------------------

### Create Fido2Client and make credential with PIN handling

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/client.md

Implements the client half of a WebAuthn flow: sets up a Fido2Client with a custom CliInteraction that returns None on PIN cancel, makes a credential, and handles DEVICE_INELIGIBLE and TIMEOUT errors. Prints client options and the new credential raw ID.

```python
from fido2.client import DefaultClientDataCollector, Fido2Client, UserInteraction, ClientError
from fido2.hid import CtapHidDevice

class CliInteraction(UserInteraction):
    def request_pin(self, permissions, rp_id):
        return input("PIN: ") or None   # None cancels -> PinRequiredError

dev = next(CtapHidDevice.list_devices())
client = Fido2Client(
    dev,
    client_data_collector=DefaultClientDataCollector("https://example.com"),
    user_interaction=CliInteraction(),
)
print(client.info.options)  # e.g. {"rk": True, "clientPin": True}

try:
    result = client.make_credential(create_options["publicKey"])
    print("New credential:", result.raw_id.hex())
    dev.close()
except ClientError as e:
    if e.code == ClientError.ERR.DEVICE_INELIGIBLE:
        print("Credential already exists or device declined")
    elif e.code == ClientError.ERR.TIMEOUT:
        print("Operation timed out")

```

--------------------------------

### Attestation class

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/attestation.md

Abstract base class for attestation verification. Provides an abstract verify method and a static for_type method to get an Attestation subclass for a given format.

```APIDOC
## Attestation class

### Description
Implements verification of a specific attestation type. Abstract base class.

### Methods

#### verify(statement, auth_data, client_data_hash) -> AttestationResult

##### Description
Verifies attestation statement.

##### Parameters
- **statement** (Mapping[str, Any]) - Required - The attestation statement.
- **auth_data** (AuthenticatorData) - Required - The authenticator data.
- **client_data_hash** (bytes) - Required - The client data hash.

##### Returns
- **AttestationResult** - An AttestationResult if successful.

#### for_type(fmt: str) -> type[Attestation]

##### Description
Get an Attestation subclass type for the given format.

##### Parameters
- **fmt** (str) - Required - The attestation format identifier.

##### Returns
- **type[Attestation]** - The subclass whose FORMAT matches, or a TypedUnsupportedAttestation subtype whose verify raises UnsupportedType(auth_data, fmt).
```

--------------------------------

### Discover CTAP2 devices and print info

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/ctap2.md

Lists CTAP2-capable HID devices, creates a Ctap2 instance, and prints the AAGUID and options. Throws ValueError if the device is not CTAP2-capable.

```python
from fido2.hid import CtapHidDevice
from fido2.ctap2 import Ctap2

for dev in CtapHidDevice.list_devices():
    ctap2 = Ctap2(dev)  # throws ValueError if the device is not CTAP2-capable
    info = ctap2.info
    print("AAGUID:", info.aaguid)
    print("Options:", info.options)
    dev.close()
```

--------------------------------

### Run tests with uv

Source: https://github.com/yubico/python-fido2/blob/main/README.adoc

Run the test suite using uv. Note that most tests require a connected FIDO2 device and are destructive, factory resetting the device under test.

```bash
uv run pytest
```

--------------------------------

### Large blob read/write

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/management.md

Shows large blob read/write operations using the LargeBlobs class. Requires a PIN with the LARGE_BLOB_WRITE permission. The example writes, reads, and deletes a blob identified by a largeBlobKey.

```python
from fido2.ctap2 import Ctap2, ClientPin, LargeBlobs

ctap2 = Ctap2(dev)
client_pin = ClientPin(ctap2)
token = client_pin.get_pin_token("1234", ClientPin.PERMISSION.LARGE_BLOB_WRITE)

blobs = LargeBlobs(ctap2, client_pin.protocol, token)

# Write a blob for a credential identified by its largeBlobKey
blobs.put_blob(large_blob_key, b"my backup data")

# Read it back
data = blobs.get_blob(large_blob_key)

# Delete it
blobs.delete_blob(large_blob_key)
```

--------------------------------

### Fido2Server.register_begin

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/server.md

Generates registration options for the client. Takes a user entity and optional user verification requirement, returning a dictionary of options and a state object to be stored server-side.

```APIDOC
## Fido2Server.register_begin

### Description
Generates options for the client to initiate a WebAuthn registration ceremony. Returns a dictionary of options to send to the browser and a state object to store server-side.

### Method
register_begin

### Parameters
- **user** (PublicKeyCredentialUserEntity) - Required - The user entity containing user ID and name.
- **user_verification** (UserVerificationRequirement) - Optional - The user verification requirement (e.g., PREFERRED).

### Returns
- **create_options** (dict) - Options to send to the browser.
- **state** - State to store server-side for later verification.

### Example
```python
create_options, state = server.register_begin(
    user, user_verification=UserVerificationRequirement.PREFERRED
)
```
```

--------------------------------

### Enumerate NFC readers and get CTAP2 info with CtapPcscDevice

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/pcsc.md

Lists NFC readers via CtapPcscDevice.list_devices(), prints the reader name and ATR, and checks the CBOR capability to retrieve CTAP2 info. Each device is closed after use.

```python
from fido2.ctap2 import Ctap2
from fido2.pcsc import CtapPcscDevice
from fido2.hid import CAPABILITY

# List NFC readers in use
for dev in CtapPcscDevice.list_devices():
    print("READER:", dev)
    print("ATR:", dev.get_atr().hex())
    if CAPABILITY.CBOR in dev.capabilities:
        ctap2 = Ctap2(dev)
        print("CTAP2 info:", ctap2.info)
    dev.close()
```

--------------------------------

### ClientPin Constructor

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/configuration.md

Creates a ClientPin object for managing PIN and UV protocols.

```APIDOC
## Constructor: ClientPin

### Description
Creates a ClientPin instance for PIN/UV protocol operations.

### Method
Constructor

### Endpoint
ClientPin(protocol=None)

### Parameters
#### Constructor Parameters
- **protocol** (PinProtocol | None) - Optional - Default: None - Explicit PIN/UV protocol; None negotiates V2 then V1 against info.pin_uv_protocols.

### Response
#### Success Response
- **ClientPin** (ClientPin) - The instantiated client PIN object.

```

--------------------------------

### decode_from(data: bytes) -> tuple[Any, bytes]

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/cbor.md

Decodes a CBOR-encoded value from the start of a byte string, returning the decoded object and any remaining data. Supports major types 0, 1, 2, 3, 4, 5, and 7.

```APIDOC
## decode_from(data: bytes) -> tuple[Any, bytes]

### Description
Decodes a CBOR-encoded value from the start of a byte string. Additional data after a valid CBOR object is returned as well.

### Method
Function

### Signature
```python
def decode_from(data: bytes) -> tuple[Any, bytes]:
```

### Parameters
- **data** (bytes) - Required - The CBOR-encoded byte string.

### Returns
- **tuple[Any, bytes]** - A tuple containing the decoded object and any remaining bytes.

### Supported Major Types
- 0 (uint)
- 1 (nint)
- 2 (bytes)
- 3 (text)
- 4 (array)
- 5 (map)
- 7 (bool; other type-7 values raise `ValueError("Invalid additional information")`)

### Example
```python
value, rest = cbor.decode_from(blob + b"\x00\x00")
assert rest == b"\x00\x00"
```
```

--------------------------------

### Config(ctap, pin_uv_protocol=None, pin_uv_token=None)

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/management.md

Constructor for the Config class. Initializes the configuration API with a CTAP2 instance and optional PIN/UV protocol and token.

```APIDOC
## Config(ctap, pin_uv_protocol=None, pin_uv_token=None)

### Description
Initializes the Config object for the CTAP2.1 Authenticator Config API.

### Parameters
- `ctap` (Ctap2) - Required - CTAP2 instance.
- `pin_uv_protocol` (PinProtocol | None) - Optional - Required for authenticated subcommands.
- `pin_uv_token` (bytes | None) - Optional - PIN/UV token with AUTHENTICATOR_CFG permission.

### Raises
- `ValueError` - If the authenticator does not support Config (info.options["authnrCfg"] not set).
- `ValueError` - If a subcommand is not supported by the authenticator (when info.authenticator_config_commands is present and does not include the subcommand).
```

--------------------------------

### Parse COSE key and convert cryptography key

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/cose.md

Shows how to parse a COSE key from an authenticator using CoseKey.parse, verify a signature, and convert a cryptography key to an ES256 COSE key. The example prints the key type and algorithm, and catches InvalidSignature exceptions.

```python
from fido2.cose import CoseKey, ES256
from cryptography.hazmat.primitives.asymmetric import ec

# Parse a COSE key from an authenticator
cose = {1: 2, 3: -7, -1: 1,
        -2: b"\x5f" * 32, -3: b"\x0a" * 32}
key = CoseKey.parse(cose)
print(type(key).__name__)          # ES256

try:
    key.verify(message, signature)  # raises InvalidSignature on mismatch
except Exception:
    print("Signature invalid")

# Convert a cryptography key the other way
priv = ec.generate_private_key(ec.SECP256R1())
es256 = ES256.from_cryptography_key(priv.public_key())
print(es256.ALGORITHM)             # -7
```

--------------------------------

### Using CtapDevice as a context manager

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/ctap.md

Shows how to use a CtapDevice instance with a 'with' statement; close() is invoked on exit.

```python
with dev:  # close() is invoked on exit
    ...
```

--------------------------------

### CollectedClientData class definition

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/webauthn.md

Defines the CollectedClientData class as a frozen dataclass extending bytes. It includes a TYPE enum for create and get operations, and fields for type, challenge, origin, cross_origin, and raw data. The class provides a create method and properties for base64 and hash.

```python
@dataclass(init=False, frozen=True)
class CollectedClientData(bytes):
    @unique
    class TYPE(_StringEnum):
        CREATE = "webauthn.create"
        GET = "webauthn.get"

    _data: Mapping[str, Any]
    type: str
    challenge: bytes
    origin: str
    cross_origin: bool = False
```

--------------------------------

### Config - set_min_pin_length, toggle_always_uv

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/management.md

Demonstrates how to configure authenticator settings using the Config class.

```APIDOC
## Config - set_min_pin_length, toggle_always_uv

### Description
This example shows how to configure authenticator settings using the Config class.

### Methods
- `set_min_pin_length(min_pin_length, force_change_pin)` - Sets the minimum PIN length and optionally forces a PIN change.
- `toggle_always_uv()` - Toggles the always-on user verification setting.

### Parameters
- `min_pin_length` (int) - Required - The minimum PIN length.
- `force_change_pin` (bool) - Required - Whether to force a PIN change.

### Example
```python
from fido2.ctap2 import Ctap2, ClientPin, Config

ctap2 = Ctap2(dev)
client_pin = ClientPin(ctap2)
token = client_pin.get_pin_token("1234", ClientPin.PERMISSION.AUTHENTICATOR_CFG)

cfg = Config(ctap2, client_pin.protocol, token)
cfg.set_min_pin_length(min_pin_length=6, force_change_pin=True)
cfg.toggle_always_uv()
```
```

--------------------------------

### AttestationVerifier.__init__

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/attestation.md

Initializes an AttestationVerifier with a sequence of attestation format verifiers. Defaults to all subclasses except 'none'.

```APIDOC
## AttestationVerifier.__init__

### Description
Initializes an AttestationVerifier with a sequence of attestation format verifiers. Defaults to all subclasses except 'none'.

### Method
Constructor

### Signature
`__init__(attestation_types: Sequence[Attestation] | None = None)`

### Parameters
- **attestation_types** (Sequence[Attestation] | None) - Optional - Attestation format verifiers to use; defaults to all subclasses except `none`.

### Source
`fido2/attestation/base.py:206`
```

--------------------------------

### New Approach: Using importlib.metadata for version

Source: https://github.com/yubico/python-fido2/blob/main/doc/Migration_1-2.adoc

Use importlib.metadata.version to retrieve the package version instead of __version__.

```python
from importlib.metadata import version

print(version("fido2"))
```

--------------------------------

### Old Approach: Importing WindowsClient from fido2.client

Source: https://github.com/yubico/python-fido2/blob/main/doc/Migration_1-2.adoc

In version 1.x, WindowsClient was always importable from fido2.client. This is the old approach.

```python
from fido2.client import WindowsClient  # Always importable

if WindowsClient.is_available():  # Check if the OS supports the webauthn.h API
    client = WindowsClient(...)
else:
    # Handle platforms that do not support WindowsClient
    ...
```

--------------------------------

### Upload release to PyPI

Source: https://github.com/yubico/python-fido2/blob/main/RELEASE.adoc

Publishes the built distribution to PyPI using uv.

```shell
$ uv publish
```

--------------------------------

### Fido2Client class initialization

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/client.md

Defines the Fido2Client class constructor. It selects a CTAP2 backend by default, falling back to CTAP1/U2F if a ValueError (no CBOR) or CtapError occurs.

```python
class Fido2Client(WebAuthnClient):
    """WebAuthn-like client implementation.

    The client allows registration and authentication of WebAuthn credentials against
    an Authenticator using CTAP (1 or 2).

    :param device: CtapDevice to use.
    :param str origin: The origin to use.
    :param verify: Function to verify an RP ID for a given origin.
    """

    def __init__(
        self,
        device: CtapDevice,
        client_data_collector: ClientDataCollector,
        user_interaction: UserInteraction = UserInteraction(),
        extensions: Sequence[Ctap2Extension] = _DEFAULT_EXTENSIONS,
    ):
        self._client_data_collector = client_data_collector

        # TODO: Decide how to configure this list.
        self._enterprise_rpid_list: Sequence[str] | None = None

        try:
            self._backend: _ClientBackend = _Ctap2ClientBackend(
                device, user_interaction, extensions
            )
        except (ValueError, CtapError):
            self._backend = _Ctap1ClientBackend(device, user_interaction)
```

--------------------------------

### Use Fido2Client over PC/SC to make a credential

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/pcsc.md

Creates a Fido2Client over a PC/SC device, filtering readers by the name "Yubico", and performs make_credential with a publicKey create_options. The device is explicitly closed after the operation.

```python
from fido2.client import DefaultClientDataCollector, Fido2Client, UserInteraction
from fido2.pcsc import CtapPcscDevice

dev = next(CtapPcscDevice.list_devices("Yubico"))
client = Fido2Client(
    dev,
    client_data_collector=DefaultClientDataCollector("https://example.com"),
    user_interaction=UserInteraction(),
)
result = client.make_credential(create_options["publicKey"])
dev.close()
```

--------------------------------

### enroll_capture_next(template_id, timeout=None, event=None, on_keepalive=None)

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/bio.md

Continues the enrollment process by capturing the next fingerprint sample.

```APIDOC
## enroll_capture_next(template_id, timeout=None, event=None, on_keepalive=None)

### Description
Continues enrollment by capturing the next sample.

### Parameters
- `template_id` (bytes) - Required - The template ID from the enrollment begin.
- `timeout` (int | None) - Optional - Timeout in milliseconds.
- `event` (threading.Event | None) - Optional - Cancellation event.
- `on_keepalive` (Callable[[int], None] | None) - Optional - Keep-alive callback.

### Returns
tuple[FPBioEnrollment.FEEDBACK, int] - `(sample_status, samples_remaining)`.
```

--------------------------------

### CtapHidDevice(descriptor, connection)

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/hid.md

Constructor for CtapHidDevice. Initializes the device with a descriptor and an open connection, performing CTAPHID INIT for channel negotiation.

```APIDOC
## CtapHidDevice(descriptor, connection)

### Description
Initializes a CtapHidDevice with the given descriptor and connection. The constructor immediately performs CTAPHID INIT for channel negotiation.

### Parameters
- **descriptor** (HidDescriptor) - Required - Device descriptor (path, IDs, report sizes).
- **connection** (CtapHidConnection) - Required - Open connection; the constructor performs CTAPHID INIT immediately.

### Raises
- **ConnectionFailure** - If INIT fails (wrong nonce).

```

--------------------------------

### CtapPcscDevice constructor with CTAP2 probe

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/pcsc.md

Initializes a PC/SC NFC transport device. Connects, selects the FIDO applet, and probes for CTAP2 by calling GET_INFO. Raises ValueError("Unsupported device") if the device is neither CTAP1 nor CTAP2.

```python
class CtapPcscDevice(CtapDevice):
    """
    CtapDevice implementation using pyscard (PCSC).

    This class is intended for use with NFC readers.
    """

    def __init__(self, connection: CardConnection | CardConnectionDecorator, name: str):
        self._name = name
        self._capabilities = CAPABILITY(0)
        self.use_ext_apdu = False
        self.use_nfcctap_getresponse = True
        self._conn = connection
        self.connect()

        try:  # Probe for CTAP2 by calling GET_INFO
            self.call(CTAPHID.CBOR, b"\x04")
            self._capabilities |= CAPABILITY.CBOR
        except CtapError:
            if not self._capabilities:
                raise ValueError("Unsupported device")
```

--------------------------------

### open_device

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/hid.md

Opens a specific FIDO HID device by its path.

```APIDOC
## open_device

### Description
Opens a specific FIDO HID device by its path.

### Function Signature
`open_device(path) -> CtapHidDevice`

### Parameters
- **path** (str or bytes) - Required - The OS device path of the device to open.

### Returns
- **CtapHidDevice** - The opened device object.

```

--------------------------------

### list_devices(name)

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/pcsc.md

Classmethod that yields a CtapPcscDevice for each matching reader, skipping readers that fail to initialize.

```APIDOC
## list_devices(name)

### Description
Classmethod that yields a CtapPcscDevice for each matching reader, skipping readers that fail to initialize (logged at debug level).

### Parameters
- **name** (str) - Optional - Default: `""` - Substring filter on reader name; empty matches all readers.

### Returns
- **Iterator[CtapPcscDevice]** - An iterator of CtapPcscDevice instances.
```

--------------------------------

### enroll(timeout=None)

Source: https://github.com/yubico/python-fido2/blob/main/_autodocs/api-reference/bio.md

Creates an initialized FPEnrollmentContext for the caller's enrollment loop.

```APIDOC
## enroll(timeout=None)

### Description
Creates an initialized FPEnrollmentContext for the caller's enrollment loop.

### Parameters
- `timeout` (int | None) - Optional - Timeout in milliseconds.

### Returns
FPEnrollmentContext - An initialized context for enrollment.
```
Tokens:
Raw