Add transparency-log checkpoint mode alongside git-checkpoint - #13
Open
BenBirt wants to merge 1 commit into
Open
Add transparency-log checkpoint mode alongside git-checkpoint#13BenBirt wants to merge 1 commit into
BenBirt wants to merge 1 commit into
Conversation
Implements the variant proposed in project-oak#11: a Merkle transparency log of ref updates, stored in the repository as Git refs and checkpointed with a standard C2SP tlog-checkpoint that standard tlog-witness witnesses can cosign. Both modes ship; select with --mode on checkpoint/verify/audit and the witness server. git-checkpoint remains the default and is unchanged. The motivation is witness diversity. In git-checkpoint mode the witness checks Git commit ancestry, which makes the ratchet an enforced property but requires every witness operator to run git-ratchet's own implementation. A tlog checkpoint carries no Git-specific fields, so witnesses that have never heard of git-ratchet can cosign it. The trade is that a witness verifying only tree consistency will cosign a rollback -- appending a rolled-back state to a log is a consistent operation. The ratchet is preserved by verify walking the logged entries: branch entries must each descend from the last, tags must be logged exactly once. The walk is local and cheap because the log ships with the repository, and it is always performed; there is no cheaper verification path, because a cheaper one would not be safe. TestTlogDetectsBranchRollback asserts both halves of this: the checkpoint succeeds, and verify rejects it. Design decisions: - One log per repository, not per ref. Witness state and operator onboarding are per log, so per-ref logs would multiply the registrations that speaking a standard protocol was meant to avoid. - Entries record state ("<ref> <hash>"), not transitions. The log's ordering already establishes the predecessor; a self-asserted one could not be trusted anyway. - The log ref points at a commit, so it can only be advanced by a fast-forward push and an ordinary Git server rejects a rewritten log for free. - Merkle math is implemented in-tree against RFC 6962 rather than taking a dependency; no new modules are required. - Entry bundles use the tlog-tiles path scheme. Hash tiles are not stored: every consumer holds the whole log, and witnesses are sent their consistency proof in the request. ML-DSA-44 cosignatures over a tlog-checkpoint use the tlog-cosignature binary struct with its fields carrying their intended values -- log_origin, tree size and root hash -- rather than the repurposing a git-checkpoint body forces. Not implemented for tlog mode: the decomposed checkpoint-request/checkpoint-store workflow, and therefore the GitHub Issue witness transport. See docs/tlog-variant.md.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements the variant proposed in #11: a Merkle transparency log of ref updates, stored in the repository as Git refs and checkpointed with a standard C2SP tlog-checkpoint that standard tlog-witness witnesses can cosign.
Both modes ship; select with --mode on checkpoint/verify/audit and the witness server. git-checkpoint remains the default and is unchanged.
The motivation is witness diversity. In git-checkpoint mode the witness checks Git commit ancestry, which makes the ratchet an enforced property but requires every witness operator to run git-ratchet's own implementation. A tlog checkpoint carries no Git-specific fields, so witnesses that have never heard of git-ratchet can cosign it.
The trade is that a witness verifying only tree consistency will cosign a rollback -- appending a rolled-back state to a log is a consistent operation. The ratchet is preserved by verify walking the logged entries: branch entries must each descend from the last, tags must be logged exactly once. The walk is local and cheap because the log ships with the repository, and it is always performed; there is no cheaper verification path, because a cheaper one would not be safe. TestTlogDetectsBranchRollback asserts both halves of this: the checkpoint succeeds, and verify rejects it.
Design decisions:
ML-DSA-44 cosignatures over a tlog-checkpoint use the tlog-cosignature binary struct with its fields carrying their intended values -- log_origin, tree size and root hash -- rather than the repurposing a git-checkpoint body forces.
Not implemented for tlog mode: the decomposed checkpoint-request/checkpoint-store workflow, and therefore the GitHub Issue witness transport. See docs/tlog-variant.md.