README
¶
Witness
Overview
A witness is an entity which helps to prevent split-view attacks by transprarency logs (tlogs). It does this by verifying that tlogs are evolving in an append-only manner, and counter-signs checkpoints that represent an append-only evolution from any previously witnessed checkpoints.
Clients of tlogs can use these countersignatures to ensure that they are not being targeted by a log wanting to present a different view of the entries it contains to that seen by others. See below for a more detailed explanation.
This repository contains libraries and binaries for running witnesses which comply with the tlog-witness spec and
can integrate with the public witness network.
Users wishing to run this should start with the OmniWitness.
Importance of Witnesses
Some important terminology:
| Term | Definition |
|---|---|
| Log | A verifiable data structure that commits to a list of entries |
| Append Only | New entries added to a log can only be added to the end of the list |
| Checkpoint | A Checkpoint is a signed commitment to the state of a Log at a given size |
| Split View | A split view is a situation where a Log presents two views of its data where one is not a prefix of the other |
| Consistency Proof | A crytographic proof between two checkpoints that proves one of them is an Append Only evolution of the other |
| Witness | Tracks one or more logs, verifying Consistency Proofs to ensure it cannot cross any Split Views, and counter-signs consistent Checkpoints |
Witnesses are a critical part of a secure transparency ecosystem by providing an anchor that guards against split view attacks by log operators.
A log that could successfully perform a split view would be able to show one list of entries to users that rely on the data (e.g. malware), and a different list of data to the verifiers of this data (e.g. only good builds of software).
This fundamentally undermines the main property of logs: discoverability. Discoverability ensures that any data that is relied upon by one user will eventually be discovered and verified by someone that is holding the claimant and the log to account. See https://transparency.dev/how-to-design-a-verifiable-system/ for information on the Claimant Model, which succinctly describes roles in a transparency ecosystem.
A Witness keeps a single Checkpoint for each log in secure storage. On first initialization, this Checkpoint may come from the Log and be Trusted On First Use (TOFU). Thereafter:
- The witness acquires a new Checkpoint and a Consistency Proof from its previous state
- This Consistency Proof is verified, and if the new Checkpoint is confirmed to be Append Only from the previous one, it updates its state
- The new Checkpoint is countersigned by the Witness, and made available to the public
A feature of Checkpoints is that they allow multiple signatures to be added. This means that a common way to see Checkpoints in a witnessed ecosystem is with a log signature and multiple witness signatures. An example witnessed checkpoint is:
developers.google.com/android/binary_transparency/0
611
2GZ1zmS5VkfUZmn2ZyR4KZXwHLD+xnwBIWzql/cD50w=
— pixel_transparency_log csh42zBFAiAd3Y1FwqNTt5RglY0uG7heC6Yu1gEbXXPYmZ7LdOILMAIhAIt68PnR/3TADAaC7hvrSHbpziV7TmpIwOUydLmcjyTQ
— ArmoredWitness-small-breeze nRq5UQAAAABnoqrsRIofXn68vTohcAm2KG4ACGyRPNePUk02BSWD0WKV5ElejTk5Z+Tm3GmJ5j/etA+fkL9XuaQsnTyZbr437sF4AQ==
— ArmoredWitness-autumn-wood qZb5XQAAAABnoqrl57G9CblEl3lwwuqzbaJvVMqNiZCbYZseYT1YZHYmls3CmT1wxZ1fNgM4RxHuUxjAwcI2ghTx6R5aCg+L0DGPBA==
See also the distributor project, which makes available witnessed checkpoints from the Armored Witness, a dedicated hardware device that runs the witness code from this repository.
API
The witness is an HTTP service that stores checkpoints it has seen from different verifiable logs in a sqlite database. This is a very lightweight way to help detect or even prevent split-view attacks.
The HTTP service implements the https://c2sp.org/tlog-witness API, and returns
cosignature/v1 signatures.
Running the witness
Most users wanting to run a witness will simply deploy the OmniWitness, which is preconfigured to witness all known logs using the checkpoint format.
Support
Directories
¶
| Path | Synopsis |
|---|---|
|
Package api provides the API endpoints for the witness.
|
Package api provides the API endpoints for the witness. |
|
client
|
|
|
http
Package http is a simple client for interacting with witnesses over HTTP.
|
Package http is a simple client for interacting with witnesses over HTTP. |
|
cmd
|
|
|
feedwitness
command
feedwitness is a tool for submitting checkpoints from known logs to witnesses, either directly or behind bastions.
|
feedwitness is a tool for submitting checkpoints from known logs to witnesses, either directly or behind bastions. |
|
gcp/omniwitness
command
gcp/omniwitness is a single executable that runs a witness using GCP services.
|
gcp/omniwitness is a single executable that runs a witness using GCP services. |
|
loadtest
command
loadtest is an executable that connects to a witness and determines how many updates it can handle before it is unable to maintain a given latency.
|
loadtest is an executable that connects to a witness and determines how many updates it can handle before it is unable to maintain a given latency. |
|
omniwitness
command
omniwitness is a single executable that runs all of the feeders and witness in a single process.
|
omniwitness is a single executable that runs all of the feeders and witness in a single process. |
|
internal
|
|
|
bastion
Package bastion implements support for the https://c2sp.org/https-bastion protocol.
|
Package bastion implements support for the https://c2sp.org/https-bastion protocol. |
|
client
Package client contains a basic client for the SumDB log.
|
Package client contains a basic client for the SumDB log. |
|
feeder
Package feeder provides support for building witness feeder implementations.
|
Package feeder provides support for building witness feeder implementations. |
|
feeder/pixelbt
Package pixelbt is an implementation of a witness feeder for the Pixel BT log.
|
Package pixelbt is an implementation of a witness feeder for the Pixel BT log. |
|
feeder/rekor_v1
Package rekor is an implementation of a witness feeder for the Sigstore log: Rekór.
|
Package rekor is an implementation of a witness feeder for the Sigstore log: Rekór. |
|
feeder/serverless
Package serverless is an implementation of a witness feeder for serverless logs.
|
Package serverless is an implementation of a witness feeder for serverless logs. |
|
feeder/sumdb
Package sumdb implements a feeder for the Go SumDB log.
|
Package sumdb implements a feeder for the Go SumDB log. |
|
feeder/tiles
Package tiles is an implementation of a witness feeder for C2SP tlog-tiles compatible logs.
|
Package tiles is an implementation of a witness feeder for C2SP tlog-tiles compatible logs. |
|
persistence
Package persistence defines interfaces and tests for storing log state.
|
Package persistence defines interfaces and tests for storing log state. |
|
persistence/inmemory
Package inmemory provides a persistence implementation that lives only in memory.
|
Package inmemory provides a persistence implementation that lives only in memory. |
|
persistence/sql
Package sql provides log state persistence backed by a SQL database.
|
Package sql provides log state persistence backed by a SQL database. |
|
witness
Package witness is designed to make sure the checkpoints of verifiable logs are consistent and store/serve/sign them if so.
|
Package witness is designed to make sure the checkpoints of verifiable logs are consistent and store/serve/sign them if so. |
|
Package monitoring contains interfaces and bindings for collecting metrics about behaviour of the witness.
|
Package monitoring contains interfaces and bindings for collecting metrics about behaviour of the witness. |
|
prometheus
Package prometheus contains bindings to prometheus for the interfaces in the parent monitoring package.
|
Package prometheus contains bindings to prometheus for the interfaces in the parent monitoring package. |
|
Package omniwitness provides a single Main file that runs the omniwitness.
|
Package omniwitness provides a single Main file that runs the omniwitness. |