libfido2 Documentation

libfido2 is a library and command-line toolset used to communicate with FIDO devices over USB or NFC. It enables developers to implement FIDO U2F (CTAP 1) and FIDO2 (CTAP 2) protocols, allowing for the verification of attestation and assertion signatures.

Key features:

• Support for FIDO U2F and FIDO2 protocols.
• Communication via USB or NFC.
• Tools for interacting with FIDO devices.
• Available bindings for .NET, Go, Perl, and Rust.

When using the libfido2 command-line examples, several placeholder terms are used to represent specific inputs:

• <device>: The file system path or subsystem-specific identification string of a FIDO device.
• <pin>, [oldpin]: Strings passed directly as command arguments.
• <cred_id>: A file system path to a file containing a FIDO credential ID in binary representation.
• <pubkey>: A file system path to a file containing a public key in PEM format.
• <blobkey>: A file system path to a file containing a credential's associated CTAP 2.1 "largeBlob" symmetric key.

To build libfido2 on UNIX-like systems, use CMake and Make. Ensure pkg-config is installed or the PKG_CONFIG_PATH environment variable is set if necessary.

$ cmake -B build
$ make -C build
$ sudo make -C build install

macOS

Install via Homebrew.

Windows

Download the appropriate artefacts (ARM, ARM64, Win32, or Win64) from the Yubico release page.

Deployment Note: For safe usage, unpack artefacts in a trusted, non-writable directory with DLLs located alongside the executable. The dynamically linked artefacts are built with /MD and may require the corresponding Visual C++ runtime.

# macOS
$ brew install libfido2

The fido2-token CLI tool is used to find and manage FIDO2 authenticators. It allows for tasks such as changing PINs, managing resident credentials, handling largeBlobs, and performing device resets.

General Behavior:

• If a tty is available, the tool uses it to prompt for PINs. Otherwise, it uses stdin.
• The tool exits with 0 on success and 1 on error.
• Use the -d flag to emit debugging output to stderr.

fido2-token [options] [device]

In libfido2, a FIDO2 assertion is represented by the fido_assert_t type. An assertion is a collection of statements, where each statement maps a challenge and credential to a signature and various ancillary attributes.

To use assertions, you must allocate them using fido_assert_new and ensure they are properly deallocated using fido_assert_free to prevent memory leaks. When using fido_assert_free, the pointer passed is set to NULL automatically.

// Allocation
fido_assert_t *assert = fido_assert_new();
if (assert == NULL) {
    // Handle allocation error
}

// ... use assert ...

// Deallocation
fido_assert_free(&assert);
// assert is now NULL

The fido_cred_set_* family of functions allows you to populate a fido_cred_t object with the necessary parameters for FIDO2 credential operations. This is used in two primary scenarios:

1. FIDO2 Client: Preparing a credential object before calling fido_dev_make_cred to generate a new credential on a device.
2. FIDO2 Server: Preparing a credential object for validation using fido_cred_verify.

Most functions copy the provided data, so the caller does not need to maintain the original pointers after the function call.

// See cred.c in the libfido2 repository for a concrete utilization example.

When -DFUZZ=ON is enabled, symbols listed in wrapped.sym are wrapped in the resulting shared object. These wrapper functions simulate failures using a deterministic RNG and probabilities defined in wrap.c.

To use this functionality in a harness:

1. Call prng_init() with a seed obtained from the fuzzer's corpus.
2. For libFuzzer, to mutate only the seed part of the corpora, use the flag: -reduce_inputs=0 --fido-mutate=seed.

// In your libFuzzer harness
// prng_init(seed_from_corpus);