Maintain the approved PCR 7 unlock policy

3 files changed, 101 insertions, 0 deletions

diff --git a/docs/tpm-unlock.md b/docs/tpm-unlock.md
new file mode 100644
index 0000000..d499928
--- /dev/null
+++ b/docs/tpm-unlock.md
@@ -0,0 +1,89 @@
+# TPM Unlock on Arch
+
+The root volume uses a systemd TPM enrollment with a `pcrlock` policy that
+protects PCR 7. Keep a working disk passphrase and the policy recovery PIN in
+a secure location accessible without unlocking this laptop.
+
+The policy, enrollment, and generated component files are host state. Do not
+copy them into this repo. Deploy this configuration only after policy creation,
+enrollment, and an automatic unlock test have succeeded.
+
+## Deploy
+
+Run on the Arch host, outside aibox:
+
+```sh
+just apply
+sudo systemctl daemon-reload
+sudo systemctl enable systemd-pcrlock-make-policy.service
+sudo systemctl restart systemd-pcrlock-make-policy.service
+sudo journalctl -b -u systemd-pcrlock-make-policy.service --no-pager
+```
+
+The journal must show PCR 7 in the protection mask, or report that the policy
+has not changed. Check for errors and unmet conditions. A successful command
+exit alone does not prove that a conditional service ran.
+
+The service runs after root is unlocked. It updates the existing TPM policy
+and boot credential from the approved component files. It selects only PCR 7
+and requires the policy files and the mounted EFI System Partition at `/boot`.
+On a host without an existing policy, the service skips execution.
+
+Leave `systemd-pcrlock-secureboot-policy.service` and
+`systemd-pcrlock-secureboot-authority.service` disabled. These services generate
+component files from the current system. This setup retains the approved
+components instead of automatically accepting changes to Secure Boot settings.
+
+## Updates
+
+Normal kernel and initramfs updates do not require LUKS re-enrollment. Keep the
+existing mkinitcpio and Secure Boot signing hooks. Policy maintenance does not
+build or sign UKIs.
+
+After a systemd update, check the prediction before rebooting:
+
+```sh
+sudo /usr/lib/systemd/systemd-pcrlock --pcr=7 --location=770 predict
+```
+
+If PCR 7 is included and the prediction completes without errors, refresh the
+policy and check the journal:
+
+```sh
+sudo systemctl restart systemd-pcrlock-make-policy.service
+sudo journalctl -b -u systemd-pcrlock-make-policy.service --no-pager
+```
+
+Prediction uses the current boot log. It cannot guarantee that changed firmware
+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.
+
+## Recovery
+
+If automatic unlock fails, use the disk passphrase. Inspect the boot journal
+and `systemd-pcrlock log` before changing policy. Do not clear the TPM, remove
+the policy, or remove password slots.
+
+After confirming that a Secure Boot change was intended, regenerate its
+component files:
+
+```sh
+sudo /usr/lib/systemd/systemd-pcrlock lock-secureboot-policy
+sudo /usr/lib/systemd/systemd-pcrlock lock-secureboot-authority
+sudo /usr/lib/systemd/systemd-pcrlock --pcr=7 --location=770 predict
+```
+
+Proceed only if PCR 7 is included. Update the existing policy with its recovery
+PIN when the old policy no longer permits updates:
+
+```sh
+sudo /usr/lib/systemd/systemd-pcrlock \
+  --pcr=7 --location=770 --recovery-pin=query make-policy
+```
+
+Enter the policy recovery PIN, not the disk passphrase. Do not record this
+session or share the PIN. Reboot to test automatic unlock. An update to the
+existing policy normally needs neither re-enrollment nor a UKI rebuild.
+
+Reference: [systemd-pcrlock manual](https://man.archlinux.org/man/systemd-pcrlock.8.en).
diff --git a/etc/systemd/system/systemd-pcrlock-make-policy.service.d/pcr7.conf b/etc/systemd/system/systemd-pcrlock-make-policy.service.d/pcr7.conf
new file mode 100644
index 0000000..01a51a5
--- /dev/null
+++ b/etc/systemd/system/systemd-pcrlock-make-policy.service.d/pcr7.conf
@@ -0,0 +1,9 @@
+[Unit]
+ConditionPathExists=/var/lib/systemd/pcrlock.json
+ConditionPathExistsGlob=/var/lib/pcrlock.d/*-secureboot-policy.pcrlock.d/generated.pcrlock
+ConditionPathExistsGlob=/var/lib/pcrlock.d/*-secureboot-authority.pcrlock.d/generated.pcrlock
+RequiresMountsFor=/boot /var/lib/systemd /var/lib/pcrlock.d
+
+[Service]
+ExecStart=
+ExecStart=/usr/lib/systemd/systemd-pcrlock make-policy --pcr=7 --location=770
diff --git a/systemd-units/system.txt b/systemd-units/system.txt
index 1c31da3..f9a44d4 100644
--- a/systemd-units/system.txt
+++ b/systemd-units/system.txt
@@ -22,6 +22,9 @@ btrfs-balance@-.timer
 arch-audit.timer
 lostfiles.timer
 
+# --- TPM policy maintenance ---
+systemd-pcrlock-make-policy.service
+
 # --- bluetooth ---
 bluetooth.service