initrd/gpg: add reprovision smartcard from GPG key backup flow

- Add gpg_card_factory_reset() shared function for factory-reset +
  forcesig + key-attr setting (RSA and ECC/P-256), extracted from
  oem-factory-reset.sh with explicit --passphrase-file support
- Add gpg_keytocard_subkeys() shared function: enable USB, verify card,
  move subkeys to slots 1-3 (sign, encrypt, auth)
- Add gpg_set_card_identity() shared function for cardholder name and
  login fields with explicit admin PIN
- Add gpg_reset_nk3_secret_app() shared function for Nitrokey 3 Secrets
  app reset, parameterized on admin PIN
- Replace oem-factory-reset.sh function bodies with thin wrappers that
  call the shared gpg_* functions via positional args
- Add reprovision_smartcard_from_backup(): 10-phase flow that mounts
  the LUKS backup, detects key type from imported key, mounts public
  partition, factory-resets card, restores subkeys, sets identity,
  offers ROM flash
- Add k option to GPG Management Menu (gpg-gui.sh), always visible
- Add K option in prompt_missing_gpg_key_action (gui-init.sh)
- Add clean boot wizard offering OEM reset, reprovision, or ignore
- Update doc/gpg.md, doc/configuring-keys.md, doc/architecture.md
  for the new recovery path
- Document QEMU testing workflow and hardlink preservation pattern
  in doc/qemu.md (USB flash drive workflow + reprovision test)
- Add Authentication and Resetting Configuration sections to
  doc/recovery-shell.md

Extends PR #1515 (2023): authentication via gpg_auth can now be
enforced with key material restored from a backup, allowing recovery
shell access control even after dongle replacement.

Tested on Nitrokey 3: OEM factory reset creates LUKS backup + provisions
dongle successfully.  Tested on Nitrokey Pro 2: reprovision from backup
restores subkeys to (new) dongle, PIN changes, public key import, ROM
flash, and gpg_auth works after reboot.  Config wipe from Options menu
correctly triggers clean boot wizard with OEM/reprovision/ignore choice.

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

Author: tlaurion

doc/architecture.md

@@ -132,7 +132,7 @@ The CI pipeline's workspace and cache behavior is documented in
 
 - **No network at boot** — all verification is local; no certificate authorities
 - **Hardware root of trust** — the coreboot bootblock (IBB) is the Static Core Root of Trust for Measurement (S-CRTM): the first code executed by the CPU, directly from SPI flash.  Coreboot implements a transitive measurement chain: the CRTM measures FMAP and the bootblock image into the preram log, then each subsequent stage measures the next before executing it — bootblock measures romstage, romstage measures ramstage, ramstage measures the Heads payload.  Measurements are taken during CBFS file loading, before decompression, and are recorded in TPM PCR 2 (SRTM) once the TPM hardware is initialized (`tpm_setup()`).  Measurements taken before TPM init are cached in the preram log and flushed to PCR 2 by `tspi_measure_cache_to_pcr()` during `tpm_setup()`.  The full chain — bootblock → romstage → ramstage → Heads Linux kernel + initrd — is recorded into PCR 2.  PCRs 0, 1, and 3 remain zero as policy anchors.  See [tpm.md](tpm.md#srtm-in-coreboot) for TPM init timing per board.  See [wp-notes.md](wp-notes.md#pr0-chipset-locking) for SPI write-protection and PR0 chipset locking details.
-- **Fail-closed** — failed integrity verification drops to a recovery shell.  Recovery shell authentication via GPG smartcard is enforced when GPG key backup has been configured (`CONFIG_HAVE_GPG_KEY_BACKUP=y`), which is set by answering "y" to `"Would you like to format an encrypted USB Thumb drive to store GPG key material? (Required to enable GPG authentication)"` during OEM Factory Reset / Re-Ownership.  Otherwise the recovery shell is unauthenticated.  An "Ignore tampering and force a boot (Unsafe!)" option is available to override this.
+- **Fail-closed** -- failed integrity verification drops to a recovery shell.  Recovery shell authentication via GPG smartcard is enforced when GPG key backup has been configured (`CONFIG_HAVE_GPG_KEY_BACKUP=y`), which is set by answering "y" to `"Would you like to format an encrypted USB Thumb drive to store GPG key material? (Required to enable GPG authentication)"` during OEM Factory Reset / Re-Ownership, or by running "Reprovision smartcard from GPG key backup" from the GPG Management Menu.  Otherwise the recovery shell is unauthenticated.  An "Ignore tampering and force a boot (Unsafe!)" option is available to override this.  See [recovery-shell.md](recovery-shell.md#authentication) for details.
 - **Separation of duties** — the public key that verifies `/boot` signatures is stored in CBFS (ROM).  The private key that signs `/boot` stays on a USB security dongle and never leaves it.
 - **Auditability** — all source is open, builds are reproducible, ROM images are verifiable
 

doc/configuring-keys.md

@@ -160,6 +160,23 @@ If you already have a provisioned USB Security dongle:
 3. Follow the steps.  After reflashing, reboot.
 4. Generate a new TOTP/HOTP secret when prompted.
 
+### Restoring Keys from Backup
+
+If you chose the in-memory backup path during OEM factory reset and your
+dongle is lost, broken, or wiped:
+
+1. Insert the backup USB thumb drive and your (new) dongle.
+2. Go to `Options -> GPG Management -> Reprovision smartcard from GPG key backup`.
+3. Enter the backup passphrase when prompted.
+4. Heads detects the key type from the backup, factory-resets the dongle,
+   restores the subkeys, and sets the card identity.
+5. After success, flash the public key to the running BIOS for persistence.
+6. Re-sign /boot via `Options -> Update checksums and sign all files in /boot`.
+
+This requires the LUKS-encrypted backup USB drive created during OEM factory
+reset (answer Y to "format an encrypted USB Thumb drive").  Without it, run
+a new OEM Factory Reset / Re-Ownership to rekey the device.
+
 ## Forgotten GPG User PIN
 
 From Recovery Shell with the dongle inserted:

doc/gpg.md

@@ -130,6 +130,18 @@ public key into the Heads firmware:
 3. From Heads: `Options -> GPG Management -> Add a GPG key to the running BIOS + reflash`.
 4. Reboot.  Generate a new TOTP/HOTP secret when prompted.
 
+### Restoring Keys from Backup
+
+See [configuring-keys.md](configuring-keys.md#restoring-keys-from-backup) for
+the full recovery flow.  In short:
+
+1. Insert the backup USB thumb drive and the replacement dongle.
+2. From Heads: `Options -> GPG Management -> Reprovision smartcard from GPG key backup`.
+3. Enter the backup passphrase.
+
+The backup drive must have been created by the OEM factory reset flow with
+the "format an encrypted USB Thumb drive" option set to Y.
+
 ## Nitrokey 3 Specifics
 
 - Supports NIST P-256 ECC keys in addition to RSA — significantly faster key

doc/qemu.md

@@ -126,27 +126,32 @@ Use `qemu-img snapshot` before modifying the root disk.
 ### USB flash drive workflow
 
 ```bash
-mkdir -p qemu_img                             # safe storage inside clone
+mkdir -p ~/Qemu_img           # persistent storage outside repo
+                               # (same filesystem as repo;
+                               #  hardlinks only work within
+                               #  a single partition)
 
 # Step 1: Create the USB image via the Makefile.
 ./docker_repro.sh make BOARD=qemu-coreboot-fbwhiptail-tpm2 \
   QEMU_USB_SIZE=64G run
-# → build/x86/.../usb_fd.raw now exists.
+# -> build/x86/.../usb_fd.raw now exists.
 
-# Step 2: Save a master copy IMMEDIATELY (before population).
-cp build/x86/qemu-coreboot-fbwhiptail-tpm2/usb_fd.raw qemu_img/usb_fd.img
-rm build/x86/qemu-coreboot-fbwhiptail-tpm2/usb_fd.raw
-cp -alf qemu_img/usb_fd.img build/x86/qemu-coreboot-fbwhiptail-tpm2/usb_fd.raw
+# Step 2: Save a master copy (hardlink, zero-cost, survives make clean).
+cp -al build/x86/qemu-coreboot-fbwhiptail-tpm2/usb_fd.raw \
+      ~/Qemu_img/usb_fd.img
 
 # Step 3: Populate with ISOs.
-sudo losetup --find --show --partscan build/x86/.../usb_fd.raw
+sudo losetup --find --show --partscan \
+  build/x86/qemu-coreboot-fbwhiptail-tpm2/usb_fd.raw
 sudo mount /dev/loop0p1 /mnt
 cp ~/Downloads/ISOs/*.iso /mnt/
 sudo umount /mnt && sudo losetup -d /dev/loop0
 
-# Step 4: Hardlink into other board build directories.
-cp -alf qemu_img/usb_fd.img build/x86/qemu-coreboot-fbwhiptail-tpm1-hotp/usb_fd.raw
-cp -alf qemu_img/usb_fd.img build/x86/qemu-coreboot-fbwhiptail-tpm2-hotp/usb_fd.raw
+# Step 4: Hardlink into other board build directories (zero-cost).
+cp -alf ~/Qemu_img/usb_fd.img \
+       build/x86/qemu-coreboot-fbwhiptail-tpm1-hotp/usb_fd.raw
+cp -alf ~/Qemu_img/usb_fd.img \
+       build/x86/qemu-coreboot-fbwhiptail-tpm2-hotp/usb_fd.raw
 
 # Next run uses the hardlink — Makefile skips creation since the file exists.
 ```
@@ -162,6 +167,50 @@ After OS install + USB provisioned, reference both from `./qemu_img/`:
       inject_gpg run
 
 
+### Testing GPG key reprovision from a backup drive
+
+The GPG key reprovision flow ('k' in the GPG Management Menu, or the 'K'
+option when signing fails) restores subkeys from a LUKS-encrypted backup
+drive created during OEM factory reset onto a (new) OpenPGP smartcard.
+This can be tested in QEMU.
+
+First run OEM factory reset to populate the virtual USB drive with backup
+material (this creates `build/x86/<board>/usb_fd.raw` with the LUKS private
++ exFAT public partition layout).  Afterwards, save the virtual USB drive
+and canokey state, then hardlink back for the second run:
+
+```bash
+# ~/Qemu_img/ stores files OUTSIDE the repo so they survive make clean.
+# Hardlinks work because ~/heads/ and ~/Qemu_img/ share the same partition.
+mkdir -p ~/Qemu_img
+
+# Save canokey state and populated USB backup image (hardlink, zero-cost).
+cp -al build/x86/qemu-coreboot-fbwhiptail-tpm1-hotp/.canokey-file \
+       ~/Qemu_img/.canokey-file
+cp -al build/x86/qemu-coreboot-fbwhiptail-tpm1-hotp/usb_fd.raw \
+       ~/Qemu_img/backup_drive.raw
+
+# Hardlink back into the build dir so make run picks them up.
+cp -alf ~/Qemu_img/.canokey-file \
+       build/x86/qemu-coreboot-fbwhiptail-tpm1-hotp/.canokey-file
+cp -alf ~/Qemu_img/backup_drive.raw \
+       build/x86/qemu-coreboot-fbwhiptail-tpm1-hotp/usb_fd.raw
+
+# Second run uses the preserved backup with no USB_FD_IMG override.
+./docker_repro.sh make BOARD=qemu-coreboot-fbwhiptail-tpm1-hotp run
+```
+
+Inside the VM: Options -> GPG Options -> 'k' Reprovision smartcard from GPG
+key backup.  Enter the backup passphrase (the Admin PIN you set during OEM
+factory reset).  The flow will:
+- Detect the key type (RSA or ECC) from the backup
+- Factory-reset the virtual canokey and set matching key attributes
+- Import the master key and subkeys from the LUKS partition
+- Move subkeys to the smartcard via keytocard
+- Set the card identity (name, email) from the backup key's UID
+- Offer to flash the public key to ROM (decline -- QEMU cannot reflash)
+
+
 Running via Docker wrappers
 ===
 We provide convenient wrapper scripts at the repository root that encapsulate Docker invocation and automatically handle common host integrations needed for QEMU runs.
@@ -188,7 +237,7 @@ environment reference. Important ones are `HEADS_DISABLE_USB`
 
 Make variables such as `USB_TOKEN`, `PUBKEY_ASC`, `INSTALL_IMG`,
 `QEMU_MEMORY_SIZE`, `QEMU_DISK_SIZE`, `QEMU_USB_SIZE`,
-`ROOT_DISK_IMG`, `CPUS` and `V`
+`ROOT_DISK_IMG`, `USB_FD_IMG`, `CPUS` and `V`
 are forwarded to the `make` invocation and affect how
 `targets/qemu.mk` runs QEMU. See `targets/qemu.mk` for token formats
 and examples.

doc/recovery-shell.md

@@ -20,6 +20,57 @@ The Recovery Shell boots with PCR 4 set to `recovery` instead of
 - TOTP/HOTP sealing and TPM Disk Unlock Key creation/unsealing do not work.
 - To perform seal/unseal operations return to the normal GUI boot.
 
+## Authentication
+
+When `CONFIG_HAVE_GPG_KEY_BACKUP=y` (set during OEM Factory Reset / Re-Ownership
+with the in-memory backup path, or by running the reprovision flow from the GPG
+Management Menu), the recovery shell requires GPG smartcard authentication before
+the bash prompt opens.
+
+**Scope:** This ONLY guards recovery shell entry.  USB boot, TPM operations,
+flash/update, GPG management, and all other GUI menu functions are NOT gated
+by this check — they remain accessible from the main menu.
+
+**What it guards against:** Recovery shell access gives full bash within the
+initrd, including direct block device read/write, SPI flash access, TPM
+commands, and GPG key operations.  An unauthenticated physical attacker with
+shell access could flash malicious firmware, delete `/boot` content, lock TPM
+PIN counters permanently, sign unauthorized `/boot` content, or attempt
+LUKS disk decryption.
+
+**How it works:** `gpg_auth()` in `initrd/etc/functions.sh` generates a random
+nonce, the user signs it with their GPG key (smartcard or backup USB drive)
+within 3 attempts, and the signature is verified against the ROM-fused public
+keyring.  On failure, `DIE` exits the session.  With `CONFIG_RESTRICTED_BOOT=y`,
+the shell is blocked entirely and the system reboots after 5 seconds.
+
+**Without authentication:** If `CONFIG_HAVE_GPG_KEY_BACKUP` is not set,
+`gpg_auth()` is a no-op and the recovery shell opens without prompting.
+
+## Resetting Configuration
+
+`Options -> Change configuration settings -> 'r'` (`Clear GPG key(s) and reset
+all user settings`) wipes the running system configuration:
+
+- Clears `~/.gnupg` (GPG keyring, trustdb)
+- Deletes `/boot/kexec*` (signatures, checksums, boot options)
+- Removes all `heads/` files from CBFS (keyring, trustdb, config.user)
+- Reflashes the cleaned firmware
+- Resets the TPM if present
+
+**Attestation impact:** Removing `heads/` files from CBFS changes the SPI flash
+contents measured into PCR 7 by `cbfs-init` at next boot.  Combined with the
+TPM reset, TOTP/HOTP unseal will fail on the next boot — Heads shows the
+standard red-menu TOTP error prompt.
+
+**Recovery after wipe:** Run OEM Factory Reset / Re-Ownership (Options -> 'F')
+to fully reprovision ([configuring-keys.md](configuring-keys.md)).  If you have a
+GPG key backup USB drive from a previous in-memory OEM reset, use
+`GPG Options -> 'k' Reprovision USB Security dongle from GPG key backup`
+to restore subkeys from the backup ([configuring-keys.md#restoring-keys-from-backup](configuring-keys.md#restoring-keys-from-backup)),
+then flash the public key to ROM, re-sign /boot, and generate new TOTP/HOTP
+secrets.
+
 ## Common Operations
 
 ### Manual boot

initrd/bin/gpg-gui.sh

@@ -10,15 +10,20 @@ TRACE_FUNC
 
 while true; do
 	unset menu_choice
+	# Build menu options dynamically
+	menu_options=(
+		'r' ' Add GPG key to running BIOS and reflash'
+		'a' ' Add GPG key to standalone BIOS image and flash'
+		'e' ' Replace GPG key(s) in the current ROM and reflash'
+		'l' ' List GPG keys in your keyring'
+		'p' ' Export public GPG key to USB drive'
+		'g' ' Generate GPG keys manually on a USB security dongle'
+		'k' ' Reprovision USB Security dongle from GPG key backup'
+	)
+	menu_options+=('x' ' Exit')
 	whiptail_type $BG_COLOR_MAIN_MENU --title "GPG Management Menu" \
 		--menu 'Select the GPG function to perform' 0 80 10 \
-		'r' ' Add GPG key to running BIOS and reflash' \
-		'a' ' Add GPG key to standalone BIOS image and flash' \
-		'e' ' Replace GPG key(s) in the current ROM and reflash' \
-		'l' ' List GPG keys in your keyring' \
-		'p' ' Export public GPG key to USB drive' \
-		'g' ' Generate GPG keys manually on a USB security dongle' \
-		'x' ' Exit' \
+		"${menu_options[@]}" \
 		2>/tmp/whiptail || recovery "GUI menu failed"
 
 	menu_choice=$(cat /tmp/whiptail)
@@ -64,6 +69,9 @@ while true; do
 			gpg_post_gen_mgmt
 		fi
 		;;
+	"k")
+		reprovision_smartcard_from_backup
+		;;
 	esac
 
 done

initrd/bin/gui-init.sh

@@ -241,12 +241,18 @@ prompt_missing_gpg_key_action() {
 		retry_label=" Retry (after connecting $DONGLE_BRAND)"
 		retry_msg="Cannot sign /boot because no private GPG signing key is available ($DONGLE_BRAND not inserted, wiped, or key not set up).\n\nInsert your $DONGLE_BRAND and retry.\n\nHow would you like to proceed?"
 	fi
+	menu_options=(
+		'r' "$retry_label"
+		'F' ' OEM Factory Reset / Re-Ownership'
+		'K' ' Reprovision USB Security dongle from GPG key backup'
+	)
+	menu_options+=(
+		'm' ' Return to main menu'
+		'x' ' Exit to recovery shell'
+	)
 	whiptail_error --title "ERROR: GPG signing key unavailable" \
-		--menu "$retry_msg" 0 80 4 \
-		'r' "$retry_label" \
-		'F' ' OEM Factory Reset / Re-Ownership' \
-		'm' ' Return to main menu' \
-		'x' ' Exit to recovery shell' \
+		--menu "$retry_msg" 0 80 6 \
+		"${menu_options[@]}" \
 		2>/tmp/whiptail || recovery "GUI menu failed"
 
 	option=$(cat /tmp/whiptail)
@@ -257,6 +263,9 @@ prompt_missing_gpg_key_action() {
 	F)
 		oem-factory-reset.sh
 		;;
+	K)
+		reprovision_smartcard_from_backup
+		;;
 	x)
 		recovery "User requested recovery shell"
 		;;
@@ -543,9 +552,26 @@ clean_boot_check() {
 	fi
 
 	# OS is installed, no kexec files present, no GPG keys in keyring, security token present
-	# prompt user to run OEM factory reset
-	oem-factory-reset.sh \
-		"Clean Boot Detected - Perform OEM Factory Reset / Re-Ownership?"
+	# offer to provision or reprovision
+	if ! whiptail_warning --title "Heads setup wizard" \
+		--menu "No GPG keys, no /boot signatures, and a USB Security dongle\ndetected. /boot has an installed OS.\n\nHow would you like to proceed?" 0 80 5 \
+		'F' ' OEM Factory Reset / Re-Ownership (full provisioning)' \
+		'K' ' Reprovision USB Security dongle from GPG key backup' \
+		'i' ' Ignore and continue to main menu' \
+		2>/tmp/whiptail; then
+		return
+	fi
+
+	option=$(cat /tmp/whiptail)
+	case "$option" in
+	F)
+		oem-factory-reset.sh \
+			"Clean Boot Detected - Perform OEM Factory Reset / Re-Ownership?"
+		;;
+	K)
+		reprovision_smartcard_from_backup
+		;;
+	esac
 }
 
 check_gpg_key() {
@@ -558,27 +584,35 @@ check_gpg_key() {
 		fi
 		local gpg_error_msg
 		gpg_error_msg="ERROR: $CONFIG_BRAND_NAME couldn't find any GPG keys in your keyring.\n\nIf this is the first time the system has booted, you should add a public GPG key to the BIOS now.\n\nIf you just reflashed a new BIOS, you'll need to add at least one public key to the keyring.\n\nIf you have not just reflashed your BIOS, THIS COULD INDICATE TAMPERING!\n\nHow would you like to proceed?"
+		menu_options=(
+			'g' ' Add a GPG key to the running BIOS'
+			'F' ' OEM Factory Reset / Re-Ownership'
+			'K' ' Reprovision USB Security dongle from GPG key backup'
+		)
+		menu_options+=(
+			'i' ' Ignore error and continue to main menu'
+			'x' ' Exit to recovery shell'
+		)
 		whiptail_error --title "ERROR: GPG keyring empty!" \
-			--menu "$gpg_error_msg" 0 80 4 \
-			'g' ' Add a GPG key to the running BIOS' \
-			'F' ' OEM Factory Reset / Re-Ownership' \
-			'i' ' Ignore error and continue to main menu' \
-			'x' ' Exit to recovery shell' \
+			--menu "$gpg_error_msg" 0 80 6 \
+			"${menu_options[@]}" \
 			2>/tmp/whiptail || recovery "GUI menu failed"
 
 		option=$(cat /tmp/whiptail)
 		case "$option" in
 		g)
 			gpg-gui.sh && BG_COLOR_MAIN_MENU="normal"
 			;;
+		F)
+			oem-factory-reset.sh
+			;;
+		K)
+			reprovision_smartcard_from_backup
+			;;
 		i)
 			skip_to_menu="true"
 			return 1
 			;;
-		F)
-			oem-factory-reset.sh
-			;;
-
 		x)
 			recovery "User requested recovery shell"
 			;;