Merge pull request #757 from Dstack-TEE/codex/gcp-unified-os-image-hash

gcp: unify OS image hash measurement

Author: kvinwang

docs/attestation-gcp.md

@@ -36,6 +36,12 @@ Verification runs in `Attestation::verify_with_time` and splits into TDX + TPM.
    `tpm_qvl::get_collateral_and_verify(tpm_quote)`.
 2. **Replay runtime events** to compute runtime PCR and compare with quoted PCR.
 3. **Check qualifying data** equals `sha256(tdx_quote)`.
+4. **Bind the OS image identity**:
+   `vm_config.os_image_hash` is the unified image digest
+   `sha256(sha256sum.txt)`. The verifier requires `vm_config.gcp_measurement`,
+   checks that `sha256sum.txt` commits to `measurement.gcp.cbor`, then compares
+   the UKI Authenticode hash inside that CBOR file with the GCP TPM PCR2 UKI
+   event.
 
 ### Optional RA TLS binding
 If the verifier provides a RA TLS pubkey, it enforces:

docs/security/security-model.md

@@ -106,27 +106,30 @@ 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,
+For the no-image-download TDX lite path, the AMD SEV-SNP path, and the GCP TDX
+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.
+parameter, the SEV firmware is committed by `measurement.snp.cbor`, and the GCP
+UKI Authenticode hash is committed by `measurement.gcp.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:
+`measurement.snp.cbor`, or `measurement.gcp.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`.
+   MRTD/RTMR values, SEV-SNP launch `MEASUREMENT`/`HOST_DATA`, or the GCP TPM
+   UKI event.
 
 Only after these checks pass does the verifier treat the returned
 `os_image_hash` as the measured OS image identity. Downstream authorization

dstack-mr/src/main.rs

@@ -14,9 +14,10 @@ use std::path::Path;
 const USAGE: &str = "\
 usage:
   dstack-mr measure-os <image_dir>
-  dstack-mr inspect-measurement [tdx|snp] <measurement.cbor>
+  dstack-mr inspect-measurement [tdx|snp|gcp] <measurement.cbor>
   dstack-mr tdx-measurement-cbor <image_dir>
   dstack-mr snp-measurement-cbor <image_dir>
+  dstack-mr gcp-measurement-cbor <uki_auth_hash_file>
   dstack-mr tdx-measurement-hash <image_dir>
   dstack-mr snp-measurement-hash <image_dir>
 
@@ -65,6 +66,20 @@ fn main() -> Result<()> {
                 .context("failed to write amd sev-snp measurement CBOR")?;
             Ok(())
         }
+        Some("gcp-measurement-cbor") => {
+            let hash_file = args.next().context(USAGE)?;
+            let hash =
+                read_hex_file(&hash_file).context("failed to read GCP UKI Authenticode hash")?;
+            let hash =
+                hex::decode(hash.trim()).context("GCP UKI Authenticode hash is not valid hex")?;
+            let cbor = dstack_types::GcpOsImageMeasurement::new(hash)
+                .map_err(anyhow::Error::msg)?
+                .to_cbor_vec();
+            std::io::stdout()
+                .write_all(&cbor)
+                .context("failed to write GCP measurement CBOR")?;
+            Ok(())
+        }
         Some("tdx-measurement-cbor") => {
             let image_dir = args.next().context(USAGE)?;
             let cbor =
@@ -105,10 +120,17 @@ fn inspect_measurement(kind: &str, path: &Path) -> Result<Value> {
             .map_err(anyhow::Error::msg),
         "snp" | "sev" => dstack_types::SevOsImageMeasurement::cbor_json_value_from_slice(&cbor)
             .map_err(anyhow::Error::msg),
-        other => bail!("unknown measurement kind {other:?}; expected tdx or snp"),
+        "gcp" => dstack_types::GcpOsImageMeasurement::cbor_json_value_from_slice(&cbor)
+            .map_err(anyhow::Error::msg),
+        other => bail!("unknown measurement kind {other:?}; expected tdx, snp, or gcp"),
     }
 }
 
+fn read_hex_file(path: &str) -> Result<String> {
+    let path = Path::new(path);
+    fs_err::read_to_string(path).with_context(|| format!("failed to read {}", path.display()))
+}
+
 fn infer_measurement_kind(path: &str) -> Result<String> {
     let filename = Path::new(path)
         .file_name()
@@ -118,7 +140,9 @@ fn infer_measurement_kind(path: &str) -> Result<String> {
         Ok("tdx".to_string())
     } else if filename.contains(".snp.") || filename.contains("snp") || filename.contains("sev") {
         Ok("snp".to_string())
+    } else if filename.contains(".gcp.") || filename.contains("gcp") {
+        Ok("gcp".to_string())
     } else {
-        bail!("cannot infer measurement kind from {filename:?}; pass tdx or snp explicitly")
+        bail!("cannot infer measurement kind from {filename:?}; pass tdx, snp, or gcp explicitly")
     }
 }

dstack-mr/src/measurement.rs

@@ -6,8 +6,9 @@
 
 use anyhow::{Context, Result};
 use dstack_types::{
-    OsImageMeasurementDocument, SevOsImageMeasurementDocument, TdxOsImageMeasurementDocument,
-    SNP_MEASUREMENT_FILENAME, TDX_MEASUREMENT_FILENAME,
+    GcpOsImageMeasurementDocument, OsImageMeasurementDocument, SevOsImageMeasurementDocument,
+    TdxOsImageMeasurementDocument, GCP_MEASUREMENT_FILENAME, SNP_MEASUREMENT_FILENAME,
+    TDX_MEASUREMENT_FILENAME,
 };
 use fs_err as fs;
 use serde::Deserialize;
@@ -56,5 +57,16 @@ pub fn os_image_measurement_document_for_image_dir(
         None
     };
 
-    Ok(OsImageMeasurementDocument::new(tdx, snp))
+    let gcp_path = image_dir.join(GCP_MEASUREMENT_FILENAME);
+    let gcp = if gcp_path.exists() {
+        Some(GcpOsImageMeasurementDocument::new(
+            fs::read(&sha256sum_path)
+                .with_context(|| format!("cannot read {}", sha256sum_path.display()))?,
+            fs::read(&gcp_path).with_context(|| format!("cannot read {}", gcp_path.display()))?,
+        ))
+    } else {
+        None
+    };
+
+    Ok(OsImageMeasurementDocument::new(tdx, snp, gcp))
 }

dstack-types/src/lib.rs

@@ -298,6 +298,12 @@ pub struct VmConfig {
     /// `tdx_attestation_variant = "lite"` and omitted for legacy TDX.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub tdx_measurement: Option<TdxOsImageMeasurementDocument>,
+    /// GCP TDX no-image-download measurement material. Present for GCP
+    /// deployments so `os_image_hash` can remain the unified image digest
+    /// (`sha256(sha256sum.txt)`) while the verifier still binds the TPM UKI
+    /// Authenticode event to that digest.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub gcp_measurement: Option<GcpOsImageMeasurementDocument>,
 }
 
 /// One OVMF SEV metadata section (gpa/size/type) that affects the SEV-SNP
@@ -331,6 +337,7 @@ fn sha256(bytes: &[u8]) -> [u8; 32] {
 
 pub const TDX_MEASUREMENT_FILENAME: &str = "measurement.tdx.cbor";
 pub const SNP_MEASUREMENT_FILENAME: &str = "measurement.snp.cbor";
+pub const GCP_MEASUREMENT_FILENAME: &str = "measurement.gcp.cbor";
 
 pub fn image_hash_from_sha256sum(checksum_file: &[u8]) -> [u8; 32] {
     sha256(checksum_file)
@@ -401,6 +408,130 @@ pub fn verify_measurement_material(
     Ok(())
 }
 
+/// Image-invariant GCP TDX measurement material. GCP's TPM event log measures
+/// the UKI as a PE/COFF Authenticode SHA-256 digest. The unified image identity
+/// remains `sha256(sha256sum.txt)`; this material is bound to that identity by
+/// the `measurement.gcp.cbor` entry in `sha256sum.txt`.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct GcpOsImageMeasurement {
+    #[serde(with = "hex_bytes")]
+    pub uki_authenticode_sha256: Vec<u8>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+struct CborGcpOsImageMeasurement {
+    version: u32,
+    #[serde(rename = "uki_auth", with = "hex_bytes")]
+    uki_authenticode_sha256: Vec<u8>,
+}
+
+impl From<&GcpOsImageMeasurement> for CborGcpOsImageMeasurement {
+    fn from(measurement: &GcpOsImageMeasurement) -> Self {
+        Self {
+            version: GcpOsImageMeasurement::VERSION,
+            uki_authenticode_sha256: measurement.uki_authenticode_sha256.clone(),
+        }
+    }
+}
+
+impl From<CborGcpOsImageMeasurement> for GcpOsImageMeasurement {
+    fn from(measurement: CborGcpOsImageMeasurement) -> Self {
+        Self {
+            uki_authenticode_sha256: measurement.uki_authenticode_sha256,
+        }
+    }
+}
+
+impl GcpOsImageMeasurement {
+    pub const VERSION: u32 = 1;
+    pub const UKI_AUTHENTICODE_SHA256_LEN: usize = 32;
+
+    pub fn new(uki_authenticode_sha256: Vec<u8>) -> Result<Self, String> {
+        if uki_authenticode_sha256.len() != Self::UKI_AUTHENTICODE_SHA256_LEN {
+            return Err(format!(
+                "GcpOsImageMeasurement: UKI Authenticode hash has invalid length {}, expected {}",
+                uki_authenticode_sha256.len(),
+                Self::UKI_AUTHENTICODE_SHA256_LEN
+            ));
+        }
+        Ok(Self {
+            uki_authenticode_sha256,
+        })
+    }
+
+    pub fn to_cbor_vec(&self) -> Vec<u8> {
+        cbor_to_vec(
+            &CborGcpOsImageMeasurement::from(self),
+            "GcpOsImageMeasurement",
+        )
+    }
+
+    pub fn from_cbor_slice(bytes: &[u8]) -> Result<Self, String> {
+        let measurement: CborGcpOsImageMeasurement =
+            cbor_from_slice(bytes, "GcpOsImageMeasurement")?;
+        if measurement.version != Self::VERSION {
+            return Err(format!(
+                "GcpOsImageMeasurement unsupported version {}, expected {}",
+                measurement.version,
+                Self::VERSION
+            ));
+        }
+        Self::new(measurement.uki_authenticode_sha256)
+    }
+
+    pub fn cbor_json_value_from_slice(bytes: &[u8]) -> Result<serde_json::Value, String> {
+        let measurement: CborGcpOsImageMeasurement =
+            cbor_from_slice(bytes, "GcpOsImageMeasurement")?;
+        serde_json::to_value(measurement)
+            .map_err(|e| format!("GcpOsImageMeasurement: failed to convert to JSON: {e}"))
+    }
+
+    pub fn measurement_hash(&self) -> [u8; 32] {
+        sha256(&self.to_cbor_vec())
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct GcpOsImageMeasurementDocument {
+    /// Raw checksum file bytes (`sha256sum.txt`). `sha256(checksum_file)` is
+    /// the unified `os_image_hash`.
+    #[serde(with = "serde_human_bytes::base64")]
+    pub checksum_file: Vec<u8>,
+    /// Raw bytes of `measurement.gcp.cbor`.
+    #[serde(with = "serde_human_bytes::base64")]
+    pub measurement: Vec<u8>,
+}
+
+impl GcpOsImageMeasurementDocument {
+    pub fn new(checksum_file: Vec<u8>, measurement: Vec<u8>) -> Self {
+        Self {
+            checksum_file,
+            measurement,
+        }
+    }
+
+    pub fn from_measurement(checksum_file: Vec<u8>, measurement: GcpOsImageMeasurement) -> Self {
+        Self::new(checksum_file, measurement.to_cbor_vec())
+    }
+
+    pub fn decode_measurement(&self) -> Result<GcpOsImageMeasurement, String> {
+        GcpOsImageMeasurement::from_cbor_slice(&self.measurement)
+    }
+
+    pub fn decode_measurement_value(&self) -> Result<serde_json::Value, String> {
+        GcpOsImageMeasurement::cbor_json_value_from_slice(&self.measurement)
+    }
+
+    pub fn verify(&self, os_image_hash: &[u8]) -> Result<(), String> {
+        verify_measurement_material(
+            os_image_hash,
+            &self.checksum_file,
+            &self.measurement,
+            GCP_MEASUREMENT_FILENAME,
+        )
+    }
+}
+
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 struct CborOvmfSection {
     gpa: u64,
@@ -796,6 +927,8 @@ pub struct OsImageMeasurementDocument {
     pub tdx: Option<TdxOsImageMeasurementDocument>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub snp: Option<SevOsImageMeasurementDocument>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub gcp: Option<GcpOsImageMeasurementDocument>,
 }
 
 impl OsImageMeasurementDocument {
@@ -804,11 +937,13 @@ impl OsImageMeasurementDocument {
     pub fn new(
         tdx: Option<TdxOsImageMeasurementDocument>,
         snp: Option<SevOsImageMeasurementDocument>,
+        gcp: Option<GcpOsImageMeasurementDocument>,
     ) -> Self {
         Self {
             version: Self::VERSION,
             tdx,
             snp,
+            gcp,
         }
     }
 }