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

[tlaurion]

Changes

This PR adds a "reprovision smartcard from GPG key backup" flow and
factors common GPG/smartcard operations into shared helper functions
that are reused by both the OEM factory-reset path and the new
reprovision path.

Commit 1: initrd changes

Shared functions (gpg_functions.sh):

• gpg_card_factory_reset() -- factory-reset + forcesig + key-attr setting (RSA and ECC/P-256)
• gpg_keytocard_subkeys() -- move subkeys to card slots 1-3 (sign, encrypt, auth)
• gpg_set_card_identity() -- cardholder name and login fields
• gpg_reset_nk3_secret_app() -- Nitrokey 3 Secrets app reset
• gpg_card_change_pin() -- PIN change via gpg --card-edit
• reprovision_smartcard_from_backup() -- 10-phase flow: mount LUKS backup, detect key type, factory-reset card, restore subkeys, set identity, offer ROM flash

Menu integration:

• gpg-gui.sh: k option (always visible) in GPG Management Menu
• gui-init.sh: K option in clean boot wizard, integrity report, TPM State Inconsistent dialog

OEM consolidation:

• oem-factory-reset.sh: gpg_key_factory_reset and gpg_key_change_pin replaced with thin wrappers calling shared functions

Security hardening:

• mount-usb.sh: --pass-file stores passphrase in 0600 temp file, shredded on exit
• gpg_functions.sh: PINs via --passphrase-file, temp files shredded; PIN bounds validated (6-64 admin, 6-25 user)
• gpg_add_key_reflash returns 1 instead of exit 1
• kexec_default.*.txt removal moved before signing loop (B1)
• Master secret keys deleted in _luks_cleanup on all exit paths

Commit 2: documentation

• doc/configuring-keys.md: reprovision entry points, TPM-reset guidance
• doc/qemu.md: hardlink preservation workflow using ~/Qemu_img/, reprovision test steps, USB flash drive workflow
• doc/recovery-shell.md: authentication scope, reprovision and configuration sections
• doc/modules.md: fix real.gitclean target descriptions to match Makefile
• doc/gpg.md, doc/architecture.md: minor cross-reference updates

[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 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

[Copilot]

Pull request overview

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

Suppressed comments (8)

initrd/etc/gpg_functions.sh:200

• A failed forcesig operation is now treated as success, so provisioning can finish with signature-PIN forcing disabled. The previous OEM implementation aborted here; because this setting prevents cached-PIN signing, failure should propagate instead of silently weakening the provisioned card.

		if [ $rc -ne 0 ]; then
			WARN "Could not enable forced signature PIN; continuing anyway"
		else
			STATUS_OK "Forced signature PIN enabled"
		fi

initrd/etc/gpg_functions.sh:262

• The documented card_admin_pin argument is never supplied to GPG, so this shared helper only works when scdaemon happens to retain an admin-PIN cache from an earlier operation. That makes the explicit-PIN API ineffective and standalone/reconnected calls fail or consume subsequent scripted input as the PIN. Pass the PIN through GPG's loopback input explicitly, or remove the parameter and make the cache precondition explicit.

	# $3: card_admin_pin (default 12345678)
	TRACE_FUNC
	local gpg_name="$1"
	local gpg_email="$2"
	local card_admin_pin="$3"

initrd/etc/gpg_functions.sh:610

• The prompt advertises a length constraint but this loop accepts any nonempty value. In particular, the existing OEM flow caps admin PINs at 25 characters because longer values break HOTP on supported Nitrokey/Librem Key firmware (oem-factory-reset.sh:52-53,1145-1151). Validate both bounds before changing the card PIN.

		NOTE "${pin_label_admin}: for GPG card admin operations, 6-64 chars."
		while [ -z "$new_admin_pin" ]; do
			INPUT "Enter new ${pin_label_admin} (6-64 chars):" -r -s new_admin_pin
		done

initrd/etc/gpg_functions.sh:622

• This success message claims both the OpenPGP admin PIN and NK3 Secrets-app PIN changed before the Secrets-app update runs. If that update fails, only a debug line is emitted and the flow still reports successful reprovisioning, leaving HOTP on an unexpected PIN. Report success only after both operations succeed, and surface or fail the flow when the NK3 reset fails.

		STATUS_OK "${pin_label_admin} changed"

		release_scdaemon
		gpg_reset_nk3_secret_app "$new_admin_pin" || \
			DEBUG "NK3 Secrets app PIN update failed -- HOTP will need the default PIN (12345678)"

initrd/etc/gpg_functions.sh:627

• As with the admin PIN, this accepts values outside the advertised 6–25 range and relies on the card command to fail after earlier destructive phases and possibly after the admin PIN has already changed. Validate the value before invoking gpg_card_change_pin so a simple input error does not leave a partially provisioned card.

		NOTE "GPG User PIN: signing /boot and encryption, 3 attempts max.\nRecommended: 2 diceware words (6-25 chars)"
		while [ -z "$new_user_pin" ]; do
			INPUT "Enter new GPG User PIN (6-25 chars):" -r -s new_user_pin
		done

initrd/etc/gpg_functions.sh:724

• tpm_counter_ok is unset by design on TPM-less GPG boards such as boards/librem_11/librem_11.config:33, so those users are incorrectly told to reset a TPM they do not have. Only emit this warning when TPM rollback protection is enabled and counter creation was expected.

	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

doc/modules.md:158

• This maintenance section does not match the implemented targets. Makefile:1135-1170 defines real.gitclean with single-force git clean -fxd, recreates .canary, and provides real.gitclean_keep_packages{,_and_build}; it defines no real.devclean*, real.gitclean_keep_pkg, or real.gitclean_keep_build targets. As written, most documented commands fail, while the claimed nuclear behavior never occurs. Update the Makefile and docs together or document the existing targets.

#### Nuclear clean (`real.gitclean*`)

Use `git clean -ffxd` (double `-f`).  Deletes everything not tracked by Git, including
downloaded git repositories (coreboot forks, dasharo-ec, tpm-gpio-fail, etc.).
Produces a pristine working tree — all modules must be re-cloned and rebuilt from scratch.
No `.canary` is recreated after the wipe.

doc/recovery-shell.md:36

• Reprovisioning only updates /etc/config.user in RAM and explicitly allows the user to decline flashing; QEMU skips internal flashing entirely. Therefore CONFIG_HAVE_GPG_KEY_BACKUP=y is persisted in CBFS only after a successful ROM flash, not after every reprovision. Qualify this statement so users do not expect authentication to survive reboot when flashing was skipped or failed.

After OEM Factory Reset / Re-Ownership or the reprovision flow,
`CONFIG_HAVE_GPG_KEY_BACKUP=y` is persisted in the user config stored in
CBFS, so that recovery shell and USB boot authentication is enforced
even on boards where the compile-time default differs.

[tlaurion]

#2186 moved initrd/tests (which was under heads.cpio->initrd.cpio.xz->payload) to /tests, so free space got obtained

[Copilot]

Pull request overview

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

Suppressed comments (3)

initrd/etc/gpg_functions.sh:799

• check_config calls DIE on verification failure, so invoking it directly exits the process before sign_ok handling can restore the previous manifests. Isolate it in a subshell so a failed verification reaches the restoration branch below.

			if check_config /boot >/dev/null 2>/tmp/sign_err; then

initrd/etc/gpg_functions.sh:827

• If /boot cannot be remounted writable, the flow continues to export/flash the new key and later offers a reboot while /boot still has signatures for the old key. That can make the next boot unverifiable; abort before ROM flashing just as the signing-failure branch does.

	else
		WARN "/boot not writable; skipping signing"
	fi

initrd/etc/gpg_functions.sh:902

• This reboot prompt is still reached when QEMU skipped persistence, the user declined flashing, or gpg_flash_rom returned after a flash failure. In the empty-keyring/clean-boot entry paths, the new signature then has no key in ROM after reboot. Track successful persistence and do not offer reboot until the key is actually in ROM (or QEMU injection has been completed).

	if whiptail_warning --title 'Reboot?' --yesno "$reboot_msg" 0 80; then

[Copilot]

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