feat(tee): certify the gateway measurement so it is signed evidence (#432)

[imran-siddique]

Second and final half of #432. PR1 (#451) measured the gateway into a TPM_NT_EXTEND NV index; this makes that measurement verifiable by a relying party.

The problem PR1 left open

The NV index value travelled as an ordinary NV read, which no signature covers. So the measurement was a local integrity control only: a compromised gateway could report any value and a verifier had no way to tell. #451 said so explicitly rather than implying otherwise.

Two certifies, bracketing the extend

Per the decision recorded on #432 and in RFC section 5 P2:

V0 = NV_Certify(index)        <- TPM-signed
NV_Extend(gateway_digest)
V1 = NV_Certify(index)        <- TPM-signed

verifier: V1 == H(V0 || expected_gateway_digest)

Why two and not one: TPM2_NV_Certify signs only the index's current value and cannot attest to a previous one, while extends accumulate across reboots. So there is no absolute value a verifier could expect, and a single certify is uncheckable. Two give TPM-signed values whose relation is verifiable, with nothing collector-asserted and no verifier-side state.

The two calls commit different qualifying data (pre / post), so each blob's role is signed rather than inferred from its position in the envelope. Swapping them already fails the relation check; signing the role means a verifier never has to trust ordering.

The shortcut that looks equivalent and is not: reading the index and committing the result into a quote's qualifying data. The collector would be asserting the value it read, and a compromised gateway is precisely the adversary. Recorded in the module docstring so it does not get "simplified" later.

Only the platform key certifies

A transient attestation key produces a verifiable signature with no provenance, which is worse than an honest absence because it looks like evidence. So TPMProvider.platform_attestation_key returns the certified platform key or None, never the transient fallback, and a platform without one falls back to the unsigned extend and ships no evidence at all. That distinction was previously only reachable through a _last_key_was_transient side channel.

Startup ordering

The certify calls commit the attestation nonce, which is derived from the signing key, so the signing key is now generated before the measurement. It has no dependencies of its own, so this is ordering only, not a behaviour change. The documented sequence in run_startup is updated: detect provider, signing key and nonce, measure and certify, produce the report.

Why this is not delegated to agent-manifest

agent_manifest.verify_tpm_quote rejects any attest type that is not TPM_ST_ATTEST_QUOTE, and parse_tpm_quote assumes the attested union is a TPML_PCR_SELECTION followed by a PCR digest. An NV certify carries TPMS_NV_CERTIFY_INFO, so neither can read it.

The certificate chain is delegated to agent_manifest.verify_cert_chain, matching cmcp_verify.sev_snp and cmcp_verify.tdx. Only the TPM_ST_ATTEST_NV and TPMT_SIGNATURE wire formats are local, tracked upstream as agentrust-io/agent-manifest#255.

Tests

23 new, 1021 passing overall. The appraisal is fail-closed at every step, and there is a test for each way the pair can be forged or degraded:

• broken extend relation, and a different gateway digest than expected
• a pair replayed from another session (nonce mismatch)
• pre and post swapped
• two certifies of different NV indices, which would otherwise let a clean index be paired with the real one's successor
• tampered attest, and a signature from an unrelated key
• untrusted root, and no roots at all
• a PCR quote substituted for a certify, which the type check rejects; without it a quote's PCR-selection bytes would be misread as an index name and contents
• malformed and wrong-version envelopes
• an accumulated index (5 prior extends) still verifying, which is the case the whole design exists for

Also asserted: with no expected digest supplied, the result is verified but carries a note saying the measurement was not compared against a known-good value, so internal consistency is not reported as more than it is.

Not validated on hardware

TPM2_NV_Certify has not run against a TPM. The pytss nv_certify signature is written against the documented API, exactly as nv_define_space and nv_extend were before the 2026-08-01 run confirmed them. Everything else here is covered by real tests. Worth one more Azure Trusted Launch run before this path is trusted; that run would also exercise the certify against the platform AK whose chain is host-dependent (#453).

Incidental

mypy src is clean for the first time (55 files). The five pre-existing errors in cmcp_verify/tpm.py were a type[HashAlgorithm] inference that made hash_cls() read as instantiating the abstract base; typing the lookup as a factory fixes it, and padding.PSS.DIGEST_LENGTH replaces hash_cls.digest_size for the same salt length with a correct type. That removes the reviewer note I have been carrying on three PRs.

🤖 Generated with Claude Code