Concepts

This page explains the ideas behind Attestium: who produces evidence and who checks it, what evidence and references are, how a nonceA random value the verifier chooses for one request, so that an old answer cannot be replayed. and a digest make evidence fresh and tamper-evident, why every running file must be explained, how a failing result differs from an inconclusive one, and what each evidence level proves.

Roles#

Attestium follows the IETF remote attestation architecture, RATSRemote ATtestation procedureS: the IETF architecture (RFC 9334) that defines attester, verifier and relying party. (RFC 9334).

In RATS terms, Attestium evidence is RATS evidence, and a verifier's report is an attestation result. The references are what RATS calls reference values and endorsements.

The split matters because the attester runs on the machine under test. If that machine is compromised, its attester may be too. A verifier that trusts nothing from the machine except what it can check against an outside reference, or what hardware signs, keeps the decision out of the attacker's hands.

Evidence#

Evidence is a JSON document in the format defined by SPEC.md and schema/evidence.schema.json. It lists facts:

• the files of each service directory, with their SHA-256 and git mode;
• the installed packages of each ecosystem, with the hash of every file;
• every running process of each service: executable, command line, runtime, integrity findings;
• every executable and every library mapped executable, once, with its hash and owning distribution package;
• containers: the image the runtime names, mounts, the writable layer, the root filesystem;
• optionally: a TPMTrusted Platform Module: a chip with keys that cannot be exported and registers (PCRs) that can be extended but never set. quote, a confidential VM report, the IMAIntegrity Measurement Architecture: the Linux kernel hashes files as they are used, logs each hash and extends PCR 10. log, and a record of programs run since the last audit.

Evidence contains no verdicts. A process's integrity.findings are facts too (for example "LD_PRELOAD is set"); the verifier decides what they mean.

References#

A reference is what the verifier compares a fact with. The verifier obtains every reference itself, never from the evidence:

Where a reference is content-addressed (a registry tarball with an integrity hash, an image layer, a git commit), fetch it by digest and check the digest. A reference that could not be fetched makes the check inconclusive; it never makes it pass.

Nonce and digest binding#

A verifier must know that evidence is fresh and has not been changed. Attestium does this in three steps:

1. The verifier picks a random nonce of 16 to 64 bytes and sends it hex encoded.
2. The attester collects the evidence, puts the nonce in it, and computes evidenceDigest: the SHA-256 of the canonical JSON of the evidence without evidenceDigest, tpm, ima and confidential.
3. When hardware is present, the attester asks it to sign both values:
   • a TPM quote with qualifying data SHA-256(nonce || evidenceDigest);
   • a confidential VM report with report data SHA-512(nonce || evidenceDigest).

The verifier checks that the nonce is its own, that collectedAt is inside its time window, and recomputes the digest. Then it checks the hardware statement with keys it trusts. A replayed answer fails the nonce check. Changed evidence fails the digest check. Evidence produced elsewhere fails the hardware check.

Without hardware, the digest proves only that the evidence was not changed after the digest was computed. Anyone who controls the attester can compute a new digest over forged evidence. See Evidence levels and Forged answers.

Explaining every running file#

A server runs more than the application: an interpreter, shared libraries, helper programs, tools started by cron. Any of them can carry an attacker's code. So the evidence lists every file that an inspected process runs or maps executable, and the verifier must explain each one by a reference:

• a service file that matched its commit, build or attested release;
• a file of a verified package;
• a file of the container image;
• an official runtime release (Node.js);
• a pinned hash, or an entry in a signed published checksum list;
• the file of its owning Debian or Ubuntu package in the signed archive, using an archive snapshot from the install time when the version was superseded.

A file that matches no reference is unexplained. A file that contradicts its reference (the dpkg database says package libssl3 owns it, but the file differs from the one in that package) fails.

The same applies to the monitor's record. A program that ran between two audits and was then deleted leaves no file to hash; the record still names it, and the verifier reports it.

Build information inside Go and Rust binaries is written by the build, so it proves nothing about the binary by itself. The binary's own hash does. The build information shows which dependencies were compiled in, and those are compared with the lockfile at the commit.

Pass, fail and inconclusive#

Every check ends in one of three states:

Treat inconclusive as not passing. A clean result means nothing unless every check ran. Attestium reports this explicitly:

• ProcessIntegrity#checkAll() returns incomplete, and passed is false when it is not empty.
• Ecosystem comparisons return per-package statuses failed, unverifiable and error; any of them makes passed false.
• Evidence fields truncated, errors and incomplete tell the verifier where the attester could not see.

Evidence levels#

The strength of a result depends on what backs it. Report the level with every result.

Hardware statements are checked only with keys the verifier pinned or with chains to vendor roots it ships, never with keys taken from the evidence.

Where to go next#

• Getting started builds an attester and a verifier.
• Security describes the threat model and limits.
• SPEC.md defines the format.