Skip to content

refactor: mint self-issued RA-TLS client certificates for guest KMS calls - #1108

Merged
kvinwang merged 5 commits into
nextfrom
feat/ratls-guest-self-signed
Nov 7, 2026
Merged

kvinwang merged 5 commits into
nextfrom
feat/ratls-guest-self-signed

Conversation

@kvinwang

@kvinwang kvinwang commented Aug 23, 2026 •

Copy link
Copy Markdown
Collaborator

Guests now mint self-issued RA-TLS client certificates and fetch the KMS root CA through GetMeta. This removes their GetTempCaCert dependency and stops persisting temporary CA material in .appkeys.json. Existing files still deserialize; reserialization drops the obsolete fields.

Tokenless KMS onboarding retains temporary-CA compatibility, but verifies the source attestation on the connection that actually returns the root keys before importing them. The shared client construction preserves the authenticated admin path. Legacy guests and tokenless onboarding still need GetTempCaCert, so the endpoint remains.

New guests require KMS 0.6.0 or later, whose client authentication verifies attestation rather than the issuer. The initial root-CA fetch retains the existing trust model; key-provider measurement and optional pins bind that identity. The obsolete RaClient::new_mtls helper is removed.

Rebased onto next (d7e15dc902), preserving release notes under Unreleased. Reviewed certificate/SPKI binding, actual-connection source verification, legacy file compatibility, and remaining callers; updated stale migration comments and added a legacy-file regression test.

Validation: 320 tests passed across ra-tls, ra-rpc, cert-client, dstack-util, dstack-kms, and dstack-types, including local Rocket TLS tests for self-issued and temporary-CA certificates and rejection of certificates without attestation. Linux x86_64, Rust 1.92.0, --all-features --locked --offline; Clippy passed with -D warnings --allow unused_variables, workspace formatting and REUSE passed. Local TLS fixtures do not establish production quote validity. No real-TEE guest boot, SignCert hardware round trip, or onboarding from a deployed 0.5.x source was run in this review.

CI setup also constrains hishel<2 in both SDK runners: PDM 2.29.3 calls SyncSqliteStorage, removed in hishel 2.0.0. The previous successful mainline run used hishel 1.4.0; the unconstrained fresh install failed before Python tests started. Both runner scripts pass bash -n.

@kvinwang kvinwang changed the title refactor(guest): mint self-issued RA-TLS client certificates for KMS calls refactor: mint self-issued RA-TLS client certificates for KMS calls Aug 23, 2026
@kvinwang
kvinwang force-pushed the feat/ratls-guest-self-signed branch 3 times, most recently from c1cfe16 to 2f6a1f9 Compare August 23, 2026 16:57
Base automatically changed from feat/ratls-self-signed-client-certs to next August 24, 2026 02:22
@kvinwang
kvinwang force-pushed the feat/ratls-guest-self-signed branch from 2f6a1f9 to 3d5f600 Compare August 24, 2026 02:22
@kvinwang
kvinwang removed this pull request from stack #1109 September 24, 2026 15:24
@kvinwang
kvinwang marked this pull request as ready for review October 3, 2026 01:22

@kvinwang kvinwang left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review after marking ready. The guest-side change still makes sense. The onboarding half needs rework on top of current next, and the PR needs a rebase.

1. The onboarding commit is superseded by next and would break the path it touches.
Since this branch was cut, #1302/#1406 moved handover to Admin.GetKmsKey. With a source_token, Keys::onboard on next already does what this commit does: a self-issued cert on a single client that carries the cert_validator, with ensure_kms_allowed run after the fetch. The tokenless path that remains exists for sources older than 0.6.0, which serve KMS.GetKmsKey publicly (public_key_handover) and pin their temp CA. Moving that path to self-issued certs would make it refuse exactly the sources it is there for.

The binding gap this PR fixes is still present on that path, though. RaClient::new_mtls sets no validator, so the source attestation is checked on the GetTempCaCert connection while the keys arrive on another one. Suggested shape: drop this commit's onboarding change. On the tokenless path, keep minting from the temp CA for compatibility, attach the same capturing validator to the mTLS client, and run ensure_kms_allowed on the attestation captured from the connection that returned the keys. new_mtls can then go.

2. The verify_key_provider_id claim is too strong (code comment in request_app_keys_from_kms_url, CHANGELOG, PR body).
verify_key_provider_id returns Ok(()) when app_compose.key_provider_id is empty, which is the default, so in general a substituted CA does survive to key use. The posture is unchanged from GetTempCaCert, and that is fine. The binding a relying party checks is the key-provider launch event (RTMR3/PCR14) against the on-chain kmsInfo or a pinned key, with verify_key_provider_id as an extra in-guest check only when the app pins it. Please word it that way.

3. Compatibility.
A guest built from this change fails at the TLS handshake against any KMS ≤ 0.5.11. With 0.6.0 released that is acceptable, but the failure surfaces as a bare handshake error at boot. Consider adding context to that error, e.g. "KMS refused a self-issued RA-TLS certificate; the KMS must be ≥ 0.6.0".

4. Nits.

  • Dropping tmp_ca_key/tmp_ca_cert from the public dstack_types::KeyProvider::Kms breaks out-of-tree readers that deserialize new .appkeys.json files with those fields required. That is probably acceptable; worth a line in the CHANGELOG entry next to the existing "readers ignore them" note.
  • The onboarding gen_ra_cert duplicates the body of generate_self_signed_ra_cert except for the quote source. A small helper that takes a VersionedAttestation would let both share the cert construction. This is moot if (1) drops that change.

@kvinwang
kvinwang force-pushed the feat/ratls-guest-self-signed branch from 3d5f600 to 862f4ce Compare October 3, 2026 01:47
@kvinwang kvinwang changed the title refactor: mint self-issued RA-TLS client certificates for KMS calls refactor: mint self-issued RA-TLS client certificates for guest KMS calls Oct 3, 2026
@kvinwang
kvinwang force-pushed the feat/ratls-guest-self-signed branch from 862f4ce to f23abfa Compare October 9, 2026 03:07
Signed-off-by: Kevin Wang <wy721@qq.com>
Signed-off-by: Kevin Wang <wy721@qq.com>
Signed-off-by: Kevin Wang <wy721@qq.com>
@kvinwang
kvinwang force-pushed the feat/ratls-guest-self-signed branch from f23abfa to 5ade496 Compare November 7, 2026 01:49
Signed-off-by: Kevin Wang <wy721@qq.com>
@kvinwang
kvinwang merged commit 963883c into next Nov 7, 2026
14 checks passed
@kvinwang
kvinwang deleted the feat/ratls-guest-self-signed branch November 7, 2026 02:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant