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

[tlaurion]

• 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/USB boot access control even after dongle replacement.

Tested on real hw with

• Nitrokey 3: OEM factory reset creates LUKS backup + provisions dongle successfully.
• 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.
• qemu with canokey

---

For the sake of this test, as per doc/qemu.md guidelines, on host

./docker_repro.sh make BOARD=qemu-coreboot-fbwhiptail-tpm2-prod_quiet
./docker_repro.sh make BOARD=qemu-coreboot-fbwhiptail-tpm2-prod_quiet run

Workflow

Restore key material backup from prior OEM factory reset/ Re-Ownership having creating such backup

Simulation: wipe cakokey
sudo rm build/x86/qemu-coreboot-fbwhiptail-tpm2-prod_quiet/.canokey-file
Let's reprovisioning of key material backup
./docker_repro.sh make BOARD=qemu-coreboot-fbwhiptail-tpm2-prod_quiet run

Again a qemu consideration, but to truely simulate enabled authentication, and because qemu cannot inject things in firmware, one have to switch the feature on in board config (not on real hardware):

#Enable HAVE_GPG_KEY_BACKUP to test GPG key backup drive (we cannot inject config under QEMU (no internal flashing))
export CONFIG_HAVE_GPG_KEY_BACKUP=y

And then final test, after resealing etc on reboot per firmware changes:
./docker_repro.sh make BOARD=qemu-coreboot-fbwhiptail-tpm2-prod_quiet PUBKEY_ASC=pubkey.asc inject_gpg run

Accessing Recovery Shell, authenticating with key material backup on thumb drive signature test:

Accessing Recovery Shell, authenticating with OpenPGP smartcard signature test:

Booting from USB

Note that OEM factory reset/Re-Ownership, flashing, changing config is not guarded since Heads makes tampering evident and doesn't pretent preventing it.

User has to create key material backup from OEM factory reset/ Re-Ownership

Answering yes to

The for sake of this test, as per doc/qemu.md guidelines, on host (Qemu still can't inject stuff in firmware):

We want to locally map virtualized thumb drive to host:

sudo losetup --find --show --partscan ./build/x86/qemu-coreboot-fbwhiptail-tpm2-prod_quiet/usb_fd.raw 
/dev/loop36

We want to extract public key from public partition created on virtualized thumb drive:

sudo mount /dev/loop36p2 /media/cdrom/
cp /media/cdrom/pubkey.asc pubkey.asc 
sudo umount /media/cdrom

And for sake of dealing with qemu limitations, inject public key:
./docker_repro.sh make BOARD=qemu-coreboot-fbwhiptail-tpm2-prod_quiet PUBKEY_ASC=pubkey.asc inject_gpg run

[Copilot]

Pull request overview

This PR extends Heads’ GPG provisioning/recovery capabilities by adding a “reprovision smartcard from GPG key backup” flow, factoring common GPG/smartcard operations into shared initrd functions, wiring the new flow into UI entry points, and documenting the recovery/testing workflows.

Changes:

• Added shared gpg_* helpers in initrd/etc/gpg_functions.sh, including a new reprovision_smartcard_from_backup() end-to-end recovery flow.
• Refactored oem-factory-reset.sh to delegate to the new shared helpers and added UI menu options to trigger reprovisioning.
• Updated documentation for recovery-shell authentication semantics and QEMU testing workflows.

Reviewed changes

Copilot reviewed 6 out of 9 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
initrd/etc/gpg_functions.sh	Adds shared smartcard/GPG helper functions and implements the reprovision-from-backup flow.
initrd/bin/oem-factory-reset.sh	Replaces inlined GPG/smartcard logic with thin wrappers calling shared gpg_* functions.
initrd/bin/gui-init.sh	Adds new reprovision menu options to “missing key” flows and clean-boot wizard.
initrd/bin/gpg-gui.sh	Adds k option to trigger reprovisioning from the GPG Management Menu.
doc/recovery-shell.md	Documents recovery-shell authentication and configuration-reset implications.
doc/qemu.md	Documents QEMU USB workflow improvements and reprovision-from-backup testing steps.
doc/gpg.md	Adds a “Restoring Keys from Backup” section.
doc/configuring-keys.md	Documents the restore-from-backup recovery procedure.
doc/architecture.md	Updates architecture text to reference reprovision path and recovery-shell auth docs.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 9 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 9 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 9 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 9 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 10 changed files in this pull request and generated 1 comment.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 13 changed files in this pull request and generated no new comments.

Suppressed comments (3)

initrd/etc/gpg_functions.sh:518

• UID parsing sets key_name to the full UID string (often including the <email> portion). That ends up writing an email address into the cardholder name fields in gpg_set_card_identity. Strip comment and <...> from the UID when deriving key_name.

	if echo "$uid_line" | grep -q '('; then
		key_name="$(echo "$uid_line" | sed 's/ (.*//')"
		key_comment="$(echo "$uid_line" | sed 's/.*(//;s/).*//')"
	else
		key_name="$uid_line"

initrd/etc/gpg_functions.sh:308

• gpg_set_card_identity accepts card_admin_pin but never uses it. That makes the function depend on scdaemon PIN caching from a previous operation and contradicts the comment/PR description about explicit admin PIN support. Pass the PIN via --passphrase-fd (same approach used in gpg_card_factory_reset) so this works reliably even if scdaemon was restarted.

		fi
		echo "quit"
	} | DO_WITH_DEBUG gpg --command-fd=0 --status-fd=2 --pinentry-mode=loopback --card-edit \
		>/tmp/gpg_card_edit_output 2>&1 ||
		DIE "Failed to set identity fields on OpenPGP smartcard"

initrd/etc/gpg_functions.sh:724

• The TPM rollback counter warning is unconditional when tpm_counter_ok is unset, so it will also display on systems with no TPM or with rollback checks disabled. Gate this warning on CONFIG_TPM=y (and rollback checks enabled) so users don't get incorrect instructions.

	if [ "$tpm_counter_ok" != "y" ]; then
		WARN "TPM rollback counter was not created. Reset the TPM from"
		WARN "Options -> TPM/TOTP/HOTP Options -> Reset the TPM before"
		WARN "the next boot to avoid being dropped into recovery shell."
	fi