be explicit with key type; define struct message, for tree_leaf

Specify who's verification key -- log, witness or submitter.

Move shard_hint and checksum in tree_leaf into its own struct, for a
more explicit definition of what to be signed.

1 files changed, 34 insertions, 25 deletions

diff --git a/doc/api.md b/doc/api.md
index 2d54001..0fa445a 100644
--- a/doc/api.md
+++ b/doc/api.md
@@ -87,14 +87,18 @@ is backdated or future-dated more than 12 hours.
 #### Merkle tree leaf
 The log supports a single leaf type.  It contains a shard hint, a checksum over whatever the submitter wants to log a checksum for,
 a signature that the submitter computed over the shard hint and the checksum, and a hash of the
-public verification key that can be used to verify the signature.
+submitter's public verification key, that can be used to verify the signature.
 
 ```
+struct message {
+    u64 shard_hint;
+    u8 checksum[32];
+};
+
 struct tree_leaf {
-	u64 shard_hint;
-	u8 checksum[32];
-    u8 signature[32];
-	u8 key_hash[32];
+    struct message;
+    u8 signature_over_message[32];
+    u8 key_hash[32];
 }
 ```
 
@@ -116,17 +120,20 @@ Without a shard hint, the good Samaritan could log all leaves from an earlier
 shard into a newer one.  Not only would that defeat the purpose of sharding, but
 it would also become a potential denial-of-service vector.
 
-The signed message is composed of the selected shard hint and the submitter's
-checksum.  It must be possible to verify the signature using the
-submitter's public verification key.
+The signed message is composed of the chosen `shard_hint` and the
+submitter's `checksum`.  It must be possible to verify
+`signature_over_message` using the submitter's public verification
+key.
 
-Note that the way `shard_hint` and `chekcsum` are serialized with
+Note that the way `shard_hint` and `checksum` are serialized with
 regards to signing differs from how they're being transmitted to the
 log.
 
-A key hash is included in the leaf so that the leaf can be attributed to the
-submitter.  A hash, rather than the full public verification key, is used to motivate
-the verifier to locate the appropriate key and make an explicit trust decision.
+A `key_hash` of the key used for signing `message` is included in
+`tree_leaf` so that the leaf can be attributed to the submitter.  A
+hash, rather than the full public key, is used to motivate the
+verifier to locate the appropriate key and make an explicit trust
+decision.
 
 ## Public endpoints
 Every log has a base URL that identifies it uniquely.  The only constraint is
@@ -155,8 +162,8 @@ Output on success:
 - "tree_size": `tree_head.tree_size` ASCII-encoded decimal number.
 - "root_hash": `tree_head.root_hash` hex-encoded.
 - "signature": hex-encoded Ed25519 signature over `tree_head` serialzed as described in section `Merkle tree head`.
-- "key_hash": a hash of the public verification key that can be used to verify
-the signature.  The key is encoded as defined in [RFC 8032, section 5.1.2](https://tools.ietf.org/html/rfc8032#section-5.1.2), and then
+- "key_hash": a hash of the public verification key (belonging to either the log or to one of its witnesses), which can be used to verify
+the most recent `signature`.  The key is encoded as defined in [RFC 8032, section 5.1.2](https://tools.ietf.org/html/rfc8032#section-5.1.2), and then
 hashed using SHA256.  The hash value is hex-encoded.
 
 The "signature" and "key_hash" fields may repeat. The first signature
@@ -179,16 +186,16 @@ Output on success:
 - "tree_size": `tree_head.tree_size` ASCII-encoded decimal number.
 - "root_hash": `tree_head.root_hash` hex-encoded.
 - "signature": hex-encoded Ed25519 signature over `tree_head` serialzed as described in section `Merkle tree head`.
-- "key_hash": a hash of the public verification key that can be used to verify
-the signature.  The key is encoded as defined in [RFC 8032, section 5.1.2](https://tools.ietf.org/html/rfc8032#section-5.1.2), and then
+- "key_hash": a hash of the log's public verification key, which can be used to verify
+`signature`.  The key is encoded as defined in [RFC 8032, section 5.1.2](https://tools.ietf.org/html/rfc8032#section-5.1.2), and then
 hashed using SHA256.  The hash value is hex-encoded.
 
 There is exactly one `signature` and one `key_hash` field. The
-`key_hash` refers to the log's signing key.
+`key_hash` refers to the log's public verification key.
 
 
 ### get-tree-head-latest
-Returns the latest tree head, signed only by the log. Used for debug.
+Returns the latest tree head, signed only by the log. Used for debugging purposes.
 
 ```
 GET <base url>/st/v0/get-tree-head-latest
@@ -202,12 +209,13 @@ Output on success:
 - "tree_size": `tree_head.tree_size` ASCII-encoded decimal number.
 - "root_hash": `tree_head.root_hash` hex-encoded.
 - "signature": hex-encoded Ed25519 signature over `tree_head` serialzed as described in section `Merkle tree head`.
-- "key_hash": a hash of the public verification key that can be used to verify
-the signature.  The key is encoded as defined in [RFC 8032, section 5.1.2](https://tools.ietf.org/html/rfc8032#section-5.1.2), and then
-hashed using SHA256.  The hash value is hex-encoded.
+- "key_hash": a hash of the log's public verification key that can be
+used to verify `signature`.  The key is encoded as defined in
+[RFC 8032, section 5.1.2](https://tools.ietf.org/html/rfc8032#section-5.1.2),
+and then hashed using SHA256.  The hash value is hex-encoded.
 
 There is exactly one `signature` and one `key_hash` field. The
-`key_hash` refers to the log's signing key.
+`key_hash` refers to the log's public verification key.
 
 
 ### get-proof-by-hash
@@ -317,9 +325,10 @@ POST <base url>/st/v0/add-cosignature
 Input:
 - "signature": an Ed25519 signature over `tree_head`.  The result is
 hex-encoded.
-- "key_hash": a hash of the public verification key that can be used to verify
-the signature.  The public verification key is serialized as in RFC 8032, then
-hashed using SHA256.  The result is hex-encoded.
+- "key_hash": a hash of the witness' public verification key that can be used
+to verify the signature.  The key is encoded as defined in [RFC 8032,
+section 5.1.2](https://tools.ietf.org/html/rfc8032#section-5.1.2), and
+then hashed using SHA256.  The hash value is hex-encoded.
 
 Output on success:
 - None