mirror of https://github.com/Dasharo/heads.git synced 2026-06-13 10:16:29 -07:00

Files

T

Thierry Laurion 3ca84e5ce8 oem-factory-reset: improve dongle-aware UX, fix GPG operations, label NK3 Secrets app PIN

- Auto-adjust RSA key size based on dongle type; show firmware version
  before reset; add firmware-aware RSA keygen timing guidance
- Fix GPG signing failure by clearing scdaemon CCID lock before signing
- Fix keytocard 'Invalid command': remove spurious echo arguments from
  RSA subkey generation and keytocard operations (scdaemon caches card
  admin PIN after first keytocard; stale ADMIN_PIN_DEF was landing at
  keyedit.prompt causing 'No user ID with index 12345678')
- Fix set_card_identity sending ADMIN_PIN_DEF to cardedit.prompt after
  name/login commands (scdaemon caches admin PIN; no re-prompt needed)
- Fix ECC P-256 encryption subkey generation: remove invalid 'echo Q'
  (option 12 skips capabilities menu, goes straight to curve selection)
- Use DONGLE_BRAND variable in GPG User PIN prompt for consistent branding
- Label ADMIN_PIN as 'NK3 Secrets app PIN / GPG Admin PIN' when Nitrokey 3
  is detected, in all user-facing prompts and status messages

Signed-off-by: Thierry Laurion <insurgo@riseup.net>

2026-04-06 20:43:06 -04:00

2.0 KiB

Raw Blame History

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:

VID:PID	Dongle
`20a0:42b2`	Nitrokey 3
`20a0:4108`	Nitrokey Pro
`20a0:4109`	Nitrokey Storage
`316d:4c4b`	Purism Librem Key

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

2.0 KiB Raw Blame History