Commit 321e11ce authored by Niels Möller's avatar Niels Möller
Browse files

Review feedback

parent 6ff0b8d0
......@@ -294,16 +294,19 @@ Output on success:
A submission will not be accepted if `signature` is invalid.
Processing of add-leaf request is subject to rate-limit, and public
logs are expected to require an [authentication token](#rate-limiting)
passed in HTTP headers. A submission may not be accepted if the
submitter has exceeded its rate limit. A rate limit should only be
applied on success.
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.
Processing of the add-leaf request may be subject to rate limiting.
When a public log is configured to allows submissions from anyone, it
is expected to require an [authentication token](#Rate-limiting)
passed in HTTP headers. A submission may be refused if the submitter
has exceeded its rate limit. By above, adding a leaf typically
involves multiple add-leaf requests. The rate limit is not applied to
the number of requests, but rather to the number of unique leaves
added.
Example:
```
$ echo "message=315f5bdb76d078c43b8ac0064e4a0164612b1fce77c869345bfc94c75894edd3
......@@ -359,13 +362,13 @@ Ed25519 as signature scheme. SHA256 as hash function.
- **Public key**: public key that is used to verify tree head
cosignatures.
## 5 - Domain-based rate-limit mechanism {rate-limiting}
## 5 - Rate limiting
Domain-based rate limiting is an optional feature of the protocol, but
it is expected that all public logs will require it. Using this
mechanism is required only for the `add-leaf` request, and it is
intended to limit the rate at which leaves are added to the Merkle
tree, by submitter domain.
it is expected that a public logs that allows submissions from anyone
will require it. Using this mechanism is required only for the
`add-leaf` request, and it is intended to limit the rate at which
leaves are added to the Merkle tree, by submitter domain.
### 5.1 Setup
......@@ -380,12 +383,13 @@ must do a one-time setup, with these three steps.
e.g., `_sigsum_v0.foocorp.example.com`. The contents of the TXT
record is the hex-encoded public key.
3. Use the private key to sign the target log's key hash. More
precisely, hash the log's public ed25519 key using SHA256, use this
hash value as the message `M` in SSH's signing format. The hash
algorithm string must be "sha256". The reserved string must be
empty. The namespace field must be set to
"submit-token:v0@sigsum.org".
3. Use the private key to sign the target log's public key. More
precisely, use the log's public ed25519 key (formatted according to
[RFC 8032, section
5.1.2](https://tools.ietf.org/html/rfc8032#section-5.1.2)), and use
as message `M` in SSH's signing format. The hash algorithm string
must be "sha256". The reserved string must be empty. The namespace
field must be set to "submit-token:v0@sigsum.org".
The signature will act as the submit token. Since it's a signature on
the log's key hash, it is not valid for submission to any other log.
......@@ -431,8 +435,7 @@ leaves are added to the Merkle tree.
Similarly to HTTP authorization using basic auth or cookies, the
submitter must use an encrypted channel for the requests that include
sigsum's submit token. I.e., submission to the log must use HTTPS, not
plain HTTP.
sigsum's submit token. E.g., use HTTPS rather than plain HTTP.
The fixed token implies that there is no way to prevent replay
attacks. There are a couple of reasons that this is ok for this
......
......@@ -187,8 +187,7 @@ A sigsum log maintains a public append-only Merkle tree. Independent witnesses
verify that this tree is fresh and append-only before cosigning it to achieve a
distributed form of trust. A tree leaf contains three fields:
- **checksum**: a cryptographic hash that commits to some data.
- **signature**: a digital signature that is computed by a signer for the
selected shard hint and checksum.
- **signature**: a digital signature on that checksum, computed by a signer.
- **key_hash**: a cryptographic hash of the signer's public key that can
be used to verify the signature.
......@@ -221,15 +220,15 @@ 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 message, signature, public key and domain
hint as ASCII key-value pairs. The log uses the submitted message to
compute the signer's checksum, and verifies the signature. The public
key is then hashed to construct the Merkle tree leaf as described in
Section 3.1.
The signer submits their message, signature and public key as ASCII
key-value pairs. The log uses the submitted message to compute the
signer's checksum, and verifies the signature. The public key is then
hashed to construct the Merkle tree leaf as described in Section 3.1.
Before a new leaf is accepter, the log also verifies that the
secondary rate-limit key is present in DNS, and uses it check validity
of the submit token, and apply domain-based rate limiting.
Before a new leaf is accepted, the log may verify the submitter's
domain and submit token and apply a domain-based rate limit. To verify
the token, the log looks up the submitter's public rate-limit key in
DNS, and uses it check validity of the submit token.
A sigsum log will
[try](https://git.sigsum.org/sigsum/tree/doc/proposals/2022-01-add-leaf-endpoint)
......@@ -351,7 +350,7 @@ data mining while at the same time making the overall protocol less heavy.
#### 4.3 - What is the point of the submit token?
The submit token, and associated rate limit public key registered in
DNS, helpd log operators combat spam. By verifying that every signer
DNS, help log operators combat spam. By verifying that every signer
controls a domain name that is aware of their public key, rate limits
can be applied per registered domain (e.g, using
<https://publicsuffix.org/list/>). You would need a large number of
......@@ -367,14 +366,11 @@ Using DNS as an anti-spam mechanism is not a perfect solution. It is however
better than not having any anti-spam mechanism at all. We picked DNS because
many signers have a domain. A single domain name is also relatively cheap.
A signer's domain hint is not part of the logged leaf because key management is
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 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)
The public rate-limit key is attached as a TXT record on a domain with
the left-most label set `_sigsum_v0`, to 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.
We are considering if additional anti-spam mechanisms should be supported in v1.
......@@ -429,7 +425,7 @@ A list of some debated topics:
while only giving _lower latency_; not _low latency_. The "slow" cosigned
tree head endpoint could also be implemented to just rotate a bit faster.
- Should there be support for any alternative rate-limiting mechanism? A
domain hint could be viewed as a subset of several possible _ownership hints_.
domain + submit token hint could be viewed as a subset of several possible _ownership hints_.
- Should there be any IANA registration for the future `_sigsum_v1` DNS label?
[checkpoint format]: https://github.com/google/trillian-examples/blob/master/formats/log/README.md
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment