torchwood: add Policy and VerifyCheckpoint

Author: FiloSottile

checkpoint.go

@@ -11,6 +11,7 @@ import (
 	"strconv"
 	"strings"
 
+	"golang.org/x/mod/sumdb/note"
 	"golang.org/x/mod/sumdb/tlog"
 )
 
@@ -34,6 +35,7 @@ type Checkpoint struct {
 	Extension string
 }
 
+// ParseCheckpoint parses a c2sp.org/tlog-checkpoint payload without signatures.
 func ParseCheckpoint(text string) (Checkpoint, error) {
 	// This is an extended version of tlog.ParseTree.
 
@@ -78,3 +80,42 @@ func (c Checkpoint) String() string {
 		c.Extension,
 	)
 }
+
+type unverifiedNoteError struct {
+	err error
+	n   *note.Note
+}
+
+func (e *unverifiedNoteError) Error() string {
+	return fmt.Sprintf("note verification failed: %v", e.err)
+}
+
+func (e *unverifiedNoteError) Unwrap() []error {
+	return []error{e.err, &note.UnverifiedNoteError{Note: e.n}}
+}
+
+// VerifyCheckpoint parses and verifies a signed c2sp.org/tlog-checkpoint.
+//
+// If the note signatures do not satisfy the provided policy, an error wrapping
+// *[note.UnverifiedNoteError] is returned.
+func VerifyCheckpoint(origin string, policy Policy, signedCheckpoint []byte) (Checkpoint, *note.Note, error) {
+	// Peek at the origin, if it's wrong, opening will likely fail.
+	if s, _, _ := strings.Cut(string(signedCheckpoint), "\n"); s != origin {
+		return Checkpoint{}, nil, fmt.Errorf("checkpoint origin mismatch: got %q, want %q", s, origin)
+	}
+	n, err := note.Open(signedCheckpoint, policy)
+	if err != nil {
+		return Checkpoint{}, nil, err
+	}
+	if err := policy.Check(n.Sigs); err != nil {
+		return Checkpoint{}, nil, &unverifiedNoteError{err: err, n: n}
+	}
+	c, err := ParseCheckpoint(n.Text)
+	if err != nil {
+		return Checkpoint{}, nil, err
+	}
+	if c.Origin != origin {
+		return Checkpoint{}, nil, fmt.Errorf("checkpoint origin mismatch: got %q, want %q", c.Origin, origin)
+	}
+	return c, n, nil
+}

policy.go

@@ -0,0 +1,200 @@
+package torchwood
+
+import (
+	"errors"
+	"fmt"
+	"strconv"
+	"strings"
+
+	"golang.org/x/mod/sumdb/note"
+)
+
+// Policy encodes the requirements for a set of (co)signatures on a [note.Note].
+//
+// The Verifier method allows the policy to be passed in as the known parameter
+// to [note.Open], while the Check method must be applied to [note.Note.Sigs]
+// after [note.Open].
+type Policy interface {
+	// Check returns nil if the provided signatures satisfy the policy.
+	//
+	// The signatures must already have been verified with their respective
+	// verifiers, and would usually be obtained from [note.Note.Sigs].
+	Check(sigs []note.Signature) error
+
+	// Verifier implements [note.Verifiers], returning the Verifier for any of
+	// the cosigners in the policy.
+	Verifier(name string, hash uint32) (note.Verifier, error)
+}
+
+// SingleVerifierPolicy returns a Policy that requires a single verifier to have
+// signed the note.
+func SingleVerifierPolicy(v note.Verifier) Policy {
+	return &singleVerifierPolicy{v: v}
+}
+
+type singleVerifierPolicy struct {
+	v note.Verifier
+}
+
+func (w *singleVerifierPolicy) Check(sigs []note.Signature) error {
+	for _, sig := range sigs {
+		if sig.Name == w.v.Name() && sig.Hash == w.v.KeyHash() {
+			return nil
+		}
+	}
+	return fmt.Errorf("verifier %q (%08x) did not sign", w.v.Name(), w.v.KeyHash())
+}
+
+func (w *singleVerifierPolicy) Verifier(name string, hash uint32) (note.Verifier, error) {
+	if name == w.v.Name() && hash == w.v.KeyHash() {
+		return w.v, nil
+	}
+	return nil, &note.UnknownVerifierError{Name: name, KeyHash: hash}
+}
+
+// ThresholdPolicy returns a Policy that requires at least n of the
+// provided policies to be satisfied.
+//
+// It panics if n is less than zero or greater than the number of polcies.
+func ThresholdPolicy(n int, policies ...Policy) Policy {
+	if n < 0 || n > len(policies) {
+		panic(fmt.Errorf("threshold of %d outside bounds for policies %s", n, policies))
+	}
+	return &thresholdPolicy{
+		policies:  policies,
+		threshold: n,
+	}
+}
+
+type thresholdPolicy struct {
+	policies  []Policy
+	threshold int
+}
+
+func (w *thresholdPolicy) Check(sigs []note.Signature) error {
+	satisfied := 0
+	for _, p := range w.policies {
+		if err := p.Check(sigs); err == nil {
+			satisfied++
+		}
+	}
+	if satisfied >= w.threshold {
+		return nil
+	}
+	return fmt.Errorf("only %d/%d required policies satisfied", satisfied, w.threshold)
+}
+
+func (w *thresholdPolicy) Verifier(name string, hash uint32) (note.Verifier, error) {
+	var verifier note.Verifier
+	for _, p := range w.policies {
+		v, err := p.Verifier(name, hash)
+		if _, ok := err.(*note.UnknownVerifierError); ok {
+			continue
+		}
+		if err != nil {
+			return nil, err
+		}
+		if verifier != nil {
+			// This, for now, requires not having the same verifier in multiple
+			// groups, which matches the Sigsum policy specification. If we
+			// change our mind, we will need some way to check the verifiers for
+			// equality.
+			return nil, fmt.Errorf("multiple verifiers found for %q (%08x)", name, hash)
+		}
+		verifier = v
+	}
+	if verifier != nil {
+		return verifier, nil
+	}
+	return nil, &note.UnknownVerifierError{Name: name, KeyHash: hash}
+}
+
+// ParsePolicy parses a witness policy from the provided byte slice.
+//
+// As the policy format doesn't currently support specifying a log vkey, the
+// return value would usually be paired with a [note.Verifier] with
+// [ThresholdPolicy] and a threshold of 2-of-2. The log origin also needs to be
+// passed to [VerifyProof] or [VerifyCheckpoint].
+//
+// The policy format is EXPERIMENTAL and may change in future releases. It is
+// based on [the Sigsum policy format] but it uses vkeys instead of raw public
+// keys. It is compatible with Tessera witness policies.
+//
+// [the Sigsum policy format]: https://git.glasklar.is/sigsum/core/sigsum-go/-/blob/main/doc/policy.md
+func ParsePolicy(p []byte) (Policy, error) {
+	var quorum string
+	policies := make(map[string]Policy)
+	for i, line := range strings.Split(string(p), "\n") {
+		line, _, _ = strings.Cut(line, "#")
+		if strings.Trim(line, " \t") == "" {
+			continue
+		}
+		switch fields := strings.Fields(line); fields[0] {
+		case "witness":
+			if len(fields) < 3 {
+				return nil, fmt.Errorf("line %d: invalid witness definition: %q", i+1, line)
+			}
+			name, vkey := fields[1], fields[2]
+			if _, ok := policies[name]; ok {
+				return nil, fmt.Errorf("line %d: duplicate component name: %q", i+1, name)
+			}
+			v, err := NewCosignatureVerifier(vkey)
+			if err != nil {
+				return nil, fmt.Errorf("line %d: invalid witness vkey %q: %w", i+1, vkey, err)
+			}
+			policies[name] = SingleVerifierPolicy(v)
+		case "group":
+			if len(fields) < 4 {
+				return nil, fmt.Errorf("line %d: invalid group definition: %q", i+1, line)
+			}
+			name, nStr, children := fields[1], fields[2], fields[3:]
+			if _, ok := policies[name]; ok {
+				return nil, fmt.Errorf("line %d: duplicate component name: %q", i+1, name)
+			}
+			var n int
+			switch nStr {
+			case "any":
+				n = 1
+			case "all":
+				n = len(children)
+			default:
+				var err error
+				n, err = strconv.Atoi(nStr)
+				if err != nil || n < 1 || n > len(children) {
+					return nil, fmt.Errorf("line %d: invalid group threshold %q", i+1, nStr)
+				}
+			}
+			c := make([]Policy, 0, len(children))
+			for _, cn := range children {
+				child, ok := policies[cn]
+				if !ok {
+					return nil, fmt.Errorf("line %d: unknown component %q in group %q definition", i+1, cn, name)
+				}
+				c = append(c, child)
+			}
+			policies[name] = ThresholdPolicy(n, c...)
+		case "quorum":
+			if len(fields) != 2 {
+				return nil, fmt.Errorf("line %d: invalid quorum definition: %q", i+1, line)
+			}
+			if quorum != "" {
+				return nil, fmt.Errorf("line %d: multiple quorum definitions", i+1)
+			}
+			quorum = fields[1]
+		default:
+			return nil, fmt.Errorf("line %d: unknown keyword: %q", i+1, fields[0])
+		}
+	}
+	switch quorum {
+	case "":
+		return nil, errors.New("no quorum defined in policy")
+	case "none":
+		return ThresholdPolicy(0), nil
+	default:
+		policy, ok := policies[quorum]
+		if !ok {
+			return nil, fmt.Errorf("quorum %q not defined in policy", quorum)
+		}
+		return policy, nil
+	}
+}

spicy.go

@@ -8,7 +8,6 @@ import (
 	"strconv"
 	"strings"
 
-	"golang.org/x/mod/sumdb/note"
 	"golang.org/x/mod/sumdb/tlog"
 )
 
@@ -60,11 +59,11 @@ func (e *VerifyRecordError) Error() string {
 // c2sp.org/tlog-sig@v1) for a record hash rh (generally produced with
 // [tlog.RecordHash]).
 //
-// The origin must match the log's origin, and the open function will be used to
-// verify the signed checkpoint included in the proof. If open returns an error,
-// it is returned directly. If the proof is valid but does not verify the record
-// hash rh at the given index, a *[VerifyRecordError] is returned.
-func VerifyProof(origin string, open func([]byte) (*note.Note, error), rh tlog.Hash, proof []byte) error {
+// If the note signatures do not satisfy the provided policy, an error wrapping
+// *[note.UnverifiedNoteError] is returned. If the proof is valid but does not
+// verify the record hash rh at the given index, a *[VerifyRecordError] is
+// returned.
+func VerifyProof(origin string, policy Policy, rh tlog.Hash, proof []byte) error {
 	hdr, rest, ok := strings.Cut(string(proof), "\n")
 	if !ok || hdr != "c2sp.org/tlog-sig@v1" {
 		return errors.New("malformed tlog proof: missing header, this may not be a tlog proof")
@@ -116,21 +115,10 @@ func VerifyProof(origin string, open func([]byte) (*note.Note, error), rh tlog.H
 		}
 		p = append(p, tlog.Hash(h))
 	}
-	// Peek at the origin, if it's wrong, opening will likely fail.
-	if s, _, _ := strings.Cut(rest, "\n"); s != origin {
-		return fmt.Errorf("proof origin mismatch: got %q, want %q", s, origin)
-	}
-	n, err := open([]byte(rest))
+	c, _, err := VerifyCheckpoint(origin, policy, []byte(rest))
 	if err != nil {
 		return err
 	}
-	c, err := ParseCheckpoint(n.Text)
-	if err != nil {
-		return fmt.Errorf("invalid checkpoint in proof: %w", err)
-	}
-	if c.Origin != origin {
-		return fmt.Errorf("checkpoint origin mismatch: got %q, want %q", c.Origin, origin)
-	}
 	if err := tlog.CheckRecord(p, c.N, c.Hash, idx, rh); err != nil {
 		return &VerifyRecordError{
 			Index: idx,