aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorRasmus Dahlberg <rasmus@mullvad.net>2021-12-04 19:42:47 +0100
committerRasmus Dahlberg <rasmus@mullvad.net>2021-12-04 19:42:47 +0100
commit4ea13eb1ceee1610d9044965c1a90b6d5443518b (patch)
tree885b871670028c1163478dfb8a4b4b3025e3c2f2 /doc
parent0559211c99cef8c7aec24eaad39eabaac72c4fe2 (diff)
added proposal into main documentation
Sigsum logs should now use open-ended shard intervals.
Diffstat (limited to 'doc')
-rw-r--r--doc/api.md4
-rw-r--r--doc/design.md22
-rw-r--r--doc/proposals/2021-11-open-ended-shard-interval.md2
3 files changed, 16 insertions, 12 deletions
diff --git a/doc/api.md b/doc/api.md
index e6b0c41..bf429d8 100644
--- a/doc/api.md
+++ b/doc/api.md
@@ -380,8 +380,8 @@ Ed25519 as signature scheme. SHA256 as hash function.
prefix to be used to construct a version 0 specific endpoint.
- **Shard interval start**: the earliest time at which logging
requests are accepted as the number of seconds since the UNIX epoch.
-- **Shard interval end**: The latest time at which logging
- requests are accepted as the number of seconds since the UNIX epoch.
+- **Shard interval end**: determined by policy. A log that is active should
+ use the number of seconds since the UNIX epoch as a dynamic shard end.
### 4.2 - Witness
- **Public key**: public verification key that is used to verify tree head
diff --git a/doc/design.md b/doc/design.md
index 4c24827..3a1fbd5 100644
--- a/doc/design.md
+++ b/doc/design.md
@@ -352,20 +352,24 @@ We are considering if additional anti-spam mechanisms should be supported.
#### 4.3 - What is the point of having a shard hint?
Unlike TLS certificates which already have validity ranges, a checksum does not
carry any such information. Therefore, we require that the signer selects a
-shard hint. The selected shard hint must be within a log's shard interval. A
-shard interval is defined by a start time and an end time. Both ends of the
-shard interval are inclusive and expressed as the number of seconds since the
-UNIX epoch (January 1, 1970 00:00 UTC).
+shard hint. The selected shard hint must be within a log's shard interval.
+That shard interval is open-ended, meaning there is a fixed start time and a
+_policy-defined_ end time that the operator may increase but not decrease
+ [\[OESI\]](https://git.sigsum.org/sigsum/tree/doc/proposals/2021-11-open-ended-shard-interval.md).
+A log's shard start is inclusive and expressed expressed as the number of
+seconds since the UNIX epoch (January 1, 1970 00:00 UTC). A log that is still
+active should use the number of seconds since the UNIX epoch as its shard end.
Without sharding, a good Samaritan can add all leaves from an old log into a
newer one that just started its operations. This makes log operations
-unsustainable in the long run because log sizes grow indefinitely.
-
-Such re-logging also comes at the risk of activating someone else's rate limits.
+unsustainable in the long run because log sizes grow indefinitely. Such
+re-logging also comes at the risk of activating someone else's rate limits.
Note that a signer's shard hint is not a verified timestamp. We recommend to
-set it as large as possible. If a verified timestamp is needed to reason about
-the time of logging, you may use a cosigned tree head instead
+set it to the maximum value that all active logs accept as valid
+ [\[OESI\]](https://git.sigsum.org/sigsum/tree/doc/proposals/2021-11-open-ended-shard-interval.md).
+If a verified timestamp is needed to reason about the time of logging, you may
+use a cosigned tree head instead
[\[TS\]](https://git.sigsum.org/sigsum/commit/?id=fef460586e847e378a197381ef1ae3a64e6ea38b).
A log operator that shuts down a completed shard will not affect verifiers. In
diff --git a/doc/proposals/2021-11-open-ended-shard-interval.md b/doc/proposals/2021-11-open-ended-shard-interval.md
index b9de1bc..dee127e 100644
--- a/doc/proposals/2021-11-open-ended-shard-interval.md
+++ b/doc/proposals/2021-11-open-ended-shard-interval.md
@@ -1,6 +1,6 @@
**Title**: Open-ended shard interval </br>
**Date**: 2021-12-04 </br>
-**State**: To be implemented </br>
+**State**: Implemented </br>
# Summary
We would like to remove `shard_end` from a log's static metadata, and instead