minor wording tweaks and fixes

The majority of this commit is from ln5, thank you.

2 files changed, 37 insertions, 33 deletions

diff --git a/doc/api.md b/doc/api.md
index 05852b1..1f3f07b 100644
--- a/doc/api.md
+++ b/doc/api.md
@@ -32,9 +32,9 @@ Figure 1 of our design document gives an intuition of all involved parties.
 ### 2.1 - Cryptography
 Logs use the same Merkle tree hash strategy as
 	[RFC 6962,§2](https://tools.ietf.org/html/rfc6962#section-2).
-Any mention of hash functions or digital signature schemes refers to
+Any mentions of hash functions or digital signature schemes refer to
 	[SHA256](https://csrc.nist.gov/csrc/media/publications/fips/180/4/final/documents/fips180-4-draft-aug2014.pdf)
-as well as
+and
 	[Ed25519](https://tools.ietf.org/html/rfc8032).
 The exact
 	[signature format](https://github.com/openssh/openssh-portable/blob/master/PROTOCOL.sshsig)
@@ -78,7 +78,7 @@ to prove to a verifier that public logging happened within some interval
 
 #### 2.3.2 - (Co)signed tree head
 Logs and witnesses perform (co)signing operations by treating the serialized
-tree head as the message `M` in SSH's 
+tree head as the message `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.
 The namespace field must be set to `tree_head:v0:<key-hash>@sigsum.org`, where
@@ -91,7 +91,7 @@ prevents a possible
 in multi-log ecosystems.
 
 A witness must not cosign a tree head if it is inconsistent with prior history
-or if the timestamp is older than 5 minutes.  This means that a witness plays
+or if the timestamp is older than five (5) minutes.  This means that a witness plays
 	[two abstract roles](https://git.sigsum.org/sigsum/tree/archive/2021-08-31-checkpoint-timestamp-continued#n84):
 Verifier("append-only") and Verifier("freshness").
 
@@ -111,12 +111,12 @@ struct tree_leaf {
 }
 ```
 
-`checksum` is a hashed preimage.  The signer selects a 32-byte preimage which
-represents some data.  It is recommended to set this preimage to `H(data)`, in
+`checksum` is a the 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 will be `H(H(data))`.
 
 `signature` is computed by treating the above preimage as the message `M`
-in SSH's 
+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.
 The namespace field must be set to `tree_leaf:v0:<shard_hint>@sigsum.org`, where
@@ -180,9 +180,10 @@ Output on success:
 - `root_hash`: `tree_head.root_hash`, hex-encoded.
 - `signature`: log signature for the above tree head, hex-encoded.
 
-### 3.2 - get-tree-head-cosigned
-Returns a cosigned tree head that corresponds to the previous to-cosign tree
-head.  The list of cosignatures is thus fixed.  Used by Signers and Monitors.
+### 3.2 - get-tree-head-quickly
+Returns a tree head that has been cosigned by at least one witness.  The list of
+cosignatures is updated every time a new cosignature gets added.  This
+endpoint is used by Signers that want _enough cosignatures as fast as possible_.
 
 ```
 GET <base url>/sigsum/v0/get-tree-head-cosigned
@@ -306,7 +307,7 @@ Output on success:
 A submission will not be accepted if `signature` or `shard_hint` is invalid.
 The retrieved key hash must also match the specified verification key.
 
-A submission may not be accepted if the second-level domain name exceeded its
+A submission may not be accepted if the second-level domain name has exceeded its
 rate limit.  A rate limit should only be charged for the specified domain hint
 on success.
 
diff --git a/doc/design.md b/doc/design.md
index 8a46fd2..a022ef8 100644
--- a/doc/design.md
+++ b/doc/design.md
@@ -91,8 +91,8 @@ from anyone at arbitrary rates can lead to abusive usage patterns.  We store as
 little metadata as possible to combat log poisoning.  We piggyback on DNS to
 combat log spam.  Sharding is also helpful to combat log spam in the long run.
 - **Built-in mechanisms that ensure a globally consistent log:** transparency
-logs rely on gossip protocols to detect forks.  We built a proactive gossip
-protocol directly into the log.  It is a variant of
+logs rely on gossip protocols to detect split-views.  We built a proactive
+gossip protocol directly into the log.  It is a variant of
 	[witness cosigning](https://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=7546521).
 - **No cryptographic agility**: the only supported signature schemes and hash
 functions are Ed25519 and SHA256.  Not having any cryptographic agility makes
@@ -209,15 +209,15 @@ independently of logs, and trust them explicitly.
 ### 3.2 - Usage pattern
 #### 3.2.1 - Prepare a request
 A signer computes the checksum to be logged.  For example, it could be a
-hash that commits to an executable binary or something else.
+hash that commits to an executable binary.
 
 The signer also selects a shard hint representing an abstract statement like
 "sigsum logs that are active during 2021".  Shard hints ensure that a log's
 leaves cannot be replayed in a non-overlapping shard.
 
-The signer signs the selected checksum using a sigsum-specific context that
-incorporates the above shard hint.  The exact signing format is compatible with
-`ssh-keygen -Y` when using Ed25519 and SHA256.
+The signer signs the checksum using a sigsum-specific context that
+incorporates the shard hint.  The exact signing format is compatible with
+`ssh-keygen -Y sign` when using Ed25519 and SHA256.
 
 The signer also has to do a one-time DNS setup.  As outlined below, logs will
 check that _some domain_ is aware of the signer's verification key.  This is
@@ -235,22 +235,25 @@ specified preimage 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
-in Section 3.1. 
+in Section 3.1.
 
 A sigsum log will
 	[try](https://git.sigsum.org/sigsum/tree/doc/proposals/2022-01-add-leaf-endpoint)
-to merge the submitted request, but without making any _promise of public
-logging_ as in Certificate Transparency with so-called SCTs.  Therefore, sigsum
-logs cannot guarantee low latency.  The signer needs to wait until the log
+to add the submitted request to its tree, a process known as merging.
+It will not issue _promises of public logging_ though, as done in Certificate Transparency
+with so-called SCTs. Therefore, sigsum
+logs cannot guarantee low latency.  The signer needs to wait until the log has
 accepted their request, after which it can be verified using an inclusion proof.
+A log must use a merge interval of five (5) minutes or shorter in order to
+fulfill the freshness criteria that witnesses require, see also 3.2.3.
 
 #### 3.2.3 - Wait for witness cosigning
-Cosigning witnesses poll the logs for tree heads to be cosigned once per minute,
-verifying that they are fresh (not back-dated more than five minutes) and
+Cosigning witnesses poll logs for tree heads to be cosigned at least once per minute,
+verifying that they are fresh (not older than five minutes) and
 append-only (no leaves were removed or modified) before doing any cosignature
 operations.  Tree heads are signed using the same signing format as tree leaves,
-expect that a different sigsum and log-specific context is used.  Cosignatures
-are posted back to the logs, making them available in one place.
+except that a different sigsum and log-specific context is being used.  Cosignatures
+are posted back to their respective logs, making them available in one place per log.
 
 The above means that it takes up to 5-10 minutes before a cosigned tree head is
 available.  Depending on implementation it may be as short as one minute.  The
@@ -261,7 +264,7 @@ logging by removing the need for reactive gossip-audit protocols
 	[G3,](https://petsymposium.org/2021/files/papers/issue2/popets-2021-0024.pdf)
 	[G4\]](https://docs.google.com/document/d/16G-Q7iN3kB46GSW5b-sfH5MO3nKSYyEb77YsM7TMZGE/edit).
 
-Use-cases like instant certificate issuance are not supported by design.
+Use-cases like instant certificate issuance are by design not supported.
 
 #### 3.2.4 - Distribution
 Once a signer has collected proofs of public logging the distribution phase can
@@ -339,17 +342,17 @@ about.  We are still open to remove, add, or change things.
 
 # 4.2 - Why use the OpenSSH signing format?
 Our main criteria for a signing format is that it can express signing contexts
-without any complex parsers.  A magic preamble would be good for overall hygiene
+without any complex parsers.  A magic preamble is good for overall hygiene
 as well.  We sketched on such a format using Trunnel.  We realized that by
 tweaking a few constants it would be compatible with SSH's signing format.  If
-it is possible to share a format with an existing reliable ecosystem, great!
+it is possible to share format with an existing reliable and widely deployed
+ecosystem, great!
 
 #### 4.3 - What is the point of submitting a checksum's preimage?
 Logging arbitrary bytes can poison a log with inappropriate content.  While a
-leaf is already light in Sigsum, a stream of leaves could be used.  By not
-allowing any checksum to be arbitrary because logs compute them, a malicious
-party would have to craft leaves that are computationally costly to encode more
-than a few bytes.
+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
@@ -377,7 +380,7 @@ more complex than that.  A separate project should focus on transparent key
 management.  Our work is about transparent _key-usage_.
 
 A signer's domain hint must have the left-most label set to `_sigsum_v0` to
-reduce the space of valid DNS TXT RRs that the log needs to permit queries for.
+reduce the space of valid DNS TXT RRs that a log needs to permit queries for.
 See further details in the
 	[proposal](https://git.sigsum.org/sigsum/tree/doc/proposals/2022-01-domain-hint)
 that added this criteria.