# Prerequisites

## USB Security Dongles

All USB Security dongles used with Heads must support the **OpenPGP card
applet**.  FIDO2 and U2F are not used by Heads.

HOTP verification requires a dongle with HOTP support and a compatible firmware
version.  Without HOTP, Heads falls back to TPMTOTP (smartphone-based).

| Dongle | OpenPGP | HOTP | Notes |
|--------|---------|------|-------|
| Nitrokey Pro 2 | Yes | Yes | Full support |
| Nitrokey Storage 2 | Yes | Yes | Full support |
| Nitrokey 3 | Yes | Yes | Full support; NIST P-256 ECC available |
| Purism Librem Key | Yes | Yes | Full support; rebranded NK Pro |
| YubiKey 5 Series | Yes | No | OpenPGP signing only; no HOTP |
| Nitrokey Pro (v1, fw < 0.8) | Yes | Limited | Older firmware may report no HOTP support; test before use |

Heads detects dongle branding at runtime via USB VID:PID.

Source of truth for IDs is `initrd/etc/dongle-versions`.

| VID:PID | Dongle |
|---------|--------|
| `20a0:42b2` | Nitrokey 3 |
| `20a0:42d4` | Canokey (QEMU) |
| `20a0:4108` | Nitrokey Pro |
| `20a0:4109` | Nitrokey Storage |
| `316d:4c4b` | Purism Librem Key |
| `16d0:21dc` | Canokey |
| `1050:*` | YubiKey |

## HOTP vs. TPMTOTP

**HOTP (recommended when available):**
- Heads generates HOTP codes and the dongle verifies them automatically.
- Pass = green LED, fail = red LED and boot halt.
- Does not require accurate time.

**TPMTOTP (smartphone fallback):**
- Heads generates a TOTP code on screen; the user compares it against a phone
  app (Google Authenticator, FreeOTP+, etc.).
- Requires correct UTC time set in `Options -> Time`.
- Less automated — relies on the user noticing a mismatch.

## OS Requirements

- A dedicated `/boot` partition (not `/boot` inside an LVM or btrfs subvolume
  unless the board config supports it).
- LUKS-encrypted root (for TPM Disk Unlock Key functionality).

## Supported Flashing Methods

See board-specific configs under `boards/`.  Most x86 boards support:

- External SPI flashing (initial install) via `flashprog`.
- Internal flashing (upgrades) via `Options -> Flash/Update BIOS` for firmware
  built after November 2023.

Run from Recovery Shell to verify internal flash is unlocked:

```
flashprog -p internal
```
