Document how to reseal disk encryption key in the TPM

[rbreslow]

From https://github.com/osresearch/heads/pull/1282:

I had trouble after reflashing because it wasn't obvious how to reseal the disk encryption key in the TPM. For posterity: You have to navigate Options --> → Boot Options --> → Show OS boot menu → Qubes,_with_Xen_hypervisor → Make default and then Heads will prompt Do you want to reseal a disk key to the TPM [y/N]:.

We should document things that could lead to this. For example, flashing an updated Heads that changes TPM measurements. Perhaps it belongs in the upgrade guide or an FAQ?

Edit: Soon as I posted this, I found https://osresearch.net/Updating#re-owning-the-states:

• Sign /boot content (GPG User PIN required)
• Select a new boot default through Boot Options (GPG User PIN required to sign the new default)
  • Optionally set a TPM Disk Unlock Key (Disk Recovery Key passphrase and GPG User PIN required)

I don't think this is clear, and it doesn't explicitly mention resealing the disk encryption key.

[tlaurion]

@rbreslow yes.

I am playing with TPM disk unlock sealing/unsealing right now under https://github.com/osresearch/heads/issues/1283 and i'm realizing as part of qemu-coreboot-fbwhiptail-tpm1 testings that

if:

• /boot/kexec_key_devices.txt exists per past TPM disk unlock key sealing
  • then maybe an additional /boot/kexec_tcpa_log.txt file should be created, containing either raw output of cbmem -L (the TCPA log containing coreboot's measured boot trace for transparency or either a digest (sha256sum of that output) into that file.

With that in place, selecting default boot could pick up on the differences in TCPA log (afterall, reflashing requires resealing measurements for TPMTOTP/HOTP because unsealing wasn't possible because measurements wee inconsistent).

The reasoning of this proposition is that two mechanisms are at play under Heads:

• TPM measurements + sealing/unsealing
• Detach signing of /boot digests and more precisely kexec_* content

When comes the time to unseal, we ask the user to reseal if TPM measurements are inconsistent. But we do not ask the user to recreate hashes and resign (those should not be inconsistent and should not matter). The only place where that matters is at default boot, where the disk unlock key will not unseal if additional things changed. For the matter, if the LUKS header changed, unsealing will fail since measured and sealed for TPM disk unlock key.

With the above proposed change, at time of unsealing, the user could be made aware that what was part of coreboot measured boot changed (maybe show diff even if technically valid but not relevant for non-technical users).

Other thoughts

---

• The default boot code path with TPM disk unlock key depends of the presence of /boot/kexec_key_devices.txt, which as all other kexec_* files, cannot change. One other way to do this would be to delete that file, or have flashing add another file under boot (which would now be detected per https://github.com/osresearch/heads/pull/1262 and is now impractical as well, which would trigger file addition in tree and trigger a resigning)

• Setting a default boot also signs /boot content today. This is why I propose to add a TCPA log, which would be added on next default setup and could be checked on default boot selection

• The whole "Logical encrypted volume" and "encrypted disk" prompts are irrelevant today when resealing. This should be reworked to take advantage of blkid output and attempting cryptsetup isLuks on them, and feed the user only possible options and pre-enter past selected options present under /boot/kexec_key_devices.txt (and another file I do not remember on top of my head being the result of logical encrypted volume previous selection. Point being that we should propose to the user valid options instead of a free typing area, and ease the resealing option by pre-filling the selection from existing configuration as well.

[tlaurion]

@rbreslow counter thought?