torchwood: add CosignatureSigner.SignSubtree and CosignatureVerifier.VerifySubtree

Author: FiloSottile

NEWS.md

@@ -8,6 +8,9 @@
 
 - Added ML-DSA-44 cosignature support.
 
+- Added `CosignatureSigner.SignSubtree` and `CosignatureVerifier.VerifySubtree`
+  to sign and verify subtree cosignatures.
+
 - Added `NewCosignatureVerifierFromKey` to produce a verifier from a
   `crypto.PublicKey` instead of a vkey.
 

cosignature.go

@@ -23,6 +23,7 @@ import (
 
 	"golang.org/x/crypto/cryptobyte"
 	"golang.org/x/mod/sumdb/note"
+	"golang.org/x/mod/sumdb/tlog"
 )
 
 const (
@@ -40,7 +41,7 @@ func NewCosignatureSigner(name string, key crypto.Signer) (*CosignatureSigner, e
 	if err != nil {
 		return nil, err
 	}
-	s := &CosignatureSigner{v: *v}
+	s := &CosignatureSigner{v: *v, key: key}
 	switch pubKey.(type) {
 	case ed25519.PublicKey:
 		s.sign = func(msg []byte) ([]byte, error) {
@@ -104,18 +105,6 @@ func formatCosignatureV1(t uint64, msg []byte) ([]byte, error) {
 }
 
 func formatSubtreeV1(name string, t uint64, msg []byte) ([]byte, error) {
-	// The signed message is in the following format
-	//
-	// struct {
-	//     uint8 label[12] = "subtree/v1\n\0";
-	//     opaque cosigner_name<1..2^8-1>;
-	//     uint64 timestamp;
-	//     opaque log_origin<1..2^8-1>;
-	//     uint64 start;
-	//     uint64 end;
-	//     uint8 hash[32];
-	// } cosigned_message;
-
 	c, err := ParseCheckpoint(string(msg))
 	if err != nil {
 		return nil, fmt.Errorf("message being signed is not a valid checkpoint: %w", err)
@@ -128,18 +117,46 @@ func formatSubtreeV1(name string, t uint64, msg []byte) ([]byte, error) {
 	if string(msg) != c.String() {
 		return nil, errors.New("message being signed does not match parsed checkpoint")
 	}
+	return subtreeCosignedMessage(name, t, c.Origin, 0, c.N, c.Hash)
+}
+
+func subtreeCosignedMessage(name string, t uint64, origin string, start, end int64, hash tlog.Hash) ([]byte, error) {
+	// The signed message is in the following format
+	//
+	// struct {
+	//     uint8 label[12] = "subtree/v1\n\0";
+	//     opaque cosigner_name<1..2^8-1>;
+	//     uint64 timestamp;
+	//     opaque log_origin<1..2^8-1>;
+	//     uint64 start;
+	//     uint64 end;
+	//     uint8 hash[32];
+	// } cosigned_message;
+
 	b := &cryptobyte.Builder{}
 	b.AddBytes([]byte("subtree/v1\n\x00"))
+	if len(name) == 0 || len(name) > 255 {
+		return nil, errors.New("cosigner name must be 1-255 bytes")
+	}
 	b.AddUint8LengthPrefixed(func(b *cryptobyte.Builder) {
 		b.AddBytes([]byte(name))
 	})
+	if t > math.MaxInt64 {
+		return nil, errors.New("timestamp is too large")
+	}
+	if t != 0 && start != 0 {
+		return nil, errors.New("timestamp must be zero for non-root subtrees")
+	}
 	b.AddUint64(t)
+	if len(origin) == 0 || len(origin) > 255 {
+		return nil, errors.New("log origin must be 1-255 bytes")
+	}
 	b.AddUint8LengthPrefixed(func(b *cryptobyte.Builder) {
-		b.AddBytes([]byte(c.Origin))
+		b.AddBytes([]byte(origin))
 	})
-	b.AddUint64(0)
-	b.AddUint64(uint64(c.N))
-	b.AddBytes(c.Hash[:])
+	b.AddUint64(uint64(start))
+	b.AddUint64(uint64(end))
+	b.AddBytes(hash[:])
 	return b.Bytes()
 }
 
@@ -148,6 +165,7 @@ func formatSubtreeV1(name string, t uint64, msg []byte) ([]byte, error) {
 type CosignatureSigner struct {
 	v    CosignatureVerifier
 	sign func([]byte) ([]byte, error)
+	key  crypto.Signer
 }
 
 func (s *CosignatureSigner) Name() string                    { return s.v.Name() }
@@ -157,6 +175,37 @@ func (s *CosignatureSigner) Verifier() *CosignatureVerifier  { return &s.v }
 
 var _ note.Signer = &CosignatureSigner{}
 
+// SignSubtree signs a subtree [start, end) with the given hash for the log with
+// the given origin. The timestamp is set to zero. The returned signature is in
+// the format of a note signature, starting with the — and ending with a newline.
+func (s *CosignatureSigner) SignSubtree(origin string, start, end int64, hash tlog.Hash) ([]byte, error) {
+	if _, ok := s.v.PublicKey().(*mldsa.PublicKey); !ok {
+		return nil, errors.New("subtree signatures are only supported for ML-DSA-44 keys")
+	}
+	if !ValidSubtree(start, end) {
+		return nil, errors.New("invalid subtree")
+	}
+
+	m, err := subtreeCosignedMessage(s.Name(), 0, origin, start, end, hash)
+	if err != nil {
+		return nil, err
+	}
+
+	ss, err := s.key.Sign(nil, m, crypto.Hash(0))
+	if err != nil {
+		return nil, err
+	}
+
+	// key hash || timestamp || signature.
+	sig := make([]byte, 0, 4+8+mldsa.MLDSA44SignatureSize)
+	sig = binary.BigEndian.AppendUint32(sig, s.KeyHash())
+	sig = binary.BigEndian.AppendUint64(sig, 0)
+	sig = append(sig, ss...)
+
+	res := "— " + s.Name() + " " + base64.StdEncoding.EncodeToString(sig) + "\n"
+	return []byte(res), nil
+}
+
 // CosignatureVerifier is a [note.Verifier] that verifies cosignatures
 // according to c2sp.org/tlog-cosignature.
 type CosignatureVerifier struct {
@@ -281,6 +330,59 @@ func (v *CosignatureVerifier) PublicKey() crypto.PublicKey {
 	return v.key
 }
 
+// VerifySubtree reports whether signature is a valid cosignature by this
+// verifier over the subtree [start, end) with the given hash for the log with
+// the given origin.
+//
+// signature must be a single note signature line ending in a newline, like the
+// one returned by [CosignatureSigner.SignSubtree], and its key name and hash
+// must match this verifier.
+//
+// Note that a checkpoint cosignature is a valid cosignature over the equivalent
+// subtree, and this method allows non-zero timestamps for root subtrees.
+func (v *CosignatureVerifier) VerifySubtree(origin string, start, end int64, hash tlog.Hash, signature []byte) bool {
+	k, ok := v.key.(*mldsa.PublicKey)
+	if !ok {
+		return false
+	}
+	if !ValidSubtree(start, end) {
+		return false
+	}
+
+	line, ok := strings.CutSuffix(string(signature), "\n")
+	if !ok {
+		return false
+	}
+	line, ok = strings.CutPrefix(line, "— ")
+	if !ok {
+		return false
+	}
+	name, b64, _ := strings.Cut(line, " ")
+	sig, err := base64.StdEncoding.DecodeString(b64)
+	if err != nil || b64 == "" || len(sig) < 4 {
+		return false
+	}
+	if name != v.name || binary.BigEndian.Uint32(sig) != v.hash {
+		return false
+	}
+	sig = sig[4:]
+
+	if len(sig) != 8+mldsa.MLDSA44SignatureSize {
+		return false
+	}
+	t := binary.BigEndian.Uint64(sig)
+	sig = sig[8:]
+	// If start is not zero, the timestamp must be zero.
+	if t > math.MaxInt64 || (start != 0 && t != 0) {
+		return false
+	}
+	m, err := subtreeCosignedMessage(v.name, t, origin, start, end, hash)
+	if err != nil {
+		return false
+	}
+	return mldsa.Verify(k, m, sig, nil) == nil
+}
+
 // String returns the vkey encoding of the verifier, according to
 // c2sp.org/signed-note.
 func (v *CosignatureVerifier) String() string {

cosignature_test.go

@@ -5,11 +5,14 @@ import (
 	"crypto"
 	"crypto/ed25519"
 	"crypto/rand"
+	"encoding/base64"
+	"strings"
 	"testing"
 
 	"filippo.io/mldsa"
 	"filippo.io/torchwood"
 	"golang.org/x/mod/sumdb/note"
+	"golang.org/x/mod/sumdb/tlog"
 )
 
 func TestSignerRoundtrip(t *testing.T) {
@@ -29,6 +32,110 @@ func TestSignerRoundtrip(t *testing.T) {
 	})
 }
 
+func TestSubtreeRoundtrip(t *testing.T) {
+	k, err := mldsa.GenerateKey(mldsa.MLDSA44())
+	if err != nil {
+		t.Fatal(err)
+	}
+	s, err := torchwood.NewCosignatureSigner("witness.example/w1", k)
+	if err != nil {
+		t.Fatal(err)
+	}
+	v := s.Verifier()
+
+	th := tlog.RecordHash([]byte("test"))
+	sig, err := s.SignSubtree("example.com/log", 8, 13, th)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if !v.VerifySubtree("example.com/log", 8, 13, th, sig) {
+		t.Fatal("signature did not verify")
+	}
+
+	if v.VerifySubtree("example.com/other", 8, 13, th, sig) {
+		t.Fatal("expected failure verifying wrong origin")
+	}
+	if v.VerifySubtree("example.com/log", 8, 12, th, sig) {
+		t.Fatal("expected failure verifying wrong range")
+	}
+	if v.VerifySubtree("example.com/log", 4, 12, th, sig) {
+		t.Fatal("expected failure verifying invalid subtree")
+	}
+	th2 := tlog.RecordHash([]byte("test2"))
+	if v.VerifySubtree("example.com/log", 8, 13, th2, sig) {
+		t.Fatal("expected failure verifying wrong hash")
+	}
+
+	// A tampered signature doesn't verify.
+	line, ok := strings.CutPrefix(strings.TrimSuffix(string(sig), "\n"), "— witness.example/w1 ")
+	if !ok {
+		t.Fatalf("unexpected signature line: %q", sig)
+	}
+	raw, err := base64.StdEncoding.DecodeString(line)
+	if err != nil {
+		t.Fatal(err)
+	}
+	raw[len(raw)-1] ^= 1
+	tampered := []byte("— witness.example/w1 " + base64.StdEncoding.EncodeToString(raw) + "\n")
+	if v.VerifySubtree("example.com/log", 8, 13, th, tampered) {
+		t.Fatal("expected failure verifying tampered signature")
+	}
+
+	// A signature line from another key doesn't verify, and multi-line
+	// inputs are rejected.
+	k2, err := mldsa.GenerateKey(mldsa.MLDSA44())
+	if err != nil {
+		t.Fatal(err)
+	}
+	s2, err := torchwood.NewCosignatureSigner("witness.example/w2", k2)
+	if err != nil {
+		t.Fatal(err)
+	}
+	sig2, err := s2.SignSubtree("example.com/log", 8, 13, th)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if v.VerifySubtree("example.com/log", 8, 13, th, sig2) {
+		t.Fatal("expected failure verifying another witness's signature")
+	}
+	both := append(append([]byte{}, sig2...), sig...)
+	if v.VerifySubtree("example.com/log", 8, 13, th, both) {
+		t.Fatal("expected failure verifying multi-line input")
+	}
+
+	// Ed25519 keys can't sign or verify subtrees.
+	_, ek, err := ed25519.GenerateKey(rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	es, err := torchwood.NewCosignatureSigner("witness.example/ed", ek)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := es.SignSubtree("example.com/log", 8, 13, th); err == nil {
+		t.Fatal("expected error signing subtree with Ed25519 key")
+	}
+	if es.Verifier().VerifySubtree("example.com/log", 8, 13, th, sig) {
+		t.Fatal("expected failure verifying with Ed25519 key")
+	}
+
+	// An ML-DSA checkpoint cosignature verifies as a cosignature over the
+	// whole tree.
+	checkpoint := "example.com/log\n123\n" + base64.StdEncoding.EncodeToString(th[:]) + "\n"
+	n, err := note.Sign(&note.Note{Text: checkpoint}, s)
+	if err != nil {
+		t.Fatal(err)
+	}
+	_, checkpointSig, ok := strings.Cut(string(n), "\n\n")
+	if !ok {
+		t.Fatalf("unexpected note: %q", n)
+	}
+	if !v.VerifySubtree("example.com/log", 0, 123, th, []byte(checkpointSig)) {
+		t.Fatal("checkpoint cosignature did not verify as subtree cosignature")
+	}
+}
+
 func testSignerRoundtrip(t *testing.T, k crypto.Signer, extensions bool) {
 	s, err := torchwood.NewCosignatureSigner("example.com", k)
 	if err != nil {