physistool 0.1.0__py3-none-any.whl

physis/attestation.py

@@ -0,0 +1,754 @@
+"""AWS Nitro Enclaves attestation verifier for the PhysisFold client.
+
+This is the **centre of trust** of the open-source client (``client-and-api.md``
+§3, ``testing-plan.md`` §1.5): *"verify me, don't trust me"*. Before the client
+sends any input to the folding endpoint (CONTRACT.md §1) it fetches an
+attestation document from ``GET /attestation`` and calls
+:func:`verify_attestation` on it. Only after the AWS signature chain and the
+published PCR0 both check out does it trust the ``enclave_pubkey`` and seal input
+to it.
+
+What a real attestation document is
+-----------------------------------
+The AWS Nitro Security Module (NSM) produces an **attestation document**: a
+``COSE_Sign1`` object (RFC 8152) whose payload is a CBOR map. The relevant
+payload fields (AWS "Nitro Enclaves" attestation spec) are::
+
+    module_id    text        enclave id
+    timestamp    uint        ms since epoch (freshness / anti-replay)
+    digest       text        PCR hash algorithm, "SHA384"
+    pcrs         {int: bstr} PCR index -> measurement (PCR0 = index 0)
+    certificate  bstr        DER leaf cert (public key that signed COSE_Sign1)
+    cabundle     [bstr]      DER intermediate certs, ROOT-FIRST toward leaf
+    public_key   bstr?       the enclave app public key (our X25519 pubkey)
+    user_data    bstr?       optional app data
+    nonce        bstr?       optional caller-supplied challenge
+
+The COSE_Sign1 is signed by the leaf certificate's private key (ECDSA/P-384).
+The leaf chains (via ``cabundle``) up to the **AWS Nitro Enclaves root CA**,
+whose certificate is public and pinned here (:data:`AWS_NITRO_ROOT_CA_PEM`, or
+a fixture path via :func:`set_trust_anchor`).
+
+Wire shape consumed here
+------------------------
+``GET /attestation`` returns JSON (CONTRACT.md §1). Two shapes:
+
+* ``{"stub": true, "pcr0": ..., "enclave_pubkey": ...}`` — Stage-A local dev
+  fixture. **Not** AWS-signed. :func:`verify_attestation` skips verification with
+  a warning and trusts the (dev-only) pubkey, matching today's client behaviour.
+* ``{"stub": false, "document_b64": "<base64 COSE_Sign1 bytes>", ...}`` — a real
+  NSM document. Here the outer JSON is **untrusted**: ``pcr0`` and
+  ``enclave_pubkey`` are taken from the *signed COSE payload*, never from the
+  outer fields. (An outer ``pcr0`` / ``enclave_pubkey``, if present, is ignored
+  for trust — the parent could set them to anything.)
+
+Security properties (why the parent cannot forge)
+--------------------------------------------------
+The value returned by :func:`verify_attestation` is trusted **only** after ALL
+of the following pass, in order — any failure raises before anything is
+returned:
+
+1. The COSE_Sign1 signature verifies against the **leaf certificate** public key.
+2. The certificate chain leaf -> ``cabundle`` links validly (each cert signed by
+   the next), and the top of the chain is signed by the **pinned AWS Nitro root**.
+3. ``payload.pcrs[0] == expected_pcr0`` — a single flipped byte rejects.
+4. The document is fresh: ``timestamp`` within :data:`MAX_AGE_MS` of now and not
+   in the future (anti-replay of an old, otherwise-valid document).
+
+The parent EC2 instance has no AWS Nitro root private key, so it cannot mint a
+leaf that chains to the root, nor re-sign a tampered payload. It also cannot
+change PCR0 without changing the enclave image measurement.
+
+Dependencies
+------------
+Uses ``cryptography`` (already a client dep via ``envelope.py``) for X.509 and
+ECDSA. For CBOR/COSE parsing it prefers ``cbor2`` if installed; otherwise it
+falls back to a **minimal, self-contained CBOR reader** (:func:`_cbor_load`)
+sufficient for NSM documents. This keeps the verifier importable even where
+``cbor2`` is not available. The client is open-source and permitted third-party
+deps; only the compiled engine is dependency-restricted.
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+import struct
+import sys
+import time
+from typing import Any, Optional
+
+from cryptography import x509
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import ec, padding, rsa
+from cryptography.hazmat.primitives.asymmetric.utils import (
+    encode_dss_signature,
+)
+
+# Optional fast CBOR path.
+try:  # pragma: no cover - trivial import guard
+    import cbor2 as _cbor2  # type: ignore
+except Exception:  # pragma: no cover
+    _cbor2 = None
+
+
+# ── Trust anchor: AWS Nitro Enclaves root CA ─────────────────────────────────
+#
+# The AWS Nitro Enclaves root certificate is PUBLIC. AWS publishes it (and its
+# SHA-256 fingerprint) at
+# https://aws-nitro-enclaves.amazonaws.com/AWS_NitroEnclaves_Root-G1.zip
+# It is pinned here so the verifier needs no network access. Operators can
+# override it with a fixture via :func:`set_trust_anchor` (used by the test
+# suite to exercise the chain logic against a *synthetic* root without shipping
+# a forged AWS-looking cert).
+#
+# The pinned AWS Nitro Enclaves Root G1 certificate, downloaded from
+# https://aws-nitro-enclaves.amazonaws.com/AWS_NitroEnclaves_Root-G1.zip and
+# verified against its published DER SHA-256 fingerprint:
+#     641a0321a3e244efe456463195d606317ed7cdcc3c1756e09893f3c68f79bb5b
+# Self-signed, CN=aws.nitro-enclaves, valid 2019-10-28 .. 2049-10-28. This is a
+# PUBLIC certificate; pinning it (not fetching at runtime) is what makes the
+# verifier trustworthy offline. A deploy may still override it via
+# ``set_trust_anchor(...)`` or the PHYSIS_NITRO_ROOT_PEM[_FILE] env vars.
+AWS_NITRO_ROOT_CA_PEM: bytes = b"""-----BEGIN CERTIFICATE-----
+MIICETCCAZagAwIBAgIRAPkxdWgbkK/hHUbMtOTn+FYwCgYIKoZIzj0EAwMwSTEL
+MAkGA1UEBhMCVVMxDzANBgNVBAoMBkFtYXpvbjEMMAoGA1UECwwDQVdTMRswGQYD
+VQQDDBJhd3Mubml0cm8tZW5jbGF2ZXMwHhcNMTkxMDI4MTMyODA1WhcNNDkxMDI4
+MTQyODA1WjBJMQswCQYDVQQGEwJVUzEPMA0GA1UECgwGQW1hem9uMQwwCgYDVQQL
+DANBV1MxGzAZBgNVBAMMEmF3cy5uaXRyby1lbmNsYXZlczB2MBAGByqGSM49AgEG
+BSuBBAAiA2IABPwCVOumCMHzaHDimtqQvkY4MpJzbolL//Zy2YlES1BR5TSksfbb
+48C8WBoyt7F2Bw7eEtaaP+ohG2bnUs990d0JX28TcPQXCEPZ3BABIeTPYwEoCWZE
+h8l5YoQwTcU/9KNCMEAwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUkCW1DdkF
+R+eWw5b6cp3PmanfS5YwDgYDVR0PAQH/BAQDAgGGMAoGCCqGSM49BAMDA2kAMGYC
+MQCjfy+Rocm9Xue4YnwWmNJVA44fA0P5W2OpYow9OYCVRaEevL8uO1XYru5xtMPW
+rfMCMQCi85sWBbJwKKXdS6BptQFuZbT73o/gBh1qUxl/nNr12UO8Yfwr6wPLb+6N
+IwLz3/Y=
+-----END CERTIFICATE-----
+"""
+
+# Freshness window for a real attestation document (anti-replay). AWS NSM
+# timestamps are ms since epoch. 5 minutes is generous for clock skew + fetch.
+MAX_AGE_MS: int = 5 * 60 * 1000
+
+# Small tolerance for a document dated slightly in the future (clock skew).
+FUTURE_SKEW_MS: int = 60 * 1000
+
+
+class AttestationError(Exception):
+    """Raised when an attestation document cannot be trusted.
+
+    Deliberately raised *before* :func:`verify_attestation` returns any value,
+    so a caller that reaches the ``enclave_pubkey`` return is guaranteed the
+    document was fully verified (or was an explicitly-warned stub).
+    """
+
+
+# A process-level trust anchor override. When ``None``, the pinned
+# :data:`AWS_NITRO_ROOT_CA_PEM` is used.
+_TRUST_ANCHOR_PEM: Optional[bytes] = None
+
+
+def set_trust_anchor(pem_bytes: Optional[bytes]) -> None:
+    """Override the root CA used for chain verification (PEM bytes).
+
+    Passing ``None`` restores the pinned :data:`AWS_NITRO_ROOT_CA_PEM`. Used at
+    deploy time to load the published AWS root from a fixture, and by the test
+    suite to swap in a synthetic root (so the chain logic is exercised without
+    shipping a fake AWS-looking certificate).
+    """
+    global _TRUST_ANCHOR_PEM
+    _TRUST_ANCHOR_PEM = pem_bytes
+
+
+# Deploy-time root-CA injection without editing source. Checked ONLY when neither
+# an explicit :func:`set_trust_anchor` override nor the pinned
+# :data:`AWS_NITRO_ROOT_CA_PEM` is set. ``PHYSIS_NITRO_ROOT_PEM`` carries the PEM
+# text directly; ``PHYSIS_NITRO_ROOT_PEM_FILE`` a path to read it from.
+_ENV_ROOT_PEM = "PHYSIS_NITRO_ROOT_PEM"
+_ENV_ROOT_PEM_FILE = "PHYSIS_NITRO_ROOT_PEM_FILE"
+
+
+def _root_pem_from_env() -> Optional[bytes]:
+    pem = os.environ.get(_ENV_ROOT_PEM)
+    if pem:
+        return pem.encode("utf-8") if isinstance(pem, str) else pem
+    path = os.environ.get(_ENV_ROOT_PEM_FILE)
+    if path:
+        try:
+            with open(path, "rb") as fh:
+                return fh.read()
+        except OSError as exc:
+            raise AttestationError(
+                f"{_ENV_ROOT_PEM_FILE}={path!r} could not be read: {exc}"
+            ) from exc
+    return None
+
+
+def _root_ca_cert() -> x509.Certificate:
+    if _TRUST_ANCHOR_PEM is not None:
+        pem = _TRUST_ANCHOR_PEM
+    else:
+        pem = AWS_NITRO_ROOT_CA_PEM or _root_pem_from_env() or b""
+    if not pem:
+        raise AttestationError(
+            "no AWS Nitro root CA pinned. Set attestation.AWS_NITRO_ROOT_CA_PEM "
+            "to the published AWS_NitroEnclaves_Root-G1.pem, call "
+            "set_trust_anchor(pem_bytes=...), or set the "
+            f"{_ENV_ROOT_PEM}/{_ENV_ROOT_PEM_FILE} environment variable."
+        )
+    try:
+        return x509.load_pem_x509_certificate(pem)
+    except Exception as exc:  # noqa: BLE001
+        raise AttestationError(f"invalid pinned root CA PEM: {exc}") from exc
+
+
+# ── Public API ───────────────────────────────────────────────────────────────
+
+def verify_attestation(doc: dict, expected_pcr0: str) -> str:
+    """Verify an attestation document and return the trusted ``enclave_pubkey``.
+
+    Parameters
+    ----------
+    doc : dict
+        The parsed JSON body of ``GET /attestation`` (CONTRACT.md §1). Either a
+        Stage-A stub (``{"stub": true, ...}``) or a real document carrying the
+        raw AWS COSE_Sign1 bytes in ``document_b64`` (base64) — also accepted
+        under the keys ``attestation_b64`` / ``cose_b64`` / ``document``.
+    expected_pcr0 : str
+        The PCR0 measurement of the *published* build, as a hex string. The
+        document's signed PCR0 must equal this exactly.
+
+    Returns
+    -------
+    str
+        The enclave X25519 public key as base64 — the value the client seals
+        input to (Stage C). For a stub, the (unverified, dev-only) outer
+        ``enclave_pubkey``.
+
+    Raises
+    ------
+    AttestationError
+        On any verification failure — wrong PCR0 (even one byte), broken/invalid
+        AWS signature, an untrusted certificate chain, a stale/future document,
+        or a malformed document. Raised **before** any pubkey is returned.
+    """
+    if not isinstance(doc, dict):
+        raise AttestationError("attestation document must be a JSON object")
+
+    # ── Stage-A stub: skip verification with a warning (matches client today).
+    if doc.get("stub"):
+        print(
+            "[stub attestation - AWS signature NOT verified - local dev only]",
+            file=sys.stderr,
+        )
+        pub = doc.get("enclave_pubkey")
+        if not isinstance(pub, str) or not pub:
+            raise AttestationError("stub attestation is missing enclave_pubkey")
+        return pub
+
+    # ── Real document: the outer JSON is UNTRUSTED. Everything trusted comes
+    #    from the signed COSE payload below.
+    cose_b64 = (
+        doc.get("document_b64")
+        or doc.get("attestation_b64")
+        or doc.get("cose_b64")
+        or doc.get("document")
+    )
+    if not isinstance(cose_b64, str) or not cose_b64:
+        raise AttestationError(
+            "non-stub attestation is missing the COSE_Sign1 document "
+            "(expected base64 under 'document_b64')"
+        )
+    try:
+        cose_bytes = base64.b64decode(cose_b64, validate=True)
+    except Exception as exc:  # noqa: BLE001
+        raise AttestationError(f"attestation document is not valid base64: {exc}") from exc
+
+    payload = _verify_cose_and_chain(cose_bytes)
+
+    # ── PCR0 check (constant-shape, exact match; one byte mismatch rejects).
+    pcrs = payload.get("pcrs")
+    if not isinstance(pcrs, dict) or 0 not in pcrs:
+        raise AttestationError("attestation payload has no PCR0")
+    pcr0_bytes = pcrs[0]
+    if not isinstance(pcr0_bytes, (bytes, bytearray)):
+        raise AttestationError("PCR0 is not a byte string")
+    pcr0_hex = bytes(pcr0_bytes).hex()
+
+    expected = _normalize_pcr0(expected_pcr0)
+    if not _consttime_eq(pcr0_hex.lower(), expected):
+        raise AttestationError(
+            "PCR0 mismatch: enclave image is not the published build "
+            f"(got {pcr0_hex[:16]}..., expected {expected[:16]}...)"
+        )
+
+    # ── Freshness (anti-replay of an old but otherwise-valid document).
+    _check_freshness(payload.get("timestamp"))
+
+    # ── Only now do we trust the enclave public key, taken from the SIGNED
+    #    payload (not the outer JSON).
+    pub_bytes = payload.get("public_key")
+    if not isinstance(pub_bytes, (bytes, bytearray)) or len(pub_bytes) == 0:
+        raise AttestationError("attestation payload has no enclave public_key")
+    return base64.b64encode(bytes(pub_bytes)).decode("ascii")
+
+
+# ── COSE_Sign1 + certificate chain verification ──────────────────────────────
+
+def _verify_cose_and_chain(cose_bytes: bytes) -> dict:
+    """Parse a COSE_Sign1, verify its signature + cert chain, return the payload.
+
+    Returns the decoded CBOR payload map (with int-keyed PCRs). Raises
+    :class:`AttestationError` on any structural, signature, or chain failure.
+    """
+    protected_bstr, payload_bytes, signature = _parse_cose_sign1(cose_bytes)
+
+    # Decode the payload (CBOR map) — the attestation fields live here.
+    try:
+        payload = _cbor_load(payload_bytes)
+    except Exception as exc:  # noqa: BLE001
+        raise AttestationError(f"attestation payload is not valid CBOR: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise AttestationError("attestation payload is not a CBOR map")
+
+    # Leaf certificate (signs the COSE_Sign1) + CA bundle (root-first).
+    leaf_der = payload.get("certificate")
+    cabundle = payload.get("cabundle") or []
+    if not isinstance(leaf_der, (bytes, bytearray)):
+        raise AttestationError("attestation payload has no leaf certificate")
+    if not isinstance(cabundle, list):
+        raise AttestationError("attestation cabundle is not a list")
+    try:
+        leaf = x509.load_der_x509_certificate(bytes(leaf_der))
+    except Exception as exc:  # noqa: BLE001
+        raise AttestationError(f"invalid leaf certificate: {exc}") from exc
+
+    # 1) COSE_Sign1 signature against the leaf public key.
+    _verify_cose_signature(protected_bstr, payload_bytes, signature, leaf)
+
+    # 2) Certificate chain: leaf -> cabundle -> pinned AWS Nitro root.
+    _verify_cert_chain(leaf, [bytes(c) for c in cabundle])
+
+    return payload
+
+
+def _parse_cose_sign1(cose_bytes: bytes) -> tuple[bytes, bytes, bytes]:
+    """Decode a COSE_Sign1 into (protected_bstr, payload_bstr, signature).
+
+    A COSE_Sign1 is a CBOR array (optionally tag 18) of four elements:
+    ``[protected: bstr, unprotected: map, payload: bstr, signature: bstr]``.
+    We keep ``protected`` and ``payload`` as raw byte strings because the
+    Sig_structure that gets signed reuses their exact serialised bytes.
+    """
+    try:
+        obj = _cbor_load(cose_bytes)
+    except Exception as exc:  # noqa: BLE001
+        raise AttestationError(f"attestation is not valid CBOR/COSE: {exc}") from exc
+    # cbor2 surfaces the tag as a CBORTag; the minimal reader unwraps tag 18.
+    if _cbor2 is not None and isinstance(obj, _cbor2.CBORTag):
+        obj = obj.value
+    if not isinstance(obj, (list, tuple)) or len(obj) != 4:
+        raise AttestationError("COSE_Sign1 must be a 4-element array")
+    protected, _unprotected, payload, signature = obj
+    if not isinstance(protected, (bytes, bytearray)):
+        raise AttestationError("COSE_Sign1 protected header must be a byte string")
+    if not isinstance(payload, (bytes, bytearray)):
+        raise AttestationError("COSE_Sign1 payload must be a byte string (detached not supported)")
+    if not isinstance(signature, (bytes, bytearray)):
+        raise AttestationError("COSE_Sign1 signature must be a byte string")
+    return bytes(protected), bytes(payload), bytes(signature)
+
+
+def _verify_cose_signature(
+    protected: bytes, payload: bytes, signature: bytes, leaf: x509.Certificate
+) -> None:
+    """Verify the COSE_Sign1 signature over the Sig_structure with the leaf key.
+
+    Sig_structure (RFC 8152 §4.4) for COSE_Sign1::
+
+        [ "Signature1", protected, external_aad (b""), payload ]
+
+    AWS Nitro uses ECDSA over P-384 (COSE alg ES384). The COSE signature is the
+    raw ``r || s`` concatenation; ``cryptography`` wants a DER-encoded ECDSA
+    signature, so we re-encode. RSA leaves are also handled defensively.
+    """
+    sig_structure = _cbor_dump(["Signature1", protected, b"", payload])
+
+    pub = leaf.public_key()
+    try:
+        if isinstance(pub, ec.EllipticCurvePublicKey):
+            der_sig = _raw_ecdsa_to_der(signature)
+            pub.verify(der_sig, sig_structure, ec.ECDSA(_curve_hash(pub.curve)))
+        elif isinstance(pub, rsa.RSAPublicKey):
+            pub.verify(signature, sig_structure, padding.PKCS1v15(), hashes.SHA384())
+        else:  # pragma: no cover - AWS never uses these
+            raise AttestationError(
+                f"unsupported leaf key type for COSE verify: {type(pub).__name__}"
+            )
+    except InvalidSignature as exc:
+        raise AttestationError("COSE_Sign1 signature is invalid (bad AWS signature)") from exc
+    except AttestationError:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        raise AttestationError(f"COSE_Sign1 signature verification failed: {exc}") from exc
+
+
+def _verify_cert_chain(leaf: x509.Certificate, cabundle_der: list[bytes]) -> None:
+    """Verify leaf -> cabundle -> pinned AWS Nitro root.
+
+    ``cabundle`` is ordered **root-first** in the AWS document. We build the
+    ordered chain leaf..root and check every link (child signed by the next
+    cert's public key). The top of the presented chain must be signed by the
+    pinned root, and we anchor trust in that pinned root (identity check against
+    the top intermediate's issuer / self-signed root).
+
+    Each certificate's validity window (notBefore/notAfter) is also enforced.
+    """
+    root = _root_ca_cert()
+
+    # Parse intermediates. AWS orders cabundle root-first; reverse to leaf->root.
+    intermediates: list[x509.Certificate] = []
+    for der in cabundle_der:
+        try:
+            intermediates.append(x509.load_der_x509_certificate(der))
+        except Exception as exc:  # noqa: BLE001
+            raise AttestationError(f"invalid certificate in cabundle: {exc}") from exc
+    intermediates_leaf_first = list(reversed(intermediates))
+
+    # Ordered chain from leaf up to (but not including) the pinned root.
+    chain = [leaf] + intermediates_leaf_first
+
+    now = _utcnow()
+    for cert in chain + [root]:
+        _check_validity_window(cert, now)
+
+    # Each cert in the chain must be signed by the next one's public key; the
+    # last one in the chain must be signed by the pinned root.
+    for i, cert in enumerate(chain):
+        issuer_cert = chain[i + 1] if i + 1 < len(chain) else root
+        _check_signed_by(cert, issuer_cert)
+
+    # Anchor: the top of the presented chain must actually chain to OUR pinned
+    # root (issuer name match), and the root must be self-signed (trust anchor).
+    top = chain[-1]
+    if top.issuer != root.subject:
+        raise AttestationError(
+            "certificate chain does not terminate at the pinned AWS Nitro root"
+        )
+    _check_signed_by(root, root)  # root is self-signed; verifies our anchor
+
+
+def _check_signed_by(cert: x509.Certificate, issuer: x509.Certificate) -> None:
+    """Assert ``cert`` was signed by ``issuer``'s private key."""
+    issuer_pub = issuer.public_key()
+    try:
+        if isinstance(issuer_pub, ec.EllipticCurvePublicKey):
+            issuer_pub.verify(
+                cert.signature,
+                cert.tbs_certificate_bytes,
+                ec.ECDSA(cert.signature_hash_algorithm),
+            )
+        elif isinstance(issuer_pub, rsa.RSAPublicKey):
+            issuer_pub.verify(
+                cert.signature,
+                cert.tbs_certificate_bytes,
+                padding.PKCS1v15(),
+                cert.signature_hash_algorithm,
+            )
+        else:  # pragma: no cover
+            raise AttestationError(
+                f"unsupported issuer key type: {type(issuer_pub).__name__}"
+            )
+    except InvalidSignature as exc:
+        raise AttestationError(
+            "broken certificate chain: a certificate is not signed by its issuer"
+        ) from exc
+    except AttestationError:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        raise AttestationError(f"certificate chain verification failed: {exc}") from exc
+
+
+def _check_validity_window(cert: x509.Certificate, now: float) -> None:
+    """Reject a certificate that is not currently valid (expired / not yet valid)."""
+    try:
+        not_before = cert.not_valid_before_utc.timestamp()
+        not_after = cert.not_valid_after_utc.timestamp()
+    except AttributeError:  # cryptography < 42 fallback
+        not_before = cert.not_valid_before.timestamp()
+        not_after = cert.not_valid_after.timestamp()
+    if now < not_before:
+        raise AttestationError("a certificate in the chain is not yet valid")
+    if now > not_after:
+        raise AttestationError("a certificate in the chain has expired")
+
+
+# ── Freshness / anti-replay ──────────────────────────────────────────────────
+
+def _check_freshness(timestamp_ms: Any) -> None:
+    """Reject a document whose timestamp is stale or in the future."""
+    if timestamp_ms is None:
+        raise AttestationError("attestation payload has no timestamp (cannot check freshness)")
+    if not isinstance(timestamp_ms, (int, float)):
+        raise AttestationError("attestation timestamp is not a number")
+    now_ms = time.time() * 1000.0
+    age = now_ms - float(timestamp_ms)
+    if age > MAX_AGE_MS:
+        raise AttestationError(
+            f"attestation document is stale (age {int(age)} ms > {MAX_AGE_MS} ms) - "
+            "possible replay"
+        )
+    if age < -FUTURE_SKEW_MS:
+        raise AttestationError("attestation document timestamp is in the future")
+
+
+# ── Small helpers ────────────────────────────────────────────────────────────
+
+def _normalize_pcr0(pcr0: str) -> str:
+    if not isinstance(pcr0, str) or not pcr0:
+        raise AttestationError("expected_pcr0 must be a non-empty hex string")
+    s = pcr0.strip().lower()
+    if s.startswith("0x"):
+        s = s[2:]
+    try:
+        bytes.fromhex(s)
+    except ValueError as exc:
+        raise AttestationError(f"expected_pcr0 is not valid hex: {exc}") from exc
+    return s
+
+
+def _consttime_eq(a: str, b: str) -> bool:
+    """Constant-time-ish string compare (avoid early-exit timing on PCR0)."""
+    if len(a) != len(b):
+        return False
+    result = 0
+    for x, y in zip(a, b):
+        result |= ord(x) ^ ord(y)
+    return result == 0
+
+
+def _curve_hash(curve: ec.EllipticCurve) -> hashes.HashAlgorithm:
+    """Pick the COSE hash for an EC curve (P-384 -> SHA-384, AWS default)."""
+    name = curve.name
+    if name == "secp256r1":
+        return hashes.SHA256()
+    if name == "secp521r1":
+        return hashes.SHA512()
+    return hashes.SHA384()  # secp384r1 (AWS Nitro) and default
+
+
+def _raw_ecdsa_to_der(raw: bytes) -> bytes:
+    """Convert a COSE raw ``r || s`` ECDSA signature to DER."""
+    if len(raw) % 2 != 0:
+        raise AttestationError("raw ECDSA signature has odd length")
+    half = len(raw) // 2
+    r = int.from_bytes(raw[:half], "big")
+    s = int.from_bytes(raw[half:], "big")
+    return encode_dss_signature(r, s)
+
+
+def _utcnow() -> float:
+    return time.time()
+
+
+# ── CBOR: prefer cbor2, else a minimal self-contained reader/writer ──────────
+#
+# The minimal reader/writer supports exactly what an NSM attestation document
+# needs: unsigned/negative ints, byte strings, text strings, arrays, maps, the
+# COSE tag (18), and simple values. It is intentionally small; ``cbor2`` is used
+# when present.
+
+def _cbor_load(data: bytes) -> Any:
+    if _cbor2 is not None:
+        return _cbor2.loads(data)
+    value, off = _MinimalCBOR.decode(data, 0)
+    return value
+
+
+def _cbor_dump(obj: Any) -> bytes:
+    if _cbor2 is not None:
+        return _cbor2.dumps(obj)
+    return _MinimalCBOR.encode(obj)
+
+
+class _MinimalCBOR:
+    """A tiny, dependency-free CBOR codec (subset for COSE/NSM).
+
+    Only the constructs used by NSM attestation + the COSE Sig_structure are
+    implemented. Not a general-purpose CBOR library.
+    """
+
+    # ---- decode ----
+    _BREAK = 0xFF  # major 7, minor 31 — the "break" stop code for indefinite items
+
+    @staticmethod
+    def decode(data: bytes, off: int) -> tuple[Any, int]:
+        if off >= len(data):
+            raise ValueError("unexpected end of CBOR data")
+        ib = data[off]
+        major = ib >> 5
+        minor = ib & 0x1F
+        off += 1
+
+        # Indefinite-length items (minor 31): byte/text strings, arrays, maps run
+        # until a 0xFF break. AWS NSM attestation documents encode the payload map
+        # (and its ``pcrs`` sub-map) this way, so the verifier MUST handle it.
+        if minor == 31 and major in (2, 3, 4, 5):
+            return _MinimalCBOR._decode_indefinite(data, off, major)
+
+        val, off = _MinimalCBOR._read_len(data, off, minor)
+
+        if major == 0:  # unsigned int
+            return val, off
+        if major == 1:  # negative int
+            return -1 - val, off
+        if major == 2:  # byte string
+            end = off + val
+            if end > len(data):
+                raise ValueError("truncated byte string")
+            return data[off:end], end
+        if major == 3:  # text string
+            end = off + val
+            if end > len(data):
+                raise ValueError("truncated text string")
+            return data[off:end].decode("utf-8"), end
+        if major == 4:  # array
+            arr = []
+            for _ in range(val):
+                item, off = _MinimalCBOR.decode(data, off)
+                arr.append(item)
+            return arr, off
+        if major == 5:  # map
+            d = {}
+            for _ in range(val):
+                k, off = _MinimalCBOR.decode(data, off)
+                v, off = _MinimalCBOR.decode(data, off)
+                d[k] = v
+            return d, off
+        if major == 6:  # tag
+            inner, off = _MinimalCBOR.decode(data, off)
+            return inner, off  # unwrap tag (COSE tag 18) transparently
+        if major == 7:  # simple / float
+            if minor == 20:
+                return False, off
+            if minor == 21:
+                return True, off
+            if minor == 22:
+                return None, off
+            if minor == 23:
+                return None, off  # undefined
+            if minor == 25:
+                return struct.unpack(">e", data[off - 2:off])[0], off
+            if minor == 26:
+                return struct.unpack(">f", data[off - 4:off])[0], off
+            if minor == 27:
+                return struct.unpack(">d", data[off - 8:off])[0], off
+            return val, off
+        raise ValueError(f"unsupported CBOR major type {major}")
+
+    @staticmethod
+    def _decode_indefinite(data: bytes, off: int, major: int) -> tuple[Any, int]:
+        """Decode an indefinite-length item (major 2/3/4/5), consuming its break.
+
+        Items run until the 0xFF break byte. Strings concatenate their definite
+        chunks; arrays/maps collect elements until the break.
+        """
+        if major == 2:  # byte string: concat definite chunks
+            out = b""
+            while True:
+                if off >= len(data):
+                    raise ValueError("unterminated indefinite byte string")
+                if data[off] == _MinimalCBOR._BREAK:
+                    return out, off + 1
+                chunk, off = _MinimalCBOR.decode(data, off)
+                if not isinstance(chunk, (bytes, bytearray)):
+                    raise ValueError("bad chunk in indefinite byte string")
+                out += bytes(chunk)
+        if major == 3:  # text string: concat definite chunks
+            out_s = ""
+            while True:
+                if off >= len(data):
+                    raise ValueError("unterminated indefinite text string")
+                if data[off] == _MinimalCBOR._BREAK:
+                    return out_s, off + 1
+                chunk, off = _MinimalCBOR.decode(data, off)
+                if not isinstance(chunk, str):
+                    raise ValueError("bad chunk in indefinite text string")
+                out_s += chunk
+        if major == 4:  # array
+            arr = []
+            while True:
+                if off >= len(data):
+                    raise ValueError("unterminated indefinite array")
+                if data[off] == _MinimalCBOR._BREAK:
+                    return arr, off + 1
+                item, off = _MinimalCBOR.decode(data, off)
+                arr.append(item)
+        # major == 5: map
+        d = {}
+        while True:
+            if off >= len(data):
+                raise ValueError("unterminated indefinite map")
+            if data[off] == _MinimalCBOR._BREAK:
+                return d, off + 1
+            k, off = _MinimalCBOR.decode(data, off)
+            v, off = _MinimalCBOR.decode(data, off)
+            d[k] = v
+
+    @staticmethod
+    def _read_len(data: bytes, off: int, minor: int) -> tuple[int, int]:
+        if minor < 24:
+            return minor, off
+        if minor == 24:
+            return data[off], off + 1
+        if minor == 25:
+            return struct.unpack(">H", data[off:off + 2])[0], off + 2
+        if minor == 26:
+            return struct.unpack(">I", data[off:off + 4])[0], off + 4
+        if minor == 27:
+            return struct.unpack(">Q", data[off:off + 8])[0], off + 8
+        raise ValueError(f"unsupported CBOR length encoding {minor}")
+
+    # ---- encode (only what _cbor_dump needs: str, bytes, list) ----
+    @staticmethod
+    def encode(obj: Any) -> bytes:
+        if isinstance(obj, str):
+            b = obj.encode("utf-8")
+            return _MinimalCBOR._head(3, len(b)) + b
+        if isinstance(obj, (bytes, bytearray)):
+            b = bytes(obj)
+            return _MinimalCBOR._head(2, len(b)) + b
+        if isinstance(obj, bool):  # before int (bool is int subclass)
+            return b"\xf5" if obj else b"\xf4"
+        if isinstance(obj, int):
+            if obj < 0:
+                return _MinimalCBOR._head(1, -1 - obj)
+            return _MinimalCBOR._head(0, obj)
+        if obj is None:
+            return b"\xf6"
+        if isinstance(obj, (list, tuple)):
+            out = _MinimalCBOR._head(4, len(obj))
+            for item in obj:
+                out += _MinimalCBOR.encode(item)
+            return out
+        if isinstance(obj, dict):
+            out = _MinimalCBOR._head(5, len(obj))
+            for k, v in obj.items():
+                out += _MinimalCBOR.encode(k)
+                out += _MinimalCBOR.encode(v)
+            return out
+        raise ValueError(f"cannot CBOR-encode {type(obj).__name__}")
+
+    @staticmethod
+    def _head(major: int, length: int) -> bytes:
+        mt = major << 5
+        if length < 24:
+            return bytes([mt | length])
+        if length < 0x100:
+            return bytes([mt | 24, length])
+        if length < 0x10000:
+            return bytes([mt | 25]) + struct.pack(">H", length)
+        if length < 0x100000000:
+            return bytes([mt | 26]) + struct.pack(">I", length)
+        return bytes([mt | 27]) + struct.pack(">Q", length)