aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/api.md53
-rw-r--r--doc/design.md2
2 files changed, 29 insertions, 26 deletions
diff --git a/doc/api.md b/doc/api.md
index bf429d8..172ea4f 100644
--- a/doc/api.md
+++ b/doc/api.md
@@ -9,16 +9,18 @@ This is a work-in-progress document that may be moved or modified.
## 1 - Overview
A log implements an HTTP(S) API for accepting requests and sending responses.
-- Requests without any input data use the HTTP GET method.
-- Requests with input data use the HTTP POST method.
-- Input data in requests and output data in responses are expressed as
+- Requests that retrieve data from the log uses the HTTP GET method.
+- Requests that add data to the log uses the HTTP POST method.
+- Input data in get-requests are expressed as ASCII values that are
+slash-delimited at the end of the respective endpoint URLs.
+- Input data in add-requests and output data in responses are expressed as
ASCII-encoded key/value pairs.
- Binary data is hex-encoded before being transmitted.
-The motivation for using a text based key/value format for request and
-response data is that it is simple to parse. Note that this format is
-not being used for the serialization of signed or logged data, where a
-more well defined and storage efficient format is desirable.
+The motivation for using text-based formats for request and response data is
+that it is simple to parse and understand for humans. These formats are not
+used for the serialization of signed and/or logged data, where a more well
+defined and storage efficient format is desirable.
A _signer_ should distribute log responses to their verifiers in any format that
suits them. The (de)serialization required for _verifiers_ is a small subset of
@@ -41,8 +43,8 @@ the overall attack surface: two hash functions must be collision
resistant instead of one.
### 2.2 - Serialization
-Log requests and responses are transmitted as ASCII-encoded key/value
-pairs, for a smaller dependency than an alternative parser like JSON.
+Log requests and responses are transmitted using simple ASCII encodings, for a
+smaller dependency than alternative parsers like JSON or percent-encoded URLs.
Some input and output data is binary: cryptographic hashes and signatures.
Binary data must be lower-case base16-encoded, also known as lower-case hex
encoding. Using hex as opposed to base64 is motivated by it being simpler,
@@ -144,8 +146,12 @@ appended: `/sigsum/v0/<endpoint>`. Example of a valid base URL:
https://log.example.com:4711/opossum/2021`.
```
-Input data (in requests) is POST:ed in the HTTP message body as line-terminated
-ASCII key/value pairs. In more detail, the key-value format is `Key=Value\n`.
+Input data in `get-*` requests are added at the end of an endpoint's
+URL. Values are delimited by a `/`. The order of values is defined by
+the respective endpoints. For an example, see Section 3.4.
+
+Input data in `add-*` requests is POST:ed in the HTTP message body as
+line-terminated ASCII key/value pairs. The key-value format is `Key=Value\n`.
Everything before the first equal-sign is considered a key.
Everything after the first equal sign and before the next new line character is
considered a value. Different keys may appear in any order. A key may be
@@ -157,7 +163,7 @@ blue=second value for blue key
```
Output data (in replies) is sent in the HTTP message body using the same
-key-value format as input data.
+key-value format as for `add-*` input data.
The HTTP status code is 200 OK to indicate success. A different HTTP
status code is used to indicate failure. A log must respond with a
@@ -232,14 +238,14 @@ success. The number of witness signatures and key hashes must match.
### 3.4 - get-inclusion-proof
```
-POST <base url>/sigsum/v0/get-inclusion-proof
+GET <base url>/sigsum/v0/get-inclusion-proof/<tree_size>/<leaf_hash>
```
Input:
-- `leaf_hash`: leaf hash identifying which `tree_leaf` the log should prove
- inclusion of, hex-encoded.
- `tree_size`: tree size of the tree head that the proof should be
based on, ASCII-encoded decimal number.
+- `leaf_hash`: leaf hash identifying which `tree_leaf` the log should prove
+ inclusion of, hex-encoded.
Output on success:
- `leaf_index`: zero-based index of the leaf that the proof is based on,
@@ -254,19 +260,18 @@ follow from the hash strategy, see RFC 6962.
Example:
```
-$ echo "leaf_hash=241fd4538d0a35c2d0394e4710ea9e6916854d08f62602fb03b55221dcdac90f
-tree_size=4711" | curl --data-binary @- <base url>/sigsum/v0/get-inclusion-proof
+$ curl <base url>/sigsum/v0/get-inclusion-proof/4711/241fd4538d0a35c2d0394e4710ea9e6916854d08f62602fb03b55221dcdac90f
```
### 3.5 - get-consistency-proof
```
-POST <base url>/sigsum/v0/get-consistency-proof
+GET <base url>/sigsum/v0/get-consistency-proof/<old_size>/<new_size>
```
Input:
-- `new_size`: tree size of a newer tree head, ASCII-encoded decimal number.
- `old_size`: tree size of an older tree head that the log should prove is
- consistent with the newer tree head, ASCII-encoded decimal number.
+ consistent with a newer tree head, ASCII-encoded decimal number.
+- `new_size`: tree size of a newer tree head, ASCII-encoded decimal number.
Output on success:
- `consistency_path`: node hash, hex-encoded.
@@ -276,13 +281,12 @@ hashes follow from the hash strategy, see RFC 6962.
Example:
```
-$ echo "new_size=4711
-old_size=42" | curl --data-binary @- <base url>/sigsum/v0/get-consistency-proof
+$ curl <base url>/sigsum/v0/get-consistency-proof/42/4711
```
### 3.6 - get-leaves
```
-POST <base url>/sigsum/v0/get-leaves
+GET <base url>/sigsum/v0/get-leaves/<start_size>/<end_size>
```
Input:
@@ -305,8 +309,7 @@ must be returned on success.
Example:
```
-$ echo "start_size=42
-end_size=4711" | curl --data-binary @- <base url>/sigsum/v0/get-leaves
+$ curl <base url>/sigsum/v0/get-leaves/42/4711
```
### 3.7 - add-leaf
diff --git a/doc/design.md b/doc/design.md
index c046888..439f8c5 100644
--- a/doc/design.md
+++ b/doc/design.md
@@ -104,7 +104,7 @@ constrained environments. Signed and logged data can be (de)serialized using
[Trunnel](https://gitlab.torproject.org/tpo/core/trunnel/-/blob/main/doc/trunnel.md),
or "by hand" in many modern programming languages. This is the only parsing
that a verifier is required to support. Signers, monitors, and witnesses
-additionally need to interact with a sigsum log's line-terminated ASCII HTTP(S)
+additionally need to interact with a sigsum log's ASCII HTTP(S)
[API](https://git.sigsum.org/sigsum/tree/doc/api.md).
## 2 - Threat model