Commit eac2663
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
- docs
- dstack/guest-agent/rpc/proto
- sdk/curl
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
156 | 156 | | |
157 | 157 | | |
158 | 158 | | |
| 159 | + | |
159 | 160 | | |
160 | 161 | | |
161 | 162 | | |
| |||
0 commit comments