docs(security): describe both external API surfaces in cvm-boundaries - #1119
Open
kvinwang wants to merge 1 commit into
Open
docs(security): describe both external API surfaces in cvm-boundaries#1119kvinwang wants to merge 1 commit into
kvinwang wants to merge 1 commit into
Conversation
The public-listener section predated the v0/v1 split: it showed one Worker service with Health bolted onto the frozen method table by a footnote, and said nothing about how the two surfaces bound what an anonymous caller can cost or learn. Split the method list into the frozen surface and the v1 surface, state the invariant that makes the listener safe to expose (no key material, no caller-chosen signing or attestation -- that lives on the internal socket, which is not a CVM boundary), and extend the cost/exposure bullets to the v1 methods: cached identity behind Info, the retry throttle, the deliberate absence of a v1 attestation-on-demand entry point, and the public_tcbinfo reach difference between the two Info methods. Point at guest-api-v1.md as the normative reference and at agent_rpc_v1.proto alongside the frozen proto.
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.
Follow-up to #1116.
docs/security/cvm-boundaries.mddocuments what crosses the CVM boundary, and its public-listener section predated the v0/v1 split: it showed a singleWorkerservice withHealthbolted onto the frozen method table by a parenthetical, and namedAttestAppKey— a method that briefly existed onnextand that #1116 reversed back to the frozenGetAttestationForAppKey.Since that section is the reference for what an unauthenticated caller can reach, a stale method table there is worse than an incomplete one.
What changed
Two tables, one per surface. The frozen
Workerat/prpc(alias/prpc/v0) with its three v0.5.11 methods, and the v1Workerat/prpc/v1withInfo,Version,Health. Correct return types on both.The invariant is stated, not implied. Neither surface returns key material and neither lets a caller choose what gets signed or attested. That — not the method list — is what makes the listener safe to expose, and it is why the internal socket is not a CVM boundary at all: it is reachable only by the application itself.
The cost/exposure bullets now cover v1. The existing analysis of
Health's narrow oracle andGetAttestationForAppKey's per-call attestation is kept and extended with: whyGetAttestationForAppKeyhas no v1 counterpart (a v1 app attests its own key through the internal socket, so the public listener never gained a second attestation-on-demand entry point); the difference between the frozenInfo, which decodes identity from a boot attestation per call, and the v1Info, which serves it from a cache decoded once at startup so an anonymous caller cannot drive quote generation; and the twoInfomethods' differentpublic_tcbinforeach — the frozen one always serveskey_provider_info, v1 blanks it and carries no measurement registers at all.Links now point at
guest-api-v1.mdas the normative v1 reference and at both protos.No behavior change; documentation only.