Pico FIDO

This project transforms your Raspberry Pi Pico or ESP32 microcontroller into an integrated FIDO Passkey, functioning like a standard USB Passkey for authentication.

If you are looking for a OpenPGP + Fido, see: https://github.com/polhenarejos/pico-fido2. Available through PicoKey App.

Features

Pico FIDO includes the following features:

• CTAP 2.3 / CTAP 1
• Authenticated passkey export and import through the open-source Pico Vault
• FIDO 2.3 extensions, including UVM, third-party payments, and PIN complexity policy
• WebAuthn
• U2F
• HMAC-Secret extension
• CredProtect extension
• User presence enforcement through physical button
• User verification with PIN
• Discoverable credentials (resident keys)
• Configurable policy to deny creation of resident/discoverable credentials
• Credential expiration and revocation metadata
• Credential management
• ECDSA and EDDSA authentication
• Support for SECP256R1, SECP384R1, SECP521R1, SECP256K1 and Ed25519 curves
• App registration and login
• Device selection
• Support for vendor configuration
• Backup with 24 words
• Secure lock to protect the device from flash dumps
• Permissions support (MC, GA, CM, ACFG, LBW)
• Authenticator configuration
• minPinLength extension
• Self attestation
• Enterprise attestation
• credBlobs extension
• largeBlobKey extension
• Large blobs support (2048 bytes max)
• OATH (based on YKOATH protocol specification)
• TOTP / HOTP
• Yubikey One Time Password
• Challenge-response generation
• Emulated keyboard interface
• Button press generates an OTP that is directly typed
• Yubico Authenticator app compatible
• Yubico YKMAN compatible
• Nitrokey nitropy and nitroapp compatible
• Secure Boot and Secure Lock in RP2350 and ESP32-S3 MCUs
• One Time Programming to store the master key that encrypts all resident keys and seeds.
• Rescue interface to allow recovery of the device if it becomes unresponsive or undetectable.
• LED customization with PicoKey App.

The authenticated credential export and import design is described in Pol Henarejos, Vaulted Passkeys: A Device-Bound Proposal for Authenticated Credential Export and Import. The proposal and implementation notes are also available in docs/vault.

All features comply with the specifications. If you encounter unexpected behavior or deviations from the specifications, please open an issue.

Security Considerations

Microcontrollers RP2350 and ESP32-S3 are designed to support secure environments when Secure Boot is enabled, and optionally, Secure Lock. These features allow a master key encryption key (MKEK) to be stored in a one-time programmable (OTP) memory region, which is inaccessible from outside secure code. This master key is then used to encrypt all private and secret keys on the device, protecting sensitive data from potential flash memory dumps.

However, the RP2040 microcontroller lacks this level of security hardware, meaning that it cannot provide the same protection. Data stored on its flash memory, including private or master keys, can be easily accessed or dumped, as encryption of the master key itself is not feasible. Consequently, if an RP2040 device is stolen, any stored private or secret keys may be exposed.

Download

If you own an ESP32-S3 board, go to ESP32 Flasher for flashing your Pico FIDO.

If you own a Raspberry Pico (RP2040 or RP2350), go to Download page, select your vendor and model and download the proper firmware; or go to Release page and download the UF2 file for your board.

UF2 files are shiped with a VID/PID granted by RaspberryPi (2E8A:10FE). If you plan to use it with OpenSC or similar tools, you should modify Info.plist of CCID driver to add these VID/PID or use the PicoKey App.

You can use whatever VID/PID for internal purposes, but remember that you are not authorized to distribute the binary with a VID/PID that you do not own.

Note that the PicoKey App is the most recommended.

Build for Raspberry Pico

Before building, ensure you have installed the toolchain for the Pico and that the Pico SDK is properly located on your drive.

git clone https://github.com/polhenarejos/pico-fido
git submodule update --init --recursive
cd pico-fido
mkdir build
cd build
PICO_SDK_PATH=/path/to/pico-sdk cmake .. -DPICO_BOARD=board_type -DUSB_VID=0x1234 -DUSB_PID=0x5678
make

Note that PICO_BOARD, USB_VID and USB_PID are optional. If not provided, pico board and VID/PID FEFF:FCFD will be used.

Additionally, you can pass the VIDPID=value parameter to build the firmware with a known VID/PID. The supported values are:

• NitroHSM
• NitroFIDO2
• NitroStart
• NitroPro
• Nitro3
• Yubikey5
• YubikeyNeo
• YubiHSM
• Gnuk
• GnuPG

After running make, the binary file pico_fido.uf2 will be generated. To load this onto your Pico board:

1. Put the Pico board into loading mode by holding the BOOTSEL button while plugging it in.
2. Copy the pico_fido.uf2 file to the new USB mass storage device that appears.
3. Once the file is copied, the Pico mass storage device will automatically disconnect, and the Pico board will reset with the new firmware.
4. A blinking LED will indicate that the device is ready to work.

Led blink

Pico FIDO uses the led to indicate the current status. Four states are available:

Press to confirm

The Led is almost on all the time. It goes off for 100 miliseconds every second.

Idle mode

In idle mode, the Pico FIDO goes to sleep. It waits for a command and it is awaken by the driver. The Led is almost off all the time. It goes on for 500 milliseconds every second.

Active mode

In active mode, the Pico FIDO is awaken and ready to receive a command. It blinks four times in a second.

Processing

While processing, the Pico FIDO is busy and cannot receive additional commands until the current is processed. In this state, the Led blinks 20 times in a second.

Driver

Pico FIDO uses the HID driver, which is present in all operating systems. It should be detected by all OS and browser/applications just like normal USB FIDO keys.

Tests

Tests can be found in the tests folder. They are based on FIDO2 tests from Solokeys but adapted to the python-fido2 v1.0 package, which is a major refactor from the previous 0.8 version and includes the latest improvements from CTAP 2.1.

To run all tests, use:

pytest

To run a subset of tests, use the -k <test> flag:

pytest -k test_credprotect

License and Commercial Use

This project is available under two editions:

Community Edition (FOSS)

• Released under the GNU Affero General Public License v3 (AGPLv3).
• You are free to study, modify, and run the code, including for internal evaluation.
• If you distribute modified binaries/firmware, OR if you run a modified version of this project as a network-accessible service, you must provide the corresponding source code to the users of that binary or service, as required by AGPLv3.
• No warranty. No SLA. No guaranteed support.

Enterprise / Commercial Edition

• Proprietary license for organizations that want to:
  • run this in production with multiple users/devices,
  • integrate it into their own product/appliance,
  • enforce corporate policies (PIN policy, admin/user roles, revocation),
  • deploy it as an internal virtualized / cloud-style service,
  • and not be required to publish derivative source code.
• Base package includes:
  • commercial license (no AGPLv3 disclosure obligation for your modifications / integration)
  • onboarding call
  • access to officially signed builds
• Optional / on-demand enterprise components that can be added case-by-case:
  • ability to operate in multi-user / multi-device environments
  • device inventory, traceability and secure revocation/offboarding
  • custom attestation, per-organization device identity / anti-cloning
  • virtualization / internal "HSM or auth backend" service for multiple teams or tenants
  • post-quantum (PQC) key material handling and secure PQC credential storage
  • hierarchical deterministic key derivation (HD wallet–style key trees for per-user / per-tenant keys, firmware signing trees, etc.)
  • cryptographically signed audit trail / tamper-evident logging
  • dual-control / two-person approval for high-risk operations
  • secure key escrow / disaster recovery strategy
  • release-signing / supply-chain hardening toolchain
  • policy-locked hardened mode ("FIPS-style profile")
  • priority security-response SLA
  • white-label demo / pre-sales bundle

Typical licensing models:

• Internal use (single legal entity, including internal private cloud / virtualized deployments).
• OEM / Redistribution / Service (ship in your product OR offer it as a service to third parties).

These options are scoped and priced individually depending on which components you actually need.

For commercial licensing and enterprise features, email pol@henarejos.me Subject: ENTERPRISE LICENSE <your company name>

See ENTERPRISE.md for details.

Credits

Pico FIDO uses the following libraries or portion of code:

• MbedTLS for cryptographic operations.
• TinyUSB for low level USB procedures.
• TinyCBOR for CBOR parsing and formatting.