Enable signed initrd and NvPCR measurements

1 files changed, 186 insertions, 33 deletions

diff --git a/docs/tpm-unlock.md b/docs/tpm-unlock.md
index 0cd915b..be02edd 100644
--- a/docs/tpm-unlock.md
+++ b/docs/tpm-unlock.md
@@ -59,56 +59,209 @@ or boot software will produce the same measurements on the next boot. Keep the
 disk passphrase available. No unattended hook relaxes protection or replaces
 LUKS enrollments.
 
-## Unused NvPCR Measurements
+## NvPCR Measurements
 
-This host uses PCR 7 for root unlock. It does not use the default `cryptsetup`,
-`hardware`, `login`, or `verity` NvPCR measurements. Systemd 262 requires a signed
-initrd PCR policy for NvPCR initialization, which this boot setup does not provide.
-This is separate from the NV index that stores the `pcrlock` policy.
+This setup initializes the four systemd NvPCRs. It records hardware identity,
+the logged-in user, and the LUKS root unlock method and keyslot. It also records
+the root volume key in ordinary PCR 15. The verity NvPCR has no event on this
+host because it does not use dm-verity. Root unlock still uses only the existing
+PCR 7 `pcrlock` policy. The NvPCR indices are separate from that policy's index.
 
-Empty files in `etc/nvpcr/` mask the four vendor definitions. Empty unit files
-mask only `systemd-pcrproduct.service` and `systemd-pcrlogin@.service`. Keep these
-files at zero bytes: adding comments removes the mask. SRK setup and PCR 7
-policy maintenance remain active. No TPM index or LUKS keyslot is deleted.
-The mkinitcpio drop-in includes the masks in each rebuilt initramfs.
+Ukify signs an initrd PCR 11 policy with reference `initrd` and embeds its public
+key in each UKI. The `sbctl` mkinitcpio post hook signs the complete UKI for
+Secure Boot. Keep the PCR private key outside the repo and EFI System Partition
+(ESP). Do not regenerate it during updates.
 
-Deploy outside aibox, with the recovery passphrase available:
+### First Activation
 
-```sh
-just apply
-sudo mkinitcpio -P
-sudo sbctl sign-all
-sudo sbctl verify
-```
+Run these steps on Halley2. Keep the LUKS passphrase and pcrlock recovery PIN
+available without unlocking this laptop. Do not reboot until the requested test
+is agreed. Stop if any command fails.
+
+1. Install the declared Arch packages. A full Arch update may rebuild UKIs. If
+   it does, verify Secure Boot signing and automatic unlock on a separate,
+   approved reboot before taking the recovery copy below.
+
+   ```sh
+   sudo pacman -Syu --needed systemd-ukify efibootmgr sbsigntools
+   pacman -Q systemd systemd-ukify mkinitcpio
+   sudo sbctl verify
+   sudo /usr/lib/systemd/systemd-pcrlock --strict=yes --pcr=7 --location=770 predict
+   df -h /boot
+   ```
+
+   `systemd` and `systemd-ukify` must have the same package version. Check that
+   `/boot` can hold one more complete hardened UKI and temporary replacement
+   files. Leave enough free space for normal kernel updates.
+
+2. Save the current boot images and affected `/etc` files in a root-only backup.
+   Do this once, before `just apply`. Do not overwrite this backup on a retry.
+
+   ```sh
+   sudo bash -euo pipefail -c '
+     backup=/var/lib/dotfiles/tpm-nvpcr/backup
+     test ! -e "$backup"
+     install -d -m 0700 "$backup"
+     cp -a /boot/EFI/Linux/arch-linux-hardened*.efi \
+       /boot/EFI/Linux/arch-linux-lts*.efi "$backup/"
+     tar -C / -cpf "$backup/etc.tar" \
+       etc/nvpcr/cryptsetup.nvpcr etc/nvpcr/hardware.nvpcr \
+       etc/nvpcr/login.nvpcr etc/nvpcr/verity.nvpcr \
+       etc/systemd/system/systemd-pcrlogin@.service \
+       etc/systemd/system/systemd-pcrproduct.service \
+       etc/mkinitcpio.conf.d/60-no-nvpcr.conf \
+       etc/mkinitcpio.conf etc/kernel/cmdline \
+       etc/kernel/cmdline-linux-hardened
+   '
+   ```
+
+3. Copy and check a working recovery UKI. Use `--create-only` so this entry does
+   not change the normal EFI boot order. Read its entry number from `efibootmgr -v`.
+
+   ```sh
+   sudo cp -a /boot/EFI/Linux/arch-linux-hardened.efi \
+     /boot/EFI/Linux/arch-linux-hardened-nvpcr-recovery.efi
+   sudo sbverify --cert /var/lib/sbctl/keys/db/db.pem \
+     /boot/EFI/Linux/arch-linux-hardened-nvpcr-recovery.efi
+   sudo efibootmgr --create-only --disk /dev/nvme0n1 --part 1 \
+     --label 'Arch NvPCR Recovery' \
+     --loader '\EFI\Linux\arch-linux-hardened-nvpcr-recovery.efi'
+   sudo efibootmgr -v
+   ```
+
+   On an approved reboot, select this entry once with `efibootmgr --bootnext`
+   or the firmware menu. Confirm automatic unlock. Return to the normal entry.
+   The recovery copy is outside all mkinitcpio presets.
+
+4. Create a dedicated PCR signing key pair if neither file exists. Ukify refuses
+   to replace existing key files. Check permissions and that the keys match.
+
+   ```sh
+   sudo ukify --pcr-private-key=/etc/systemd/tpm2-pcr-private-key.pem \
+     --pcr-public-key=/etc/systemd/tpm2-pcr-public-key.pem genkey
+   sudo stat -c '%U:%G:%a %n' /etc/systemd/tpm2-pcr-private-key.pem
+   sudo openssl pkey -in /etc/systemd/tpm2-pcr-private-key.pem -pubout |
+     sudo cmp - /etc/systemd/tpm2-pcr-public-key.pem
+   ```
+
+   The private file must be `root:root:600`. If either file already exists,
+   verify the pair and do not run `genkey` again. Never copy the private key
+   into the repo, an initramfs, or the ESP.
 
-Stop if image generation or signing fails. Confirm that the rebuilt UKIs are
-signed before rebooting. No re-enrollment is required. The current boot's failed
-setup status can remain until the next boot; do not restart TPM setup merely
-to clear that status.
+5. Apply the repo files and remove only the prior masks. The deployment checks
+   the key pair, ukify version, and recovery image before it changes `/etc`.
+   Chezmoi does not delete files that were removed from its source directory;
+   `tpm-nvpcr-unmask` checks their exact old contents before removing them.
 
-After an approved reboot, confirm automatic unlock and inspect:
+   ```sh
+   just apply
+   just tpm-nvpcr-unmask
+   ```
+
+6. Build and sign all four candidate UKIs on the root filesystem. These
+   commands do not replace the active boot images.
+
+   ```sh
+   sudo install -d -m 0700 /var/lib/dotfiles/tpm-nvpcr/stage
+   sudo mkinitcpio -k /boot/vmlinuz-linux-hardened \
+     -U /var/lib/dotfiles/tpm-nvpcr/stage/arch-linux-hardened.efi \
+     --cmdline /etc/kernel/cmdline-linux-hardened \
+     --ukiconfig /etc/kernel/uki.conf
+   sudo mkinitcpio -k /boot/vmlinuz-linux-hardened \
+     -U /var/lib/dotfiles/tpm-nvpcr/stage/arch-linux-hardened-fallback.efi \
+     --cmdline /etc/kernel/cmdline-linux-hardened \
+     --ukiconfig /etc/kernel/uki.conf -S autodetect
+   sudo mkinitcpio -k /boot/vmlinuz-linux-lts \
+     -U /var/lib/dotfiles/tpm-nvpcr/stage/arch-linux-lts.efi \
+     --cmdline /etc/kernel/cmdline --ukiconfig /etc/kernel/uki.conf
+   sudo mkinitcpio -k /boot/vmlinuz-linux-lts \
+     -U /var/lib/dotfiles/tpm-nvpcr/stage/arch-linux-lts-fallback.efi \
+     --cmdline /etc/kernel/cmdline --ukiconfig /etc/kernel/uki.conf \
+     -S autodetect
+   just tpm-nvpcr-check \
+     /var/lib/dotfiles/tpm-nvpcr/stage/arch-linux-hardened.efi \
+     /var/lib/dotfiles/tpm-nvpcr/stage/arch-linux-hardened-fallback.efi \
+     /var/lib/dotfiles/tpm-nvpcr/stage/arch-linux-lts.efi \
+     /var/lib/dotfiles/tpm-nvpcr/stage/arch-linux-lts-fallback.efi
+   ```
+
+   The check reads `.pcrpkey`, `.pcrsig`, and `.cmdline` using ukify, then
+   verifies each Secure Boot signature with the enrolled `sbctl` certificate.
+   Stop on any mismatch. The `systemd-pcrextend` socket and early setup units
+   must be present in both initramfs variants.
+
+7. Copy the checked images to the ESP with temporary names, then rename them
+   into place. Do not reboot after a partial copy. Restore from the backup if
+   a copy or verification fails.
+
+   ```sh
+   sudo bash -euo pipefail -c '
+     for name in arch-linux-hardened.efi arch-linux-hardened-fallback.efi \
+       arch-linux-lts.efi arch-linux-lts-fallback.efi; do
+       install -m 0644 "/var/lib/dotfiles/tpm-nvpcr/stage/$name" \
+         "/boot/EFI/Linux/$name.next"
+     done
+     for name in arch-linux-hardened.efi arch-linux-hardened-fallback.efi \
+       arch-linux-lts.efi arch-linux-lts-fallback.efi; do
+       mv -f "/boot/EFI/Linux/$name.next" "/boot/EFI/Linux/$name"
+     done
+   '
+   sudo sbctl verify
+   just tpm-nvpcr-check /boot/EFI/Linux/arch-linux-hardened.efi \
+     /boot/EFI/Linux/arch-linux-hardened-fallback.efi \
+     /boot/EFI/Linux/arch-linux-lts.efi \
+     /boot/EFI/Linux/arch-linux-lts-fallback.efi
+   ```
+
+### Boot Checks
+
+After an approved reboot into a new UKI, confirm automatic unlock and run:
 
 ```sh
+just tpm-nvpcr-check
 sudo journalctl -b --no-pager \
   -u systemd-tpm2-setup-early.service \
-  -u systemd-tpm2-setup.service \
+  -u systemd-pcrnvdone.service \
+  -u systemd-pcrproduct.service \
+  -u systemd-pcrlogin@1000.service \
+  -u systemd-cryptsetup@root.service \
   -u systemd-pcrlock-make-policy.service
 systemctl --failed --no-pager
-systemctl is-enabled systemd-pcrproduct.service systemd-pcrlogin@.service
+systemd-analyze nvpcrs
 ```
 
-The two measurement units must report `masked`. SRK setup must have no NvPCR
-initialization failures, and the policy must retain PCR 7 protection.
+The early setup and NvPCR separator must succeed. The `hardware`, `login`, and
+`cryptsetup` records must appear after their events; `verity` can stay at its
+initial value. Check that PCR 7 is still the only disk-unlock policy PCR.
+Boot-test hardened and LTS default and fallback UKIs with explicit approval.
+Then rebuild with `sudo mkinitcpio -P` and repeat a normal boot test. Keep the
+recovery UKI until these checks pass.
+
+### Rollback
+
+If a new image does not boot or automatic unlock fails, select the recovery
+entry and use the disk passphrase if needed. On the running host, restore the
+saved images and exact `/etc` files. Do not remove any TPM indices or keyslots.
+
+```sh
+sudo install -d -m 0700 /var/lib/dotfiles/tpm-nvpcr
+sudo touch /var/lib/dotfiles/tpm-nvpcr/rollback
+sudo bash -euo pipefail -c '
+  cp -a /var/lib/dotfiles/tpm-nvpcr/backup/arch-linux-hardened*.efi \
+    /var/lib/dotfiles/tpm-nvpcr/backup/arch-linux-lts*.efi /boot/EFI/Linux/
+'
+sudo tar -C / -xpf /var/lib/dotfiles/tpm-nvpcr/backup/etc.tar
+sudo rm -f /etc/kernel/uki.conf /etc/initcpio/install/nvpcr
+sudo systemctl daemon-reload
+sudo sbctl verify
+```
 
-To roll back, remove the four `/etc/nvpcr/*.nvpcr` masks listed above, the two
-empty unit files, and `/etc/mkinitcpio.conf.d/60-no-nvpcr.conf`. Remove the same
-files from the repo to prevent redeployment. Reload systemd, rebuild and sign
-the UKIs, and test at the next approved reboot. This restores the vendor
-behavior, including its errors if signed initrd PCR policies are still absent.
+Revert this task's repo commit before another `just apply`. The rollback marker
+blocks redeployment until then. Keep the key pair and recovery UKI for diagnosis.
 
 Sources: [systemd 262 release notes](https://github.com/systemd/systemd/releases/tag/v262),
-[NvPCR setup](https://github.com/systemd/systemd/blob/v262/src/tpm2-setup/tpm2-setup.c),
-and [empty-file mask handling](https://github.com/systemd/systemd/blob/v262/src/basic/conf-files.c).
+[ukify](https://github.com/systemd/systemd/blob/v262/man/ukify.xml), and
+[systemd TPM measurement guide](https://github.com/systemd/systemd/blob/v262/docs/TPM2_PCR_MEASUREMENTS.md).
 
 ## Recovery