Getting Started

This guide walks you through building and using your first KeyForge security key.

What You’ll Need

Hardware

  • Seeed XIAO ESP32-S3 - Available from Seeed Studio (~$8)
  • USB-C cable - For programming and daily use

Software

  • PlatformIO - Install guide
  • Git - For cloning the repository
  • Go (optional) - For building the flash tool from source

Step 1: Clone the Repository

git clone https://github.com/authgrid-io/keyforge
cd keyforge

Step 2: Build the Firmware

For development/testing (no security features):

pio run -e seeed_xiao_esp32s3

For production use (Secure Boot + NVS encryption):

# First, generate a signing key (keep this safe!)
~/.platformio/penv/.espidf-5.3.2/bin/python3 \
    ~/.platformio/packages/tool-esptoolpy/espsecure.py \
    generate_signing_key --version 2 --scheme rsa3072 \
    keys/secure_boot_signing_key.pem

# Build with security features
pio run -e seeed_xiao_esp32s3_secure

Step 3: Flash Your Device

Option A: Web Flash (Easiest)

Use our browser-based flasher - no tools to install:

  1. Put the ESP32-S3 in download mode:

    • Hold the BOOT button
    • Plug in the USB cable
    • Release BOOT after 1 second

  2. Go to Flash Device and click “Install KeyForge Secure”

  3. Select the serial port when prompted

Note: Web flashing requires Chrome, Edge, or Opera. It flashes the secure firmware which permanently locks the device to KeyForge.

Option B: Command Line

For more control, use the keyforge-flash tool:

New Device (First Time)

  1. Put the ESP32-S3 in download mode:

    • Hold the BOOT button
    • Plug in the USB cable
    • Release BOOT after 1 second

  2. Flash with the keyforge-flash tool:

cd tools/keyforge-flash
./keyforge-flash --setup

Existing Device (OTA Update)

Just plug in and run:

cd tools/keyforge-flash
./keyforge-flash

Step 4: First Boot

On first boot, the device will:

  1. Generate a random 32-byte master seed
  2. Initialize the credential store
  3. (Secure build only) Burn security eFuses

The yellow LED will blink to indicate the device is ready.

Step 5: Set a PIN

  1. Go to webauthn.io in Chrome, Firefox, or Edge
  2. Enter a username and click Register
  3. When prompted, create a PIN (4+ characters)
  4. Touch the capacitive pad on the device to approve

Step 6: Test Authentication

  1. On the same site, click Authenticate
  2. Enter your PIN when prompted
  3. Touch the device to approve

If authentication succeeds, your KeyForge is working correctly.

Next Steps

Troubleshooting

Device not recognized

  • Try a different USB cable (some are charge-only)
  • Check if the device appears in lsusb output
  • On Linux, you may need udev rules for HID access

Registration fails

  • Make sure you’re using a supported browser (Chrome, Firefox, Edge)
  • Some sites require HTTPS
  • Check the serial console for debug output

Touch not working

  • The capacitive touch is on GPIO7 (pin D8 on the board)
  • Touch the metal pad firmly
  • Ensure your finger is making good contact

Need Help?