aboutsummaryrefslogtreecommitdiff
path: root/doc/formats.md
diff options
context:
space:
mode:
authorRasmus Dahlberg <rasmus.dahlberg@kau.se>2021-04-20 12:28:28 +0200
committerRasmus Dahlberg <rasmus.dahlberg@kau.se>2021-04-20 12:28:28 +0200
commit24cc6b0db8ef9c718925d14b329f21938e5d2b1b (patch)
treeecf078b59ea10d8212615dbfc4f0879c3d6560a0 /doc/formats.md
parentf3134997ccbb525cd09a8144ed6daeeb3245326a (diff)
started on our in-progress (re)design documents
Diffstat (limited to 'doc/formats.md')
-rw-r--r--doc/formats.md160
1 files changed, 0 insertions, 160 deletions
diff --git a/doc/formats.md b/doc/formats.md
deleted file mode 100644
index bffd05f..0000000
--- a/doc/formats.md
+++ /dev/null
@@ -1,160 +0,0 @@
-# Formats
-This document defines data structures and data formats.
-
-## Overview
-Here we give an overview of our presentation language / serialization rules.
-
-All integers are represented by 64-bit unsigned integers in network byte order.
-
-Variable length lists have an integer specifying its length. Then each list
-item is enumerated.
-
-TODO: fixme.
-
-## Items
-Every item type start with a versioned format specifier. Protocol version 1
-uses format specifiers in the range 1--X.
-
-### Request data structures
-Log endpoints that take input data use the following request data structures.
-
-#### `get_entries_v1`
-```
-0 Format 8 16 24
-+----------+----------------+----------------+
-| 1 | Start Size | End Size |
-+----------+----------------+----------------+
- uint64 uint64 uint64
-```
-- Format is always 1 for items of type `get_entries_v1`.
-- Start size specifies the index of the first Merkle tree leaf to retrieve.
-- End size specifies the index of the last Merkle tree leaf to retrieve.
-
-#### `get_proof_by_hash_v1`
-```
-0 Format 8 16 48
-+----------+----------------+----------------+
-| 2 | Tree size | Leaf hash |
-+----------+----------------+----------------+
- uint64 uint64 fixed byte array
-```
-- Format is always 2 for items of type `get_proof_by_hash_v1`.
-- Leaf hash is computed as described in [RFC 6962/bis, §2.1.1](https://tools.ietf.org/html/draft-ietf-trans-rfc6962-bis-35#section-2.1.1).
-- Tree size specifies which Merkle tree root inclusion should be proven for.
-
-#### `get_consistency_proof_v1`
-```
-0 Format 8 16 24
-+----------+----------------+----------------+
-| 3 | Old size | New size |
-+----------+----------------+----------------+
- uint64 uint64 uint64
-```
-- Format is always 3 for items of type `get_consistency_proof_v1`.
-- Old size specifies the tree size of an older Merkle tree head.
-- New size specifies the tree size of a newer Merkle tree head.
-
-### Proof and log data structures
-#### `inclusion_proof_v1`
-```
- --zero or more node hashes-->
-0 Format 8 48 56 64 72 72+Length
-+----------+----------------+----------------+----------------+----------------+--------//--------+
-| 4 | Identifier | Tree size | Leaf index | Length | Node hashes |
-+----------+----------------+----------------+----------------+----------------+--------//--------+
- uint64 ed25519_v1 uint64 uint64 uint64 list body
-```
-- Format is always 4 for items of type `inclusion_proof_v1`.
-- Identifier identifies the log uniquely as an `ed25519_v1` item.
-- Tree size is the size of the Merkle tree that the proof is based on.
-- Leaf index is a zero-based index of the log entry that the proof is based on.
-- The remaining part is a list of node hashes.
- - Length specifies the full byte size of the list. It must be `32 * m`,
- where `m >= 0`. This means that an inclusion needs zero or more node
- hashes to be well-formed.
- - Node hash is a node hash in the Merkle tree that the proof is based on.
-
-Remark: the list of node hashes is generated and verified as in [RFC 6962/bis,
-§2.1.3](https://tools.ietf.org/html/draft-ietf-trans-rfc6962-bis-35#section-2.1.3).
-
-#### `consistency_proof_v1`
-```
- --zero or more node hashes-->
-0 Format 8 48 56 64 72 72+Length
-+----------+----------------+----------------+----------------+----------------+--------//--------+
-| 5 | Identifier | Old size | New size | Length | Node hashes |
-+----------+----------------+----------------+----------------+----------------+--------//--------+
- uint64 ed25519_v1 uint64 uint64 uint64 list body
-```
-- Format is always 5 for items of type `consistency_proof_v1`.
-- Identifier identifies the log uniquely as an `ed25519_v1` item.
-- Old size is the tree size of the older Merkle tree.
-- New size is the tree size of the newer Merkle tree.
-- The remaining part is a list of node hashes.
- - Length specifies the full byte size of the list. It must be `32 * m`,
- where `m >= 0`. This means that a consistenty proof needs zero or more node
- hashes to be well-formed.
- - Node hash is a node hash from the older or the newer Merkle tree.
-
-Remark: the list of node hashes is generated and verified as in [RFC 6962/bis,
-§2.1.4](https://tools.ietf.org/html/draft-ietf-trans-rfc6962-bis-35#section-2.1.4).
-
-#### `signed_tree_head_v1`
-```
- ----one or more signature-identifier pairs------->
-0 Format 8 16 24 56 64 128 168 64+Length
-+----------+----------------+----------------+----------------+----------------+----------------+----------------+--//--+
-| 6 | Timestamp | Tree size | Root hash | Length | Signature | Identifier | .... |
-+----------+----------------+----------------+----------------+----------------+----------------+----------------+--//--+
- uint64 uint64 uint64 fixed byte array uint64 fixed byte array ed25519_v1 cont. list body
-```
-- Format is always 6 for items of type `signed_tree_head_v1`.
-- Timestamp is the time since the UNIX epoch (January 1, 1970 00:00:00 UTC) in
-milliseconds.
-- Tree size is the number of leaves in the current Merkle tree.
-- Root hash is the root hash of the current Merkle tree.
-- The remaining part is a list of signature-identifier pairs.
- - Length specifies the full byte size of the list. It must be `104 * m`,
- where `m > 1`. This means that a signed tree head needs at least one
- signature-identifier pair to be well-formed.
- - Signature is an Ed25519 signature over bytes 0--56. The signature is
- encodes as in [RFC 8032, §3.3](https://tools.ietf.org/html/rfc8032#section-3.3).
- - Identifier identifies the signer uniquely as an `ed25519_v1` item.
-
-Remark: there may be multiple signature-identifier pairs if the log is cosigned.
-
-#### `signed_checksum32_ed25519_v1`
-```
-0 Format 8 40 56 56+Length 120+Length 160+Length
-+----------+----------------+----------------+-------//---------+----------------+--------//--------+
-| 7 | Checksum | Length | Identifier | Signature | Namespace |
-+----------+----------------+----------------+-------//---------+----------------+--------//--------+
- uint64 fixed byte array uint64 byte array fixed byte array ed25519_v1
-```
-- Format is always 7 for items of type `signed_checksum32_ed25519_v1`.
-- Checksum is a 32-byte checksum that represents a data item of opaque type.
-- Length specified the full byte size of the following identifier. It must be
-larger than zero and less than 128.
-- Identifier identifies what the checksum represents. The aforementioned length
-constraint means that the identifier cannot be omitted or exceed 128 bytes.
-- Signature is an Ed25519 signature over bytes 0--56+Length. The signature is
-encodes as in [RFC 8032, §3.3](https://tools.ietf.org/html/rfc8032#section-3.3).
-- Namespace is an `ed25519_v1` item that identifies the signer uniquely.
-
-Remark: to keep this checksum entry as simple as possible it does not have a
-variable length checksum or any agility with regards to the signing namespace.
-This means that we need to have multiple leaf types that follow the pattern
-`signed_checksum{32,64}_namespace_v1`.
-
-### Namespace data structures
-#### `ed25519_v1`
-```
-0 Format 8 40
-+----------+----------------+
-| 8 | public key |
-+----------+----------------+
- uint64 fixed byte array
-```
-- The format is always 8 for items of type `ed25519_v1`.
-- The public Ed25519 verification key is always 32 bytes. See encoding in [RFC
-8032, §3.2](https://tools.ietf.org/html/rfc8032#section-3.2).