KeyForge

Open-Source WebAuthn Security Key

A DIY USB WebAuthn-compatible hardware security key built on the ESP32-S3. CTAP2 and U2F protocol support, deterministic key derivation, and hardware-backed security features.

View on GitHub Documentation Flash Device

Features

WebAuthn Compatible

CTAP2 implementation including getInfo, makeCredential, getAssertion, clientPIN, credentialManagement, and reset. U2F/CTAP1 backward compatibility for legacy sites.

Discoverable Credentials

128 resident credential slots for passwordless login. The authenticator finds credentials by RP ID without needing the server to provide credential IDs.

Client PIN Protocol

Full pinUvAuthProtocol 1 & 2 support with ECDH key agreement, encrypted PIN exchange, and pinToken-based authentication.

Capacitive Touch

User presence verification via capacitive touch on GPIO7. No external components needed - just touch the pin to approve operations.

Deterministic Backup

All credential private keys are derived via HKDF-SHA256 from a 32-byte master seed. Same seed + same credential IDs = same keys on any device.

Hardware Security

ESP32-S3 eFuse protection, Secure Boot v2, encrypted NVS storage with hardware HMAC, and signed serial numbers for device authenticity.

OTA Updates

Update firmware over USB HID with the keyforge-flash tool. Dual OTA partitions with automatic rollback on failed updates.

SSH & Disk Encryption

hmac-secret extension enables hardware-backed SSH keys (ssh-keygen -t ecdsa-sk) and LUKS disk encryption (systemd-cryptenroll).

Composite USB Device

CTAP HID + CDC serial debug console on a single USB-C port. Debug output and serial commands available during development.

Technical Specifications

MCU

ESP32-S3 (dual-core Xtensa LX7, 240 MHz)

USB

Native USB OTG via TinyUSB (composite HID + CDC)

Crypto

ECC P-256, ECDSA, SHA-256, HKDF, ECDH, AES-256-CBC (mbedTLS)

Storage

NVS flash, 128 credential slots

User Presence

Capacitive touch on GPIO7

USB VID/PID

0x1209 / 0xF1D0

Protocols

CTAP2, CTAP1/U2F, WebAuthn

Security

Secure Boot v2, NVS encryption, eFuse key storage

How It Works

KeyForge uses a 32-byte master seed stored in NVS flash. All credential private keys are derived deterministically:

private_key = HKDF-SHA256(master_seed, credential_id, "keyforge-ec-p256")

This means the same seed + same credential IDs will produce the same keys on any ESP32-S3. Back up your seed once, and you can restore your credentials to any device.

Security Model

Layer	Protection
Secure Boot v2	Only firmware signed with your RSA-3072 key can run
NVS Encryption	Seed and credentials encrypted with eFuse HMAC key
eFuse Protection	JTAG disabled, USB-Serial-JTAG disabled, secure download mode
Client PIN	ECDH key agreement with AES-256-CBC encrypted PIN exchange

Getting Started

Get a Seeed XIAO ESP32-S3
Clone the repository and build with PlatformIO
Flash with keyforge-flash --setup
Set a PIN via your browser and start registering credentials

The device works with any WebAuthn-enabled service: Google, Microsoft, GitHub, GitLab, AWS, Cloudflare, and thousands more.

Get Started with KeyForge

Ready to take control of your authentication security?

View on GitHub