renamed doc folder

1 files changed, 205 insertions, 0 deletions

diff --git a/markup/api.md b/markup/api.md
new file mode 100644
index 0000000..ebd666d
--- /dev/null
+++ b/markup/api.md
@@ -0,0 +1,205 @@
+# 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.