Antler

In development

Early access

Docs

Test vectors

vectors/ holds one worked example of every format, with the keys that check it. The record vectors are the frozen record fixtures, byte for byte; the rest were made once with keys derived from fixed seeds and are regenerated only by Antler's own generator, which makes the same bytes on every run.

An implementation written from this specification is right when it:

  1. accepts every vector, and
  2. refuses each vector once any single byte of any of its files is changed, except the text no check reads: a vector's description and its list of what is unsigned, the name and input_b64 of the canonical vectors (an input may be spelled in many ways), what a bundle vector lists as unsigned, and the updated_at of a segments vector's head.json.

antler-verify vector <directory>... runs the first check with Antler's verifier and exits 0 when every vector under the directories checks:

$ antler-verify vector docs/formats/vectors

A vector

A vector is a directory with a vector.json and the files it names:

{
  "format": "antler-format-vector-v1",
  "kind": "chain",
  "description": "What the vector shows.",
  "files": {"chain": "chain.jsonl", "public_key": "device.pub"},
  "params": {"head_hash": "…", "last_seq": "23"}
}

files names the vector's files by role, relative to its directory; params holds the kind's other inputs and expectations, as strings; unsigned lists what no signature, hash or check covers. vector.json is read strictly: an unknown member, kind or file role is an error.

File forms:

Kinds

KindFiles (by role)ParamsIt checks
canonicalvectorsEach input sanitizes and encodes to the canonical bytes given, whose SHA-256 is given
recordrecord, public_keyOne record line: canonical, hashed, signed by the key, whose id it derives
chainchain, public_keyhead_hash, last_seqEvery record, and the links from seq 1 to the head
checkpointnote, verifier_keysize, root (hex)The signed note, under the key's name as origin
inclusionproof, note, verifier_keyThe proof against the note's root
consistencyproof, from_note, to_note, verifier_keyThat the first note's tree is a prefix of the second's
signed-objectobject, keyspurpose, payload_sha256The object's signature for the purpose, and its payload's hash
receiptreceipt, keysdevice_idThe receipt, for that device
reportreport, keysThe signed report, valid with every key of the keys file pinned
search-exportexport, fingerprintsThe export, valid with the header's keys pinned by the fingerprints
bundlebundle (a directory), fingerprints, witness (optional), tsa_cert (optional)The bundle, valid with the manifest's keys pinned by the fingerprints, against the witnessed checkpoints, and with its timestamp tokens verified against the certificate
timestampnote, verifier_key, token, tsa_certtime, imprint_sha256 (hex)The token over the note's checkpoint: its imprint, its signature against the certificate, and its time
hardware-chainchain, public_keyhead_hash, last_seq, hardware_key (base64), hardware_store, hardware_anchored (runs from-to joined by commas), anchors_counted, anchors_not_counted, anchors_without_headThe chain as chain checks it, and that its hardware anchors give that key, those anchored runs and those counts
segmentssegments (a directory), fingerprints, tsa_cert (optional)The delivery, valid with the newest header's keys pinned by the fingerprints, and with its timestamp tokens verified against the certificate

The vectors

VectorKindWhat it is
01-canonical-v1canonicalSchema v1 records as a writer might spell them (the frozen fixture)
02-canonical-v2canonicalThe same for schema v2
03-record-v1recordThe first record of the frozen v1 device chain
04-chain-v1chainThe frozen v1 device chain: every v1 event and field
05-server-chain-v1chainThe frozen v1 server chain, signed with an audit key
06-chain-v2chainThe frozen v2 device chain
07-checkpointcheckpointA checkpoint of a log of 25 records
08-inclusioninclusionLeaf 5 in that checkpoint
09-consistencyconsistencySize 8 as a prefix of size 25
10-signed-objectsigned-objectA signed object of purpose policy
11-receiptreceiptThe receipt of the head of vector 04's chain
12-report-coverage-v1reportA coverage report of the first format
13-report-coverage-v2reportA coverage report of the second format
14-report-recall-v1reportA recall report of the first format, every member set
15-report-recall-v2reportA credential recall's report of the second format
16-report-credential-v1reportA credential report
17-search-exportsearch-exportA search export of four records
18-bundlebundleAn evidence bundle: two chains, two checkpoints, a report, a ledger file and a witness file
19-hardware-chainhardware-chainA device chain whose heartbeats carry hardware anchors: records 1 to 9 of 13 are anchored
20-hardware-chain-copiedhardware-chainThat chain continued from a copy of the device's files: a heartbeat without an anchor, one anchored by another key; still only records 1 to 9 are anchored
21-timestamptimestampA timestamp token over the checkpoint of size 8
22-bundle-timestampsbundleThe bundle of vector 18 with a timestamp token for each of its checkpoints
23-segmentssegmentsA delivery of three segments: the two chains in the order of the log, two seals, an unsealed segment, and both timestamp tokens
24-canonical-context-v1canonicalSchema v1 records with the process context's keys as a writer might spell them
25-chain-context-v1chainA device chain with the process context and a reach record of each kind and state
26-report-coverage-v3reportA coverage report of the third format

The keys of vectors 07 to 18 and of vector 26 are test keys. Their seeds are the SHA-256 of the string antler format vector key: <name>, for the names checkpoint, policy, approval, receipt, report and audit; the device keys of the frozen fixtures are in their vectors. They sign nothing but these vectors.

The keys of vectors 19 and 20 are test keys too, derived from the same seed string with other names: hardware-device for the device key (the SHA-256 is its Ed25519 seed), and hardware and hardware-other for the two P-256 keys (the SHA-256, as a big-endian number, is the private scalar). No chip holds them. The timestamp tokens of vectors 21 to 23 are signed by a stand-in authority made for these vectors, which no one should trust for anything else: an Ed25519 root and a timestamping certificate it issued, whose key seeds are the SHA-256 of stand-in timestamp authority: format vectors: root and of stand-in timestamp authority: format vectors: signer. The vectors pin the timestamping certificate itself, so every byte of the pin is read.

In a segments vector, head.json's updated_at is text no check reads, as a bundle vector's unsigned members are.

The files

Every file of the test vectors and the fixed sentences, as the specification names them.