From 24cc6b0db8ef9c718925d14b329f21938e5d2b1b Mon Sep 17 00:00:00 2001 From: Rasmus Dahlberg Date: Tue, 20 Apr 2021 12:28:28 +0200 Subject: started on our in-progress (re)design documents --- doc/schema/consistency_proof.schema.json | 30 +++++++++++++++++++ doc/schema/example/consistency_proof.json | 7 +++++ doc/schema/example/inclusion_proof.json | 7 +++++ doc/schema/example/leaves.json | 14 +++++++++ doc/schema/example/sth.json | 11 +++++++ doc/schema/inclusion_proof.schema.json | 30 +++++++++++++++++++ doc/schema/leaves.schema.json | 38 +++++++++++++++++++++++ doc/schema/sth.schema.json | 50 +++++++++++++++++++++++++++++++ 8 files changed, 187 insertions(+) create mode 100644 doc/schema/consistency_proof.schema.json create mode 100644 doc/schema/example/consistency_proof.json create mode 100644 doc/schema/example/inclusion_proof.json create mode 100644 doc/schema/example/leaves.json create mode 100644 doc/schema/example/sth.json create mode 100644 doc/schema/inclusion_proof.schema.json create mode 100644 doc/schema/leaves.schema.json create mode 100644 doc/schema/sth.schema.json (limited to 'doc/schema') diff --git a/doc/schema/consistency_proof.schema.json b/doc/schema/consistency_proof.schema.json new file mode 100644 index 0000000..003f3c7 --- /dev/null +++ b/doc/schema/consistency_proof.schema.json @@ -0,0 +1,30 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "title": "inclusion_proof", + "description": "JSON-formatted inclusion proof, version 0.", + + "type": "object", + "required": [ "new_size", "old_size", "consistency_proof" ], + "properties": { + "new_size": { + "description": "The tree size of the newer Merkle tree head.", + "type": "integer", + "minimum": 0 + }, + "old_size": { + "description": "The tree size of the older Merkle tree head.", + "type": "integer", + "minimum": 0 + }, + "consistency_proof": { + "description": "A list of base64-encoded node hashes that proves consistency", + "type": "array", + "items": { + "description": "A node hash in base64", + "type": "string", + "minLength": 44, + "maxLength": 44 + } + } + } +} diff --git a/doc/schema/example/consistency_proof.json b/doc/schema/example/consistency_proof.json new file mode 100644 index 0000000..0a323b7 --- /dev/null +++ b/doc/schema/example/consistency_proof.json @@ -0,0 +1,7 @@ +{ + "new_size": 2, + "old_size": 1, + "consistency_proof": [ + "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=" + ] +} diff --git a/doc/schema/example/inclusion_proof.json b/doc/schema/example/inclusion_proof.json new file mode 100644 index 0000000..d46d426 --- /dev/null +++ b/doc/schema/example/inclusion_proof.json @@ -0,0 +1,7 @@ +{ + "tree_size": 2, + "leaf_index": 0, + "inclusion_proof": [ + "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=" + ] +} diff --git a/doc/schema/example/leaves.json b/doc/schema/example/leaves.json new file mode 100644 index 0000000..1eed05d --- /dev/null +++ b/doc/schema/example/leaves.json @@ -0,0 +1,14 @@ +[ + { + "checksum": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=", + "signature_scheme": 1, + "signature": "CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC=", + "key_hash": "DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD=" + }, + { + "checksum": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=", + "signature_scheme": 2, + "signature": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=", + "key_hash": "CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC=" + } +] diff --git a/doc/schema/example/sth.json b/doc/schema/example/sth.json new file mode 100644 index 0000000..ec3ad11 --- /dev/null +++ b/doc/schema/example/sth.json @@ -0,0 +1,11 @@ +{ + "timestamp": 0, + "tree_size": 0, + "root_hash": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=", + "signatures": [ + { + "key_hash": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=", + "signature": "CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC=" + } + ] +} diff --git a/doc/schema/inclusion_proof.schema.json b/doc/schema/inclusion_proof.schema.json new file mode 100644 index 0000000..3309d37 --- /dev/null +++ b/doc/schema/inclusion_proof.schema.json @@ -0,0 +1,30 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "title": "inclusion_proof", + "description": "JSON-formatted inclusion proof, version 0.", + + "type": "object", + "required": [ "tree_size", "leaf_index", "inclusion_proof" ], + "properties": { + "tree_size": { + "description": "The Merkle tree size that the inclusion proof is based on.", + "type": "integer", + "minimum": 0 + }, + "leaf_index": { + "description": "The zero-based index of the leaf that the inclusion proof is for.", + "type": "integer", + "minimum": 0 + }, + "inclusion_proof": { + "description": "A list of base64-encoded node hashes that proves inclusion", + "type": "array", + "items": { + "description": "A node hash in base64", + "type": "string", + "minLength": 44, + "maxLength": 44 + } + } + } +} diff --git a/doc/schema/leaves.schema.json b/doc/schema/leaves.schema.json new file mode 100644 index 0000000..74d7454 --- /dev/null +++ b/doc/schema/leaves.schema.json @@ -0,0 +1,38 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "title": "list of tree_leaf", + "description": "JSON-formatted tree leaf list, version 0.", + + "type": "array", + "description": "A list Merkle tree leaves", + "items": { + "type": "object", + "required": [ "checksum", "signature_scheme", "signature", "key_hash" ], + "properties": { + "checksum": { + "description": "A cryptographic hash that is computed over some data of opaque type. The result is base64-encoded.", + "type": "string", + "minLength": 44, + "maxLength": 44 + }, + "signature_scheme": { + "description": "An integer that identifies the signature scheme used by the submitter. See API documentation.", + "type": "integer", + "enum": [ 1, 2, 3 ] + }, + "signature": { + "description": "The submitter's signature over the checksum in base64", + "type": "string", + "minLength": 44, + "maxLength": 684 + }, + "key_hash": { + "description": "A public verification-key hash that identifies the signer.", + "type": "string", + "minLength": 44, + "maxLength": 44 + } + } + }, + "minItems": 1 +} diff --git a/doc/schema/sth.schema.json b/doc/schema/sth.schema.json new file mode 100644 index 0000000..86de2d3 --- /dev/null +++ b/doc/schema/sth.schema.json @@ -0,0 +1,50 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "title": "signed_tree_head_v0", + "description": "JSON-formatted signed tree head, version 0.", + + "type": "object", + "required": [ "timestamp", "tree_size", "root_hash", "signatures" ], + "properties": { + "timestamp": { + "description": "The number of milliseconds since the UNIX epoch (January 1, 1970 00:00:00 UTC).", + "type": "integer", + "minimum": 0 + }, + "tree_size": { + "description": "The number of entries that are stored in the log's Merkle tree.", + "type": "integer", + "minimum": 0 + }, + "root_hash": { + "description": "The log's Merkle tree root hash in base64.", + "type": "string", + "minLength": 44, + "maxLength": 44 + }, + "signatures": { + "description": "A list of signer-signature pairs.", + "type": "array", + "items": { + "description": "A signer-signature pair.", + "type": "object", + "required": [ "key_hash", "signature" ], + "properties": { + "key_hash": { + "description": "A public verification-key hash that identifies the signer in base64.", + "type": "string", + "minLength": 44, + "maxLength": 44 + }, + "signature": { + "description": "The signer's signature over the log's tree_leaf structure in base64.", + "type": "string", + "minLength": 44, + "maxLength": 44 + } + } + }, + "minItems": 1 + } + } +} -- cgit v1.2.3