From 92efe562a9b3db5c15e37a5d9e7fba43675c1af7 Mon Sep 17 00:00:00 2001 From: Abhishek Krishna Date: Sat, 4 Jul 2026 23:18:55 +0530 Subject: [PATCH] docs(attestation): add package README (#7) Anchors the attestation package's API + trust model + vendor integrations + production status. Adjacent to LP-5300 / LP-5301 PoT/PoI receipts insofar as PoT is a form of computation attestation. Pure docs. No behavior change. --- attestation/README.md | 136 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 attestation/README.md diff --git a/attestation/README.md b/attestation/README.md new file mode 100644 index 0000000..1fe91ec --- /dev/null +++ b/attestation/README.md @@ -0,0 +1,136 @@ +# attestation + +Remote-attestation quote verification for TEEs (Intel SGX DCAP v3, Intel TDX +DCAP v4, AMD SEV-SNP). Given a raw hardware quote and a pinned trust policy, +this package cryptographically checks the claim: "I am running the expected +code inside a genuine enclave, and my confidentiality key is bound to that +enclave." A quote either passes all four soundness checks or is rejected with +a specific error — nothing is skipped. + +## Scope + +**Does:** + +- Parse Intel SGX (DCAP v3), Intel TDX (DCAP v4), and AMD SEV-SNP quote wire + formats into a canonical `Quote` shape (`vendor.go`). +- Verify the attestation-key certificate chain to a **pinned** vendor root + (`attestation.go:74-89`, `vendor.go:49-68`). +- Verify the ECDSA signature over the exact signed region of the quote + (SGX/TDX: header ‖ report body under P-256/SHA-256; SNP: `report[0:0x2A0]` + under P-384/SHA-384) (`vendor.go:136-139`, `vendor.go:207-209`, + `vendor.go:257-259`). +- Enforce a caller-supplied enclave measurement allow-list (`MRENCLAVE` for + SGX, `MRTD` for TDX/SNP) (`attestation.go:99-102`). +- Enforce the operator-key binding: `report_data[0:32] == sha256(operatorPub)` + (`attestation.go:57-60`, `vendor.go:273-277`). + +**Does not:** + +- Fetch PCK / VCEK certificates from Intel PCS or AMD KDS. Callers supply the + cert chain in the quote or as a separate parameter (`VerifySNP` takes + `vcekDER` + `askDER` explicitly, `vendor.go:237`). +- Manage the pinned root store or measurement allow-list. Callers construct + `*x509.CertPool` and `map[[32]byte]bool` / `map[[48]byte]bool` themselves + (`attestation.go:35-38`). +- Rotate or revoke roots. Pin lifecycle is upstream policy. + +## Public API + +Verified against HEAD. + +| Symbol | Location | Purpose | +|---------------------------------|-----------------------------|------------------------------------------------------------------------| +| `Quote` | `attestation.go:26-32` | Canonical parsed quote (measurement, report data, leaf, chain, sig). | +| `Policy` | `attestation.go:35-38` | Trust policy: pinned roots + allowed 32-byte measurements. | +| `BindKey(operatorPub) [32]byte` | `attestation.go:58-60` | The value an enclave must place in `ReportData` to bind a pub key. | +| `Verify(q, policy, boundKey)` | `attestation.go:66-109` | Verify a canonical `Quote` against policy + operator key binding. | +| `VerifySGX(...)` | `vendor.go:90-150` | Parse + verify an Intel SGX DCAP v3 quote; returns MRENCLAVE (32B). | +| `VerifyTDX(...)` | `vendor.go:166-220` | Parse + verify an Intel TDX DCAP v4 quote; returns MRTD (48B). | +| `VerifySNP(...)` | `vendor.go:237-269` | Parse + verify an AMD SEV-SNP report; returns measurement (48B). | +| `VendorSGX / VendorTDX / VendorSNP` | `vendor.go:29-33` | String vendor tags. | +| `ErrChain / ErrSignature / ErrMeasurement / ErrBinding / ErrFormat` | `attestation.go:40-46` | Distinguishable verification failures. | +| `ErrQuoteLayout` | `vendor.go:35` | Wire-format-level parse failure (short buffer, bad r‖s width). | + +## Vendor integrations + +`vendor.go` implements the three production TEE quote formats directly (no +third-party dependency, no CGO). Offsets follow the Intel SGX/TDX DCAP quote +spec and the AMD SEV-SNP firmware ABI (`vendor.go:11-13`): + +- **Intel SGX DCAP v3** — `Header(48) ‖ ReportBody(384) ‖ sigDataLen(4) ‖ + sigData`. MRENCLAVE at absolute offset 112; report_data at 368. ECDSA-P256 + over SHA-256. The QE report binds the attestation key via + `report_data = sha256(attestPub ‖ authData)` (`vendor.go:70-150`). +- **Intel TDX DCAP v4** — `Header(48) ‖ TDReport(584) ‖ sigDataLen(4) ‖ + sigData`. MRTD at 184; report_data at 568. Same sigData shape as SGX; + ECDSA-P256/SHA-256 (`vendor.go:152-220`). +- **AMD SEV-SNP** — 1184-byte attestation report. report_data at `0x50`; + measurement at `0x90`; signature at `0x2A0` as raw little-endian r‖s (72 + bytes each). ECDSA-P384 over SHA-384. VCEK leaf must be supplied by the + caller and chain to a pinned AMD root (ARK/ASK) (`vendor.go:222-269`). + +Signature scalars for SGX/TDX ship as raw big-endian r‖s; SNP ships them +little-endian. Both are re-encoded to ASN.1 for `crypto/ecdsa` +(`vendor.go:37-46`, `vendor.go:245-251`, `vendor.go:290-297`). + +## Security model + +Trust root is a **pinned** `*x509.CertPool` supplied by the caller — typically +the Intel SGX/TDX root and/or AMD ARK/ASK. Verification is all-or-nothing: a +quote with a valid measurement but a bad signature, or a valid signature +under an unpinned chain, is rejected (`attestation.go:63-65`). + +The four checks (`attestation.go:66-109`) are: + +1. **Chain** — attestation-key certificate chains to a pinned root + (`ErrChain`). +2. **Signature** — ECDSA signature over the exact signed preimage verifies + under the attestation key (`ErrSignature`). Preimage is + `domain ‖ Measurement ‖ ReportData` where `domain = "hanzo/poi/tee-quote/v1"` + for the canonical shape (`attestation.go:22-23`, `attestation.go:49-55`); + for vendor-native quotes, the signed region is the header + report body + verbatim (`vendor.go:99`, `vendor.go:175`, `vendor.go:243`). +3. **Measurement** — `MRENCLAVE` / `MRTD` on the caller's allow-list + (`ErrMeasurement`). +4. **Binding** — `report_data[0:32] == sha256(boundKey)` (`ErrBinding`). + This is the load-bearing link to `promptseal`: it proves the sealed prompt + can only be opened inside the attested enclave (`attestation.go:1-9`). + +**Replay guards** are out of scope. `Verify` is stateless; nonce / freshness +handling belongs to the caller (typically a challenge in `boundKey` derivation +or an outer transcript). + +Off-curve points are rejected before use (`vendor.go:341-352`), and byte +comparisons for the key-binding check use `equalFixed` — a constant-time +XOR reduction (`vendor.go:279-288`). + +## Production status + +**Real implementation.** Not a scaffolding stub. + +- `attestation.go` (109 lines) — canonical `Verify` performs all four checks + with no bypass; each has a specific error and a dedicated code path + (`attestation.go:74-107`). +- `vendor.go` (369 lines) — three production TEE quote parsers with real + spec-derived byte offsets (`vendor.go:82-87`, `vendor.go:158-163`, + `vendor.go:227-233`), raw-r‖s → ASN.1 re-encoding for `crypto/ecdsa` + (`vendor.go:37-46`), and P-256 / P-384 dispatch by vendor + (`vendor.go:137`, `vendor.go:257`). +- `attestation_test.go` (196 lines) + `vendor_test.go` (252 lines) — tests + cover chain failure, bad signature, disallowed measurement, and wrong + binding for each vendor path. + +Verified at commit HEAD on the `docs/attestation-readme` branch base. + +## References + +- Adjacent to **LP-5300 / LP-5301** (Proof-of-Thought / Proof-of-Inference + receipts) insofar as PoT is a form of computation attestation: an enclave + attestation is the hardware-rooted variant of the same "I ran this code" + claim that PoT expresses at the LP layer. +- The `domain = "hanzo/poi/tee-quote/v1"` tag (`attestation.go:23`) and the + package doc's promptseal reference point to the Hanzo Proof-of-Inference + pipeline: attested-TEE decryption is how PoI achieves non-custodial + delegated operation. +- Intel SGX / TDX DCAP quote spec (Intel). +- AMD SEV-SNP firmware ABI (AMD).