Antler

In development

Early access

Docs

The evidence bundle and the search export

Two documents carry records out of a workspace for offline checking. The bundle carries whole chains with the checkpoints, proofs and reports that go with them. The search export carries the results of one search. Each names the keys it was signed with; a verifier pins them by fingerprint (log.md).

Vectors: 18-bundle, 17-search-export.

The bundle

A bundle is a tar archive of regular files:

A verifier reads regular files only, by their cleaned slash-separated paths, and refuses a manifest over 16 MiB or another file over 1 GiB. antler-verify also accepts the directory an archive was extracted into.

The manifest

Format antler-bundle-v1. Members, in order:

MemberTypeMeaning
formatstringantler-bundle-v1
org_idstringThe workspace's id
originstringThe origin of the workspace's log, which every checkpoint must name
created_at, created_bystringWhen and by whom the bundle was made
keysobjectThe published keys: {"keys":[{purpose, key_id, key}, …]}
checkpoint_keystringThe checkpoint key, as a verifier key
checkpointstringThe newest signed checkpoint note; it covers every exported record
checkpointslist of stringsThe stored notes, oldest first
consistencylistConsistency proofs {from, to, hashes}, one from each checkpoint to the next
chainslistOne entry per chain (below)
workspace, regionstringThe workspace and its region; optional
fingerprintsmapThe current keys' fingerprints by purpose; optional
windowobject{from, to}, RFC 3339: the records at or after from and before to; absent for a whole ledger
reportslist{file, kind, sha256} for each signed report in the bundle; optional
ledgerobject{file, sha256} of the credential ledger file; optional
timestampslist{size, file} for each timestamp token in the bundle, oldest first: the size of the checkpoint it is over and the token's file; optional

A chain entry:

MemberTypeMeaning
device_idstringThe chain: a device's id, or server
public_keystringThe key the chain is signed with, base64: the device's key, or the audit key for the server chain
filestringThe chain file's path in the bundle
first_seq, last_seqintegerThe first and last seq of the chain as exported
head_hashstringThe hash of the record at last_seq
server_redactedlist of integersThe seqs whose stored copy the server redacted; optional
missinglist of {from, to}Inclusive ranges of seqs in [first_seq, last_seq] that the file does not hold: declared losses, or records past retention; optional
beforeintegerSet when the file starts after seq 1 because the window does: records 1 to before are older than the window; optional
inclusionobjectThe inclusion proof of the chain's last record in checkpoint; optional
receiptobjectThe newest ingest receipt of the chain, a signed object; optional

Checking a bundle

With the keys pinned (fingerprints matched against keys and checkpoint_key, or the keys of an enrolled computer):

  1. Checkpoints. Verify every note in checkpoints, and checkpoint when it is not among them, with the checkpoint key under origin. A note that does not verify is a failure. Two of the same size with different roots are a failure. Order them by size: each consecutive pair must have a consistency proof in consistency that checks. The newest checkpoint is the largest that verified.
  2. Each chain. Find its key: a key pinned for the device; for the server chain, the pinned audit key equal to public_key; otherwise public_key itself, which is accepted only as step 5 says. The key of a device chain must derive device_id. A bundle that names no usable key for a chain is a failure. Parse the file's lines strictly, check every record and link (records.md), starting from seq 1, or from the file's first record when missing and before cover every seq before it. Every record must name the entry's device_id.
  3. The head. The file must end at last_seq with head_hash. When it ends earlier and missing covers the rest, the end stays unproven; otherwise it is a failure.
  4. The end. The chain's end is proven by inclusion, when the proof is for the file's last record, against the newest checkpoint, and checks; or by receipt, when it verifies with a pinned receipt key, names the file's last seq and hash, and its log_size is at least the newest checkpoint's size. An inclusion proof that does not check, or a receipt that does not verify, is a failure. A receipt that names a seq the file holds must name that record's hash. A receipt ahead of the file, in a log the newest checkpoint already covers, with the records between not listed as missing, is a failure: the server held records the bundle leaves out.
  5. Device keys taken from the bundle. When the server's keys are pinned by fingerprint, a device chain's public_key is accepted when step 4 proved its head with the pinned log or a pinned receipt. A chain whose key is neither pinned nor vouched for this way is a failure.
  6. Reports. Each file under reports must be in the bundle with the listed sha256, and verify as a signed report (reports.md) with the pinned keys. A report that is itself unproven does not change the bundle's outcome; a report with a problem makes it invalid.
  7. The ledger. The file under ledger must be in the bundle with the listed sha256. It is derived from the records and not signed.
  8. Timestamps. Each file under timestamps must be in the bundle, the bundle must hold a verified checkpoint of the entry's size, and the token must check against that checkpoint and, when the reader pinned the authority's certificate, against it (timestamps.md). With a certificate pinned, a bundle without any token is a failure.

The bundle is valid when nothing failed and every chain's end is proven; unproven when nothing failed and some end is not; invalid otherwise. With no key pinned, signatures are not checked and the result is at best unproven.

A verifier told to expect a head hash or a last seq for a device chain requires the chain to end there, in place of step 4.

The witness file

An enrolled device keeps the checkpoints it verified in witness.jsonl, one JSON object a line: {"note":"<signed note>","seen_at":"<time>"}. Given a device's witness file, a verifier also checks, for each line: the note verifies; when its size is at most the bundle's newest checkpoint, the bundle holds a checkpoint of that size with the same root (another root proves the server showed the device a different log; a missing one is a failure, since an honest export holds every stored checkpoint). Notes newer than the bundle are counted and not checked. seen_at is the device's own note and proves nothing.

What nothing signs

These members of a manifest are stated by whoever made the bundle and are covered by no signature or hash. A verifier shows them as stated and relies on none of them: format, org_id, created_at, created_by, workspace, region, fingerprints, window, a chain's first_seq and a report entry's kind. Everything else in a manifest is either signed (notes, receipts, timestamp tokens), hashed (report and ledger files), or checked against signed or hashed data (keys against fingerprints, heads against the chain files, proofs against checkpoints, a timestamp's size against the checkpoint its token is over).

The records' own times are signed; a manifest's window is not. The fingerprints a manifest lists are never the ones a verifier pins.

The search export

A search export is a JSON-lines file: a header line, one line per record, and a trailer line.

The header

Format antler-search-export-v1. Members, in order:

MemberTypeMeaning
formatstringantler-search-export-v1
workspace, regionstringThe workspace and its region; optional
created_at, created_bystringWhen and by whom it was made
filterslist of stringsThe names of the search's filters, sorted; never their values
windowobject{from, to}: the window searched
originstringThe origin of the workspace's log
checkpointstringThe signed checkpoint note every proof checks against
checkpoint_keystringThe checkpoint key, as a verifier key
keysobjectThe published keys
fingerprintsmapThe current keys' fingerprints; optional, never pinned from here
chain_recordobjectThe inclusion proof, in checkpoint, of the export's own record in the server's chain
truncatedbooleanSet when the search matched more records than the export holds

A record line

{"line":"<the record line>","public_key":"<base64>","server_redacted":false,"proof":{"record_hash":"…","leaf":5,"tree_size":25,"hashes":["…"]}}

line is the record's line as a string; public_key the key that signed it (the audit key for a record of the server's chain); proof its inclusion proof in the header's checkpoint. server_redacted is present only when true. A record line is decoded strictly.

The trailer

{"signed":{"purpose":"report","key_id":"…","payload":"…","sig":"…"}}

a signed object of purpose report whose payload is, in order:

{"format":"antler-search-export-summary-v1","header_sha256":"<hex>","records":4,"lines_sha256":"<hex>","tree_size":25}

Checking a search export

  1. Pin the keys among the header's keys and checkpoint_key.
  2. Verify checkpoint with the checkpoint key under origin.
  3. chain_record must be for a tree of the checkpoint's size and check against its root.
  4. For each record line: parse line strictly as a record. For a device record, public_key must derive its device_id; for a record of the server's chain, public_key must be the pinned audit key. proof must be for the record's hash and the checkpoint's size, and check against its root. Then check the record's hash and signature, unless the line is marked server_redacted.
  5. Verify the trailer's signed object with the pinned report key, decode its payload strictly, and compare all four members with the file. A file with no trailer was cut.

Any failure makes the export invalid. It is valid when everything checks with pinned keys, and at best unproven without them. A search export holds records, not chains: it shows that each record is in the log the workspace signed, and that the workspace signed this set of them; it does not show that a device's chain has no other records.