updated api documentation

Specified additional details and simplified http output formatting.

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.