aboutsummaryrefslogtreecommitdiff
path: root/markup/api.md
diff options
context:
space:
mode:
authorRasmus Dahlberg <rasmus.dahlberg@kau.se>2020-10-29 16:39:42 +0100
committerRasmus Dahlberg <rasmus.dahlberg@kau.se>2020-10-29 16:39:42 +0100
commit7d186fff4f0d510581207b0603ea1c946286d7ae (patch)
treefb21c39682578d4d438a89ded0da6e1ea11cf9d3 /markup/api.md
parente0c6bca892b25ca06e1a1444f182c684574bdb4b (diff)
updated api documentation
Specified additional details and simplified http output formatting.
Diffstat (limited to 'markup/api.md')
-rw-r--r--markup/api.md73
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.