entropy-protocol 0.1.0__py3-none-any.whl

entropy_protocol/attested/azure_cgpu.py

@@ -0,0 +1,186 @@
+"""Evidence from inside an Azure confidential VM with confidential H100s (Standard_NCC*ads_H100_v5): attester side.
+
+What the guest can obtain, and how (ARCHITECTURE §7d; sources: microsoft/openvmm vTPM and IGVM attestation code,
+NVIDIA/nvtrust local GPU verifier):
+- the paravisor's report: 64 octets written to vTPM NV 0x01400002 (guest attestation input) come back in the runtime
+  claims (`user-data`, hex) of a fresh report at NV 0x01400001 - HCL header, SNP report, runtime claims JSON;
+- the vTPM attestation key (persistent handle 0x81000003; its public part is also `HCLAkPub` in the runtime claims),
+  Microsoft's certificate for it (NV 0x01C101D0), a TPM2_Quote over PCRs with chosen qualifying data, the TCG event
+  log and, when the kernel keeps one, the IMA log;
+- the VCEK and its chain from the instance metadata service (THIM);
+- each GPU's SPDM measurement report over a 32-octet nonce, and its certificate chain, through NVML.
+Linux only. The vTPM steps need root and tpm2-tools; the GPU steps need NVIDIA's driver in confidential-computing
+mode and nvidia-ml-py. Nothing here judges the evidence: appraisal is the authority's (`appraise`).
+"""
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import tempfile
+import time
+import urllib.request
+from pathlib import Path
+
+NV_GUEST_INPUT = 0x01400002
+NV_REPORT = 0x01400001
+NV_AK_CERT = 0x01C101D0
+AK_HANDLE = 0x81000003
+GUEST_INPUT_SIZE = 64
+THIM_URL = "http://169.254.169.254/metadata/THIM/amd/certification"
+EVENT_LOG = Path("/sys/kernel/security/tpm0/binary_bios_measurements")
+IMA_LOG = Path("/sys/kernel/security/ima/binary_runtime_measurements")
+SYSTEMD_TPM_LOG = Path("/run/log/systemd/tpm2-measure.log")     # PCR 11 extensions after boot (systemd-pcrphase)
+QUOTE_PCRS = tuple(range(16))
+GPU_NONCE_SIZE = 32
+
+
+class EvidenceError(RuntimeError):
+    """The platform did not produce a piece of evidence."""
+
+
+def _run(args: list[str], stdin: bytes | None = None) -> bytes:
+    p = subprocess.run(args, input=stdin, capture_output=True, check=False)
+    if p.returncode != 0:
+        raise EvidenceError(f"{' '.join(args)}: rc {p.returncode}: {p.stderr.decode(errors='replace').strip()}")
+    return p.stdout
+
+
+def nv_size(index: int) -> int | None:
+    """Data size of an NV index, or None when it is not defined."""
+    try:
+        out = _run(["tpm2_nvreadpublic", f"0x{index:08x}"]).decode()
+    except EvidenceError:
+        return None
+    m = re.search(r"^\s*size:\s*(\d+)", out, re.M)
+    return int(m.group(1)) if m else None
+
+
+def nv_read(index: int) -> bytes:
+    size = nv_size(index)
+    if size is None:
+        raise EvidenceError(f"NV index 0x{index:08x} is not defined")
+    with tempfile.TemporaryDirectory() as d:
+        out = Path(d) / "nv.bin"
+        _run(["tpm2_nvread", "-C", "o", "-s", str(size), "-o", str(out), f"0x{index:08x}"])
+        return out.read_bytes()
+
+
+REPORT_RENEW_SECONDS = 2.0     # openvmm tpm_device REPORT_TIMER_PERIOD
+
+
+def guest_report(user_data: bytes, tries: int = 4) -> bytes:
+    """The paravisor's report with ``user_data`` (64 octets) in its runtime claims; defines the input index (owner
+    read/write, empty authorization, as the paravisor's own tests do) when the guest has not defined it yet.
+
+    The paravisor renews the report when the report index is read, at most once per REPORT_TIMER_PERIOD (2 s,
+    openvmm `tpm_device`); a read within that period returns the previous report (observed on Azure NCC40ads H100 v5,
+    27.10.2026: three writes 0.1-0.3 s apart, one report). So the report is read until its runtime claims carry the
+    octets just written, waiting out the period between reads."""
+    if len(user_data) != GUEST_INPUT_SIZE:
+        raise ValueError(f"guest input is {GUEST_INPUT_SIZE} octets, got {len(user_data)}")
+    if nv_size(NV_GUEST_INPUT) is None:
+        _run(["tpm2_nvdefine", "-C", "o", "-s", str(GUEST_INPUT_SIZE), "-a",
+              "ownerread|ownerwrite|authread|authwrite", f"0x{NV_GUEST_INPUT:08x}"])
+    with tempfile.TemporaryDirectory() as d:
+        src = Path(d) / "in.bin"
+        src.write_bytes(user_data)
+        _run(["tpm2_nvwrite", "-C", "o", "-i", str(src), f"0x{NV_GUEST_INPUT:08x}"])
+    for attempt in range(tries):
+        if attempt:
+            time.sleep(REPORT_RENEW_SECONDS + 0.2)
+        rep = nv_read(NV_REPORT)
+        if _user_data_of(rep) == user_data:
+            return rep
+    raise EvidenceError(f"the paravisor's report did not take the guest input after {tries} reads")
+
+
+def _user_data_of(report: bytes) -> bytes:
+    """`user-data` of a report's runtime claims (the attester's own sanity check; the appraisal re-parses)."""
+    from .hcl import HCLError, parse
+    try:
+        return parse(report).user_data
+    except (HCLError, ValueError):
+        return b""
+
+
+def ak_public() -> dict:
+    """The attestation key's public area (TPM2B_PUBLIC as tpm2-tools writes it) and its SubjectPublicKeyInfo (DER)."""
+    with tempfile.TemporaryDirectory() as d:
+        tss, der = Path(d) / "ak.tss", Path(d) / "ak.der"
+        _run(["tpm2_readpublic", "-c", f"0x{AK_HANDLE:08x}", "-o", str(tss)])
+        _run(["tpm2_readpublic", "-c", f"0x{AK_HANDLE:08x}", "-f", "der", "-o", str(der)])
+        return {"tss": tss.read_bytes(), "spki": der.read_bytes()}
+
+
+def ak_cert() -> bytes | None:
+    """Microsoft's certificate for the attestation key, when the platform provisioned one."""
+    try:
+        return nv_read(NV_AK_CERT)
+    except EvidenceError:
+        return None
+
+
+def quote(qualifying: bytes, pcrs: tuple[int, ...] = QUOTE_PCRS) -> dict:
+    """TPM2_Quote by the attestation key over the SHA-256 bank: TPMS_ATTEST as signed, TPMT_SIGNATURE, and the PCR
+    values in selection order."""
+    sel = "sha256:" + ",".join(str(i) for i in pcrs)
+    with tempfile.TemporaryDirectory() as d:
+        msg, sig, vals = Path(d) / "msg", Path(d) / "sig", Path(d) / "pcrs"
+        _run(["tpm2_quote", "-c", f"0x{AK_HANDLE:08x}", "-l", sel, "-q", qualifying.hex(), "-g", "sha256",
+              "-m", str(msg), "-s", str(sig), "-o", str(vals), "-F", "values"])
+        return {"msg": msg.read_bytes(), "sig": sig.read_bytes(), "pcrs": vals.read_bytes(), "sel": list(pcrs)}
+
+
+def event_log() -> bytes:
+    return EVENT_LOG.read_bytes()
+
+
+def ima_log() -> bytes | None:
+    return IMA_LOG.read_bytes() if IMA_LOG.exists() else None
+
+
+def systemd_tpm_log() -> bytes | None:
+    return SYSTEMD_TPM_LOG.read_bytes() if SYSTEMD_TPM_LOG.exists() else None
+
+
+def thim() -> dict:
+    """VCEK, its chain and TCB from the instance metadata service: {"vcekCert", "certificateChain", "tcbm"} (PEM)."""
+    req = urllib.request.Request(THIM_URL, headers={"Metadata": "true"})
+    with urllib.request.urlopen(req, timeout=10) as r:  # noqa: S310 - link-local metadata endpoint
+        return json.loads(r.read())
+
+
+def gpus(nonce: bytes) -> list[dict]:
+    """Every GPU's SPDM measurement report over ``nonce`` (32 octets) and its certificate chain, with the identifiers
+    NVML gives beside them (UUID, VBIOS and driver versions, confidential-computing state)."""
+    if len(nonce) != GPU_NONCE_SIZE:
+        raise ValueError(f"GPU nonce is {GPU_NONCE_SIZE} octets, got {len(nonce)}")
+    import pynvml as nv
+
+    nv.nvmlInit()
+    try:
+        state = nv.nvmlSystemGetConfComputeState()
+        common = {"driver": _text(nv.nvmlSystemGetDriverVersion()),
+                  "cc": {"environment": int(state.environment), "feature": int(state.ccFeature),
+                         "devtools": int(state.devToolsMode)},
+                  "ready": int(nv.nvmlSystemGetConfComputeGpusReadyState())}
+        out = []
+        for i in range(nv.nvmlDeviceGetCount()):
+            h = nv.nvmlDeviceGetHandleByIndex(i)
+            rep = nv.nvmlDeviceGetConfComputeGpuAttestationReport(h, nonce)
+            cert = nv.nvmlDeviceGetConfComputeGpuCertificate(h)
+            out.append({"index": i, "uuid": _text(nv.nvmlDeviceGetUUID(h)),
+                        "vbios": _text(nv.nvmlDeviceGetVbiosVersion(h)),
+                        "report": bytes(rep.attestationReport[:rep.attestationReportSize]),
+                        "cec": bytes(rep.cecAttestationReport[:rep.cecAttestationReportSize])
+                        if getattr(rep, "isCecAttestationReportPresent", 0) else b"",
+                        "chain": bytes(cert.attestationCertChain[:cert.attestationCertChainSize]),
+                        "cert_chain": bytes(cert.certChain[:cert.certChainSize]), **common})
+        return out
+    finally:
+        nv.nvmlShutdown()
+
+
+def _text(v) -> str:
+    return v.decode() if isinstance(v, bytes) else str(v)

entropy_protocol/attested/binding.py

@@ -0,0 +1,71 @@
+"""The binding value an enrollment puts into the hardware evidence (ARCHITECTURE §7d).
+
+SHA-512 over length-prefixed fields, each a 4-octet big-endian length followed by the octets, in this order:
+  "ep1/attested-binding/v1", the freshness handle, rrp_id, target, SHA-256 of the CSR (DER), the statement key
+  (SubjectPublicKeyInfo DER), the weights digest, the tokenizer digest, the code identity, the sealing class,
+  SHA-256 of the sealing parameters (canonical CBOR).
+The 64 octets go where the platform lets the guest choose them: SEV-SNP REPORT_DATA, TDX REPORTDATA, or the Azure
+vTPM guest input that the paravisor copies into its report's runtime claims. rrp_id comes from the sealer's own
+configuration, never from the wire: only an identity the attester holds ties its evidence to one authority.
+"""
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from pathlib import Path
+
+from .. import cose
+
+LABEL = b"ep1/attested-binding/v1"
+HANDLE_LEN = 32
+
+
+def lp(parts: list[bytes]) -> bytes:
+    """Length-prefixed concatenation: 4-octet big-endian length, then the octets, for every part."""
+    return b"".join(len(p).to_bytes(4, "big") + p for p in parts)
+
+
+@dataclass(frozen=True)
+class BindingInput:
+    handle: bytes          # the authority's nonce, 32 octets
+    rrp_id: str            # the authority, from the sealer's configuration
+    target: str            # the sealing service being certified
+    csr_digest: bytes      # SHA-256 of the certificate signing request, DER
+    statement_key: bytes   # SubjectPublicKeyInfo DER of the key being certified
+    weights: bytes         # weights digest, 32 octets
+    tokenizer: bytes       # tokenizer digest, 32 octets
+    code: bytes            # code identity, 32 octets (code_identity)
+    sealing_class: str     # numerical class of the sealing pass
+    params: bytes          # SHA-256 of the sealing parameters (params_digest)
+
+    def fields(self) -> list[bytes]:
+        if len(self.handle) != HANDLE_LEN:
+            raise ValueError(f"handle must be {HANDLE_LEN} octets, got {len(self.handle)}")
+        for name in ("csr_digest", "weights", "tokenizer", "code", "params"):
+            if len(getattr(self, name)) != 32:
+                raise ValueError(f"{name} must be 32 octets")
+        return [LABEL, self.handle, self.rrp_id.encode(), self.target.encode(), self.csr_digest, self.statement_key,
+                self.weights, self.tokenizer, self.code, self.sealing_class.encode(), self.params]
+
+    def value(self) -> bytes:
+        return hashlib.sha512(lp(self.fields())).digest()
+
+
+def params_digest(params: dict) -> bytes:
+    """SHA-256 of the sealing parameters as canonical CBOR (integers and text only: no floating point on the wire)."""
+    return hashlib.sha256(cose.dumps(params)).digest()
+
+
+def package_files(root: Path | None = None) -> list[list]:
+    """[[relative path, SHA-256], ...] of every source file of the installed package, sorted by path."""
+    root = root or Path(__file__).resolve().parents[1]
+    out = []
+    for p in sorted(root.rglob("*")):
+        if p.is_file() and "__pycache__" not in p.parts and p.suffix in (".py", ".json", ".cddl"):
+            out.append([p.relative_to(root).as_posix(), hashlib.sha256(p.read_bytes()).digest()])
+    return out
+
+
+def code_identity(root: Path | None = None) -> bytes:
+    """SHA-256 of the canonical CBOR list of package files: the identity of the code that seals."""
+    return hashlib.sha256(cose.dumps(package_files(root))).digest()

entropy_protocol/attested/capture.py

@@ -0,0 +1,109 @@
+"""Capture raw evidence on an Azure confidential H100 guest, for the appraisal code and its tests (ARCHITECTURE §7d).
+
+`sudo python3 -m entropy_protocol.attested.capture --out DIR [--rounds 3]` writes, per round, a fresh 32-octet
+handle, the 64-octet guest input derived from it (SHA-512 of a label and the handle - the shape of a binding value
+without an enrollment behind it), the paravisor's report, a quote whose qualifying data is SHA-256 of that input and
+every GPU's report over the handle; once: the attestation key, its Microsoft certificate, the THIM certificates, the
+TCG event log, the IMA log when the kernel keeps one, and what the platform says about itself (os-release, kernel,
+command line, TPM properties, nvidia-smi). MANIFEST.json lists every file with its SHA-256 and every step that
+failed, with the error: a capture that stops at the first failure would hide the rest of the platform.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import platform
+import subprocess
+import time
+from pathlib import Path
+
+import cbor2
+
+from . import azure_cgpu as az
+
+LABEL = b"ep1/capture/v1"
+
+
+def _sh(cmd: list[str]) -> str:
+    p = subprocess.run(cmd, capture_output=True, text=True, check=False)
+    return f"$ {' '.join(cmd)}\nrc={p.returncode}\n{p.stdout}{p.stderr}"
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="entropy-attested-capture")
+    ap.add_argument("--out", required=True)
+    ap.add_argument("--rounds", type=int, default=3)
+    a = ap.parse_args(argv)
+    out = Path(a.out)
+    out.mkdir(parents=True, exist_ok=True)
+    files: dict[str, str] = {}
+    errors: dict[str, str] = {}
+
+    def put(name: str, data: bytes) -> None:
+        (out / name).write_bytes(data)
+        files[name] = hashlib.sha256(data).hexdigest()
+
+    def step(name: str, fn):
+        try:
+            return fn()
+        except Exception as exc:  # noqa: BLE001 - every failure is recorded and the capture goes on
+            errors[name] = f"{type(exc).__name__}: {exc}"
+            return None
+
+    for r in range(a.rounds):
+        handle = os.urandom(az.GPU_NONCE_SIZE)
+        user = hashlib.sha512(LABEL + handle).digest()
+        put(f"r{r}_handle.bin", handle)
+        put(f"r{r}_user_data.bin", user)
+        t0 = time.time()
+        rep = step(f"r{r}_report", lambda: az.guest_report(user))
+        if rep is not None:
+            put(f"r{r}_hcl_report.bin", rep)
+        q = step(f"r{r}_quote", lambda: az.quote(hashlib.sha256(user).digest()))
+        if q is not None:
+            put(f"r{r}_quote_msg.bin", q["msg"])
+            put(f"r{r}_quote_sig.bin", q["sig"])
+            put(f"r{r}_quote_pcrs.bin", q["pcrs"])
+        g = step(f"r{r}_gpus", lambda: az.gpus(handle))
+        if g is not None:
+            put(f"r{r}_gpus.cbor", cbor2.dumps(g, canonical=True))
+        files[f"r{r}_seconds"] = f"{time.time() - t0:.3f}"
+
+    ak = step("ak_public", az.ak_public)
+    if ak is not None:
+        put("ak_public.tss", ak["tss"])
+        put("ak_public.der", ak["spki"])
+    c = step("ak_cert", az.ak_cert)
+    if c:
+        put("ak_cert.der", c)
+    t = step("thim", az.thim)
+    if t is not None:
+        put("thim.json", json.dumps(t, indent=1, sort_keys=True).encode())
+    ev = step("event_log", az.event_log)
+    if ev is not None:
+        put("event_log.bin", ev)
+    ima = step("ima_log", az.ima_log)
+    if ima:
+        put("ima_log.bin", ima)
+    sd = step("systemd_tpm_log", az.systemd_tpm_log)
+    if sd:
+        put("systemd_tpm2_measure.log", sd)
+    about = "\n".join(_sh(c) for c in (
+        ["cat", "/etc/os-release"], ["uname", "-a"], ["cat", "/proc/cmdline"],
+        ["tpm2_getcap", "properties-fixed"], ["tpm2_getcap", "pcrs"], ["tpm2_getcap", "algorithms"],
+        ["tpm2_getcap", "handles-nv-index"], ["tpm2_getcap", "handles-persistent"],
+        ["nvidia-smi", "-q"], ["nvidia-smi", "conf-compute", "-q"],
+        ["sh", "-c", "grep -E '^CONFIG_(IMA|INTEGRITY|SECURITY_LOCKDOWN|MODULE_SIG)' /boot/config-$(uname -r)"],
+        ["sh", "-c", "dmesg | grep -i -E 'sev|snp|tpm|ima|lockdown|nvidia|cc ' | tail -80"]))
+    put("platform.txt", about.encode())
+    manifest = {"captured_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()), "host": platform.node(),
+                "rounds": a.rounds, "files": files, "errors": errors}
+    (out / "MANIFEST.json").write_text(json.dumps(manifest, indent=1, sort_keys=True))
+    print(json.dumps({"files": len(files), "errors": errors}, indent=1))
+    return 0 if not errors else 3
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

entropy_protocol/attested/ear.py

@@ -0,0 +1,94 @@
+"""EAT Attestation Result (draft-ietf-rats-ear-04) as a CWT: COSE_Sign1 over the CBOR claims-set.
+
+Labels (draft-ietf-rats-ear-04 §3, RFC 9711): eat_profile 265, iat 6, exp 4, eat_nonce 10, submods 266,
+ear_status 1000, ear_trustworthiness_vector 1001, ear_raw_evidence 1002, ear_appraisal_policy_ids 1003,
+ear_verifier_id 1004 {developer 0, build 1}, ear_attester_claims 1005, ear_verifier_claims 1006,
+ear_device_topology 1007. Tiers (AR4SI): none 0, affirming 2, warning 32, contraindicated 96. Trustworthiness vector:
+instance-identity 0, configuration 1, executables 2, file-system 3, hardware 4, runtime-opaque 5, storage-opaque 6,
+sourced-data 7. ep1's identities travel in a private-space claim (§4.1: integers below -65536): EP1 = -71001.
+Signed with Ed25519 by the authority's root key itself (pki: never by an end-entity key, which a sealer also holds);
+the protected header carries the root certificate (x5chain, 33) for convenience, and the reader compares it with
+the root it pins.
+"""
+from __future__ import annotations
+
+import time
+
+
+from .. import cose
+
+PROFILE = "tag:ietf.org,2026:rats/ear#04"
+EAT_PROFILE, IAT, EXP, NONCE, SUBMODS = 265, 6, 4, 10, 266
+STATUS, TVECTOR, RAW_EVIDENCE, POLICY_IDS, VERIFIER_ID, ATTESTER_CLAIMS, VERIFIER_CLAIMS, TOPOLOGY = range(1000, 1008)
+NONE, AFFIRMING, WARNING, CONTRAINDICATED = 0, 2, 32, 96
+INSTANCE_IDENTITY, CONFIGURATION, EXECUTABLES, FILE_SYSTEM, HARDWARE, RUNTIME_OPAQUE, STORAGE_OPAQUE, SOURCED_DATA = \
+    range(8)
+EP1 = -71001
+X5CHAIN = 33
+TYP = "application/eat+cwt"
+
+
+def tier_of(value: int) -> int:
+    """The tier of a trustworthiness claim value (AR4SI §2.3: -1..1 none; 2..31 and -2..-32 affirming; 32..95 and
+    -33..-96 warning; 96..127 and -97..-128 contraindicated)."""
+    if value in (-1, 0, 1):
+        return NONE
+    v = value if value > 0 else -value - 1       # -2..-32 -> 1..31, -33..-96 -> 32..95, -97..-128 -> 96..127
+    if v >= 96:
+        return CONTRAINDICATED
+    if v >= 32:
+        return WARNING
+    return AFFIRMING
+
+
+def worst(tiers) -> int:
+    order = {AFFIRMING: 0, NONE: 1, WARNING: 2, CONTRAINDICATED: 3}
+    return max(tiers, key=lambda t: order[t], default=NONE)
+
+
+def appraisal(vector: dict, policy_ids: list[str], attester: dict | None = None, verifier: dict | None = None,
+              nonce: bytes | None = None) -> dict:
+    """One submod: status = the worst tier across the vector."""
+    a = {STATUS: worst(tier_of(v) for v in vector.values()), TVECTOR: vector, POLICY_IDS: policy_ids}
+    if attester:
+        a[ATTESTER_CLAIMS] = attester
+    if verifier:
+        a[VERIFIER_CLAIMS] = verifier
+    if nonce is not None:
+        a[NONCE] = nonce
+    return a
+
+
+def claims(submods: dict, verifier_id: tuple[str, str], *, nonce: bytes, lifetime: int, topology: dict | None = None,
+           ep1: dict | None = None, iat: int | None = None) -> dict:
+    now = int(time.time()) if iat is None else int(iat)
+    c = {EAT_PROFILE: PROFILE, IAT: now, EXP: now + int(lifetime), VERIFIER_ID: {0: verifier_id[0], 1: verifier_id[1]},
+         NONCE: nonce, SUBMODS: submods, STATUS: worst(s[STATUS] for s in submods.values())}
+    if topology:
+        c[TOPOLOGY] = topology
+    if ep1:
+        c[EP1] = ep1
+    return c
+
+
+def sign(c: dict, key, chain_der: list[bytes]) -> bytes:
+    protected = {cose.ALG: cose.ED25519, cose.TYP: TYP, X5CHAIN: chain_der[0] if len(chain_der) == 1 else chain_der}
+    return cose.sign1(protected, cose.dumps(c), key)
+
+
+def read(ear: bytes, public_key) -> dict:
+    """Verify the signature under ``public_key`` (the result-signer's, already chained to a root) and return the claims."""
+    prot, _, payload = cose.verify1(ear, public_key)
+    if prot.get(cose.TYP) != TYP:
+        raise cose.COSEError("not an attestation result")
+    c = cose._thaw(cose.loads(payload))
+    if c.get(EAT_PROFILE) != PROFILE:
+        raise cose.COSEError("not an EAR of this profile")
+    return c
+
+
+def chain_of(ear: bytes) -> list[bytes]:
+    """The x5chain of a signed result, leaf first (not verified here)."""
+    prot = cose.decode1(ear)[0]
+    v = prot.get(X5CHAIN)
+    return [v] if isinstance(v, bytes) else list(v or [])

entropy_protocol/attested/enroll.py

@@ -0,0 +1,119 @@
+"""Attestation-based enrollment messages and the authority's handle book (ARCHITECTURE §7d).
+
+Message shapes follow draft-novak-rats-tacra's wire schema (CBOR maps, text keys):
+  initiation  {freshness_kind: "present-nonce", handle: bstr(32), rrp_id, expires_in, mode: "enroll",
+               acceptable_csk: ["ed25519"], acceptable_evidence: [profile]}
+  request     {freshness_kind, target, credential_type, handle, evidence: bstr, profile,
+               binding: {method: "binding-input", hash: "sha512"}, csr: bstr (PKCS#10 DER)}
+  evidence    (profile "ep1/azure-cgpu/v1", CBOR) {hcl: bstr, thim: {vcekCert, certificateChain, tcbm},
+               quote: {msg, sig, pcrs: bstr, sel: [uint]}, eventlog: bstr, ? ima: bstr, ? akcert: bstr,
+               gpus: [{report, chain, uuid, vbios, driver, cc, ready}],
+               claims: {weights: bstr, tokenizer: bstr, code: bstr, class: tstr, params: bstr}}
+The handle book is the authority's: a handle is issued once, expires, and is spent by the first enrollment that
+presents it, whatever the outcome - a refused request cannot be replayed with corrections under the same handle.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+
+
+from .. import cose
+from .binding import HANDLE_LEN
+
+PROFILE_AZURE_CGPU = "ep1/azure-cgpu/v1"
+CRED_STATEMENT = "ep1-statement-key"
+CRED_DETECTION = "ep1-detection-key"
+CREDENTIAL_TYPES = (CRED_STATEMENT, CRED_DETECTION)
+
+
+class EnrollError(ValueError):
+    """A malformed message, or a handle that cannot be used."""
+
+
+def initiation(handle: bytes, rrp_id: str, expires_in: int) -> bytes:
+    return cose.dumps({"freshness_kind": "present-nonce", "handle": handle, "rrp_id": rrp_id,
+                       "expires_in": int(expires_in), "mode": "enroll", "acceptable_csk": ["ed25519"],
+                       "acceptable_evidence": [PROFILE_AZURE_CGPU]})
+
+
+def _map(data: bytes) -> dict:
+    try:
+        m = cose._thaw(cose.loads(data))
+    except Exception as exc:  # noqa: BLE001 - every decoding failure of untrusted input is the same refusal
+        raise EnrollError(f"not CBOR ({type(exc).__name__})") from exc
+    if not isinstance(m, dict):
+        raise EnrollError("not a CBOR map")
+    return m
+
+
+def read_initiation(data: bytes) -> dict:
+    m = _map(data)
+    if m.get("freshness_kind") != "present-nonce" or m.get("mode") != "enroll":
+        raise EnrollError("not an enrollment initiation with a nonce")
+    if not isinstance(m.get("handle"), bytes) or len(m["handle"]) != HANDLE_LEN:
+        raise EnrollError("handle missing or not 32 octets")
+    return m
+
+
+def request(*, target: str, credential_type: str, handle: bytes, evidence: bytes, csr: bytes,
+            profile: str = PROFILE_AZURE_CGPU) -> bytes:
+    if credential_type not in CREDENTIAL_TYPES:
+        raise EnrollError(f"unknown credential type {credential_type}")
+    return cose.dumps({"freshness_kind": "present-nonce", "target": target, "credential_type": credential_type,
+                       "handle": handle, "evidence": evidence, "profile": profile,
+                       "binding": {"method": "binding-input", "hash": "sha512"}, "csr": csr})
+
+
+def read_request(data: bytes) -> dict:
+    m = _map(data)
+    need = {"freshness_kind": str, "target": str, "credential_type": str, "handle": bytes, "evidence": bytes,
+            "profile": str, "binding": dict, "csr": bytes}
+    for k, t in need.items():
+        if not isinstance(m.get(k), t):
+            raise EnrollError(f"request field {k} missing or of the wrong type")
+    if m["binding"] != {"method": "binding-input", "hash": "sha512"}:
+        raise EnrollError("unsupported binding method")
+    if m["credential_type"] not in CREDENTIAL_TYPES:
+        raise EnrollError(f"unknown credential type {m['credential_type']}")
+    return m
+
+
+class HandleBook:
+    """Issued handles in a JSON file: {hex: {"issued": t, "expires": t, "spent": t | null}}."""
+
+    def __init__(self, path: Path):
+        self.path = Path(path)
+
+    def _load(self) -> dict:
+        return json.loads(self.path.read_text()) if self.path.exists() else {}
+
+    def _save(self, book: dict) -> None:
+        tmp = self.path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(book, indent=1, sort_keys=True))
+        os.replace(tmp, self.path)
+
+    def issue(self, ttl: int, now: float | None = None) -> bytes:
+        now = time.time() if now is None else now
+        h = os.urandom(HANDLE_LEN)
+        book = self._load()
+        book[h.hex()] = {"issued": int(now), "expires": int(now + ttl), "spent": None}
+        self._save(book)
+        return h
+
+    def spend(self, handle: bytes, now: float | None = None) -> dict:
+        """Mark the handle spent; EnrollError if it was never issued, has expired or was already spent."""
+        now = time.time() if now is None else now
+        book = self._load()
+        e = book.get(handle.hex())
+        if e is None:
+            raise EnrollError("handle was not issued by this authority")
+        if e["spent"] is not None:
+            raise EnrollError("handle already used")
+        e["spent"] = int(now)
+        self._save(book)
+        if now > e["expires"]:
+            raise EnrollError("handle expired")
+        return e