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

[tlaurion]

⚠️ Boards dropped from CI / moved to unmaintained_boards

EOL_t420-hotp-maximized and EOL_x220-hotp-maximized are moved to
unmaintained_boards and dropped from the CircleCI build matrix in this PR.

The shared initrd grew ~4.5KB compressed with this reprovision flow. These
8MB-flash boards were already at their CBFS limit and no longer fit the ROM
image. Until issue #590 (firmware size reduction, promising PR #1991
(-Os -> -Oz, gcc 15.1.0)) frees enough space, these variants are NOT built
and will NOT get firmware updates from CI.

Users of t420/x220 are assumed to use TOTP, not HOTP, until proven otherwise.

If you own one of these boards and need HOTP remote attestation, speak up
in issue #590 -- board owners are needed to reclaim flash space.

---

Changes

• 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
• Add 'K' (reprovision from GPG key backup) to the empty-keyring error
  dialog, integrity report menus, TPM State Inconsistent preflight dialog,
  and the clean boot wizard (now a 4-option menu: F/K/i/x)
• Accept uppercase Y/D in the kexec boot confirmation
• Skip TPM counter creation during reprovision when a TPM reset is required
  (avoids dead-end owner-passphrase prompt); integrity report then directs
  to Reset the TPM
• Document reprovision entry points and TPM-reset guidance in
  doc/configuring-keys.md

[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