How it works
Firmware and software, all in the open.
Keyzforge is a web app that talks to your security key over WebUSB and Web Serial, and a firmware pipeline that builds the key firmware from source. Move your pointer over the drawings.
01 Firmware
Built in the open, from source you can fork.
Keyzforge firmware lives in firmware/: a pinned open-source FIDO2 code base plus Keyzforge patches, all AGPL-3.0. GitHub Actions builds every board in a public Docker image and publishes each release with checksums and the complete source. Change a build option, add a patch, and run the same script to get your own key.
- Source
- firmware/ (pinned source + patches)
- Build
- firmware/build.sh in firmware/Dockerfile
- Release
- fw-<version>: .bin, .uf2, SHA256SUMS, source
02 Flash
The image is checked before a single byte is written.
ESP32 boards are flashed over Web Serial with Espressif's esptool-js, and the write is verified by MD5. RP2040 and RP2350 boards are flashed over WebUSB through the bootrom's PICOBOOT interface: every 4 KiB sector is erased, written and read back. Before that, Keyzforge reads the file and refuses images built for another chip or, on a secure-boot RP2350, unsigned ones.
- ESP32-S3, ESP32-S2
- Web Serial, esptool-js, MD5 verify
- RP2040, RP2350
- WebUSB PICOBOOT, byte-for-byte verify
- Passkeys
- Kept: only the sectors in the file change
03 Configure
Board settings without a PIN or a driver.
The firmware has a small rescue applet behind its USB smart-card interface. Keyzforge talks to it over WebUSB to read and write the board record: LED pin, driver, colour order and brightness, USB name and IDs, and which interfaces are on. Writes are committed only after you press the board's BOOT button, and the page tells you when the key has restarted with them.
- Transport
- WebUSB, CCID, rescue applet
- Settings
- LED, USB identity, interfaces, timeouts
- Confirm
- BOOT button press on the key
04 Passkeys
See and remove the passkeys stored on your key.
Browsers do not let web pages use a key's FIDO channel directly, so Keyzforge sends the same CTAP2 commands through the FIDO applet on the smart-card interface. Your PIN is hashed and encrypted in this tab with WebCrypto before it reaches the key, and the list of sites and accounts exists only on the page.
- Protocol
- CTAP 2.1 credential management, PIN protocol 1
- Capacity
- Up to 256 passkeys per key
- Leaves the tab
- Nothing
05 Secure boot
Optional, permanent, and explained before you commit.
On ESP32-S3, ESP32-S2 and RP2350, the firmware can burn the upstream release-key digest into eFuse or OTP. After that the chip only boots firmware signed with that key. Keyzforge shows the current state, asks you to type a confirmation, and warns when the firmware you flashed would not boot under it. It never burns anything on its own.
- Chips
- ESP32-S3/S2 eFuse, RP2350 OTP
- Boots afterwards
- The upstream signed build only
- Undo
- Not possible, by design
06 Monitor
Read the boot log when something looks wrong.
The monitor opens the board's serial port and turns common boot messages into plain advice: wrong flash mode, a rejected image, a board stuck in the bootloader. It also shows how to reset each board into the mode you need.
- Transport
- Web Serial
- Hints
- Bootloader, flash, secure boot, USB
07 Privacy
Your key talks to your browser, not to us.
There are no accounts, analytics or cookies. The only network requests are the public GitHub release list and firmware downloads, which go through a same-origin route limited to a fixed list of repositories and file types. Everything else is between this tab and the USB device.
- Network
- GitHub releases, /api/firmware
- Stored
- Your theme choice, nothing else