torchwood: implement c2sp.org/tlog-proof formatting and verification

Author: FiloSottile

spicy.go

@@ -0,0 +1,171 @@
+package torchwood
+
+import (
+	"bytes"
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"strconv"
+	"strings"
+
+	"golang.org/x/mod/sumdb/note"
+	"golang.org/x/mod/sumdb/tlog"
+)
+
+// FormatProof formats a tlog record inclusion proof (a "spicy signature") for
+// the record at index idx with proof p and signed checkpoint signedCheckpoint.
+//
+// The returned byte slice is encoded according to c2sp.org/tlog-proof.
+func FormatProof(idx int64, p tlog.RecordProof, signedCheckpoint []byte) []byte {
+	return formatProof(idx, p, signedCheckpoint, nil, false)
+}
+
+// FormatProofWithHint formats a tlog record inclusion proof (a "spicy signature")
+// for the record at index idx with proof p and signed checkpoint signedCheckpoint,
+// including a hint.
+//
+// The returned byte slice is encoded according to c2sp.org/tlog-proof.
+func FormatProofWithHint(idx int64, hint []byte, p tlog.RecordProof, signedCheckpoint []byte) []byte {
+	return formatProof(idx, p, signedCheckpoint, hint, true)
+}
+
+func formatProof(idx int64, p tlog.RecordProof, signedCheckpoint []byte, hint []byte, withHint bool) []byte {
+	var buf bytes.Buffer
+	fmt.Fprintf(&buf, "c2sp.org/tlog-proof\n")
+	fmt.Fprintf(&buf, "index %d\n", idx)
+	if withHint {
+		fmt.Fprintf(&buf, "hint %s\n", base64.StdEncoding.EncodeToString([]byte(hint)))
+	}
+	for _, h := range p {
+		fmt.Fprintf(&buf, "%s\n", h)
+	}
+	fmt.Fprintf(&buf, "\n")
+	buf.Write(signedCheckpoint)
+	return buf.Bytes()
+}
+
+// VerifyRecordError is returned by [VerifyProof] when the inclusion proof does
+// not verify. It can be used to diagnose the issue or print a better error
+// message. All of its fields are unauthenticated and must not be trusted.
+type VerifyRecordError struct {
+	Index int64
+	Hint  []byte
+}
+
+func (e *VerifyRecordError) Error() string {
+	return fmt.Sprintf("tlog record inclusion proof verification failed for index %d", e.Index)
+}
+
+// VerifyProof verifies a proof (a "spicy signature" encoded according to
+// c2sp.org/tlog-proof) 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 {
+	hdr, rest, ok := strings.Cut(string(proof), "\n")
+	if !ok || hdr != "c2sp.org/tlog-proof" {
+		return errors.New("malformed tlog proof: missing header, this may not be a tlog proof")
+	}
+	rest, ok = strings.CutPrefix(rest, "index ")
+	if !ok {
+		return errors.New("malformed tlog proof")
+	}
+	s, rest, ok := strings.Cut(rest, "\n")
+	if !ok {
+		return errors.New("malformed tlog proof")
+	}
+	idx, err := strconv.ParseInt(s, 10, 64)
+	if err != nil {
+		return fmt.Errorf("malformed tlog proof: invalid index: %w", err)
+	}
+	if idx < 0 {
+		return fmt.Errorf("malformed tlog proof: negative index")
+	}
+	var hint []byte
+	if strings.HasPrefix(rest, "hint ") {
+		rest, ok = strings.CutPrefix(rest, "hint ")
+		if !ok {
+			return errors.New("malformed tlog proof")
+		}
+		s, rest, ok = strings.Cut(rest, "\n")
+		if !ok {
+			return errors.New("malformed tlog proof")
+		}
+		hint, err = base64.StdEncoding.DecodeString(s)
+		if err != nil {
+			return fmt.Errorf("malformed tlog proof: invalid hint: %w", err)
+		}
+	}
+	var p tlog.RecordProof
+	for {
+		var h64 string
+		h64, rest, ok = strings.Cut(rest, "\n")
+		if !ok {
+			return errors.New("malformed tlog proof")
+		}
+		if h64 == "" {
+			break
+		}
+		h, err := base64.StdEncoding.DecodeString(h64)
+		if err != nil {
+			return fmt.Errorf("malformed tlog proof: invalid hash: %w", err)
+		}
+		if len(h) != tlog.HashSize {
+			return fmt.Errorf("malformed tlog proof: invalid hash length: got %d, want 32", len(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))
+	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,
+			Hint:  hint,
+		}
+	}
+	return nil
+}
+
+// HintFromProof extracts the hint from a tlog proof encoded according to
+// c2sp.org/tlog-proof. If no hint is present, it returns an error.
+//
+// The hint is unauthenticated and must not be trusted.
+func HintFromProof(proof []byte) ([]byte, error) {
+	hdr, rest, ok := strings.Cut(string(proof), "\n")
+	if !ok || hdr != "c2sp.org/tlog-proof" {
+		return nil, errors.New("malformed tlog proof: missing header, this may not be a tlog proof")
+	}
+	line, rest, ok := strings.Cut(rest, "\n")
+	if !ok || !strings.HasPrefix(line, "index ") {
+		return nil, errors.New("malformed tlog proof")
+	}
+	line, _, ok = strings.Cut(rest, "\n")
+	if !ok {
+		return nil, errors.New("malformed tlog proof")
+	}
+	s, ok := strings.CutPrefix(line, "hint ")
+	if !ok {
+		return nil, errors.New("tlog proof does not contain a hint")
+	}
+	hint, err := base64.StdEncoding.DecodeString(s)
+	if err != nil {
+		return nil, fmt.Errorf("malformed tlog proof: invalid hint: %w", err)
+	}
+	return hint, nil
+}