aboutsummaryrefslogtreecommitdiff
path: root/doc/api.md
diff options
context:
space:
mode:
authorRasmus Dahlberg <rasmus.dahlberg@kau.se>2020-10-15 20:11:40 +0200
committerRasmus Dahlberg <rasmus.dahlberg@kau.se>2020-10-15 20:11:40 +0200
commit895dac9c802702fdd1ee3bb3efb5a9418274b360 (patch)
tree958074e73d1fb82b4a5e63a982735791deb7551e /doc/api.md
parent6ca8786bda9c3db7e7ed8690b9aeb3d61bab3766 (diff)
added public endpoints
Diffstat (limited to 'doc/api.md')
-rw-r--r--doc/api.md103
1 files changed, 94 insertions, 9 deletions
diff --git a/doc/api.md b/doc/api.md
index 3308205..591a8a0 100644
--- a/doc/api.md
+++ b/doc/api.md
@@ -81,8 +81,8 @@ general-purpose checksums. For now we only define the latter.
#### Checksum
A checksum entry contains a timestamp that corresponds to `UTC.now()`, a package
identifier such as `foobar-1.2.3`, and an artifact hash that uses the log's
-configured hash function. An entry must be signed by the submitter to be
-accepted by the log, and the resulting signature is part of the leaf's Appendix.
+configured hash function.
+
```
struct {
uint64 timestamp; // format defined by RFC 6962/bis, added by submitter
@@ -101,6 +101,10 @@ Note that the entry timestamp allows anyone to derive rough statistics on the
time between submission and merge into the log's Merkle tree. Base such a diff
on the first STH (timestamp) that incorporated a given entry.
+TODO: move timestamp outside of the (signed) structure that is submitted? It is
+less error-prone if the log does the time-stamping at its own discretion. E.g.,
+a `leaf_v1` that then switches onto a `checksum_v1`?
+
### 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
@@ -113,18 +117,99 @@ 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 LeafChecksumV1
+ opaque signature; // computed by the log over the entire Item
} SignedDebugInfoV1;
```
## Public endpoints
-Clients talk to the log with HTTPS GET/POST requests as in RFC 6962,
-[§4](https://tools.ietf.org/html/rfc6962#section-4). Namely, POST parameters
-are JSON objects, GET parameters are URL encoded, and binary data is first
-expressed as base-64.
+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 `Item` that corresponds to a valid leaf type. Only
+`leaf_checksum_v1` at this time.
+- signature: a `DigitallySigned` object as defined in RFC 6962,
+[§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 `Item` structure of type `signed_debug_info_v1` that covers the added
+item.
-### add-checksum
### get-entries
-### get-trust-anchors
+```
+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: `Item` 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 `Item` 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 `Item` 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 `Item` of type `signed_tree_head_v1`, which corresponds to the most
+recently known STH, which corresponds to the most recently known STH.