docs: explain os_image_hash trust binding

Author: kvinwang

docs/security/security-model.md

@@ -92,6 +92,47 @@ dstack implements layered verification from hardware to application. Each layer
 
 **Key management layer.** The KMS root CA public key hash is recorded in RTMR3 as the key-provider event. This binds your workload to a specific KMS instance. The KMS itself runs in a TEE with its own attestation quote, so you can verify the KMS the same way you verify any workload.
 
+### How `os_image_hash` becomes trusted
+
+The `os_image_hash` carried in `vm_config` is not trusted just because the guest
+or host reports it. The verifier first validates the hardware-signed quote, then
+uses the quoted measurements to bind `os_image_hash` to the software that
+actually booted.
+
+For the full-image TDX path, the verifier obtains the OS image identified by
+`os_image_hash`, checks the image checksum manifest, recomputes the expected
+MRTD and RTMR0-2 from the image and VM configuration, and requires those values
+to match the measurements in the quote. If the host substitutes either the image
+hash or the VM configuration, the recomputed measurements no longer match the
+quote.
+
+For the no-image-download TDX lite path and the AMD SEV-SNP path,
+`os_image_hash` is the unified image identity: `sha256(sha256sum.txt)`. The
+`sha256sum.txt` file is the image checksum manifest generated at image build
+time. It is a text file whose lines contain a SHA-256 digest and relative file
+name for each manifest entry, such as `metadata.json`, the kernel, initrd,
+firmware, and the split measurement file. Some launch-critical artifacts are
+represented indirectly instead of as direct manifest entries: for example, the
+rootfs is committed by the measured `dstack.rootfs_hash` kernel command-line
+parameter, and the SEV firmware is committed by `measurement.snp.cbor`. The exact
+`sha256sum.txt` bytes are hashed, so the manifest contents, file names, ordering,
+and line endings are all part of the image identity.
+
+The attestation carries a copy of the image's `sha256sum.txt` plus the platform
+specific measurement material (`measurement.tdx.cbor` or
+`measurement.snp.cbor`). The verifier checks that:
+
+1. `sha256(checksum_file) == os_image_hash`;
+2. the checksum file contains the expected `measurement.*.cbor` entry and that
+   entry hashes to the supplied measurement material;
+3. the supplied measurement material replays to the hardware-signed TDX
+   MRTD/RTMR values or SEV-SNP launch `MEASUREMENT`/`HOST_DATA`.
+
+Only after these checks pass does the verifier treat the returned
+`os_image_hash` as the measured OS image identity. Downstream authorization
+systems can then compare that trusted value against an allowlist or governance
+contract.
+
 ## Verification Checklist
 
 Use this checklist to verify a workload running in a dstack CVM.

dstack-types/src/lib.rs

@@ -38,8 +38,9 @@ impl OvmfVariant {
 /// Selects how a TDX attestation should bind the OS image.
 ///
 /// `Legacy` preserves the existing verifier behavior: `vm_config.os_image_hash`
-/// is the content digest (`digest.txt`) and the verifier recomputes the full
-/// TDX launch measurement using the legacy image/QEMU-derived path.
+/// is the image digest (`digest.txt`, i.e. `sha256(sha256sum.txt)`) and the
+/// verifier recomputes the full TDX launch measurement using the legacy
+/// image/QEMU-derived path.
 ///
 /// `Lite` opts into the no-QEMU verifier path: `vm_config.os_image_hash`
 /// remains the unified image digest (`sha256(sha256sum.txt)`),

verifier/README.md

@@ -184,9 +184,9 @@ The verifier performs three main verification steps:
 1. **Quote Verification**: Validates the TDX quote using dcap-qvl, checking the quote signature and TCB status
 2. **Event Log Verification**: Replays event logs to ensure RTMR values match and extracts app information. For RTMR3 (runtime measurements), both the digest and payload integrity are verified. For RTMR 0-2 (boot-time measurements), only the digests are verified; the payload content is not validated as dstack does not define semantics for these payloads
 3. **OS Image Hash Verification**:
-   - Automatically downloads OS images if not cached locally
-   - Uses dstack-mr to compute expected measurements
-   - Compares against the verified measurements from the quote
+   - Treats `vm_config` and any attached measurement material as untrusted inputs until they are bound to the hardware quote
+   - For the full-image TDX path, downloads or loads the image identified by `os_image_hash`, checks the image checksum manifest, uses dstack-mr to compute expected MRTD/RTMR0-2, and compares them against the verified measurements from the quote
+   - For TDX lite and AMD SEV-SNP, verifies that `os_image_hash = sha256(sha256sum.txt)`, where `sha256sum.txt` is the image build's checksum manifest (`<sha256>  <relative-file-name>` lines for image files), that the manifest entry for `measurement.tdx.cbor` or `measurement.snp.cbor` matches the supplied measurement material, and that the measurement material replays to the quote's hardware-signed measurements
 
 All three steps must pass for the verification to be considered valid.
 

verifier/src/verification.rs

@@ -742,13 +742,14 @@ impl CvmVerifier {
         };
 
         // Legacy TDX attestation keeps the original KMS verifier semantics:
-        // os_image_hash must be the image content digest, and expected MRs are
-        // recomputed through the existing full-image path.
+        // os_image_hash must be the image digest (digest.txt =
+        // sha256(sha256sum.txt)), and expected MRs are recomputed through the
+        // existing full-image path.
         let image_paths = self.ensure_image_downloaded(vm_config).await?;
         if !Self::image_hash_matches_legacy_digest(&image_paths.image_dir, &vm_config.os_image_hash)
             .context("Failed to check legacy image digest")?
         {
-            bail!("legacy TDX attestation requires the digest.txt os_image_hash");
+            bail!("legacy TDX attestation requires os_image_hash = sha256(sha256sum.txt)");
         }
         details.os_image_is_dev = Some(image_paths.is_dev);
         if !image_paths.version.is_empty() {