aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/api.md205
1 files changed, 0 insertions, 205 deletions
diff --git a/doc/api.md b/doc/api.md
deleted file mode 100644
index ebd666d..0000000
--- a/doc/api.md
+++ /dev/null
@@ -1,205 +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 generally just a checksum of
-something opaque.
-
-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 reuse RFC 6962 and its follow-up specification [RFC
-6962/bis](https://datatracker.ietf.org/doc/draft-ietf-trans-rfc6962-bis/) to the
-largest extent possible.
-
-## Log parameters
-A log is defined by the following immutable parameters:
-- Log identifier: a unique identifier
-- Public key: a unique public key
-- Base URL: where can this log be reached? E.g., example.com:1234/log
-- Hash algorithm: e.g., SHA-256
-- Signature algorithm: e.g., ECDSA on a given curve.
-
-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.
-
-## 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
- - The signing key must chain back to a valid trust anchor
-
-## 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).
-
-### 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.
-
-```
-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;
-```
-
-An `StItem` can be serialized into a list as described in RFC 6962/bis,
-[§6.2](https://datatracker.ietf.org/doc/html/draft-ietf-trans-rfc6962-bis-34#section-6.2).
-
-### 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.
-
-#### Checksum
-A checksum entry contains a package identifier such as `foobar-1.2.3` and an
-artifact hash that uses the log's configured hash function.
-
-```
-struct {
- opaque package<0..2^8-1>; // package identifier
- opaque checksum<32..2^8-1>; // artifact hash that used the log's hash func
-} ChecksumV1;
-```
-
-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.
-
-### 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 {
- LogID log_id; // defined in RFC 6962
- opaque message<0..2^16-1> // debug string that is only meant for the log
- opaque signature; // computed by the log over the StItem in question
-} SignedDebugInfoV1;
-```
-## 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).
-
-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: a `DigitallySigned` object as defined in RFC 5246,
-[§4.7](https://tools.ietf.org/html/rfc5246#section-4.7), that covers this item.
-- certificate: base-64 encoded X.509 certificate that is vouched for by a trust
-anchor and which produced the above signature.
-
-Output:
-- sdi: 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:
-- entries: an array of objects, each consisting of
- - leaf: `StItem` that corresponds to the leaf's type.
- - signature: `DigitallySigned` object that covers the retrieved item.
- - chain: an array of base-64 encoded certificates, where the first
- corresponds to the signing certificate and the final one a trust anchor.
-
-The signature and chain can be viewed as a leaf's appendix, i.e., something that
-is stored by the log but not part of the leaf itself.
-
-### get-anchors
-```
-GET https://<base url>/st/v1/get-anchors
-```
-
-No input.
-
-Output:
-- certificates: an array of base-64 encoded trust anchors 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 thee 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:
-- inclusion: 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:
-- consistency: 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:
-- sth: an `StItem` of type `signed_tree_head_v1`, which corresponds to the most
-recently known STH, which corresponds to the most recently known STH.