From eaffcf03a1fc423c9dab622de7d93a6a22cc16d2 Mon Sep 17 00:00:00 2001 From: Linus Nordberg Date: Wed, 2 Mar 2022 13:00:50 +0100 Subject: add shard hint to tree_leaf struct Needed for being able to verify signatures. Also, remove struct statement since we won't expose it and have no use for it. --- doc/api.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) (limited to 'doc/api.md') diff --git a/doc/api.md b/doc/api.md index 3ff41c3..3889301 100644 --- a/doc/api.md +++ b/doc/api.md @@ -100,29 +100,27 @@ Logs support a single leaf type. It contains a signer's statement, signature, and key hash. ``` -struct statement { - u8 checksum[32]; -} - struct tree_leaf { - struct statement statement; + u64 shard_hint; + u8 checksum_hash[32]; u8 signature[64]; u8 key_hash[32]; } ``` -`checksum` is a the hash of a preimage. The signer submits a 32-byte preimage +`shard_hint` is a shard hint that matches the log's shard interval. + +`checksum_hash` is a hash of a preimage. The signer submits a 32-byte preimage representing some data. It is recommended to set this preimage to `H(data)`, in -which case the checksum will be `H(H(data))`. +which case the checksum hash will be `H(H(data))`. `signature` is computed by treating the above preimage as the message `M` in SSH's [signing format](https://github.com/openssh/openssh-portable/blob/master/PROTOCOL.sshsig). The hash algorithm string must be "SHA256". The reserved string must be empty. The namespace field must be set to `tree_leaf:v0:@sigsum.org`, where -`` is replaced with the shortest decimal ASCII representation of a -shard hint that matches the log's shard interval. This ensures a _sigsum -shard-specific tree leaf context_. +`` is replaced with the shortest decimal ASCII representation of `shard_hint`. +This ensures a _sigsum shard-specific tree leaf context_. `key_hash` is a hash of the signer's public verification key using the same format as Section 2.3.2. It is included -- cgit v1.2.3