diff options
| -rw-r--r-- | doc/api.md | 57 |
1 files changed, 27 insertions, 30 deletions
@@ -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 |