aboutsummaryrefslogtreecommitdiff
path: root/markup/api.md
diff options
context:
space:
mode:
Diffstat (limited to 'markup/api.md')
-rw-r--r--markup/api.md90
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
```