Attestium

An open evidence format for remote attestation

Attestium evidence is a JSON document that an attesterThe component on the machine being checked. It collects facts and reports them; it never decides the result. produces and any verifierThe component that runs elsewhere, typically in CI: it sends a nonce, obtains references itself and compares. can check. The format is independent of language and transport: an attester or verifier written in Go, Python or Rust interoperates by following the specification and the published JSON Schema.

What evidence contains#

Evidence lists facts and no verdicts.

FieldContent
type, version"attestium-evidence", 2
nonce, collectedAtThe verifier's nonceA random value the verifier chooses for one request, so that an old answer cannot be replayed. and when collection started
attesterThe attester's name, version, platform and its own executable hash
hostHostname, kernel, boot id, operating system
servicesDirectory services (files with SHA-256 and git mode, installed packages, processes) and container services (image, mounts, writable layer, root filesystem)
executables, librariesEvery running executable and every file mapped executable, once, with hash and owning distribution package
monitorOptional: programs and libraries loaded since the previous window
evidenceDigestSHA-256 of the canonical JSON of the rest
tpm, ima, confidentialOptional hardware statements over the nonce and digest

A process's integrity findings are facts too, for example "LD_PRELOAD is set". The verifier decides what they mean.

Canonical JSON and the digest#

evidenceDigest is the lowercase hex SHA-256 of the canonical JSON of the evidence without evidenceDigest, tpm, ima and confidential. Canonical JSON has no whitespace, sorts object keys by UTF-16 code units, leaves out undefined members, and writes numbers and strings as ECMAScript JSON.stringify does. Other languages gives the rules in detail, a reference implementation in Python, and test vectors.

Hardware binding#

StatementBound value
TPMTrusted Platform Module: a chip with keys that cannot be exported and registers (PCRs) that can be extended but never set. 2.0 quote`SHA-256(nonce
AMD SEV-SNPAMD Secure Encrypted Virtualization with Secure Nested Paging: confidential VMs whose launch measurement the AMD chip signs. report, Intel TDXIntel Trust Domain Extensions: confidential VMs whose measurement is signed through Intel's quoting enclave. quote`SHA-512(nonce
IMAIntegrity Measurement Architecture: the Linux kernel hashes files as they are used, logs each hash and extends PCR 10. logReplayed to the quoted PCRPlatform Configuration Register: a TPM register that can only be extended with a hash. Firmware, bootloader and kernel extend PCRs with what they load. 10

The hash is taken over the raw bytes of the nonce and the digest, not over their hex text.

Verifier obligations#

A verifier implementing the format must:

  • check the evidence against the schema before using any field;
  • check the nonce, the time window and the digest;
  • verify hardware statements only with keys it pinned or chains to vendor roots it ships, never with keys taken from the evidence;
  • obtain every reference itself, by digest where the reference is content-addressed;
  • treat checks that could not complete as inconclusive, never as passing.

Release manifests#

A release deployed without git carries .attestium-manifest.json at its root: the repository, the commit and every file's hash and mode. CI writes it from the build output and attests its SHA-256, so a verifier can explain a compiled or bundled release file by file.

Validate with the schema#

The schema uses JSON Schema 2020-12 and is published at https://attestium.com/schema/evidence-v2.json, its $id:

Shell
curl -O https://attestium.com/schema/evidence.schema.json

Objects the schema closes reject unknown fields, so a new field there comes with a new version.

Next#

Edit this page on GitHub