Skip to content

Commit eac2663

Browse files
committed
docs: give the frozen v0 guest API a written contract
0.6.0 froze the unversioned surface at exactly what v0.5.11 served, and `docs/guest-api-v1.md` is normative for v1 only. So the surface that is closed forever, and that every deployed 0.5.x client talks to, is the one with no specification -- `sdk/curl/api.md` says outright that it is a tour and not the contract. Two items on the 0.6 prerelease checklist were open because of it. `docs/guest-api-v0.md` states it from the code: the KDF down to the bytes (HKDF-SHA256 under the "RATLS" salt, `info` the caller's `path` verbatim with no tag, separator or length prefix), which inputs reach it and which do not (`purpose` is echoed into the chain claim and nothing else; `algorithm` picks how the derived 32 bytes are read and does not domain-separate), the algorithm table including the `k256` alias and the empty-string default, the chain claim and the KMS link's preimages, and the verification steps down to where the trust anchor has to come from. The consequence of one KDF serving two curves is stated plainly rather than argued: derive at one path under both algorithms and you hold one secret in two representations. That is what v1's KDF changed, and a caller on this surface has to account for it. `Sign` gets the definition it never had. Its three modes differ in what is signed -- raw message under SHA-256 for secp256k1, raw message for ed25519, and a caller-supplied 32-byte digest that the agent does not re-hash for `secp256k1_prehashed` -- and all three derive the same key, at path `vms` with purpose `signing`, which nothing said anywhere. The proto's `SignRequest` carried no field comments at all; it does now. Comments only: the frozen descriptor digests are unchanged, which is the test that proves it. Two corrections fall out of writing it down. `sdk/curl/api.md` claimed `/Verify` was removed in 0.6.0 and pointed at SDK helpers named `verify_signature`/`verify_signature_chain`; the RPC is alive on the frozen service and those helpers exist nowhere. And `Tappd.RawQuote` requires exactly 64 bytes of report data where `GetQuote` pads, which no document distinguished.
1 parent 4bcf7ef commit eac2663

5 files changed

Lines changed: 744 additions & 15 deletions

File tree

README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -156,6 +156,7 @@ Apps communicate with the guest agent via HTTP over `/var/run/dstack.sock`. Use
156156

157157
**Reference**
158158
- [Guest Agent API v1](./docs/guest-api-v1.md) - Key derivation, signature chains, and the versioned guest API
159+
- [Guest Agent API v0](./docs/guest-api-v0.md) - The frozen legacy surface, for clients that still speak the unversioned API
159160
- [App Compose Format](./docs/normalized-app-compose.md) - Compose file specification
160161
- [Intel TDX Attestation](./docs/attestation-tdx.md) - Measurement and runtime-event verification
161162
- [Native TEE Interfaces](./docs/native-tee-interfaces.md) - Advanced compatibility with Linux TEE devices and configfs-tsm

0 commit comments

Comments
 (0)