change 'preimage' to 'message'

Also, change 'checksum_hash' to 'checksum' to follow terminology in
code, and general language.

Issue: #40

2 files changed, 13 insertions, 12 deletions

diff --git a/doc/api.md b/doc/api.md
index 4cc8d10..e1912e4 100644
--- a/doc/api.md
+++ b/doc/api.md
@@ -102,7 +102,7 @@ signature, and key hash.
 ```
 struct tree_leaf {
     u64 shard_hint;
-    u8 checksum_hash[32];
+    u8 checksum[32];
     u8 signature[64];
     u8 key_hash[32];
 }
@@ -110,11 +110,12 @@ struct tree_leaf {
 
 `shard_hint` is a shard hint that matches the log's shard interval.
 
-`checksum_hash` is a hash of a preimage.  The signer submits a 32-byte preimage
-representing some data.  It is recommended to set this preimage to `H(data)`, in
-which case the checksum hash will be `H(H(data))`.
+`checksum` is a hash of the 32-byte message submitted by the signer.
+The message is meant to represent some data and it is recommended that
+the signer uses `H(data)` as the message, in which case `checksum`
+will be `H(H(data))`.
 
-`signature` is computed by treating the above preimage as the message `M`
+`signature` is computed by treating the above message as the `M`
 in SSH's
 	[signing format](https://github.com/openssh/openssh-portable/blob/master/PROTOCOL.sshsig).
 The hash algorithm string must be "SHA256".  The reserved string must be empty.
@@ -290,7 +291,7 @@ POST <log URL>/add-leaf
 Input:
 - `shard_hint`: shard hint to use as tree leaf context, ASCII-encoded decimal
   number.
-- `preimage`: the preimage used to compute `tree_leaf.statement.checksum`, hex-encoded.
+- `message`: the message used to compute `tree_leaf.statement.checksum`, hex-encoded.
 - `signature`: `tree_leaf.signature`, hex-encoded.
 - `verification_key`: public verification key that can be used to verify the
   above signature.  The key is encoded as defined in [RFC 8032, section 5.1.2](https://tools.ietf.org/html/rfc8032#section-5.1.2),
@@ -316,7 +317,7 @@ should (re)send their add-leaf request until observing HTTP status 200 OK.
 Example:
 ```
 $ echo "shard_hint=1633039200
-preimage=315f5bdb76d078c43b8ac0064e4a0164612b1fce77c869345bfc94c75894edd3
+message=315f5bdb76d078c43b8ac0064e4a0164612b1fce77c869345bfc94c75894edd3
 signature=0b849ed46b71b550d47ae320a8a37401129d71888edcc387b6a604b2fe1579e25479adb0edd1769f9b525d44b843ac0b3527ea12b8d9574676464b2ec6077401
 verification_key=46a6aaceb6feee9cb50c258123e573cc5a8aa09e5e51d1a56cace9bfd7c5569c
 domain_hint=_sigsum_v0.example.com" | curl --data-binary @- <log URL>/add-leaf
diff --git a/doc/design.md b/doc/design.md
index 908052e..e0b3b68 100644
--- a/doc/design.md
+++ b/doc/design.md
@@ -229,9 +229,9 @@ Sigsum logs implement an HTTP(S) API.  Input and output is human-readable and
 use a simple ASCII format.  A more complex parser like JSON is not needed
 since the data structures being exchanged are primitive enough.
 
-The signer submits their shard hint, checksum preimage, signature, public
+The signer submits their shard hint, message, signature, public
 verification key and domain hint as ASCII key-value pairs.  The log uses the
-specified preimage to compute the signer's checksum.  The log also verifies
+submitted message to compute the signer's checksum.  The log also verifies
 that the public verification key is present in DNS, and uses it to check that
 the signature is valid for the resulting checksum and shard hint.  The public
 verification key is then hashed to construct the Merkle tree leaf as described
@@ -342,14 +342,14 @@ tweaking a few constants it would be compatible with SSH's signing format.  If
 it is possible to share format with an existing reliable and widely deployed
 ecosystem, great!
 
-#### 4.2 - What is the point of submitting a checksum's preimage?
+#### 4.2 - What is the point of hashing the submitted message?
 Logging arbitrary bytes can poison a log with inappropriate content.  While a
 leaf is already light-weight in Sigsum, a stream of leaves could be made to carry more
 meaning. Disallowing checksums to contain arbitrary bytes, by having logs compute
 them, makes crafting of leaves with chosen content computationally costly.
 
-It is worth pointing out that the submitted preimage is limited to be a 32-byte
-buffer.  If the data to be transparently signed is `D`, the recommended preimage
+It is worth pointing out that the submitted message is limited to be a 32-byte
+buffer.  If the data to be transparently signed is `D`, the recommended message
 is `H(D)`.  The resulting checksum would be `H(H(D))`.  The log will not be in a
 position to observe the data `D`, thereby removing power in the form of trivial
 data mining while at the same time making the overall protocol less heavy.