diff options
| -rw-r--r-- | markup/api.md | 278 | ||||
| -rw-r--r-- | markup/witness.md | 67 |
2 files changed, 0 insertions, 345 deletions
diff --git a/markup/api.md b/markup/api.md deleted file mode 100644 index 3659520..0000000 --- a/markup/api.md +++ /dev/null @@ -1,278 +0,0 @@ -# System Transparency Log -This document provides a sketch of System Transparency (ST) logging. The basic -idea is to insert hashes of system artifacts into a public, append-only, and -tamper-evident transparency log, such that any enforcing client can be sure that -they see the same system artifacts as everyone else. A system artifact could -be an operating system image, a Debian package, or a browser update (to mention -a few examples). - -An ST log can be implemented on-top of -[Trillian](https://trillian.transparency.dev) using a custom STFE personality. -For reference you may look at Certificate Transparency (CT) logging and -[CTFE](https://github.com/google/certificate-transparency-go/tree/master/trillian/ctfe), -which implements [RFC 6962](https://tools.ietf.org/html/rfc6962). - -We take inspiration from from RFC 6962 and its follow-up specification [RFC -6962/bis](https://datatracker.ietf.org/doc/draft-ietf-trans-rfc6962-bis/). - -## Log parameters -A log is defined by the following immutable parameters: -- Log identifier: serialized namespace of type `ed25519_v1` that defines the -log's signing algorithm and public verification key. -- Supported namespaces: a list of namespace types the log supports. Submitters -must use a supported namespace type when adding new entries. -- Base URL: where can this log be reached? E.g., example.com:1234/log - -Note that **there is no Maximum Merge Delay (MMD)**, which is in contrast to RFC -6962. New entries are merged into the log as soon as possible, and no client -should trust that something is logged until an inclusion proof can be provided -that references a trustworthy STH. - -We use the same hash strategy as described in RFC 6962: SHA256 with `0x00` as -leaf node prefix and `0x01` as interior node prefix. - -## Minimum acceptance criteria -A log should accept a submission if it is: -- Well-formed, see below. -- Digitally signed - - Verification key must be registered in the log as a namespace - - Proves which namespace submitted an entry for logging - -## Data structure definitions -Data structures are defined and serialized using the presentation language in -[RFC 5246, §4](https://tools.ietf.org/html/rfc5246). A definition of the log's -Merkle tree can be found in [RFC 6962, -§2](https://tools.ietf.org/html/rfc6962#section-2). - -### Repurposing `TransItem` as `StItem` -A general-purpose `TransItem` is defined in [RFC 6962/bis, -§4.5](https://tools.ietf.org/html/draft-ietf-trans-rfc6962-bis-34#section-4.5). -We define our own `TransItem`, but name it `STItem` to emphasize that they are -not the same. Some definitions are re-used while others are added. - -``` -enum { - reserved(0), - signed_tree_head_v1(1), // defined in RFC 6962/bis, §4.10 - signed_debug_info_v1(2), // defined below, think "almost SCT" - consistency_proof_v1(3), // defined in RFC 6962/bis, §4.11 - inclusion_proof_v1(4), // defined in RFC 6962/bis, §4.12 - checksum_v1(5), // defined below, think "leaf data" - (65535) -} StFormat; - -struct { - StFormat format; - select (format) { - case signed_tree_head_v1: SignedTreeHeadV1; - case signed_debug_info_v1: SignedDebugInfoV1; - case consistency_proof_v1: ConsistencyProofV1; - case inclusion_proof_v1: InclusionProofV1; - case checksum_v1: ChecksumV1; - } message; -} StItem; -``` - -### Namespace -A _namespace_ is a versioned data structure that contains a public verification -key (or fingerprint), as well as enough information to determine its format, -signing, and verification operations. Namespaces are used as identifiers, both -for the log itself and the parties that submit artifact hashes. -``` -enum { - reserved(0), - ed25519_v1(1), - (65535) -} NamespaceFormat; - -struct { - NamespaceFormat format; - select (format) { - case ed25519_v1: Ed25519V1; - } message; -} Namespace; -``` - -A log may reject submissions that correspond to an unknown namespace, or because -a trusted namespace exceeded a configured rate limit. As such, it is possible -to use namespaces as an anti-spam feature. - -Namespaces also allow us to separate different ecosystems. For example, -software publisher _A_ can be sure that publicly logged artifact hashes are only -considered valid if signed by their own namespace(s). - -(Credit: our namespace format is inspired by Keybase's -[key-id](https://keybase.io/docs/api/1.0/kid).) - -#### Ed25519V1 -At this time the only supported namespace type is based on Ed25519, see [RFC -8032](https://tools.ietf.org/html/rfc8032). The namespace field contains the -full verification key. -``` -struct { - opaque namespace<32>; // public verification key -} Ed25519V1; -``` - -#### Other -In the future we will support other key types, such as RSA. For example, we -could add [RSASSA-PKCS1-v1_5](https://tools.ietf.org/html/rfc3447#section-8.2) -as follows: -1. Add `rsa_v1` format and RSAV1 namespace. This is what we would register on -the server-side such that the server knows the namespace and complete key. -``` -struct { - opaque namespace<32>; // key fingerprint - // + some encoding of public key -} RSAV1; -``` -2. Add `rsassa_pkcs1_5_v1` format and `RSASSAPKCS1_5_v1`. This is what the -submitter would use to communicate namespace and RSA signature mode. -``` -struct { - opaque namespace<32>; // key fingerprint - // + necessary parameters, e.g., SHA256 as hash function -} RSASSAPKCS1_5V1; -``` - -This is just one of several options. To be decided later on. - -### Merkle tree leaf types -In the future there might be several types of leaves. Say, one for operating -system packages, another one for Debian packages, and a third one for -general-purpose checksums. For now we only define the latter. - -TODO: scope of this spec should only be checksum - -#### Checksum - -``` -struct { - opaque package<1..2^8-1>; // package identifier - opaque checksum<1..64>; // hash of some artifact - Namespace namespace; -} ChecksumV1; -``` - -A checksum entry contains a package identifier such as `foobar-1.2.3` and an -artifact hash. For example, the checksum type could be used by Firefox to -[enforce public binary logging before accepting a new software -update](https://wiki.mozilla.org/Security/Binary_Transparency). It is assumed -that the entities relying on the checksum type know how to find the artifact -source (if not already at hand) and then reproduce the logged hash from it. - -Namespace is used to determine which ecosystem an artifact belongs to. However, -note that we do not connect namespaces to real-world identities: it is up to the -respective ecosystems to communicate their own namespaces, e.g., by establishing -namespaces based on trusted verification keys that already sign their artifacts. - -### Signed Debug Info -RFC 6962 uses Signed Certificate Timestamps (SCTs) as promises of public -logging within a time known as the Maximum Merge Delay (MMD). We provide no -such promise: a Signed Debug Info (SDI) is an intent to log because the -submitter is authorized to do so and the entry appears to be valid. It will be -merged into the log's Merkle tree as soon as possible on a best-effort basis. -If an unexpected delay is encountered, the submitter can present the issued SDI -to the log operator (who can then investigate the underlying reason further). -``` -struct { - Namespace log_id; - opaque message<1..2^16-1> // debug string that is only meant for the log - opaque signature <1..2^16-1; // computed over a leaf-type StItem -} SignedDebugInfoV1; -``` - -Signature formatting and verification operations follow from the log's -namespace identifier. - -TODO: remove SDI? - -## Public endpoints -Clients talk to the log with HTTPS GET/POST requests. POST parameters -are JSON objects, GET parameters are URL encoded, and serialized data is -expressed as base-64. See details in as in RFC 6962, -[§4](https://tools.ietf.org/html/rfc6962#section-4). - -TODO: remove json -TODO: and b64? - -Unless specified otherwise, the data in question is serialized. - -### add-entry -``` -POST https://<base url>/st/v1/add-entry -``` - -Input: -- item: an `StItem` that corresponds to a valid leaf type. Only -`checksum_v1` at this time. -- signature: covers the submitted item. - -Output: -- an `StItem` structure of type `signed_debug_info_v1` that covers the added -item. - -### get-entries -``` -GET https://<base url>/st/v1/get-entries -``` - -Input: -- start: 0-based index of first entry to retrieve in decimal. -- end: 0-based index of last entry to retrieve in decimal. - -Output: -- an array of objects, each consisting of - - leaf: `StItem` that corresponds to the leaf's type. - - signature: signature that covers the retrieved item using the below - signature scheme. - -### get-namespaces -``` -GET https://<base url>/st/v1/get-namespaces -``` - -No input. - -Output: -- an array of base-64 encoded namespaces that the log accept. - -### get-proof-by-hash -``` -GET https://<base url>/st/v1/get-proof-by-hash -``` - -Input: -- hash: a base-64 encoded leaf hash. -- tree_size: the tree size that the proof should be based on in decimal. - -The leaf hash value is computed as in RFC 6962/bis, -[§4.7](https://datatracker.ietf.org/doc/html/draft-ietf-trans-rfc6962-bis-34#section-4.7). - -Output: -- an `StItem` of type `inclusion_proof_v1`. Note that this structure includes -both the leaf index and an audit path for the tree size. - -### get-consistency-proof -``` -GET https://<base url>/st/v1/get-consistency-proof -``` - -Input: -- first: the `tree_size` of the older tree in decimal. -- second: the `tree_size` of the newer tree in decimal. - -Output: -- an `StItem` of type `consistency_proof_v1` that corresponds to -the requested tree sizes. - -### get-sth -``` -GET https://<base url>/st/v1/get-sth -``` - -No input. - -Output: -- an `StItem` of type `signed_tree_head_v1`, which corresponds to the most -recently known STH. diff --git a/markup/witness.md b/markup/witness.md deleted file mode 100644 index 584aa4d..0000000 --- a/markup/witness.md +++ /dev/null @@ -1,67 +0,0 @@ -# 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. |