initrd/gpg: refactor OEM card management into shared functions for reuse, add reprovision flow

Extract shared OpenPGP smartcard management functions from
initrd/bin/oem-factory-reset.sh into initrd/etc/gpg_functions.sh
so they can be reused by multiple callers.  OEM functions become
thin wrappers passing global variables as positional args; the
reprovision flow calls the same shared functions to restore GPG
subkeys from a LUKS-encrypted backup USB onto a replacement USB
Security dongle.

Shared functions (replacing OEM inline code):
- gpg_card_factory_reset(): factory-reset + forcesig + key-attr
  (RSA and ECC/P-256), parameterized on admin PIN
- gpg_keytocard_subkeys(): enable USB, verify card, move subkeys
  to 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(): GPG User PIN change

New reprovision flow (reprovision_smartcard_from_backup()):
10-phase flow: mount LUKS backup -> detect key type -> factory-
reset card -> import subkeys -> set identity -> sign /boot -> flash

GUI integration:
- k option in GPG Management Menu (gpg-gui.sh), always visible
- K option in prompt_missing_gpg_key_action (gui-init.sh)
- Clean boot wizard: OEM reset, reprovision, or ignore

Code quality fixes from review:
- Fix 6 sites where $? was clobbered by TRACE_FUNC/DEBUG calls
- Replace --passphrase-file with --passphrase-fd 3 3< to avoid
  leaking PIN through /proc/<pid>/cmdline
- Fix algo_code/bit_len extraction: head -1 for multi-key backups
- Fix STATUS_OK mount emission: only on success
- Fix gpg_reset_nk3_secret_app: return actual error code from
  hotp_verification, explicit return 0 for non-NK3
- Remove incorrect || [ $? -eq 2 ] patch: gpg --import exit code 2
  is a fatal error, not unchanged
- Fix pubkey.asc import: check success properly, fall back to
  keyring export on failure
- Fix partition derivation for NVMe/MMC: stable [0-9]+$ regex
- Add _luks_cleanup helper for every error return path (replaces
  broken EXIT trap pattern)
- Re-run NK3 Secrets app reset with custom PIN on factory-reset
  retry
- Add chmod 600 on /tmp/secret/gpg_pin
- Write backup passphrase to /tmp/secret/backup_pass, use
  mount-usb.sh --pass-file to avoid argv leak
- Shred /tmp/secret/backup_pass on mount success and failure
- Shred /tmp/secret/gpg_pin after all GPG operations complete
- Limit key_id derivation to first match (head -1) to prevent
  multi-line values breaking gpg --edit-key calls
- Strip trailing <email> from cardholder name when no comment
  is present in UID line
- Reset card_admin_pin to default after factory-reset step so
  subsequent forcesig/key-attr use the correct PIN
- Ensure /tmp/secret exists before writing backup_pass (mkdir -p)
- Export public key from keyring instead of referencing mount
  file: after successful pubkey.asc import, re-export from the
  keyring to /tmp/reprovision_pubkey.asc rather than pointing
  PUBKEY at the potentially-stale /media/pubkey.asc
- Fix gpg_reset_nk3_secret_app header comment: removes
  inaccurate "to factory default" phrasing
- Remove unused uid_decoded local variable from reprovision_smartcard_from_backup
- Fix key_email extraction: add head -1 to prevent multi-line
  values when UID contains multiple <...> blocks
- Fix parent_disk derivation for NVMe/MMC: use p?[0-9]+$ regex
  the original partition used a p<num> separator and reconstruct the
  public partition as parent_disk+p2 vs parent_disk+2 accordingly
  hex fingerprints from gpg --with-colons
- Add --pass-file option to mount-usb.sh: use PASS_FILE variable
  and pass path directly to cryptsetup --key-file instead of
  reading into PASS and echoing via process substitution,
  eliminating the argv leak that --pass-file was meant to fix

Documentation:
- doc/gpg.md, doc/configuring-keys.md, doc/architecture.md:
  updated for the new recovery path
- doc/qemu.md: USB flash drive workflow, hardlink preservation,
  reprovision test
- doc/recovery-shell.md: Authentication and Resetting Config
  sections

Extends PR #1515 (2023): authentication via gpg_auth can now be
enforced with key material restored from a backup.

Tested on Nitrokey Pro 2 (reprovision end-to-end: factory reset,
keytocard, PIN change, public key import, flash, reboot, gpg_auth
works).  Tested on Nitrokey 3 (OEM factory reset creates LUKS
backup + provisions dongle).

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

Author: tlaurion

doc/architecture.md

@@ -5,9 +5,9 @@ Linux kernel, and a security-focused initramfs. It establishes a hardware root o
 measured boot via TPM, and verifies the OS boot environment before handing off control.
 
 See also: [security-model.md](security-model.md), [boot-process.md](boot-process.md),
-[tpm.md](tpm.md) — detailed subsystem documentation.
+[tpm.md](tpm.md)  --  detailed subsystem documentation.
 
-External reference: [deepwiki.com/linuxboot/heads](https://deepwiki.com/linuxboot/heads) —
+External reference: [deepwiki.com/linuxboot/heads](https://deepwiki.com/linuxboot/heads)  -- 
 validated against code in this repository.
 
 ---
@@ -43,7 +43,7 @@ The framebuffer initialized by coreboot (libgfxinit on pre-Alder Lake,
 FSP GOP on Alder Lake and newer) must survive across kexec for display
 to work in the booted OS.  Boards without a coreboot framebuffer
 (talos-2: kernel AST DRM, librem_l1um: BMC serial, KGPE-D16: native
-VGA init — server variants output to BMC serial + AST VGA; workstation
+VGA init  --  server variants output to BMC serial + AST VGA; workstation
 variants use external discrete NVIDIA/AMD GPUs with fbwhiptail) have
 different display paths that do not involve sysfb handoff.
 See [boot-process.md](boot-process.md#target-kernel-display-handoff)
@@ -53,7 +53,7 @@ workaround.
 
 ### Linux kernel (payload)
 
-A minimal, stripped kernel compiled specifically for Heads. No initramfs — it boots directly
+A minimal, stripped kernel compiled specifically for Heads. No initramfs  --  it boots directly
 into the Heads initramfs. Provides device drivers (TPM, USB, storage, network), filesystem
 support, and the platform for the boot scripts.
 
@@ -86,9 +86,9 @@ execution. Source lives in `initrd/`.
 
 Three-layer hierarchy:
 
-1. **`/etc/config`** — Board defaults compiled into the ROM at build time
-2. **`/etc/config.user`** — User overrides extracted from CBFS at runtime
-3. **`/tmp/config`** — Combined result, sourced during boot
+1. **`/etc/config`**  --  Board defaults compiled into the ROM at build time
+2. **`/etc/config.user`**  --  User overrides extracted from CBFS at runtime
+3. **`/tmp/config`**  --  Combined result, sourced during boot
 
 `combine_configs()` in `initrd/etc/functions.sh` merges these by concatenating
 `/etc/config*` into `/tmp/config`. User settings in CBFS take precedence
@@ -105,12 +105,12 @@ The top-level `Makefile` orchestrates:
 - Cross-compiler (`musl-cross-make`, target: `x86_64-linux-musl` or `powerpc64le-linux-musl`)
 - Modules (coreboot, Linux, busybox, GPG, cryptsetup, kexec, LVM2, …)
 - Six CPIO archives assembled into the initramfs:
-  1. `dev.cpio` — device nodes
-  2. `modules.cpio` — kernel modules
-  3. `tools.cpio` — userspace tools + configuration
-  4. `board.cpio` — board-specific scripts
-  5. `heads.cpio` — security scripts (`CONFIG_HEADS=y`)
-  6. `data.cpio` — data files
+  1. `dev.cpio`  --  device nodes
+  2. `modules.cpio`  --  kernel modules
+  3. `tools.cpio`  --  userspace tools + configuration
+  4. `board.cpio`  --  board-specific scripts
+  5. `heads.cpio`  --  security scripts (`CONFIG_HEADS=y`)
+  6. `data.cpio`  --  data files
 - Final ROM image: coreboot ROM with Linux + initramfs payload embedded
 
 Reproducible builds are achieved via Nix-pinned Docker images. See [docker.md](docker.md).
@@ -130,11 +130,11 @@ The CI pipeline's workspace and cache behavior is documented in
 
 ## Key design principles
 
-- **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.
-- **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
+- **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, 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
 
 ### Purism boot modes
 
@@ -162,13 +162,13 @@ kexec-boot.sh → lock_chip.sh → io386 0xb2 0xcb → SMI → FLOCKDN
                                                        until reset
 ```
 
-This is x86/Intel only — QEMU (emulated), Talos II (POWER9), Librem L1UM,
+This is x86/Intel only  --  QEMU (emulated), Talos II (POWER9), Librem L1UM,
 and AMD-based boards (KGPE-D16) lack Intel chipset locking.  29 Intel
 boards across all generations from Sandy Bridge to Alder Lake use this
 mechanism.
 
 See [wp-notes.md](wp-notes.md#pr0-chipset-locking) for the full config
 requirements, runtime chain details, and board-level status.
 
-See also: [wp-notes.md](wp-notes.md) — per-board write-protection
+See also: [wp-notes.md](wp-notes.md)  --  per-board write-protection
 status and tracking.

doc/configuring-keys.md

@@ -8,7 +8,7 @@ new Heads-equipped device.  It configures all security components in one pass.
 **Use a safe environment.**  Passphrases are echoed to the screen during setup.
 
 **Prepare Diceware passphrases in advance.**  Heads displays a QR code linking
-to `osresearch.net/Configuring-Keys` when you enter the questionnaire — that
+to `osresearch.net/Configuring-Keys` when you enter the questionnaire  --  that
 page lists recommended word counts per secret and links to EFF Diceware.
 Using physical dice against a wordlist produces passphrases that are both
 strong and memorable.
@@ -37,7 +37,7 @@ PINs and passphrases (12345678 / 123456) which are publicly known.  Custom
 configuration only happens once per ownership; take the time to do it properly.
 
 When you answer N, Heads displays a **QR code for osresearch.net/Configuring-Keys**
-— scan it with a phone for per-secret word-count guidance and EFF Diceware links.
+ --  scan it with a phone for per-secret word-count guidance and EFF Diceware links.
 
 ## Questionnaire
 
@@ -53,18 +53,18 @@ OS install is unknown to you and may be known to the installer.
 `Would you like to re-encrypt the LUKS container and generate a new LUKS Disk Recovery Key?`
 
 Answer **Y** if you did not install the OS yourself.  Changing the passphrase
-alone does not change the underlying encryption key — anyone with a LUKS header
+alone does not change the underlying encryption key  --  anyone with a LUKS header
 backup from before could still decrypt with the old passphrase.  Re-encryption
 generates a new key and renders old header backups useless.
 
 ### GPG Key Storage
 
 `Would you like to format an encrypted USB Thumb drive to store GPG key material?`
 
-- **Y** — Generates the GPG master key and subkeys in memory, backs them up
+- **Y**  --  Generates the GPG master key and subkeys in memory, backs them up
   to an encrypted LUKS container on a USB thumb drive, then optionally copies
   subkeys to the dongle.  Recommended for production environments.
-- **N** — Generates keys directly on the dongle's OpenPGP smartcard with no
+- **N**  --  Generates keys directly on the dongle's OpenPGP smartcard with no
   off-card backup.  Simpler but irreversible if the dongle is lost.
 
 If you answered Y:
@@ -78,16 +78,16 @@ clone it to a second drive for redundancy.
 
 `Would you like to set a single custom passphrase to all security components?`
 
-Not recommended — using one passphrase for everything means compromising one
+Not recommended  --  using one passphrase for everything means compromising one
 secret compromises all.  Useful only for OEM provisioning workflows.
 
 `Would you like to set distinct PINs/passphrases for each security component?`
 
 Answer **Y**.  You will be prompted for:
 
-- **TPM Owner Passphrase** (min 8 chars) — protects TPM NVRAM ownership
-- **GPG Admin PIN** (6-25 chars) — protects smartcard management operations
-- **GPG User PIN** (6-25 chars) — protects signing and encryption operations
+- **TPM Owner Passphrase** (min 8 chars)  --  protects TPM NVRAM ownership
+- **GPG Admin PIN** (6-25 chars)  --  protects smartcard management operations
+- **GPG User PIN** (6-25 chars)  --  protects signing and encryption operations
 
 ### Custom GPG Key Identity
 
@@ -96,10 +96,10 @@ Answer **Y**.  You will be prompted for:
 Answer **Y** if you plan to use the dongle for personal signing/encryption or
 want the public key to be searchable on keyservers.
 
-- **Real Name** — your name; becomes the cardholder name on the smartcard
-- **Email** — your email; becomes the login field on the smartcard and the
+- **Real Name**  --  your name; becomes the cardholder name on the smartcard
+- **Email**  --  your email; becomes the login field on the smartcard and the
   key UID email
-- **Comment** — distinguishes this key (e.g. "USB Security dongle"); 1-60 chars
+- **Comment**  --  distinguishes this key (e.g. "USB Security dongle"); 1-60 chars
 
 ## Key Generation
 
@@ -119,11 +119,11 @@ After the questionnaire, Heads performs the following steps in order:
 12. Displays all provisioned secrets for confirmation
 
 After completing, Heads shows a **reboot prompt**.  TOTP/HOTP secret
-generation happens on the **first normal boot** after OEM reset — Heads detects
+generation happens on the **first normal boot** after OEM reset  --  Heads detects
 the TPM was cleared and guides you through the reseal process.
 
 RSA key generation on older dongles (Nitrokey Pro, Librem Key) may take
-10 minutes or more — be patient.
+10 minutes or more  --  be patient.
 
 ## Provisioned Secrets Summary
 
@@ -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

@@ -11,7 +11,7 @@ See [configuring-keys.md](configuring-keys.md) for the full provisioning flow.
 Two generation paths are available:
 
 **On-card (default):** keys are generated directly on the smartcard.
-No off-card backup exists — losing the dongle means losing the key.
+No off-card backup exists  --  losing the dongle means losing the key.
 
 **In-memory with backup:** master key and subkeys are generated in RAM,
 backed up to an encrypted LUKS container on a USB thumb drive, then subkeys
@@ -77,22 +77,22 @@ gpg --change-pin
 ```
 
 Menu options:
-- `1` — Change User PIN (requires current User PIN)
-- `2` — Unblock User PIN (requires Admin PIN)
-- `3` — Change Admin PIN (requires current Admin PIN)
+- `1`  --  Change User PIN (requires current User PIN)
+- `2`  --  Unblock User PIN (requires Admin PIN)
+- `3`  --  Change Admin PIN (requires current Admin PIN)
 
 ### PIN Retry Counters
 
 OpenPGP cards have separate retry counters for User PIN, Reset Code, and
 Admin PIN.  The factory state counter reads `3 0 3`:
 
-- `3` — User PIN attempts remaining
-- `0` — Reset Code not configured (factory state; not exhausted)
-- `3` — Admin PIN attempts remaining
+- `3`  --  User PIN attempts remaining
+- `0`  --  Reset Code not configured (factory state; not exhausted)
+- `3`  --  Admin PIN attempts remaining
 
 When a counter reaches 0 the corresponding PIN is blocked.  A blocked User
 PIN can be unblocked with the Admin PIN.  A blocked Admin PIN **cannot be
-recovered** — the card must be fully reset (destroying all keys).
+recovered**  --  the card must be fully reset (destroying all keys).
 
 ## Full Card Reset (last resort)
 
@@ -130,9 +130,21 @@ 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
+- Supports NIST P-256 ECC keys in addition to RSA  --  significantly faster key
   generation and signing.
 - Secrets app (HOTP) PIN is separate from the OpenPGP card Admin PIN.
 - Physical touch confirmation is required for some operations (initialize,