From ccdd98a67a483e61a8557e08d5c54739f7028b80 Mon Sep 17 00:00:00 2001 From: Rasmus Dahlberg Date: Wed, 10 Feb 2021 18:59:09 +0100 Subject: added witness cosigning protocol documentation --- markup/witness.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 markup/witness.md 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:///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:///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:///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. -- cgit v1.2.3