docs(tpmmgr): expand architecture document#5934
Draft
eriknordmark wants to merge 1 commit into
Draft
Conversation
Replace the 30-line stub with a full architecture doc covering the dual single-shot CLI / long-running service shape, pubsub I/O (EdgeNodeCert, AttestQuote, TpmSanityStatus), the well-known TPM handles and NV indices, the CLI subcommand catalog with each boot-script caller, TPM-rooted vs soft cert creation, attestation quote handling, the periodic TPM sanity check that drives nodeagent's MaintenanceModeReasonTpmEncFailure / TpmQuoteFailure paths, and the four control-flow paths through the agent. The debugging section covers the canonical pubsub records, on-disk file locations, the diagnostic CLI subcommands, and how to force each transition. Preserves the references the original doc carried (trustedcomputinggroup.org, the LF Edge "Device Identity" wiki pages, https://github.com/google/go-tpm, and the /persist/newlog/devUpload log location). Structured to mirror nodeagent.md and baseosmgr.md so the pillar docs remain consistent across microservices. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: eriknordmark <erik@zededa.com>
3bf903b to
e29d62e
Compare
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.
Description
Replaces the 30-line stub at
pkg/pillar/docs/tpmmgr.mdwith a fullarchitecture document covering:
tpmmgr's dual shape — a single-shot CLI invoked from the deviceboot scripts (
createDeviceCert,createCerts,saveTpmInfo,diagnostic
print*/test*subcommands) plus a long-runningservice started under
zedbox.EdgeNodeCert(persistent, ECDH/quote/EK certs withthe EK's
TPM2B_PUBLICattached as metadata),AttestQuote(signed quote + PCRs 0–23), and
TpmSanityStatus(consumed bynodeagentto driveMaintenanceModeReasonTpmEncFailure/TpmQuoteFailure).(EK/SRK/AIK/quote/ECDH/device key persistent handles, device-cert
NV index, credentials NV index).
TPM-rooted vs soft cert-creation paths.
upgrade or attestation cycle.
startup, attestation quote, and periodic sanity check.
References from the original doc are carried forward in a "Further
reading" section: trustedcomputinggroup.org, the LF Edge "Device
Identity, Onboarding, Security Foundation" and "Device Identity
rooted at TPM" wiki pages, and a link to
https://github.com/google/go-tpm.The doc is structured to mirror
nodeagent.mdandbaseosmgr.mdso the pillar docs remain consistent across microservices, as part
of the ongoing effort to give every pillar agent an architecture
doc and unit-test suite.
How to test and validate this PR
Docs-only change. Validation is a markdown review:
pkg/pillar/docs/tpmmgr.md(e.g. on github.com) andspot-check formatting (tables, fenced code blocks, links).
pkg/pillar/cmd/tpmmgr/tpmmgr.go,pkg/pillar/scripts/device-steps.sh, andpkg/pillar/evetpm/*.gofor technical accuracy.pkg/pillar/evetpm/tpm.go.runCommandswitchin
cmd/tpmmgr/tpmmgr.go.No code changes; no automated test required.
Changelog notes
No user-facing changes.
PR Backports
Docs-only refactor, no need to backport.
Checklist