From 0d0edb3421232ac32f6f426089b46244cc838545 Mon Sep 17 00:00:00 2001 From: Rasmus Dahlberg Date: Mon, 31 Jan 2022 17:22:45 +0100 Subject: documented the decided add-leaf endpoint proposal Refer to doc/proposals/2022-01-add-leaf-endpoint for details. --- doc/api.md | 7 ++++--- doc/design.md | 11 ++++++----- 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 -- cgit v1.2.3