Repository navigation
doc: align TPM docs with code (PCR roles, sealing, counter) - #2203
Merged
Merged
Conversation
There was a problem hiding this comment.
🟡 Changes recommended
Repository documentation is left internally inconsistent (doc/security-model.md still describes PCR 16 as calcfuturepcr “scratch”), which undermines the accuracy goal of this doc-focused PR.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR corrects TPM PCR documentation and updates a stale comment in the initrd sealing flow to accurately reflect which PCR is extended during LUKS header measurement.
Changes:
- Updates the
doc/tpm.mdPCR table to mark PCR 16 as unused by Heads and not part of any sealing policy. - Fixes a stale comment in
initrd/bin/kexec-seal-key.shto correctly describe measuring LUKS headers into PCR 6 and producing/tmp/luksDump.txtforcalcfuturepcr.
File summaries
| File | Description |
|---|---|
| initrd/bin/kexec-seal-key.sh | Updates the measurement comment to correctly reference PCR 6 and /tmp/luksDump.txt. |
| doc/tpm.md | Corrects the PCR table entry for PCR 16 to reflect actual Heads behavior. |
Review details
- Files reviewed: 1/2 changed files
- Comments generated: 1
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
tlaurion
force-pushed
the
doc/tpm-pcr-corrections
branch
2 times, most recently
from
September 7, 2026 19:55
fcb9c6e to
13082a7
Compare
This was referenced Sep 7, 2026
tlaurion
force-pushed
the
doc/tpm-pcr-corrections
branch
from
September 7, 2026 20:01
13082a7 to
5d590e9
Compare
tlaurion
added a commit
to tlaurion/heads-wiki
that referenced
this pull request
Sep 7, 2026
PCR 16 was historically scratch space for calcfuturepcr on TPM1 (PCR 23 on TPM2). calcfuturepcr was later rewritten to replay from cbmem -L event log, eliminating the need for any scratch PCR. PCR 16 is now unused. Extends doc/tpm.md fix (linuxboot/heads#2203). Signed-off-by: Thierry Laurion <insurgo@riseup.net>
tlaurion
force-pushed
the
doc/tpm-pcr-corrections
branch
from
September 7, 2026 23:59
5d590e9 to
5072786
Compare
tlaurion
added a commit
to tlaurion/heads-wiki
that referenced
this pull request
Sep 7, 2026
PCR 16 was historically scratch space for calcfuturepcr on TPM1 (PCR 23 on TPM2). calcfuturepcr was later rewritten to replay from cbmem -L event log, eliminating the need for any scratch PCR. PCR 16 is now unused. Extends doc/tpm.md fix (linuxboot/heads#2203). Signed-off-by: Thierry Laurion <insurgo@riseup.net>
tlaurion
force-pushed
the
doc/tpm-pcr-corrections
branch
3 times, most recently
from
September 8, 2026 02:08
35e36b1 to
a4c25a6
Compare
tlaurion
added a commit
to tlaurion/heads-wiki
that referenced
this pull request
Sep 8, 2026
PCR 16 was historically scratch space for calcfuturepcr on TPM1 (PCR 23 on TPM2). calcfuturepcr was later rewritten to replay from cbmem -L event log, eliminating the need for any scratch PCR. PCR 16 is now unused. Extends doc/tpm.md fix (linuxboot/heads#2203). Signed-off-by: Thierry Laurion <insurgo@riseup.net>
tlaurion
force-pushed
the
doc/tpm-pcr-corrections
branch
2 times, most recently
from
September 15, 2026 21:11
15f93dd to
027ac34
Compare
tlaurion
changed the title
tlaurion
added a commit
to tlaurion/heads-wiki
that referenced
this pull request
Sep 16, 2026
PCR 16 was historically scratch space for calcfuturepcr on TPM1 (PCR 23 on TPM2). calcfuturepcr was later rewritten to replay from cbmem -L event log, eliminating the need for any scratch PCR. PCR 16 is now unused. Extends doc/tpm.md fix (linuxboot/heads#2203). Signed-off-by: Thierry Laurion <insurgo@riseup.net>
tlaurion
force-pushed
the
doc/tpm-pcr-corrections
branch
from
September 16, 2026 17:31
027ac34 to
28913d7
Compare
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved corrections remain for platform-specific PCR behavior, logging semantics, comments, and a cross-reference.
Get a fresh assessment by requesting another Copilot review.
Review details
Suppressed comments (6)
doc/architecture.md:40
- The updated anchor is correct here, but
doc/architecture.md:135still links to the removed#srtm-in-corebootanchor, so the cross-reference correction remains incomplete and that page still sends readers to a broken link. Please update the remaining reference as well.
[tpm.md](tpm.md#root-of-trust-and-srtm-chain) for per-board TPM init timing.
doc/logging.md:127
- This exact INFO message is emitted by both
kexec-insert-key.shafter a DUK unseal andkexec-select-boot.shwhen the DUK path is skipped (! -r /tmp/kexec/kexec_key_devices.txt). Describing it only as a DUK-unseal-path message omits the second normal-boot caller; please label it as the normal boot-mode PCR[4] extend more generally.
* `INFO "TPM: Extending PCR[4] with content of string 'generic' to prevent secret unsealing"` — boot-mode string extend on the DUK unseal path
doc/security-model.md:393
- This diagram still labels PCR 0 as anchored at zero, but BootGuard Measured Boot can populate PCR 0 before coreboot; only PCRs 1 and 3 are unconditionally zero in the documented configuration. Please qualify PCR 0 here so the diagram does not contradict the PCR table.
│ │ PCR 0,1,3: Unused; anchored as zero PCR 2: coreboot SRTM │ │
doc/security-model.md:404
- This second seal-policy diagram repeats the unconditional
PCR 0,1,3zero claim. BootGuard's measured-boot policy can extend PCR 0 before coreboot, so please qualify PCR 0 here as well and leave the zero-anchor statement for PCRs 1 and 3.
│ │ PCR 0,1,3: Unused; anchored as zero PCR 2: coreboot SRTM │ │
doc/tpm.md:170
- This paragraph says PCR 0 remains zero unconditionally, but the table above and the following text document that an Intel BootGuard Measured Boot policy can extend PCR 0 before coreboot. Please limit the unconditional zero-state statement to PCRs 1 and 3 and qualify PCR 0.
PCRs 0-3 are read at seal time and included in sealing policies. The zero
state of PCRs 0, 1, and 3 is intentional — any unexpected extension of those
PCRs (e.g. enabling an optional coreboot feature) would break the seal.
doc/tpm.md:53
- This status condition excludes the legacy boards that the next section explicitly lists as SRTM-capable: KGPE-D16 and the original Librem L1UM use
CONFIG_TPM_INIT=ywithoutCONFIG_TPM_MEASURED_BOOT. Please qualify this as the current-coreboot key and include the legacy key, otherwise the table reports their PCR2 measurements as inactive.
| SRTM (Static Root of Trust for Measurement) | PCR 2 (`CONFIG_PCR_SRTM=2`) | **Active on boards with TPM hardware and `CONFIG_TPM_MEASURED_BOOT=y`** (NO_TPM boards carry the `PCR_SRTM=2` slot but do not measure) |
- Files reviewed: 6/9 changed files
- Comments generated: 3
- Review effort level: Lite
There was a problem hiding this comment.
🟡 Changes recommended
One updated statement in doc/recovery-shell.md implies PCR4 is “set at boot” rather than extended on entry to the recovery shell, which undermines the PR’s goal of precise alignment with code behavior.
Get a fresh assessment by requesting another Copilot review.
Review details
- Files reviewed: 6/9 changed files
- Comments generated: 1
- Review effort level: Lite
The comments no longer described the code they sat in. The DUK seal always includes PCR 5, the TOTP/HOTP shared secret is sealed against PCRs 0,1,2,3,4,7, and the TPM 2 finalize step does not extend PCRs. Describe the counter split between the /boot HOTP file and the TPM rollback counter as it is actually implemented. Signed-off-by: Thierry Laurion <insurgo@riseup.net>
The PCR map, seal policies and rollback binding were restated in several documents and could drift, so point at tpm.md as the maintained source instead of repeating them. The BootGuard sentence also read as unconditional, which is wrong on CBnT boards where the IBB digest comes from the Boot Policy Manifest rather than PCR 0 alone, as raised in linuxboot#1172. Signed-off-by: Thierry Laurion <insurgo@riseup.net>
tlaurion
force-pushed
the
doc/tpm-pcr-corrections
branch
from
September 17, 2026 20:03
aedcc78 to
e9b202d
Compare
tlaurion
force-pushed
the
doc/tpm-pcr-corrections
branch
from
September 17, 2026 20:20
e9b202d to
1362e52
Compare
tlaurion
force-pushed
the
doc/tpm-pcr-corrections
branch
from
September 17, 2026 20:56
1362e52 to
4346166
Compare
tlaurion
force-pushed
the
doc/tpm-pcr-corrections
branch
from
September 17, 2026 21:07
4346166 to
4c35582
Compare
The IBB and the prerequisites for a PCR 0 measurement are scattered across the Intel TXT and CBnT specifications, the Dasharo fork and the review history of the PCR measurement work. Document them in one place so the PCR 0 row in tpm.md no longer has to stand alone, and point tpm.md at the new page from the PCR assignments section. Signed-off-by: Thierry Laurion <insurgo@riseup.net>
tlaurion
force-pushed
the
doc/tpm-pcr-corrections
branch
from
September 17, 2026 21:37
bdc3530 to
4043ff2
Compare
Collaborator
Author
|
if librem_l1um tanscient erros become a problem (old time race condition in fmd_scanner at build time) Heads upstream will drop it cc @JonathonHall-Purism, It's a merge, didn't think of spending so much time here and in heads-wiki. Clean state unless proven otherwise through other issues. deepwiki will be refreshed and we will improve from AI understanding, since lack of user feeback, in free time, |
tlaurion
added a commit
to tlaurion/heads
that referenced
this pull request
Sep 17, 2026
The claim that most client machines ship verified boot only, so PCR 0 stays zero, is not backed by any code or source. No code in initrd/ relies on it and the document cites nothing that states it, so remove it rather than reword it into another generalization. What remains is checkable: PCR 0 receives a Boot Guard ACM measurement when the platform is provisioned with a profile that includes measurement, and a platform provisioned without such a profile leaves PCR 0 unchanged. The wording originated in linuxboot/heads-wiki#249 and was propagated into doc/tpm.md by linuxboot#2203. Signed-off-by: Thierry Laurion <insurgo@riseup.net>
tlaurion
added a commit
to tlaurion/heads-wiki
that referenced
this pull request
Sep 17, 2026
… claim NovaCustom does not always ship unfused keys: units can ship unfused, but production TrustRoot units are provisioned and only accept firmware signed for the provisioned Boot Guard profile. Remove the assertion that most client machines ship verified boot only and therefore leave PCR 0 zero. Nothing supported that sentence, so it is deleted rather than reworded into another generalization. PCR 0 is now described only as receiving an ACM measurement when the platform is provisioned with a Boot Guard profile that includes measurement. The sentence was introduced by this work as linuxboot#249 and propagated into heads doc/tpm.md by linuxboot/heads#2203. Documentation only. Signed-off-by: Thierry Laurion <insurgo@riseup.net>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation and comments only; no runtime behaviour change.
This branch brings the TPM documentation and the stale comments in
initrd/back in line with what the sealing and attestation code actually does. It follows the earlier PCR/TPM doc sweeps (#1172, #2068).Four commits over master (all GPG-signed and signed off):
7a4acb6d0fbtpm: align documentation with sealing and attestation code— rollback wording now separates a missing record (gated byCONFIG_BOOT_REQ_ROLLBACK) from a mismatched existing record (aborts unlessCONFIG_IGNORE_ROLLBACK); removes the dead owner-passphrase wiring fromseal-totp.shand states the real 8-character minimum.ffe2bf2411cinitrd: correct stale TPM comments— comments acrossgui-init.sh,tpmr.sh,seal-hotpkey.sh,unseal-hotp.sh,seal-totp.sh,functions.sh,unseal-totp.shandwipe-totp.shnow match the code.46504c9b47cdoc: cross-reference tpm.md and qualify the BootGuard IBB claim— the PCR map, seal policies and rollback binding are no longer restated acrossarchitecture.md,boot-process.md,keys.mdandsecurity-model.md; they point atdoc/tpm.md. The BootGuard sentence no longer reads as unconditional: legacy Intel TXT references the IBB by FIT type 7, while CBnT takes the digest from the signed Boot Policy Manifest.4043ff21989doc: add IBB measurement and PCR 0 prerequisites— newdoc/ibb-measurement.mdplus theindex.mdrow and a pointer fromdoc/tpm.md.No testing performed: there is no behaviour to test.