diff options
| -rw-r--r-- | markup/api.md | 90 |
1 files changed, 46 insertions, 44 deletions
diff --git a/markup/api.md b/markup/api.md index da23488..0e5c83d 100644 --- a/markup/api.md +++ b/markup/api.md @@ -3,8 +3,8 @@ 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 generally just a checksum of -something opaque. +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. @@ -17,42 +17,38 @@ We take inspiration from from RFC 6962 and its follow-up specification [RFC ## Log parameters A log is defined by the following immutable parameters: -- Log identifier: `SHA256(public key)`, see RFC 6962 -[§3.2](https://tools.ietf.org/html/rfc6962#section-3.2). TODO: use KID instead. -- Public key: DER encoding of the key represented as `SubjectPublicKeyInfo` -- Supported signature schemes: a list of signature schemes that the -log recognizes. Possible values are defined in RFC 8446, -[§4.2.3](https://tools.ietf.org/html/rfc8446#section-4.2.3). Submitters must -use a signature algorithm that the log supports. -- Signature scheme: the signature scheme that the log uses to sign tree heads -and debug info statements. +- 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 MMD**. The idea is to merge added entries 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. +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. -Moreover, we use the same hash strategy as described in RFC 6962: SHA256 with -`0x00` as leaf node prefix and `0x01` as interior node prefix. +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 - - Proves who submitted an entry for logging - Verification key must be registered in the log as a namespace + - Proves which namespace submitted an entry for logging ## Data structure definitions -We encode everything that is digitally signed as in [RFC -5246](https://tools.ietf.org/html/rfc5246). Therefore, we use the same -description language for our data structures. A definition of the log's Merkle -tree can be found in RFC 6962, see -[§2](https://tools.ietf.org/html/rfc6962#section-2). +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 by RFC 6962/bis. Below we define our -own `TransItem`, but name it `STItem` to emphasize that they are not the same. -Some definitions are re-used and others are added. +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 { @@ -78,9 +74,10 @@ struct { ``` ### Namespace -The submitter's verification key is used to establish a _namespace_. Added -log entries must be signed by a registered namespace, such that anyone that -observes the log can determine which artifact hashes belong to which namespaces. +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), @@ -96,15 +93,24 @@ struct { } Namespace; ``` -Credit: inspired by Keybase's [KID format](https://keybase.io/docs/api/1.0/kid). +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 key type is Ed25519 as defined by [RFC +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 key + opaque namespace<32>; // public verification key } Ed25519V1; ``` @@ -129,9 +135,7 @@ struct { } RSASSAPKCS1_5V1; ``` -Another option is to just never bother with key fingerprint, i.e., use the -complete (encoded) RSA key as the namespace. Makes the leaf a lot larger -though. +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 @@ -157,8 +161,10 @@ 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 who this artifact hash belongs to. Note that we -do not connect namespaces to real-world identities. It is just _a namespace_. +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 @@ -170,19 +176,15 @@ 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 { - LogID log_id; // defined in RFC 6962, basically SHA256(pub key) + 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; ``` -The signature's encoding follows from the log's signature algorithm parameter, -e.g., `ed25519(0x0807)` refers to [RFC -8032](https://tools.ietf.org/html/rfc8032). A complete list of signature -schemes and their interpretations can be found in RFC 8446, -[§4.2.3](https://tools.ietf.org/html/rfc8446#section-4.2.3). +Signature formatting and verification operations follow from the log's +namespace identifier. -TODO: when log id is namespace this information is already communicated. TODO: remove SDI? ## Public endpoints @@ -233,7 +235,7 @@ GET https://<base url>/st/v1/get-namespaces No input. Output: -- an array of base-64 encoded namespaces that the log accept. TODO: format? +- an array of base-64 encoded namespaces that the log accept. ### get-proof-by-hash ``` |