Merge branch 'main' into improve-verify-function-api

Author: gregoire-mullvad

CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- The `Policy` type gained a full implementation of the quorum logic and the
+  ability to parse Sigsum policies.
+- There's a new `PolicyBuilder` type that can be used to programatically build
+  valid `Policy` values.
+- The crates now ships with the `sigsum-generic-2025-1` policy as well as three
+  test policies (same policies that are built into the reference Sigsum
+  tooling).
+
+### Removed
+
+- The `Policy::new_k_of_n()` constructor has been removed in favor of
+  `PolicyBuilder`.

README.md

@@ -15,36 +15,42 @@ cargo add sigsum
 ## Usage
 
 ```rust
-use sigsum::{verify, Hash, Policy, PublicKey, SigsumSignature};
+use sigsum::{verify, Hash, PublicKey, SigsumSignature};
 use hex_literal::hex;
 
-let data = b"Hello, Sigsum!";
+let data = b"Hello, Sigsum!\n";
 let signers: Vec<PublicKey> =
-    vec![hex!("8a9b8b9f45a826b541c1477861a458c7b30ef1cc9600c515d593c4e2f72f375e").into()];
-let policy = Policy::new_k_of_n(
-    vec![hex!("4644af2abd40f4895a003bca350f9d5912ab301a49c77f13e5b6d905c20a5fe6").into()],
-    vec![hex!("4a921b7caef58ae670cdc11ef4184f1c058f7b9259a9107a969f69fa54aa496f").into()],
-    1,
-);
+    vec![hex!("99ed58583e8750b20548e69df4a4e1a592379a9a66c51cd32e42fbe4e1bde78a").into()];
 let signature = SigsumSignature::from_ascii("version=2
-log=4e89cc51651f0d95f3c6127c15e1a42e3ddf7046c5b17b752689c402e773bb4d
-leaf=2ca612aaa355c19a0cc7ebaacb04723b97e873df4dbadd0f97a2e00a13d8f76a 1a5fcc2b05fb6ca66dbc7e62bcc7934fb0ebf49bba501c285222550a67e590fa3237b338ba59d2327800788b85ff9e80ea88c71157519974c70d10c825e65401
-
-size=8858
-root_hash=b8c0a14d4fa1440e8d624f0fbe1639477d41bcd3cd530317682925dcf09f1835
-signature=726ebfe875ca1b54a586ad77a0f28ecadbdc3e3bbff5fb7d8b0dd69aa1a3195a30082e51b1982a70228ac455ef0d5da329bcaacc08a9dcf0dbc765fe0cc18400
-cosignature=0d4f46a219ab309cea48cde9712e7d8486fc99802f873175eeab70fb84b4f5a4 1759300864 e1eb12119f68cb07199747398f94fae281529a138ab13e23842ff9c55c722cb1b036f0f378d5f8950f2cdac0ffd262550e57a8fe493dceece72652dce65ba60d
-cosignature=49c4cd6124b7c572f3354d854d50b2a4b057a750f786cf03103c09de339c4ea3 1759300864 fc44071f94fe33b4de857f60b4dc1703b59c8623147d68f99b1a4275bbc6897b40c23a3d03d2c20e098ac1016f73258ebcaeeeeef2fa585106be9f49e26ccc0f
-
-leaf_index=8857
-node_hash=9736194936496bfbea6e571fad7f34519f32a1132c340cff8ae6c071a4ba7320
-node_hash=42fb1dfd5f0610ae4e61f91b644c3794a24d1084331db464096beb7c0c9dc11b
-node_hash=1c0df8227e8a3a76ab618d421c89afa3923ea5c74c025eec0c53a1109d4c9d28
-node_hash=91bc923fa508d27f12ddeae047e7b51a7bb5cc529b173836d66bdd8728eab5c9
-node_hash=ca6768bb0e267f5c339e639f02101c73be12efd5dd0462959677a86e22bbb58d
-node_hash=e8bb977d7ae35a4b7e591ded5e3d7fad0afee0b958d6309a52f48fe46c679c36
+log=1643169b32bef33a3f54f8a353b87c475d19b6223cbb106390d10a29978e1cba
+leaf=2c8d843ed6237e9ea033207113329fdd1428c75f8fd3c6782ae46c92c7a00c40 38dd0b42cab5166611a4f8346db1c6ffe81ee2345f3ffe36a466eb8fce1d4b2879fbb5f26291d25e610b2dc7f30eaa603efd97739ae585657d0f7181726eec00
+
+size=381382
+root_hash=901fefc6f1d978d2c2bedb82d448755bcdc7e8626e67ac7ee80873771be9b667
+signature=8a8bf1fca60d1344fb6e2106e8f8906af833d3d75a21fe8d3af72be459f7a11f2ae6606ec6344a13b851cd454b3d281a2b1ae47732f7a8d6afbcc0134d1a2d00
+cosignature=1c997261f16e6e81d13f420900a2542a4b6a049c2d996324ee5d82a90ca3360c 1770193051 a1ee1182b265204499cbef3ae59f3ea228b928b3cbda8817a4ed5a12776823e9ad8ef1ce986b9b98d9954f1798ec4315c1820704600a231c69038ccc9726d202
+cosignature=49c4cd6124b7c572f3354d854d50b2a4b057a750f786cf03103c09de339c4ea3 1770193051 aaf642e81a54399777180f238573d74878b68c7b645d8011583621405bb450b4e7887fc76502a8142c493d64e3ed3e556d82dad1706411082e58805f64fa9d02
+cosignature=70b861a010f25030de6ff6a5267e0b951e70c04b20ba4a3ce41e7fba7b9b7dfc 1770193051 f5953f406f5fd97d9c9d1328b00b07bf434a5eb76d8da359aeda98c414de29ca1ced1872971ea0f137508a7bb05c7d322548409425677af96433706319bc0801
+cosignature=86b5414ae57f45c2953a074640bb5bedebad023925d4dc91a31de1350b710089 1770193051 3434b4646904714f4983c8e7e976a45332711f10012b19fbeb5549b6c0c04fb4ed52feed2da829354623c52b22b90093776034a8d57d660f9ff27a118f5bf801
+cosignature=c1d2d6935c2fb43bef395792b1f3c1dfe4072d4c6cadd05e0cc90b28d7141ed3 1770193051 f0dce1bcdda3a2826479d62e6afedbe9ec06e8f990ae59d8cefa84d9a6ee68c12c2820fb00e1dbdc30044b16c7695a9d1047cec4788dc757f698d34ebaec4305
+cosignature=d960fcff859a34d677343e4789c6843e897c9ff195ea7140a6ef382566df3b65 1770193051 b44c41f75566850003f7f655a6dc7bb38bb980e8e2c383871e29883805d3adec7782a08388b9386d9718380a4bb6900043e2b46080cff0fa75a500c36ef9df0a
+cosignature=e4a6a1e4657d8d7a187cc0c20ed51055d88c72f340d29534939aee32d86b4021 1770193051 70697b4a6b07e79e49d0a8e41fd7450a593ee9df11da6244cebe4b0c15c8e52f28ad3931b95a806fc7f16b4ad90197971ddc087434c7985b8b3a0223c9fa3603
+cosignature=42351ad474b29c04187fd0c8c7670656386f323f02e9a4ef0a0055ec061ecac8 1770193051 6610e5cf4ead2062d9783fbc19d2bae65eded35335495ad0cf0386277ed2d51854ced64efa21a6db0a398fdfb6761aa7d5659e54950a060d167fbdcb7b5ece05
+
+leaf_index=381381
+node_hash=d009c5dbeaaa5be1788ea9533f6f398747755a8245012165ac73f753b7917672
+node_hash=fb515551fe18f6e53d7d7f49b80abbb5c702b9662ee74fc7730e4a7685000aa4
+node_hash=e21e73ee8caf0d49cdcd2f334b3f64e85e4a151daf8d09b6034306bb21b88480
+node_hash=f77bc4db00e509149b6e2fc0028d7107dd415929dc9972f32fe758ce39bcc9a0
+node_hash=3acb38f01c633d917b899ed4e522a49a02bf20d358f98ca530e3a3065591e7f2
+node_hash=889de80c543a5ae8e35430988dc120ac7edde74b776f9082f814ea88190a601f
+node_hash=199f812b9f3667dec31f964098e32652477a2f3d458019b6f8f4acc645cf0131
+node_hash=084580f8f6324d4ae42dbcb779502ab9fab77e0c2b92519fe089be72e38d60ed
+node_hash=9ddbece4939d621df53f31e2729d5fa7802fd82f3edfb784483d8b7fa9cf41e2
+node_hash=e1c7a90c09949c263807e5970aef47f9a06164b759995ab814aff94aff9dcd00
 ")?;
-assert!(verify(&Hash::new(data), signature, signers, &policy).is_ok());
+
+verify(&Hash::new(data), signature, signers, &sigsum::policy::SIGSUM_TEST_2025_3)?;
 ```
 
 ## Contributing

src/crypto.rs

@@ -15,6 +15,10 @@ pub struct PublicKey {
 
 impl PublicKey {
     /// Verify that `sig` is a valid signature on `data` from this key.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the public key bytes are not a valid Ed25519 public key.
     pub fn verify_signature(&self, data: impl AsRef<[u8]>, sig: &Signature) -> bool {
         let verifier = ed25519_dalek::VerifyingKey::from_bytes(&self.bytes).unwrap();
         let signature = ed25519_dalek::Signature::from(&sig.bytes);

src/lib.rs

@@ -14,38 +14,42 @@
 //!
 //! ```rust
 //! # use std::error::Error;
-//! use sigsum::{verify, Hash, PolicyBuilder, PublicKey, SigsumSignature};
+//! use sigsum::{verify, Hash, PublicKey, SigsumSignature};
 //! use hex_literal::hex;
 //!
-//! let data = b"Hello, Sigsum!";
+//! let data = b"Hello, Sigsum!\n";
 //! let signers: Vec<PublicKey> =
-//!     vec![hex!("8a9b8b9f45a826b541c1477861a458c7b30ef1cc9600c515d593c4e2f72f375e").into()];
-//! let mut policy = PolicyBuilder::new();
-//! policy
-//!     .add_log(hex!("4644af2abd40f4895a003bca350f9d5912ab301a49c77f13e5b6d905c20a5fe6").into(), None)?
-//!     .add_witness(String::from("mywitness"), hex!("4a921b7caef58ae670cdc11ef4184f1c058f7b9259a9107a969f69fa54aa496f").into(), None)?
-//!     .set_quorum(String::from("mywitness"))?;
-//! let policy = policy
-//!     .build();
+//!     vec![hex!("99ed58583e8750b20548e69df4a4e1a592379a9a66c51cd32e42fbe4e1bde78a").into()];
 //! let signature = SigsumSignature::from_ascii("version=2
-//! log=4e89cc51651f0d95f3c6127c15e1a42e3ddf7046c5b17b752689c402e773bb4d
-//! leaf=2ca612aaa355c19a0cc7ebaacb04723b97e873df4dbadd0f97a2e00a13d8f76a 1a5fcc2b05fb6ca66dbc7e62bcc7934fb0ebf49bba501c285222550a67e590fa3237b338ba59d2327800788b85ff9e80ea88c71157519974c70d10c825e65401
+//! log=1643169b32bef33a3f54f8a353b87c475d19b6223cbb106390d10a29978e1cba
+//! leaf=2c8d843ed6237e9ea033207113329fdd1428c75f8fd3c6782ae46c92c7a00c40 38dd0b42cab5166611a4f8346db1c6ffe81ee2345f3ffe36a466eb8fce1d4b2879fbb5f26291d25e610b2dc7f30eaa603efd97739ae585657d0f7181726eec00
 //!
-//! size=8858
-//! root_hash=b8c0a14d4fa1440e8d624f0fbe1639477d41bcd3cd530317682925dcf09f1835
-//! signature=726ebfe875ca1b54a586ad77a0f28ecadbdc3e3bbff5fb7d8b0dd69aa1a3195a30082e51b1982a70228ac455ef0d5da329bcaacc08a9dcf0dbc765fe0cc18400
-//! cosignature=0d4f46a219ab309cea48cde9712e7d8486fc99802f873175eeab70fb84b4f5a4 1759300864 e1eb12119f68cb07199747398f94fae281529a138ab13e23842ff9c55c722cb1b036f0f378d5f8950f2cdac0ffd262550e57a8fe493dceece72652dce65ba60d
-//! cosignature=49c4cd6124b7c572f3354d854d50b2a4b057a750f786cf03103c09de339c4ea3 1759300864 fc44071f94fe33b4de857f60b4dc1703b59c8623147d68f99b1a4275bbc6897b40c23a3d03d2c20e098ac1016f73258ebcaeeeeef2fa585106be9f49e26ccc0f
+//! size=381382
+//! root_hash=901fefc6f1d978d2c2bedb82d448755bcdc7e8626e67ac7ee80873771be9b667
+//! signature=8a8bf1fca60d1344fb6e2106e8f8906af833d3d75a21fe8d3af72be459f7a11f2ae6606ec6344a13b851cd454b3d281a2b1ae47732f7a8d6afbcc0134d1a2d00
+//! cosignature=1c997261f16e6e81d13f420900a2542a4b6a049c2d996324ee5d82a90ca3360c 1770193051 a1ee1182b265204499cbef3ae59f3ea228b928b3cbda8817a4ed5a12776823e9ad8ef1ce986b9b98d9954f1798ec4315c1820704600a231c69038ccc9726d202
+//! cosignature=49c4cd6124b7c572f3354d854d50b2a4b057a750f786cf03103c09de339c4ea3 1770193051 aaf642e81a54399777180f238573d74878b68c7b645d8011583621405bb450b4e7887fc76502a8142c493d64e3ed3e556d82dad1706411082e58805f64fa9d02
+//! cosignature=70b861a010f25030de6ff6a5267e0b951e70c04b20ba4a3ce41e7fba7b9b7dfc 1770193051 f5953f406f5fd97d9c9d1328b00b07bf434a5eb76d8da359aeda98c414de29ca1ced1872971ea0f137508a7bb05c7d322548409425677af96433706319bc0801
+//! cosignature=86b5414ae57f45c2953a074640bb5bedebad023925d4dc91a31de1350b710089 1770193051 3434b4646904714f4983c8e7e976a45332711f10012b19fbeb5549b6c0c04fb4ed52feed2da829354623c52b22b90093776034a8d57d660f9ff27a118f5bf801
+//! cosignature=c1d2d6935c2fb43bef395792b1f3c1dfe4072d4c6cadd05e0cc90b28d7141ed3 1770193051 f0dce1bcdda3a2826479d62e6afedbe9ec06e8f990ae59d8cefa84d9a6ee68c12c2820fb00e1dbdc30044b16c7695a9d1047cec4788dc757f698d34ebaec4305
+//! cosignature=d960fcff859a34d677343e4789c6843e897c9ff195ea7140a6ef382566df3b65 1770193051 b44c41f75566850003f7f655a6dc7bb38bb980e8e2c383871e29883805d3adec7782a08388b9386d9718380a4bb6900043e2b46080cff0fa75a500c36ef9df0a
+//! cosignature=e4a6a1e4657d8d7a187cc0c20ed51055d88c72f340d29534939aee32d86b4021 1770193051 70697b4a6b07e79e49d0a8e41fd7450a593ee9df11da6244cebe4b0c15c8e52f28ad3931b95a806fc7f16b4ad90197971ddc087434c7985b8b3a0223c9fa3603
+//! cosignature=42351ad474b29c04187fd0c8c7670656386f323f02e9a4ef0a0055ec061ecac8 1770193051 6610e5cf4ead2062d9783fbc19d2bae65eded35335495ad0cf0386277ed2d51854ced64efa21a6db0a398fdfb6761aa7d5659e54950a060d167fbdcb7b5ece05
 //!
-//! leaf_index=8857
-//! node_hash=9736194936496bfbea6e571fad7f34519f32a1132c340cff8ae6c071a4ba7320
-//! node_hash=42fb1dfd5f0610ae4e61f91b644c3794a24d1084331db464096beb7c0c9dc11b
-//! node_hash=1c0df8227e8a3a76ab618d421c89afa3923ea5c74c025eec0c53a1109d4c9d28
-//! node_hash=91bc923fa508d27f12ddeae047e7b51a7bb5cc529b173836d66bdd8728eab5c9
-//! node_hash=ca6768bb0e267f5c339e639f02101c73be12efd5dd0462959677a86e22bbb58d
-//! node_hash=e8bb977d7ae35a4b7e591ded5e3d7fad0afee0b958d6309a52f48fe46c679c36
+//! leaf_index=381381
+//! node_hash=d009c5dbeaaa5be1788ea9533f6f398747755a8245012165ac73f753b7917672
+//! node_hash=fb515551fe18f6e53d7d7f49b80abbb5c702b9662ee74fc7730e4a7685000aa4
+//! node_hash=e21e73ee8caf0d49cdcd2f334b3f64e85e4a151daf8d09b6034306bb21b88480
+//! node_hash=f77bc4db00e509149b6e2fc0028d7107dd415929dc9972f32fe758ce39bcc9a0
+//! node_hash=3acb38f01c633d917b899ed4e522a49a02bf20d358f98ca530e3a3065591e7f2
+//! node_hash=889de80c543a5ae8e35430988dc120ac7edde74b776f9082f814ea88190a601f
+//! node_hash=199f812b9f3667dec31f964098e32652477a2f3d458019b6f8f4acc645cf0131
+//! node_hash=084580f8f6324d4ae42dbcb779502ab9fab77e0c2b92519fe089be72e38d60ed
+//! node_hash=9ddbece4939d621df53f31e2729d5fa7802fd82f3edfb784483d8b7fa9cf41e2
+//! node_hash=e1c7a90c09949c263807e5970aef47f9a06164b759995ab814aff94aff9dcd00
 //! ")?;
-//! assert!(verify(&Hash::new(data), &signature, &signers, &policy).is_ok());
+//!
+//! verify(&Hash::new(data), &signature, &signers, &sigsum::policy::SIGSUM_TEST_2025_3)?;
 //! # Ok::<(), Box<dyn Error>>(())
 //! ```
 //!

src/log.rs

@@ -2,8 +2,8 @@
 
 use crate::crypto::{Hash, PublicKey, Signature};
 
-#[derive(Debug, Clone, PartialEq)]
 /// A signed tree head, as returned by the get-tree-head endpoint.
+#[derive(Debug, Clone, PartialEq)]
 pub struct SignedTreeHead {
     pub size: u64,
     pub root_hash: Hash,
@@ -19,23 +19,23 @@ pub struct WitnessCosignature {
     pub cosignature: Signature,
 }
 
-#[derive(Debug, Clone, PartialEq)]
 /// An inclusion proof, as returned by the get-inclusion-proof endpoint.
+#[derive(Debug, Clone, PartialEq)]
 pub struct InclusionProof {
     pub leaf_index: u64,
     pub node_hashes: Vec<Hash>,
 }
 
-#[derive(Debug, Clone, PartialEq)]
 /// A protoleaf, which is the data submitted to the add-leaf endpoint of a Sigsum log.
+#[derive(Debug, Clone, PartialEq)]
 pub struct Protoleaf {
     pub message: Hash,
     pub signature: Signature,
     pub public_key: PublicKey,
 }
 
-#[derive(Debug, Clone, PartialEq)]
 /// A tree leaf, as stored in a sigsum log.
+#[derive(Debug, Clone, PartialEq)]
 pub struct Leaf {
     pub digest: Hash,
     pub signature: Signature,

src/policy/mod.rs

@@ -159,7 +159,7 @@ pub enum PolicyError {
     #[error("duplicate name")]
     DuplicateName(String),
 
-    #[error("{0}: no sutch witness")]
+    #[error("{0}: no such witness")]
     UnknownName(String),
 
     #[error("quorum already set")]

src/policy/parsing.rs

@@ -350,7 +350,7 @@ mod tests {
         );
         insta::assert_snapshot!(
             parse_policy("quorum foo").unwrap_err(),
-            @"line 1: invalid quorum rule: foo: no sutch witness",
+            @"line 1: invalid quorum rule: foo: no such witness",
         );
     }
 

tools/genexample.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+
+# Regenerates the variables for the example in the lib.rs (and the README).
+
+set -eux
+
+tmpdir=$(mktemp -d)
+trap 'rm -rf $tmpdir' EXIT
+
+# We use a throaway key so we don't have a gazillion security scanners spamming
+# us about commiting an OpenSSH private key.
+keyfile="$tmpdir/signer"
+ssh-keygen -t ed25519 -N "" -f "$keyfile"
+
+data="Hello, Sigsum!\n"
+signer=$(go run sigsum.org/sigsum-go/cmd/sigsum-key@v0.14 to-hex -k "${keyfile}.pub")
+signature=$(printf "$data" | go run sigsum.org/sigsum-go/cmd/sigsum-submit@v0.14 -k "$keyfile" -P sigsum-test-2025-3)
+
+printf 'let data = b"%s";\n' "$data"
+printf 'let signers: Vec<PublicKey> =\n    vec![hex!("%s").into()];\n' "$signer";
+printf 'let signature = SigsumSignature::from_ascii("%s\n")?;\n' "$signature";