Antler

In development

Early access

Docs

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.

PageWhat it specifies
records.mdA record, its canonical encoding, hash and signature; a chain of records; declared gaps; records of a newer schema; hardware-anchored heartbeats
log.mdThe log of record hashes, checkpoints, inclusion and consistency proofs, signed objects, receipts, published keys and fingerprints
bundle.mdThe evidence bundle, the device's witness file and the search export
timestamps.mdTimestamp tokens an outside authority signs over checkpoints, and how they are checked offline
segments.mdThe records delivered to the customer's own storage as sealed segments
reports.mdThe signed coverage, recall and credential reports
vectors.mdThe test vectors and how to run them

Conventions

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:

OutcomeExit codeMeaning
valid0Every hash, signature, link and proof checks against the pinned keys, and the end of every chain is proven
invalid1Something does not check, or a pinned fingerprint matches no key the evidence was signed with
unproven3What 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.

NameDocument
antler-bundle-v1An evidence bundle's manifest
antler-search-export-v1A search export's header
antler-search-export-summary-v1The payload a search export's trailer signs
antler-coverage-report-v1, antler-coverage-report-v2, antler-coverage-report-v3A coverage report
antler-recall-report-v1, antler-recall-report-v2A recall report
antler-credential-report-v1A credential report
antler-hardware-anchor-v1A heartbeat's hardware anchor: the first line of the message the hardware key signs
antler-segment-v1A delivered segment's header
antler-segment-head-v1A delivery's head.json
antler-format-vector-v1A 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