aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorLinus Nordberg <linus@nordberg.se>2022-08-06 20:59:24 +0200
committerLinus Nordberg <linus@nordberg.se>2022-08-06 20:59:24 +0200
commit63abe7e03795797d0db7d00bc33ddf6e57d9b5b3 (patch)
treec66cc2dbfdbb60fa3ee66d78c1121bd88cb5059f /doc
parentd7a8bc59af07ac539ee809823010226fe4f036b9 (diff)
parentb3ca97dbd0b725b3fd0d5616d0d94984631d33a2 (diff)
Merge branch 'main' of git.sigsum.org:sigsum
Diffstat (limited to 'doc')
-rw-r--r--doc/proposals/2022-07-api-renaming.md23
-rw-r--r--doc/proposals/2022-07-endpoint-url.md12
-rw-r--r--doc/proposals/2022-07-permit-lack-of-witness-cosignatures.md13
-rw-r--r--doc/proposals/2022-07-replace-domain-hint-with-rate-limit.md33
4 files changed, 81 insertions, 0 deletions
diff --git a/doc/proposals/2022-07-api-renaming.md b/doc/proposals/2022-07-api-renaming.md
new file mode 100644
index 0000000..dafa98c
--- /dev/null
+++ b/doc/proposals/2022-07-api-renaming.md
@@ -0,0 +1,23 @@
+# Proposal
+
+Rename the following endpoints:
+
+ - s/get-tree-head-to-cosign/get-untrusted-tree-head/
+ - s/get-tree-head-cosigned/get-tree-head/
+ - s/get-leaves/get-entries/
+ - s/add-leaf/add-entry/
+
+Rename the following ASCII keys:
+
+ - s/start_size/start_index/
+ - s/end_size/end_index/
+
+(Reminder: specify zero-based index.)
+
+# Motivation
+
+Improve readability of api.md, especially for those that skim it quickly. For
+example, "untrusted-tree-head" is a very strong signal for what you don't want,
+and it should be easier to relate to the term "entry" rather than a "leaf".
+
+The renamed ASCII keys better reflect the text that describes them.
diff --git a/doc/proposals/2022-07-endpoint-url.md b/doc/proposals/2022-07-endpoint-url.md
new file mode 100644
index 0000000..024c3b8
--- /dev/null
+++ b/doc/proposals/2022-07-endpoint-url.md
@@ -0,0 +1,12 @@
+# Proposal
+
+Drop the criteria that the constant "sigsum/v0" must be after a log's URL and
+before a named endpoint. This does not change the definition of a log URL, but
+does mean "<endpoint>" is appended to it rather than "sigsum/v0/<endpoint>".
+
+# Motivation
+
+ - Protocol and version does not change for an active log and it should already
+ be communicated to clients via policy.
+ - A log operator that wants to specify protocol and/or version as part of
+ their URL can still do so, either in their domain name or the optional path.
diff --git a/doc/proposals/2022-07-permit-lack-of-witness-cosignatures.md b/doc/proposals/2022-07-permit-lack-of-witness-cosignatures.md
new file mode 100644
index 0000000..c0ac549
--- /dev/null
+++ b/doc/proposals/2022-07-permit-lack-of-witness-cosignatures.md
@@ -0,0 +1,13 @@
+# Proposal
+
+In api.md, ยง3.2:
+
+ - Permit that "key_hash" and "cosignature" are omitted by the log when there
+ are no witness cosignatures to set in the response.
+
+# Motivation
+
+It should be possible to return success on the get-tree-head-cosigned endpoint
+even if no witness provided a co-signature for the current to-cosign tree head.
+
+This change makes it possible to return 200 OK without witnesses.
diff --git a/doc/proposals/2022-07-replace-domain-hint-with-rate-limit.md b/doc/proposals/2022-07-replace-domain-hint-with-rate-limit.md
new file mode 100644
index 0000000..c1570c9
--- /dev/null
+++ b/doc/proposals/2022-07-replace-domain-hint-with-rate-limit.md
@@ -0,0 +1,33 @@
+# Proposal
+
+Replace the "domain_hint" key in the input to the add-leaf endpoint with
+"rate-limit". The value associated with the "rate-limit" key is on the format:
+
+ method:data
+
+where the defined methods are:
+
+ - dns: the exact same semantics as today's domain hint
+ - token: a shared secret that is negotiated between submitter and the log
+ operator out-of-band
+
+Example of a rate-limit line using DNS:
+
+ rate_limit=dns:_sigsum_v0.example.org
+
+Example of a rate-limit line using token:
+
+ rate_limit=token:xxxxxxxxxxxxxxxxxxxxxx
+
+The "rate_limt" key must not be repeated.
+
+The "rate_limit" key may be omitted. It is then up to the log server to accept
+or reject the user's requests.
+
+# Motivation
+
+There are more ways to establish something to rate-limit on than domain hints.
+The name "domain_hint" is also not descrptive; it makes understanding harder.
+
+It is also plausible that a log operator wants to run without a rate limit in
+some environments. The above change permits this as well.