diff options
| -rw-r--r-- | markup/api.md | 98 |
1 files changed, 76 insertions, 22 deletions
diff --git a/markup/api.md b/markup/api.md index 8a4f527..da23488 100644 --- a/markup/api.md +++ b/markup/api.md @@ -12,14 +12,13 @@ For reference you may look at Certificate Transparency (CT) logging and [CTFE](https://github.com/google/certificate-transparency-go/tree/master/trillian/ctfe), which implements [RFC 6962](https://tools.ietf.org/html/rfc6962). -We reuse RFC 6962 and its follow-up specification [RFC -6962/bis](https://datatracker.ietf.org/doc/draft-ietf-trans-rfc6962-bis/) to the -largest extent possible. +We take inspiration from from RFC 6962 and its follow-up specification [RFC +6962/bis](https://datatracker.ietf.org/doc/draft-ietf-trans-rfc6962-bis/). ## Log parameters A log is defined by the following immutable parameters: - Log identifier: `SHA256(public key)`, see RFC 6962 -[§3.2](https://tools.ietf.org/html/rfc6962#section-3.2) +[§3.2](https://tools.ietf.org/html/rfc6962#section-3.2). TODO: use KID instead. - Public key: DER encoding of the key represented as `SubjectPublicKeyInfo` - Supported signature schemes: a list of signature schemes that the log recognizes. Possible values are defined in RFC 8446, @@ -27,8 +26,6 @@ log recognizes. Possible values are defined in RFC 8446, use a signature algorithm that the log supports. - Signature scheme: the signature scheme that the log uses to sign tree heads and debug info statements. -- Maximum chain length: e.g., three means that we would reject submissions that -were signed by a certificate chain of length four. - Base URL: where can this log be reached? E.g., example.com:1234/log Note that **there is no MMD**. The idea is to merge added entries as soon as @@ -43,7 +40,7 @@ A log should accept a submission if it is: - Well-formed, see below. - Digitally signed - Proves who submitted an entry for logging - - The signing key must chain back to a valid trust anchor + - Verification key must be registered in the log as a namespace ## Data structure definitions We encode everything that is digitally signed as in [RFC @@ -80,16 +77,76 @@ struct { } StItem; ``` +### Namespace +The submitter's verification key is used to establish a _namespace_. Added +log entries must be signed by a registered namespace, such that anyone that +observes the log can determine which artifact hashes belong to which namespaces. +``` +enum { + reserved(0), + ed25519_v1(1), + (65535) +} NamespaceFormat; + +struct { + NamespaceFormat format; + select (format) { + case ed25519_v1: Ed25519V1; + } message; +} Namespace; +``` + +Credit: inspired by Keybase's [KID format](https://keybase.io/docs/api/1.0/kid). + +#### Ed25519V1 +At this time the only supported key type is Ed25519 as defined by [RFC +8032](https://tools.ietf.org/html/rfc8032). The namespace field contains the +full verification key. +``` +struct { + opaque namespace<32>; // public key +} Ed25519V1; +``` + +#### Other +In the future we will support other key types, such as RSA. For example, we +could add [RSASSA-PKCS1-v1_5](https://tools.ietf.org/html/rfc3447#section-8.2) +as follows: +1. Add `rsa_v1` format and RSAV1 namespace. This is what we would register on +the server-side such that the server knows the namespace and complete key. +``` +struct { + opaque namespace<32>; // key fingerprint + // + some encoding of public key +} RSAV1; +``` +2. Add `rsassa_pkcs1_5_v1` format and `RSASSAPKCS1_5_v1`. This is what the +submitter would use to communicate namespace and RSA signature mode. +``` +struct { + opaque namespace<32>; // key fingerprint + // + necessary parameters, e.g., SHA256 as hash function +} RSASSAPKCS1_5V1; +``` + +Another option is to just never bother with key fingerprint, i.e., use the +complete (encoded) RSA key as the namespace. Makes the leaf a lot larger +though. + ### Merkle tree leaf types In the future there might be several types of leaves. Say, one for operating system packages, another one for Debian packages, and a third one for general-purpose checksums. For now we only define the latter. +TODO: scope of this spec should only be checksum + #### Checksum + ``` struct { opaque package<1..2^8-1>; // package identifier opaque checksum<1..64>; // hash of some artifact + Namespace namespace; } ChecksumV1; ``` @@ -100,6 +157,9 @@ update](https://wiki.mozilla.org/Security/Binary_Transparency). It is assumed that the entities relying on the checksum type know how to find the artifact source (if not already at hand) and then reproduce the logged hash from it. +Namespace is used to determine who this artifact hash belongs to. Note that we +do not connect namespaces to real-world identities. It is just _a namespace_. + ### Signed Debug Info RFC 6962 uses Signed Certificate Timestamps (SCTs) as promises of public logging within a time known as the Maximum Merge Delay (MMD). We provide no @@ -122,12 +182,18 @@ e.g., `ed25519(0x0807)` refers to [RFC schemes and their interpretations can be found in RFC 8446, [§4.2.3](https://tools.ietf.org/html/rfc8446#section-4.2.3). +TODO: when log id is namespace this information is already communicated. +TODO: remove SDI? + ## Public endpoints Clients talk to the log with HTTPS GET/POST requests. POST parameters are JSON objects, GET parameters are URL encoded, and serialized data is expressed as base-64. See details in as in RFC 6962, [§4](https://tools.ietf.org/html/rfc6962#section-4). +TODO: remove json +TODO: and b64? + Unless specified otherwise, the data in question is serialized. ### add-entry @@ -138,12 +204,7 @@ POST https://<base url>/st/v1/add-entry Input: - item: an `StItem` that corresponds to a valid leaf type. Only `checksum_v1` at this time. -- signature_scheme: decimal, possible values are defined in RFC 8446 -[§4.2.3](https://tools.ietf.org/html/rfc8446#section-4.2.3). The serialized -signature encoding follows from this. - signature: covers the submitted item. -- chain: a list of base-64 encoded X.509 certificates that chain back to -a trust anchor and which produced the above signature. Output: - an `StItem` structure of type `signed_debug_info_v1` that covers the added @@ -163,23 +224,16 @@ Output: - leaf: `StItem` that corresponds to the leaf's type. - signature: signature that covers the retrieved item using the below signature scheme. - - signature_scheme: one that the log accepts, see supported signature - schemes and how they are represeneted in the log's parameters. - - chain: an array of base-64 encoded certificates, where the first - corresponds to the signing certificate and the final one a trust anchor. - -The signature and chain can be viewed as a leaf's appendix, i.e., something that -is stored by the log but not part of the leaf itself. -### get-anchors +### get-namespaces ``` -GET https://<base url>/st/v1/get-anchors +GET https://<base url>/st/v1/get-namespaces ``` No input. Output: -- an array of base-64 encoded trust anchors that the log accept. +- an array of base-64 encoded namespaces that the log accept. TODO: format? ### get-proof-by-hash ``` |