diff options
| -rw-r--r-- | markup/api.md | 73 |
1 files changed, 43 insertions, 30 deletions
diff --git a/markup/api.md b/markup/api.md index 2cf85c5..60658b5 100644 --- a/markup/api.md +++ b/markup/api.md @@ -18,11 +18,19 @@ 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 +- Log identifier: `SHA256(public key)`, see RFC 6962 +[§3.2](https://tools.ietf.org/html/rfc6962#section-3.2) +- Public key: DER encoding of the key represented as `SubjectPublicKeyInfo` +- Hash algorithm: used to maintain the log's Merkle tree, e.g., SHA256 +- Supported signature algorithms: a list of signature algorithms 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 algorithm: the signature algorithm that the log uses to sign +tree heads and debug info statements. +- Maximum chain length: e.g., three means that we would reject submissions that +were signed by a certificate chain of length four. - 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 @@ -70,27 +78,22 @@ struct { } 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 + opaque package<1..2^8-1>; // package identifier + opaque checksum<1..64>; // hash of some artifact } ChecksumV1; ``` -For example, the checksum type could be used by Firefox to [enforce public -binary logging before accepting a new software +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. @@ -105,11 +108,18 @@ 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 + LogID log_id; // defined in RFC 6962, basically SHA256(pub key) + 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). + ## 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 @@ -126,14 +136,16 @@ 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. +- signature_algorithm: decimal, possible values are defined in RFC 8446 +[§4.2.3](https://tools.ietf.org/html/rfc8446#section-4.2.3). The serialized +signature encoding follows from this. +- signature: covers the submitted 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. +- an `StItem` structure of type `signed_debug_info_v1` that covers the added +item. ### get-entries ``` @@ -145,9 +157,10 @@ Input: - end: 0-based index of last entry to retrieve in decimal. Output: -- entries: an array of objects, each consisting of +- an array of objects, each consisting of - leaf: `StItem` that corresponds to the leaf's type. - - signature: `DigitallySigned` object that covers the retrieved item. + - signature: signature that covers the retrieved item using the log's + configured signature algorithm. - chain: an array of base-64 encoded certificates, where the first corresponds to the signing certificate and the final one a trust anchor. @@ -162,7 +175,7 @@ GET https://<base url>/st/v1/get-anchors No input. Output: -- certificates: an array of base-64 encoded trust anchors that the log accept. +- an array of base-64 encoded trust anchors that the log accept. ### get-proof-by-hash ``` @@ -171,14 +184,14 @@ 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. +- 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: -- inclusion_proof: an `StItem` of type `inclusion_proof_v1`. Note that this -structure includes both the leaf index and an audit path for the tree size. +- 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 ``` @@ -190,7 +203,7 @@ Input: - second: the `tree_size` of the newer tree in decimal. Output: -- consistency: an `StItem` of type `consistency_proof_v1` that corresponds to +- an `StItem` of type `consistency_proof_v1` that corresponds to the requested tree sizes. ### get-sth @@ -201,5 +214,5 @@ 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. +- an `StItem` of type `signed_tree_head_v1`, which corresponds to the most +recently known STH. |