Antler evidence formats
This is the written specification of everything Antler signs or exports for offline checking: records and their chains, the log's checkpoints, receipts and proofs, the evidence bundle, the search export, the signed reports, the timestamp tokens of an outside authority and the segments delivered to a customer's own storage. It is precise enough to write a verifier from, in any language, without Antler's software: every rule a verifier applies is stated here, every fixed sentence a report must quote is published in sentences.json, and every format has a worked example with its keys under vectors/.
Antler's own verifier is antler-verify, a single binary that reads files, writes to its terminal and opens no network connection. An implementation written from this specification agrees with it when it accepts every vector and refuses each one once any byte of it is changed.
| Page | What it specifies |
|---|---|
| records.md | A record, its canonical encoding, hash and signature; a chain of records; declared gaps; records of a newer schema; hardware-anchored heartbeats |
| log.md | The log of record hashes, checkpoints, inclusion and consistency proofs, signed objects, receipts, published keys and fingerprints |
| bundle.md | The evidence bundle, the device's witness file and the search export |
| timestamps.md | Timestamp tokens an outside authority signs over checkpoints, and how they are checked offline |
| segments.md | The records delivered to the customer's own storage as sealed segments |
| reports.md | The signed coverage, recall and credential reports |
| vectors.md | The test vectors and how to run them |
Conventions
- Bytes. Every file is UTF-8. JSON-lines files hold one JSON value a line, each line ended by a line feed (0x0A), with no space around a line and no empty line.
- Hashes are SHA-256. In JSON a hash is 64 lower-case hex digits unless a field is said to be base64. An upper-case spelling is another string and does not match.
- Signatures are Ed25519 (RFC 8032). Keys are 32 bytes; signatures 64. One signature is not: a hardware anchor's, which is ECDSA on P-256 with SHA-256 (records.md). A timestamp token is the one exception: it is signed by an outside authority with the algorithm of its own certificate (timestamps.md).
- Base64 is the standard alphabet with padding (RFC 4648 section 4), read strictly: a spelling whose unused trailing bits are not zero, or whose padding is missing, is not valid. One thing is not strict: carriage returns (0x0D) and line feeds (0x0A) inside base64 text are skipped before it is decoded, wherever the text can hold them (a JSON string, or the end of a signature line of a note). So a key, a payload or a signature may be spelled with line breaks in it and is the same key, payload or signature; no other character is skipped. Nothing that is signed depends on the spelling: a signature is checked over the decoded bytes, and no hash covers a
sig. The limits on a record line and on a note bound how much a spelling can add. - Times are RFC 3339 in UTC, ending in
Z. - JSON written by Antler is compact (no insignificant space), with the members of an object in the order this specification lists them and the keys of a map sorted by their UTF-8 bytes. Where a document is signed, the signature is over the exact bytes; a verifier never re-encodes a signed payload before checking its signature.
- Unknown members. A signed payload is decoded strictly: a member this specification does not list makes it invalid. An unsigned wrapper (a bundle's manifest, a search export's header) may gain members; a verifier ignores ones it does not know.
What a verifier is given, and what it decides
A verifier is given evidence and, from somewhere the operator of the workspace does not serve, the fingerprints of the workspace's keys (see log.md). It decides one of three outcomes, which antler-verify reports as its exit code:
| Outcome | Exit code | Meaning |
|---|---|---|
| valid | 0 | Every hash, signature, link and proof checks against the pinned keys, and the end of every chain is proven |
| invalid | 1 | Something does not check, or a pinned fingerprint matches no key the evidence was signed with |
| unproven | 3 | What is there checks, but the end of a chain is not proven, or no key was pinned and only the structure was checked |
Exit code 2 is wrong usage or a file that cannot be read. A verifier with no pinned key checks structure only (hashes, links, proofs, never a signature), says so, and never reports valid.
Format names
Every document names its format. A verifier refuses a format it does not know.
| Name | Document |
|---|---|
antler-bundle-v1 | An evidence bundle's manifest |
antler-search-export-v1 | A search export's header |
antler-search-export-summary-v1 | The payload a search export's trailer signs |
antler-coverage-report-v1, antler-coverage-report-v2, antler-coverage-report-v3 | A coverage report |
antler-recall-report-v1, antler-recall-report-v2 | A recall report |
antler-credential-report-v1 | A credential report |
antler-hardware-anchor-v1 | A heartbeat's hardware anchor: the first line of the message the hardware key signs |
antler-segment-v1 | A delivered segment's header |
antler-segment-head-v1 | A delivery's head.json |
antler-format-vector-v1 | A test vector's vector.json |
A format's name changes when a verifier written for the old one could accept a document that means something else. Formats are added, never changed: a document signed under a name verifies by that name's rules for as long as it is kept.
Known limits of this version
- The exclusion sentences belong to the release that signed. A coverage report of the second or third format, and a recall or credential report, must quote the list of exclusions of the release that signed it, which is generated from that release's table of agents. This specification publishes the current list and the frozen first list in
sentences.json; a verifier built from a later version of this specification knows a later list and refuses a report that quotes an earlier one. Keep the version of this specification, or ofantler-verify, that matches the release that signed a report you keep. - An ownership report (
antler-owner-report-v1, signed with the report key) is a signed object like any other (log.md): its signature can be checked, but this version specifies no rules for its content andantler-verifydoes not accept it as a report. - What a manifest states and nothing signs is listed in bundle.md. A verifier shows it as stated and never relies on it.