Expand description
An append-only log whose history cannot be rewritten without detection.
A signature proves who wrote something; it cannot prove that everyone was shown the same something. That is what this is for. The log publishes one 32-byte root per size, and answers two questions:
- Inclusion: “is this entry in the log of size n?” — an audit path of about log₂(n) hashes.
- Consistency: “is the log of size m a prefix of the log of size n?” — the proof that nothing already published was altered or removed.
Consistency is the one that matters. Without it a server can show one history to a victim and another to everyone else; with it, doing so requires producing two roots for one size, which is permanent, transferable evidence of misbehaviour.
The hashing follows RFC 6962: leaves are prefixed 0x00 and internal nodes
0x01, so a leaf can never be reinterpreted as a node — the second-preimage
attack that an unprefixed Merkle tree allows.
§What a log cannot do by itself
It cannot detect a split view on its own: two divergent logs are each internally consistent. Catching that needs witnesses — independent parties who gossip roots and refuse to sign two roots for one size. Nothing here implements witnessing, and a log without it is a promise, not a proof.
Structs§
- Checkpoint
- The tree head a log publishes: origin, size and root.
- Consistency
Proof - Proof that a smaller log is a prefix of a larger one.
- Cosignature
- How a cosignature line was verified, so a caller can tell “the witness I meant signed this” from “some line had the right key id”.
- Inclusion
Proof - Proof that one entry is in the log at a given size.
- Note
Signature - One signature line: who, which key, and the raw signature bytes.
- Signed
Note - A parsed note: the signed text and every signature line, known or not.
- Transparency
Log - The log itself. Holds leaf hashes only: the entries are the caller’s.
- Witness
- A witness the caller trusts for this log: a name and an Ed25519 key.
Enums§
- AddCheckpoint
Outcome - What a witness said, classified from the status code exactly as
c2sp.org/tlog-witnessdefines it, so a caller never has to guess from a status alone which of the four refusals it received. - LogError
Constants§
- C2SP_
ED25519_ ALGORITHM - The C2SP algorithm byte for Ed25519 cosignatures.
c2sp.org/signed-noteassigns0x01; HIDE-Sign uses the0xffescape followed by a type string, so a note carrying both can never confuse the two. - CHECKPOINT_
CONTEXT - Signature context for a checkpoint note, log or witness alike.
- MAX_
NOTE_ BYTES - 32 HIDE-Sign lines are about 150 KB; anything larger is refused unread.
- MAX_
ORIGIN_ BYTES - Origins are ASCII without spaces or ‘+’, so a key name can equal the origin and no Unicode lookalike can name the same log twice.
- MAX_
WITNESS_ PROOF_ LINES - A witness is allowed at most 63 consistency proof lines.
Functions§
- add_
checkpoint_ body - The body of a
POST <prefix>/add-checkpointrequest: the old size line, the consistency proof lines, an empty line, then the note. - c2sp_
key_ id - The key id a C2SP cosignature line carries:
SHA-256(name || 0x0A || algorithm || public_key)[:4]. - classify_
add_ checkpoint - Classifies an
add-checkpointresponse. A status this specification does not name is refused rather than mapped onto the nearest one. - cosignature_
input - The exact bytes an Ed25519 C2SP cosignature is computed over. Every line is newline-terminated, and the timestamp is ASCII decimal with no leading zeroes.
- decode_
checkpoint - empty_
tree_ root - The empty tree, RFC 6962 §2.1: the hash of an empty string.
- encode_
checkpoint - Encodes a root for publication: size and hash together, because a hash with no size is not a commitment to anything checkable.
- epoch_
leaf - The leaf that logs one state of an identity’s epoch chain.
- identity_
leaf - The leaf that logs one state of an identity: which identity (its root link), which recovery key it binds (by device id), and which history (the head link and entry count).
- is_
empty_ tree_ checkpoint - The root a size-zero checkpoint must carry, so a caller can build one that a
witness will not reject with
422. Whether a checkpoint a witness would accept at size zero is well-formed. - key_id
SHA-256(name || 0x0A || 0xFF || "HIDE/1.0 hide-sign" || verifying_key)[:4].- leaf_
hash - Hashes a leaf. The prefix is what stops a leaf being read as a node.
- verify_
consistency - Checks that
old_rootreally is the root the log had before it grew tonew_root. This is the check that catches a rewritten history. - verify_
ed25519_ cosignature - Verifies a C2SP Ed25519 cosignature from
witnessovernote, in addition to the log’s own HIDE-Sign signature, and requires the checkpoint to be the oneoriginnames. - verify_
inclusion - Checks an audit path against a root. The verifier holds only the root, the entry, and the proof — never the log.