docs(aws): align verifier guidance with release flow

kvinwang · kvinwang · commit 0e6295d6437a · 2026-07-15T02:10:49.000-07:00
Trim the superseded security evaluation to the live threat model and property table, document the actual UKI archive and PCR sidecar layout, and remove stale recipient/fallback claims. Also simplify the certificate output and build fragments referenced by the updated runbook.
diff --git a/docs/aws-attested-instance-security-evaluation.md b/docs/aws-attested-instance-security-evaluation.md
diff --git a/docs/aws-ec2-production-verifier-runbook.md b/docs/aws-ec2-production-verifier-runbook.md
@@ -5,15 +5,16 @@ deployments under the account-admin-untrusted threat model.
 
 The relying party must not trust an AMI ID, DNS name, load balancer, AWS KMS
 key, or dstack KMS endpoint by itself. It should accept a workload only after
-checking the release evidence, NitroTPM evidence freshness, policy `BootInfo`,
+checking the release evidence, NitroTPM challenge binding, policy `BootInfo`,
 and endpoint identity.
 
 ## Inputs
 
 - The release image package for the exact release candidate, produced by the
   unified build entrypoint `os/build.sh` (the `<name>-<version>-uki.tar.gz`
-  dist archive). It contains the UKI, `sha256sum.txt`, `digest.txt`,
-  `metadata.json`, `measurement.aws.cbor`, and the `aws-pcrs.json` side-car.
+  dist archive). It contains `disk.raw`, `sha256sum.txt`, `digest.txt`, and
+  `measurement.{gcp,aws}.cbor`. The build output also contains an
+  `aws-pcrs.json` side-car, but that file is not part of the archive.
 - The dstack monorepo sources pinned at the exact release revision, for the
   reproducible rebuild.
 - A dstack verifier built from this repository.
@@ -36,12 +37,21 @@ git status --porcelain   # must be empty at the pinned release revision
 ./os/build.sh            # reproducible Yocto backend; emits images/<name>-<version>-uki.tar.gz
 ```
 
-Compare the rebuilt package against the published one:
+Compare the rebuilt package against the published one. `sha256sum.txt` lists
+the full build inputs, not only the files in the UKI archive, so do not run
+`sha256sum -c` inside the extracted UKI package:
 
 ```bash
-tar -xzf <name>-<version>-uki.tar.gz
-sha256sum -c sha256sum.txt        # artifacts match their recorded hashes
-sha256sum sha256sum.txt           # os_image_hash; must equal digest.txt and the rebuilt value
+mkdir published rebuilt
+tar -xzf published-<name>-<version>-uki.tar.gz -C published --strip-components=1
+tar -xzf rebuilt-<name>-<version>-uki.tar.gz -C rebuilt --strip-components=1
+
+cmp published/sha256sum.txt rebuilt/sha256sum.txt
+cmp published/measurement.aws.cbor rebuilt/measurement.aws.cbor
+cmp published/disk.raw rebuilt/disk.raw
+
+expected=$(sha256sum published/sha256sum.txt | awk '{print $1}')
+test "$expected" = "$(cat published/digest.txt)"
 ```
 
 BitBake enforces per-recipe input checksums during the rebuild; for full
@@ -60,9 +70,9 @@ os/yocto/tools/aws/audit-aws-ec2-image-hardening.sh \
 
 ## 2. Register the AMI and deploy with `dstack-cloud`
 
-After the release artifact hashes and AWS PCR references match the release
-package, deploy with **`dstack-cloud`** (`platform: aws`). The CLI imports the
-local UKI `disk.raw` as an Attestable AMI (UEFI + NitroTPM v2.0) when
+After the release artifact hashes and AWS PCR references match the published
+release evidence, deploy with **`dstack-cloud`** (`platform: aws`). The CLI
+imports the local UKI `disk.raw` as an Attestable AMI (UEFI + NitroTPM v2.0) when
 `aws_config.ami_id` is empty, builds the shared config disk with
 `aws_measurement` from `measurement.aws.cbor`, and launches the instance.
 
@@ -73,7 +83,7 @@ export PATH="$PATH:$(pwd)/dstack/scripts/bin"
 # project for AWS
 dstack-cloud new my-aws-app --platform aws --region us-west-2
 cd my-aws-app
-# edit dstack-app.json: aws_config.s3_bucket (vmimport), subnet/security groups as needed
+# edit app.json: aws_config.s3_bucket (vmimport), subnet/security groups as needed
 # pull or place the UKI package (must include measurement.aws.cbor) under image_search_paths
 
 dstack-cloud pull dstack-0.6.0   # UKI package must include assemble-time measurement.aws.cbor
@@ -93,11 +103,15 @@ toolchain for reference measurements):
 
 ```bash
 cargo install --git https://github.com/aws/NitroTPM-Tools --locked nitro-tpm-pcr-compute
+# The UKI is EFI/BOOT/BOOTX64.EFI in the 256 MiB EFI partition at 1 MiB.
+dd if=published/disk.raw of=efi.img bs=1M skip=1 count=256 status=none
+mcopy -i efi.img ::EFI/BOOT/BOOTX64.EFI dstack-uki.efi
 nitro-tpm-pcr-compute --image dstack-uki.efi
 pesign -h -P -i dstack-uki.efi   # UKI AuthentiCode SHA256
 ```
 
-The PCRs must match `aws-pcrs.json` in the release package, and their digest
+The PCRs must match the build-output `aws-pcrs.json` side-car when it is
+published with the release, and their digest
 `sha256(PCR4 || PCR7 || PCR12)` must equal the `boot_pcr_digest` committed in
 `measurement.aws.cbor`. For the generic hardened UKI this is the boot PCR set
 plus the UKI hash:
@@ -129,8 +143,7 @@ expected MrConfig V2 config id: <mr-config-id>
 
 Challenge binding uses **report_data → NitroTPM user_data** (same role as
 TDX/GCP): the relying party embeds its own challenge in `report_data` and
-checks it against the returned `boot_info`. There is no GetAppKey recipient
-`public_key` / v2 encryption path.
+checks it against `details.report_data` in the verifier result.
 
 Example verifier request shape:
 
@@ -150,11 +163,16 @@ Require:
 
 ```bash
 # from the release package: os_image_hash = sha256(sha256sum.txt)
-expected_os_image_hash=$(sha256sum sha256sum.txt | awk '{print $1}')
+expected_os_image_hash=$(sha256sum published/sha256sum.txt | awk '{print $1}')
+# exact 64-byte challenge used when collecting this attestation, as hex
+expected_report_data="<128-hex-characters>"
 
-jq -e --arg expected_os_image_hash "$expected_os_image_hash" '
+jq -e \
+  --arg expected_os_image_hash "$expected_os_image_hash" \
+  --arg expected_report_data "$expected_report_data" '
   .is_valid == true and
   .details.quote_verified == true and
+  .details.report_data == $expected_report_data and
   .details.boot_info.attestationMode == "dstack-aws-nitro-tpm" and
   .details.boot_info.tcbStatus == "UpToDate" and
   .details.boot_info.osImageHash == $expected_os_image_hash
@@ -177,7 +195,7 @@ For AWS NitroTPM, the policy must require:
   is required and must bind the attested boot PCRs);
 - accepted app `composeHash` and `appId`;
 - accepted KMS identity via **early `mrAggregated`** (boot-mr-done), same as
-  bare TDX — not `kms.composeHashes`;
+  bare TDX;
 - verified PCR14 event-log replay (single event lane; no PCR23 runtime split) —
   this is the authoritative app-identity binding (`composeHash`, `appId`,
   `instance-id`, `key-provider`);
@@ -227,7 +245,6 @@ Require the generated `endpoint-cert.pem.ratls-verification.json` to contain:
 ```bash
 jq -e '
   .is_valid == true and
-  .details.endpoint_identity_verified == true and
   .details.attestation_mode == "dstack-aws-nitro-tpm" and
   .details.app_info.os_image_hash_verified == true
 ' endpoint-cert.pem.ratls-verification.json
@@ -248,12 +265,13 @@ An AWS EC2 NitroTPM deployment can be promoted only when:
 1. a reproducible rebuild from the clean, pinned release sources yields a
    byte-identical `sha256sum.txt` (and therefore the same `os_image_hash`);
 2. Yocto input content is mirrored or otherwise available by content hash;
-3. independently recomputed AWS PCRs and the UKI AuthentiCode hash match
-   `aws-pcrs.json` and the `boot_pcr_digest` in `measurement.aws.cbor`;
+3. independently recomputed AWS PCRs and the UKI AuthentiCode hash match the
+   published build-output `aws-pcrs.json` side-car (when provided) and the
+   `boot_pcr_digest` in `measurement.aws.cbor`;
 4. the hardening audit has zero failures and zero warnings, or every warning has
    a documented release exception;
 5. the registered AMI has a live EC2 smoke record for the exact AMI ID and
    root snapshot in the release review package;
 6. `/verify` returns a valid AWS `BootInfo`;
-7. auth policy accepts only the intended OS, app, KMS, and recipient-key state;
+7. auth policy accepts only the intended OS, app, and KMS state;
 8. endpoint identity is RA-TLS, signed-response, or attested-gateway bound.
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -115,6 +115,8 @@ These are encrypted before leaving your machine and only decrypted inside the TE
 Deploy to your cloud provider:
 
 ```bash
+# AWS without a preconfigured aws_config.ami_id needs the local UKI package first:
+# dstack-cloud pull <release-image-name>
 dstack-cloud deploy
 ```
 
diff --git a/docs/security/security-model.md b/docs/security/security-model.md
@@ -153,7 +153,7 @@ Use this checklist to verify a workload running in a dstack CVM.
 - [ ] compose-hash matches your docker-compose
 - [ ] All images use SHA256 digests (no mutable tags)
 - [ ] Launch event log replays correctly (RTMR3 on TDX-family platforms, PCR14 on AWS NitroTPM)
-- [ ] Config commitment matches the expected app/config target (TDX `mr_config_id` / SEV `HOST_DATA`; on AWS NitroTPM the app/config identity is bound by PCR14 event-log replay, and the guest-computed `MrConfig` V2 PCR8 commitment is only an optional shortcut for verifiers that skip that replay)
+- [ ] Config commitment matches the expected app/config target (on AWS: PCR14 replay; PCR8 is an optional shortcut — see the [AWS verifier runbook](../aws-ec2-production-verifier-runbook.md))
 - [ ] reportData contains your challenge (replay protection)
 
 **Key management verification:**
diff --git a/docs/tutorials/attestation-verification.md b/docs/tutorials/attestation-verification.md
@@ -90,7 +90,7 @@ The workflow below uses TDX names because the hello-world tutorial deploys a TDX
 | AMD SEV-SNP | SNP report fields and measured config ID | `MrConfigV3` app/config target |
 | AWS EC2 NitroTPM | NitroTPM Attestation Document, AWS NitroTPM PKI, PCR4/PCR7/PCR12, OS image hash | SHA384 PCR14 launch event log through `system-ready` |
 
-For AWS EC2 NitroTPM, PCR23 is not the launch authorization register. It is resettable from the guest and is reserved for optional post-launch runtime telemetry. AWS verifiers must check PCR14 replay (the authoritative app-identity binding) and the recipient public key when key material is returned to the instance. The PCR8 `MrConfig` V2 config commitment is an optional shortcut for lightweight verifiers that would rather recompute the expected PCR8 from the known compose hash and key-provider than replay the PCR14 event log; dstack's own verifier does not check it.
+For the authoritative PCR14 replay and optional PCR8 shortcut, see the [AWS production verifier runbook](../aws-ec2-production-verifier-runbook.md).
 
 ## Understanding RA-TLS
 
@@ -784,7 +784,7 @@ OVMF   VM Config  Kernel   Initrd   App
 
 Each register builds on the previous one. A compromised kernel (RTMR1) could fake application measurements (RTMR3), so always verify from the firmware up.
 
-On AWS EC2 NitroTPM, the equivalent production chain is: verify the NitroTPM Attestation Document signature and AWS NitroTPM PKI, check the expected boot PCRs and OS image hash, replay the PCR14 launch event log, and bind any released key material to the attested recipient public key. (Optionally, a verifier that skips PCR14 event-log replay can instead recompute and check the PCR8 `MrConfig` V2 config commitment for the compose hash and key-provider.)
+On AWS EC2 NitroTPM, verify the AWS NitroTPM PKI, expected boot PCRs and OS image hash, then replay PCR14. See the [AWS production verifier runbook](../aws-ec2-production-verifier-runbook.md).
 
 ### 4. Keep expected measurements updated
 
diff --git a/docs/verification.md b/docs/verification.md
@@ -32,18 +32,12 @@ by platform.
 | --- | --- | --- | --- |
 | TDX-family dstack CVM | MRTD and RTMR0-2 | RTMR3 event log | `report_data` or RA-TLS certificate binding |
 | AMD SEV-SNP | SNP report fields plus `HOST_DATA`/config ID | `MrConfigV3` app/config target | report data or RA-TLS certificate binding |
-| AWS EC2 NitroTPM | NitroTPM Attestation Document, AWS NitroTPM PKI, PCR4/PCR7/PCR12, OS image hash | SHA384 PCR14 launch event log through `system-ready` (authoritative; the PCR8 `MrConfig` V2 config commitment is an optional shortcut for verifiers that skip event-log replay) | NitroTPM `nonce`, `user_data`, `public_key`, or RA-TLS certificate binding |
-
-For AWS EC2 NitroTPM, do not treat PCR23 as the launch authorization register.
-PCR23 is resettable from the guest and is reserved for optional post-launch
-runtime telemetry. Production AWS policy must require the NitroTPM attestation
-mode, valid AWS NitroTPM signature chain, expected boot PCRs, expected OS image
-hash, verified PCR14 replay, and the recipient public key when key material is
-returned to the instance. The PCR8 `MrConfig` V2 config commitment is an
-optional shortcut: a verifier that does not want to replay the PCR14 event log
-may instead recompute the expected PCR8 from the known compose hash and
-key-provider and compare it. It is not required, and dstack's own verifier does
-not check it.
+| AWS EC2 NitroTPM | NitroTPM Attestation Document, AWS NitroTPM PKI, PCR4/PCR7/PCR12, OS image hash | SHA384 PCR14 launch event log through `system-ready` | NitroTPM `user_data` challenge or RA-TLS certificate binding |
+
+On AWS, PCR14 replay is the authoritative application-identity check; PCR8 is
+an optional shortcut for third-party verifiers. See the
+[AWS production verifier runbook](./aws-ec2-production-verifier-runbook.md)
+for the complete platform policy.
 
 ## Learn More
 
diff --git a/dstack/kms/auth-simple/README.md b/dstack/kms/auth-simple/README.md
@@ -88,9 +88,8 @@ that early MR is precomputable.
 
 The verifier that calls auth-simple must already have verified the NitroTPM
 Attestation Document, AWS NitroTPM PKI chain, boot PCRs, PCR14 launch-event
-replay (the authoritative app-identity binding), and any recipient public key
-used for encrypted key release. The PCR8 `MrConfig` V2 config commitment is an
-optional shortcut for verifiers that skip PCR14 replay, not a required check.
+replay, and OS image binding. PCR8 is an optional third-party shortcut, not a
+required dstack check; see `docs/aws-ec2-production-verifier-runbook.md`.
 auth-simple authorizes the resulting canonical `BootInfo`; it does not verify
 raw NitroTPM evidence by itself.
 
@@ -208,9 +207,8 @@ KMS boot authorization.
 1. `tcbStatus` must be listed in `allowedTcbStatuses` (default: only `"UpToDate"`). AWS NitroTPM is normalized to `"UpToDate"` by the KMS before it reaches auth-simple.
 2. Every `advisoryIds` entry must be listed in `allowedAdvisoryIds` (default: none allowed)
 3. `osImageHash` must be in `osImages` array
-4. At least one KMS identity allowlist must be configured:
-   - `kms.mrAggregated` early/boot-mr-done aggregate MR (required)
-6. `deviceId` must be in `kms.devices` unless `allowAnyDevice` is true
+4. `mrAggregated` must be in the `kms.mrAggregated` early/boot-mr-done allowlist
+5. `deviceId` must be in `kms.devices` unless `allowAnyDevice` is true
 
 ### App Boot Validation
 
diff --git a/dstack/nsm-qvl/tests/nitro_attestation.README.md b/dstack/nsm-qvl/tests/nitro_attestation.README.md
@@ -39,17 +39,6 @@ with `TEST_FETCH_CRL` set (that path reaches AWS CRL endpoints over the network)
 - The exact capture command, host operator, and the enclave workload were **not
   recorded** in-repo — treat those as unknown.
 
-## Verified values (informational)
-
-```
-module_id:   i-0827e799ec9232d44-enc019b55a68bd2ed4b
-instance:    i-0827e799ec9232d44  (region us-east-1)
-digest:      SHA384
-signature:   ECDSA P-384 / SHA-384  (COSE alg -35 / ES384, 96 bytes)
-cert window: 2025-12-25T13:15:34Z .. 2025-12-25T16:15:37Z  (short-lived NSM cert)
-root CA:     CN=aws.nitro-enclaves (G1), valid 2019-10-28 .. 2049-10-28
-```
-
 ## Refreshing
 
 NSM leaf certificates expire a few hours after issuance, so this fixture's
diff --git a/dstack/verifier/src/main.rs b/dstack/verifier/src/main.rs
@@ -182,14 +182,11 @@ async fn run_cert_oneshot(file_path: &str, config: &Config) -> anyhow::Result<()
     let output = serde_json::json!({
         "is_valid": true,
         "details": {
-            "endpoint_identity_verified": true,
             "attestation_mode": verified.attestation.quote.mode(),
-            "tee_platform": verified.attestation.quote.mode().as_str(),
             "report_data": hex::encode(verified.attestation.report_data),
             "public_key_der": hex::encode(&verified.public_key_der),
             "app_id_extension": verified.app_id.as_ref().map(hex::encode),
             "special_usage": verified.special_usage,
-            "app_info_extension_present": verified.app_info.is_some(),
             "app_info": app_info.map(|info| serde_json::json!({
                 "app_id": hex::encode(info.app_id),
                 "compose_hash": hex::encode(info.compose_hash),
diff --git a/os/image/README.md b/os/image/README.md
@@ -20,11 +20,11 @@ Both are listed in `sha256sum.txt`, so
 Deploy tooling (`dstack-cloud prepare`) only **embeds** these files into
 `VmConfig`; it must not recompute PCRs (that would change the image identity).
 
-AWS PCR precompute prefers a host `nitro-tpm-pcr-compute` binary (Rust,
+AWS PCR precompute requires a pinned host `nitro-tpm-pcr-compute` binary (Rust,
 [aws/NitroTPM-Tools](https://github.com/aws/NitroTPM-Tools)). Set
-`NITRO_TPM_PCR_COMPUTE_BIN` or install it on `PATH`. If missing, assemble falls
-back to Docker `amazonlinux:2023` + `aws-nitro-tpm-tools`; if neither is
-available, UKI assemble **fails** (no silent skip).
+`NITRO_TPM_PCR_COMPUTE_BIN` or install it on `PATH`, for example with
+`cargo install --git https://github.com/aws/NitroTPM-Tools --locked nitro-tpm-pcr-compute`.
+If it is missing, UKI assembly fails.
 
 `mk-image-mr.sh <release.tar.gz>` creates the flattened, rootfs-free
 `mr_<digest>.tar.gz` bundle consumed by verifier/KMS image-download endpoints.
diff --git a/os/image/assemble.sh b/os/image/assemble.sh
@@ -26,8 +26,8 @@ Environment:
   DSTACK_TAR_RELEASE     Create release tarballs (default: 1)
   ENABLE_UKI_IMAGE       Create the optional UKI disk image (default: 1)
   DSTACK_MR_BIN          Existing dstack-mr binary
-  NITRO_TPM_PCR_COMPUTE_BIN  Host nitro-tpm-pcr-compute (UKI AWS PCRs; required
-                         unless Docker AL2023 fallback is available)
+  NITRO_TPM_PCR_COMPUTE_BIN  Pinned host nitro-tpm-pcr-compute (required for
+                         UKI AWS PCRs; overrides PATH lookup)
   NITRO_TPM_PCR_PK/KEK/DB    Optional Secure Boot ESL paths for PCR7
 EOF
 }
@@ -456,7 +456,6 @@ if [[ "$UKI_CREATED" = "1" ]]; then
     # measurement.aws.cbor -> sha256sum.txt -> os_image_hash, i.e. the
     # measurement the KMS and verifiers enforce. Only a version-pinned,
     # operator-installed tool may produce it.
-    pcr_json=
     if [[ -z "$pcr_compute_bin" ]]; then
         echo "Error: cannot produce measurement.aws.cbor for UKI image." >&2
         echo "Install the pinned host tool:" >&2
@@ -485,7 +484,7 @@ if [[ "$UKI_CREATED" = "1" ]]; then
     echo "Generating measurement.aws.cbor via ${DSTACK_MR_BIN}"
     "${DSTACK_MR_BIN}" aws-measurement-cbor "$pcr4" "$pcr7" "$pcr12" \
         > "${OUTPUT_DIR}/measurement.aws.cbor"
-    # Keep machine-readable PCR side-car for release manifests (not in digest).
+    # Keep a machine-readable side-car for verifier-side PCR comparison.
     printf '%s\n' "$pcr_json" > "${OUTPUT_DIR}/aws-pcrs.json"
     HAVE_MEASUREMENT_AWS=1
 fi
@@ -538,13 +537,7 @@ if [ "$DSTACK_TAR_RELEASE" = "1" ]; then
     if [[ "$UKI_CREATED" = "1" ]]; then
         rm -rf "${IMAGE_TAR_UKI}"
         echo "Archiving UKI image to ${IMAGE_TAR_UKI}"
-        UKI_FILES=(disk.raw digest.txt sha256sum.txt)
-        if [ "$HAVE_MEASUREMENT_GCP" = "1" ]; then
-            UKI_FILES+=(measurement.gcp.cbor)
-        fi
-        if [ "$HAVE_MEASUREMENT_AWS" = "1" ]; then
-            UKI_FILES+=(measurement.aws.cbor)
-        fi
+        UKI_FILES=(disk.raw digest.txt sha256sum.txt measurement.gcp.cbor measurement.aws.cbor)
         UKI_TAR_FILES=()
         for file in "${UKI_FILES[@]}"; do
             UKI_TAR_FILES+=("$TAR_DIR_NAME/$file")
diff --git a/os/yocto/layers/meta-dstack/recipes-kernel/linux/files/dstack-aws.cfg b/os/yocto/layers/meta-dstack/recipes-kernel/linux/files/dstack-aws.cfg
@@ -20,5 +20,3 @@ CONFIG_SERIAL_8250_CONSOLE=y
 CONFIG_SERIAL_8250_PCI=y
 
 # NitroTPM uses the TPM 2.0 CRB interface.
-CONFIG_TCG_TPM=y
-CONFIG_TCG_CRB=y
diff --git a/os/yocto/tools/README.md b/os/yocto/tools/README.md
@@ -12,11 +12,7 @@ the guest-OS backend interface; the supported build entrypoint is
   (`sha256sum.txt`, `measurement.aws.cbor`, `aws-pcrs.json`) come from the
   unified `os/build.sh` flow. AWS EC2 **lifecycle** (AMI import, shared-disk
   deploy, start/stop/logs) lives in `dstack-cloud`
-  (`dstack/scripts/bin/dstack-cloud`) with `platform: aws`. App/config binding
-  is **not** baked into the UKI cmdline; the guest extends the `MrConfig` V2
-  config id into PCR8 at setup, and `measurement.aws.cbor` +
-  `VmConfig.aws_measurement` provide the unified
-  `os_image_hash = sha256(sha256sum.txt)`.
+  (`dstack/scripts/bin/dstack-cloud`) with `platform: aws`.
 
 The legacy cross-cutting helpers live under [`../../../tools/`](../../../tools/)
 instead of inside this backend.
