aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorRasmus Dahlberg <rasmus.dahlberg@kau.se>2021-06-25 15:26:38 +0200
committerRasmus Dahlberg <rasmus.dahlberg@kau.se>2021-06-25 15:26:38 +0200
commit0fb2a1055475876702a003b2fa4397595efa40de (patch)
treeb8d99dbf07d79a0cebc2e29a0361f36e98624001
parent01189f114bafa2a6ad68dacc2b7418bb303bdd35 (diff)
fixed s/st/sigsum in api.md
-rw-r--r--doc/api.md57
1 files changed, 27 insertions, 30 deletions
diff --git a/doc/api.md b/doc/api.md
index 32e1bf6..eb35df4 100644
--- a/doc/api.md
+++ b/doc/api.md
@@ -1,27 +1,25 @@
-# System Transparency Logging: API v0
-This document describes details of the System Transparency logging
-API, version 0. The broader picture is not explained here. We assume
-that you have read the System Transparency Logging design document.
-It can be found
-[here](https://github.com/system-transparency/stfe/blob/design/doc/design.md).
+# Sigsum Logging API v0
+This document outlines the sigsum logging API, version 0. The broader picture
+is not explained here. We assume that you are already familiar with the sigsum
+logging [design document](https://github.com/sigsum/sigsum/blob/main/doc/design.md).
**Warning.**
This is a work-in-progress document that may be moved or modified.
## Overview
-Logs implement an HTTP(S) API for accepting requests and sending
-responses.
+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
- ASCII-encoded key/value pairs.
-- Requests with input data use HTTP POST to send the data to a log.
+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's simple to parse. Note that this format is
+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. A
-submitter may distribute log responses to their end-users in any
+submitter should distribute log responses to their end-users in any
format that suits them. The (de)serialization required for
_end-users_ is a small subset of Trunnel. Trunnel is an "idiot-proof"
wire-format in use by the Tor project.
@@ -34,7 +32,7 @@ The hash functions must be
[SHA256](https://csrc.nist.gov/csrc/media/publications/fips/180/4/final/documents/fips180-4-draft-aug2014.pdf).
Logs must sign tree heads using
[Ed25519](https://tools.ietf.org/html/rfc8032). Log witnesses
-must also sign tree heads using Ed25519.
+must cosign signed tree heads using Ed25519.
All other parts that are not Merkle tree related should use SHA256 as
the hash function. Using more than one hash function would increases
@@ -131,9 +129,8 @@ appropriate key and make an explicit trust decision.
## Public endpoints
Every log has a base URL that identifies it uniquely. The only
constraint is that it must be a valid HTTP(S) URL that can have the
-`/st/v0/<endpoint>` suffix appended. For example, a complete endpoint
-URL could be
-`https://log.example.com/2021/st/v0/get-tree-head-cosigned`.
+`/sigsum/v0/<endpoint>` suffix appended. For example, a complete endpoint
+URL could be `https://log.example.com/2021/sigsum/v0/get-tree-head-cosigned`.
Input data (in requests) is POST:ed in the HTTP message body as ASCII
key/value pairs.
@@ -145,14 +142,14 @@ format as the input data, i.e. as ASCII key/value pairs on the format
The HTTP status code is 200 OK to indicate success. A different HTTP
status code is used to indicate failure, in which case a log should
respond with a human-readable string describing what went wrong using
-the key `error`. Example: `error=Invalid signature.`.
+the key `error`. Example: `error=Invalid signature`.
### get-tree-head-cosigned
Returns the latest cosigned tree head. Used together with
`get-proof-by-hash` and `get-consistency-proof` for verifying the tree.
```
-GET <base url>/st/v0/get-tree-head-cosigned
+GET <base url>/sigsum/v0/get-tree-head-cosigned
```
Input:
@@ -183,7 +180,7 @@ success. The number of witness signatures and key hashes must match.
Returns the latest signed tree head to be cosigned. Used by witnesses.
```
-GET <base url>/st/v0/get-tree-head-to-sign
+GET <base url>/sigsum/v0/get-tree-head-to-sign
```
Input:
@@ -202,14 +199,14 @@ Output on success:
Returns the latest signed tree head. Used for debugging purposes.
```
-GET <base url>/st/v0/get-tree-head-latest
+GET <base url>/sigsum/v0/get-tree-head-latest
```
Input an output follows the same formatting as `get-tree-head-to-sign`.
### get-proof-by-hash
```
-POST <base url>/st/v0/get-proof-by-hash
+POST <base url>/sigsum/v0/get-proof-by-hash
```
Input:
@@ -233,11 +230,11 @@ proof of zero or more node hashes. The order of node hashes follow
from the hash strategy, see RFC 6962.
Example: `echo "leaf_hash=241fd4538d0a35c2d0394e4710ea9e6916854d08f62602fb03b55221dcdac90f
-tree_size=4711" | curl --data-binary @- localhost/st/v0/get-proof-by-hash`
+tree_size=4711" | curl --data-binary @- localhost/sigsum/v0/get-proof-by-hash`
### get-consistency-proof
```
-POST <base url>/st/v0/get-consistency-proof
+POST <base url>/sigsum/v0/get-consistency-proof
```
Input:
@@ -259,11 +256,11 @@ consistency proof of zero or more node hashes. The order of node
hashes follow from the hash strategy, see RFC 6962.
Example: `echo "new_size=4711
-old_size=42" | curl --data-binary @- localhost/st/v0/get-consistency-proof`
+old_size=42" | curl --data-binary @- localhost/sigsum/v0/get-consistency-proof`
### get-leaves
```
-POST <base url>/st/v0/get-leaves
+POST <base url>/sigsum/v0/get-leaves
```
Input:
@@ -288,11 +285,11 @@ A log may return fewer leaves than requested. At least one leaf
must be returned on HTTP status code 200 OK.
Example: `echo "start_size=42
-end_size=4711" | curl --data-binary @- localhost/st/v0/get-leaves`
+end_size=4711" | curl --data-binary @- localhost/sigsum/v0/get-leaves`
### add-leaf
```
-POST <base url>/st/v0/add-leaf
+POST <base url>/sigsum/v0/add-leaf
```
Input:
@@ -335,11 +332,11 @@ Example: `echo "shard_hint=1640995200
checksum=cfa2d8e78bf273ab85d3cef7bde62716261d1e42626d776f9b4e6aae7b6ff953
signature=c026687411dea494539516ee0c4e790c24450f1a4440c2eb74df311ca9a7adf2847b99273af78b0bda65dfe9c4f7d23a5d319b596a8881d3bc2964749ae9ece3
verification_key=c9a674888e905db1761ba3f10f3ad09586dddfe8581964b55787b44f318cbcdf
-domain_hint=example.com" | curl --data-binary @- localhost/st/v0/add-leaf`
+domain_hint=example.com" | curl --data-binary @- localhost/sigsum/v0/add-leaf`
### add-cosignature
```
-POST <base url>/st/v0/add-cosignature
+POST <base url>/sigsum/v0/add-cosignature
```
Input:
@@ -358,7 +355,7 @@ motivate verifiers to locate the appropriate key and make an explicit
trust decision.
Example: `echo "cosignature=d1b15061d0f287847d066630339beaa0915a6bbb77332c3e839a32f66f1831b69c678e8ca63afd24e436525554dbc6daa3b1201cc0c93721de24b778027d41af
-key_hash=662ce093682280f8fbea9939abe02fdba1f0dc39594c832b411ddafcffb75b1d" | curl --data-binary @- localhost/st/v0/add-cosignature`
+key_hash=662ce093682280f8fbea9939abe02fdba1f0dc39594c832b411ddafcffb75b1d" | curl --data-binary @- localhost/sigsum/v0/add-cosignature`
## Summary of log parameters
- **Public key**: The Ed25519 verification key to be used for