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:
- accepts every vector, and
- refuses each vector once any single byte of any of its files is changed, except the text no check reads: a vector's
descriptionand its list of what isunsigned, thenameandinput_b64of the canonical vectors (an input may be spelled in many ways), what a bundle vector lists as unsigned, and theupdated_atof a segments vector'shead.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:
- a public key file is the standard base64 of the 32-byte key and a line feed;
- a verifier key file is a checkpoint verifier key and a line feed;
- a keys file is the published keys,
{"keys":[…]}; a report's keys file also holdscheckpoint_key; - a fingerprints file is one
purpose:hexa line; - a token file is a timestamp token, DER;
- a certificate file is the timestamp authority's timestamping certificate, DER: the pin a token is checked against.
Kinds
| Kind | Files (by role) | Params | It checks |
|---|---|---|---|
canonical | vectors | Each input sanitizes and encodes to the canonical bytes given, whose SHA-256 is given | |
record | record, public_key | One record line: canonical, hashed, signed by the key, whose id it derives | |
chain | chain, public_key | head_hash, last_seq | Every record, and the links from seq 1 to the head |
checkpoint | note, verifier_key | size, root (hex) | The signed note, under the key's name as origin |
inclusion | proof, note, verifier_key | The proof against the note's root | |
consistency | proof, from_note, to_note, verifier_key | That the first note's tree is a prefix of the second's | |
signed-object | object, keys | purpose, payload_sha256 | The object's signature for the purpose, and its payload's hash |
receipt | receipt, keys | device_id | The receipt, for that device |
report | report, keys | The signed report, valid with every key of the keys file pinned | |
search-export | export, fingerprints | The export, valid with the header's keys pinned by the fingerprints | |
bundle | bundle (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 | |
timestamp | note, verifier_key, token, tsa_cert | time, imprint_sha256 (hex) | The token over the note's checkpoint: its imprint, its signature against the certificate, and its time |
hardware-chain | chain, public_key | head_hash, last_seq, hardware_key (base64), hardware_store, hardware_anchored (runs from-to joined by commas), anchors_counted, anchors_not_counted, anchors_without_head | The chain as chain checks it, and that its hardware anchors give that key, those anchored runs and those counts |
segments | segments (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
| Vector | Kind | What it is |
|---|---|---|
01-canonical-v1 | canonical | Schema v1 records as a writer might spell them (the frozen fixture) |
02-canonical-v2 | canonical | The same for schema v2 |
03-record-v1 | record | The first record of the frozen v1 device chain |
04-chain-v1 | chain | The frozen v1 device chain: every v1 event and field |
05-server-chain-v1 | chain | The frozen v1 server chain, signed with an audit key |
06-chain-v2 | chain | The frozen v2 device chain |
07-checkpoint | checkpoint | A checkpoint of a log of 25 records |
08-inclusion | inclusion | Leaf 5 in that checkpoint |
09-consistency | consistency | Size 8 as a prefix of size 25 |
10-signed-object | signed-object | A signed object of purpose policy |
11-receipt | receipt | The receipt of the head of vector 04's chain |
12-report-coverage-v1 | report | A coverage report of the first format |
13-report-coverage-v2 | report | A coverage report of the second format |
14-report-recall-v1 | report | A recall report of the first format, every member set |
15-report-recall-v2 | report | A credential recall's report of the second format |
16-report-credential-v1 | report | A credential report |
17-search-export | search-export | A search export of four records |
18-bundle | bundle | An evidence bundle: two chains, two checkpoints, a report, a ledger file and a witness file |
19-hardware-chain | hardware-chain | A device chain whose heartbeats carry hardware anchors: records 1 to 9 of 13 are anchored |
20-hardware-chain-copied | hardware-chain | That 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-timestamp | timestamp | A timestamp token over the checkpoint of size 8 |
22-bundle-timestamps | bundle | The bundle of vector 18 with a timestamp token for each of its checkpoints |
23-segments | segments | A 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-v1 | canonical | Schema v1 records with the process context's keys as a writer might spell them |
25-chain-context-v1 | chain | A device chain with the process context and a reach record of each kind and state |
26-report-coverage-v3 | report | A 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.
- sentences.json
- vectors/01-canonical-v1/vector.json
- vectors/01-canonical-v1/vectors.json
- vectors/02-canonical-v2/vector.json
- vectors/02-canonical-v2/vectors.json
- vectors/03-record-v1/device.pub
- vectors/03-record-v1/record.jsonl
- vectors/03-record-v1/vector.json
- vectors/04-chain-v1/chain.jsonl
- vectors/04-chain-v1/device.pub
- vectors/04-chain-v1/vector.json
- vectors/05-server-chain-v1/audit.pub
- vectors/05-server-chain-v1/server.jsonl
- vectors/05-server-chain-v1/vector.json
- vectors/06-chain-v2/chain.jsonl
- vectors/06-chain-v2/device.pub
- vectors/06-chain-v2/vector.json
- vectors/07-checkpoint/checkpoint.txt
- vectors/07-checkpoint/checkpoint.vkey
- vectors/07-checkpoint/vector.json
- vectors/08-inclusion/checkpoint.txt
- vectors/08-inclusion/checkpoint.vkey
- vectors/08-inclusion/proof.json
- vectors/08-inclusion/vector.json
- vectors/09-consistency/checkpoint-25.txt
- vectors/09-consistency/checkpoint-8.txt
- vectors/09-consistency/checkpoint.vkey
- vectors/09-consistency/proof.json
- vectors/09-consistency/vector.json
- vectors/10-signed-object/keys.json
- vectors/10-signed-object/object.json
- vectors/10-signed-object/vector.json
- vectors/11-receipt/keys.json
- vectors/11-receipt/receipt.json
- vectors/11-receipt/vector.json
- vectors/12-report-coverage-v1/keys.json
- vectors/12-report-coverage-v1/report.json
- vectors/12-report-coverage-v1/vector.json
- vectors/13-report-coverage-v2/keys.json
- vectors/13-report-coverage-v2/report.json
- vectors/13-report-coverage-v2/vector.json
- vectors/14-report-recall-v1/keys.json
- vectors/14-report-recall-v1/report.json
- vectors/14-report-recall-v1/vector.json
- vectors/15-report-recall-v2/keys.json
- vectors/15-report-recall-v2/report.json
- vectors/15-report-recall-v2/vector.json
- vectors/16-report-credential-v1/keys.json
- vectors/16-report-credential-v1/report.json
- vectors/16-report-credential-v1/vector.json
- vectors/17-search-export/fingerprints.txt
- vectors/17-search-export/search.jsonl
- vectors/17-search-export/vector.json
- vectors/18-bundle/bundle/ledger.jsonl
- vectors/18-bundle/bundle/manifest.json
- vectors/18-bundle/bundle/records/d_3097e2dee2cb4a34b53840cdb705aed7.jsonl
- vectors/18-bundle/bundle/records/server.jsonl
- vectors/18-bundle/bundle/reports/coverage.json
- vectors/18-bundle/fingerprints.txt
- vectors/18-bundle/vector.json
- vectors/18-bundle/witness.jsonl
- vectors/19-hardware-chain/chain.jsonl
- vectors/19-hardware-chain/device.pub
- vectors/19-hardware-chain/vector.json
- vectors/20-hardware-chain-copied/chain.jsonl
- vectors/20-hardware-chain-copied/device.pub
- vectors/20-hardware-chain-copied/vector.json
- vectors/21-timestamp/checkpoint.txt
- vectors/21-timestamp/checkpoint.vkey
- vectors/21-timestamp/token.tsr
- vectors/21-timestamp/tsa.crt
- vectors/21-timestamp/vector.json
- vectors/22-bundle-timestamps/bundle/ledger.jsonl
- vectors/22-bundle-timestamps/bundle/manifest.json
- vectors/22-bundle-timestamps/bundle/records/d_3097e2dee2cb4a34b53840cdb705aed7.jsonl
- vectors/22-bundle-timestamps/bundle/records/server.jsonl
- vectors/22-bundle-timestamps/bundle/reports/coverage.json
- vectors/22-bundle-timestamps/bundle/timestamps/25.tsr
- vectors/22-bundle-timestamps/bundle/timestamps/8.tsr
- vectors/22-bundle-timestamps/fingerprints.txt
- vectors/22-bundle-timestamps/tsa.crt
- vectors/22-bundle-timestamps/vector.json
- vectors/23-segments/delivery/head.json
- vectors/23-segments/delivery/segments/seg-000000000001.jsonl
- vectors/23-segments/delivery/segments/seg-000000000002.jsonl
- vectors/23-segments/delivery/segments/seg-000000000003.jsonl
- vectors/23-segments/fingerprints.txt
- vectors/23-segments/tsa.crt
- vectors/23-segments/vector.json
- vectors/24-canonical-context-v1/vector.json
- vectors/24-canonical-context-v1/vectors.json
- vectors/25-chain-context-v1/chain.jsonl
- vectors/25-chain-context-v1/device.pub
- vectors/25-chain-context-v1/vector.json
- vectors/26-report-coverage-v3/keys.json
- vectors/26-report-coverage-v3/report.json
- vectors/26-report-coverage-v3/vector.json