aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorRasmus Dahlberg <rasmus@mullvad.net>2022-01-31 17:22:45 +0100
committerRasmus Dahlberg <rasmus@mullvad.net>2022-01-31 17:22:45 +0100
commit0d0edb3421232ac32f6f426089b46244cc838545 (patch)
tree1dcc66f102a264f006c091f91e5145fa62325695 /doc
parent9f49af2ad70764510bb34322157209f56095260f (diff)
documented the decided add-leaf endpoint proposal
Refer to doc/proposals/2022-01-add-leaf-endpoint for details.
Diffstat (limited to 'doc')
-rw-r--r--doc/api.md7
-rw-r--r--doc/design.md11
2 files changed, 10 insertions, 8 deletions
diff --git a/doc/api.md b/doc/api.md
index abe93b1..c28c254 100644
--- a/doc/api.md
+++ b/doc/api.md
@@ -334,10 +334,11 @@ Output on success:
A submission will not be accepted if `signature` is invalid or if the retrieved
key hash does not match the specified verification key. A submission may also
not be accepted if the second-level domain name exceeded its rate limit.
+A rate limit should only be charged for the specified domain hint on success.
-Public logging must not be assumed to have happened until an inclusion proof is
-available. An inclusion proof should not be relied upon unless it leads up to a
-trustworthy tree head. Witness cosigning makes a tree head trustworthy.
+HTTP status 200 OK must not be returned unless the log has sequenced its Merkle
+tree so that the next signed tree head merged the added leaf. A submitter
+should (re)send their add-leaf request until observing HTTP status 200 OK.
Example:
```
diff --git a/doc/design.md b/doc/design.md
index 85e0ea3..1173501 100644
--- a/doc/design.md
+++ b/doc/design.md
@@ -234,11 +234,12 @@ verification key is present in DNS and uses it to check that the signature is
valid, then hashes it to construct the Merkle tree leaf as described in
Section 3.1.
-When a submitted logging request is accepted, the log _tries_ to incorporate the
-submitted leaf into its Merkle tree. There are however no _promises of public
-logging_ as in Certificate Transparency. Therefore, sigsum logs do not provide
-low latency---the signer has to wait for an inclusion proof and a cosigned tree
-head.
+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
+accepted their request, after which it can be verified using an inclusion proof.
#### 3.2.3 - Wait for witness cosigning
Sigsum logs periodically freeze the most current tree head, typically every five