aboutsummaryrefslogtreecommitdiff
path: root/markup/witness.md
diff options
context:
space:
mode:
authorRasmus Dahlberg <rasmus.dahlberg@kau.se>2021-02-10 18:59:09 +0100
committerRasmus Dahlberg <rasmus.dahlberg@kau.se>2021-02-10 18:59:09 +0100
commitccdd98a67a483e61a8557e08d5c54739f7028b80 (patch)
tree401beace5c5d779a19d6adc76902fa17530ed3a6 /markup/witness.md
parent72c8492ee1bd07d5960c9920e51b7addac11b806 (diff)
added witness cosigning protocol documentation
Diffstat (limited to 'markup/witness.md')
-rw-r--r--markup/witness.md67
1 files changed, 67 insertions, 0 deletions
diff --git a/markup/witness.md b/markup/witness.md
new file mode 100644
index 0000000..584aa4d
--- /dev/null
+++ b/markup/witness.md
@@ -0,0 +1,67 @@
+# Witness cosigning
+Transparency logs were designed to be cryptographically verifiable in the
+presence of a gossip-audit model that ensures everyone observes _the same
+cryptographically verifiable log_. The gossip-audit model is largely undefined
+in today's existing transparency logging ecosystems, which means that the logs
+must be trusted to play by the rules. We wanted to avoid that outcome in our
+ecosystem. Therefore, a gossip-audit model is built into the log.
+
+The basic idea is that an STH should only be considered valid if it is cosigned
+by a number of witnesses that verify the append-only property. Which witnesses
+to trust and under what circumstances is defined by a client-side _witness
+cosigning policy_. For example,
+ "require no witness cosigning",
+ "must have at least `k` signatures from witnesses A...J", and
+ "must have at least `k` signatures from witnesses A...J where one is from
+ witness B".
+
+Witness cosigning policies are beyond the scope of this specification.
+
+The log is configured with a list of witness namespaces. The only supported
+witness namespace format is `ed25519_v1`. The signature must span a serialized
+`signed_tree_head_v1` item.
+
+## Public endpoints
+Witnesses are expected to poll the `next-cosi` endpoint. If a new STH is
+obtained:
+1. Verify that the log is append-only by fetching a consistency proof from the
+latest STH that this witness co-signed. Stop if no valid proof is available.
+2. Sign the STH and submit using the `add-cosi` API.
+
+### add-cosi
+```
+POST https://<base url>/st/v1/add-cosi
+```
+
+Input:
+- sth: an `StItem` of type `signed_tree_head_v1`.
+- namespace: a `Namespace` item of type `ed25519_v1`.
+- signature: covers the specified STH.
+
+Output:
+- None
+
+### get-cosi
+```
+GET https://<base url>/st/v1/get-cosi
+```
+
+Input:
+- None
+
+Output:
+- A map with keys "sth" and "signatures". The former is an `StItem` of type
+`signed_tree_head_v1`. The latter an array where each entry is a map with a
+"witness" (`ed25519_v1` namespace) and a "signature".
+
+### next-cosi
+```
+GET https://<base url>/st/v1/next-cosi
+```
+
+Input
+- None
+
+Output:
+- an `StItem` of type `signed_tree_head_v1`, which corresponds to the STH
+that is currently being cosigned. Stable for a period of time, e.g., 10 minutes.