|
| 1 | +package checkpoint |
| 2 | + |
| 3 | +import ( |
| 4 | + "encoding/base64" |
| 5 | + "errors" |
| 6 | + "fmt" |
| 7 | + "strconv" |
| 8 | + "strings" |
| 9 | + "unicode/utf8" |
| 10 | + |
| 11 | + "golang.org/x/mod/sumdb/note" |
| 12 | + "golang.org/x/mod/sumdb/tlog" |
| 13 | +) |
| 14 | + |
| 15 | +// Checkpoint represents a tlog-checkpoint note text. |
| 16 | +// |
| 17 | +// https://c2sp.org/tlog-checkpoint |
| 18 | +type Checkpoint struct { |
| 19 | + Origin string |
| 20 | + Tree tlog.Tree |
| 21 | + Extensions []string |
| 22 | +} |
| 23 | + |
| 24 | +// checkNoteText returns an error if text cannot be a signed note's text, nil |
| 25 | +// otherwise. https://c2sp.org/signed-note requires note text to be valid UTF-8 |
| 26 | +// with no ASCII control characters (those below U+0020) other than newline. |
| 27 | +func checkNoteText(text string) error { |
| 28 | + switch { |
| 29 | + case !utf8.ValidString(text): |
| 30 | + return errors.New("not valid UTF-8") |
| 31 | + |
| 32 | + case strings.ContainsFunc(text, func(r rune) bool { return r < 0x20 && r != '\n' }): |
| 33 | + return errors.New("contains an ASCII control character other than newline") |
| 34 | + |
| 35 | + default: |
| 36 | + return nil |
| 37 | + } |
| 38 | +} |
| 39 | + |
| 40 | +// checkNoteField returns an error if field contains a newline, the note's line |
| 41 | +// delimiter, nil otherwise. |
| 42 | +func checkNoteField(field string) error { |
| 43 | + if strings.ContainsRune(field, '\n') { |
| 44 | + return errors.New("contains a newline") |
| 45 | + } |
| 46 | + return nil |
| 47 | +} |
| 48 | + |
| 49 | +// validate returns an error if the checkpoint's fields violate the |
| 50 | +// tlog-checkpoint requirements, nil otherwise. |
| 51 | +func (c *Checkpoint) validate() error { |
| 52 | + if c.Origin == "" { |
| 53 | + return errors.New("empty checkpoint origin") |
| 54 | + } |
| 55 | + err := checkNoteField(c.Origin) |
| 56 | + if err != nil { |
| 57 | + return fmt.Errorf("validating checkpoint origin: %w", err) |
| 58 | + } |
| 59 | + if c.Tree.N < 0 { |
| 60 | + return fmt.Errorf("negative checkpoint tree size %d", c.Tree.N) |
| 61 | + } |
| 62 | + for _, ext := range c.Extensions { |
| 63 | + if ext == "" { |
| 64 | + return errors.New("empty checkpoint extension line") |
| 65 | + } |
| 66 | + err := checkNoteField(ext) |
| 67 | + if err != nil { |
| 68 | + return fmt.Errorf("validating checkpoint extension line: %w", err) |
| 69 | + } |
| 70 | + } |
| 71 | + return nil |
| 72 | +} |
| 73 | + |
| 74 | +// Marshal returns the note text, first checking the checkpoint against the |
| 75 | +// tlog-checkpoint requirements. It returns an error if the checkpoint is |
| 76 | +// invalid. |
| 77 | +// |
| 78 | +// - https://c2sp.org/tlog-checkpoint |
| 79 | +// - https://c2sp.org/signed-note |
| 80 | +func (c *Checkpoint) Marshal() (string, error) { |
| 81 | + err := c.validate() |
| 82 | + if err != nil { |
| 83 | + return "", err |
| 84 | + } |
| 85 | + |
| 86 | + var b strings.Builder |
| 87 | + fmt.Fprintf(&b, "%s\n%d\n%s\n", c.Origin, c.Tree.N, c.Tree.Hash) |
| 88 | + for _, ext := range c.Extensions { |
| 89 | + b.WriteString(ext) |
| 90 | + b.WriteByte('\n') |
| 91 | + } |
| 92 | + text := b.String() |
| 93 | + err = checkNoteText(text) |
| 94 | + if err != nil { |
| 95 | + return "", fmt.Errorf("validating checkpoint note text: %w", err) |
| 96 | + } |
| 97 | + return text, nil |
| 98 | +} |
| 99 | + |
| 100 | +// Unmarshal parses a checkpoint note text. The text must not have any signature |
| 101 | +// lines. For a signed note, use Open. |
| 102 | +// |
| 103 | +// - https://c2sp.org/tlog-checkpoint |
| 104 | +// - https://c2sp.org/signed-note |
| 105 | +func Unmarshal(text string) (*Checkpoint, error) { |
| 106 | + err := checkNoteText(text) |
| 107 | + if err != nil { |
| 108 | + return nil, fmt.Errorf("validating checkpoint note text: %w", err) |
| 109 | + } |
| 110 | + if !strings.HasSuffix(text, "\n") { |
| 111 | + return nil, errors.New("checkpoint does not end in newline") |
| 112 | + } |
| 113 | + lines := strings.Split(strings.TrimSuffix(text, "\n"), "\n") |
| 114 | + if len(lines) < 3 { |
| 115 | + return nil, fmt.Errorf("checkpoint has %d lines, want at least 3", len(lines)) |
| 116 | + } |
| 117 | + |
| 118 | + size, err := strconv.ParseInt(lines[1], 10, 64) |
| 119 | + if err != nil { |
| 120 | + return nil, fmt.Errorf("checkpoint tree size: %w", err) |
| 121 | + } |
| 122 | + if size < 0 { |
| 123 | + return nil, fmt.Errorf("negative checkpoint tree size %d", size) |
| 124 | + } |
| 125 | + if strconv.FormatInt(size, 10) != lines[1] { |
| 126 | + return nil, errors.New("checkpoint tree size has a leading zero or sign") |
| 127 | + } |
| 128 | + |
| 129 | + hashBytes, err := base64.StdEncoding.DecodeString(lines[2]) |
| 130 | + if err != nil { |
| 131 | + return nil, fmt.Errorf("checkpoint root hash: %w", err) |
| 132 | + } |
| 133 | + if len(hashBytes) != tlog.HashSize { |
| 134 | + return nil, fmt.Errorf("checkpoint root hash is %d bytes, want %d", len(hashBytes), tlog.HashSize) |
| 135 | + } |
| 136 | + if base64.StdEncoding.EncodeToString(hashBytes) != lines[2] { |
| 137 | + return nil, errors.New("checkpoint root hash is not canonical base64") |
| 138 | + } |
| 139 | + var hash tlog.Hash |
| 140 | + copy(hash[:], hashBytes) |
| 141 | + |
| 142 | + c := &Checkpoint{Origin: lines[0], Tree: tlog.Tree{N: size, Hash: hash}, Extensions: lines[3:]} |
| 143 | + return c, c.validate() |
| 144 | +} |
| 145 | + |
| 146 | +// Open opens a signed checkpoint note and parses its text. An error is returned |
| 147 | +// if signedNote is not a well-formed note, if any of the verifiers rejects a |
| 148 | +// signature (note.InvalidSignatureError), if none of the verifiers has signed |
| 149 | +// the note (note.UnverifiedNoteError), or if the note's text is not a |
| 150 | +// well-formed checkpoint. Signatures from unknown keys are ignored. |
| 151 | +// |
| 152 | +// - https://c2sp.org/tlog-checkpoint |
| 153 | +// - https://c2sp.org/signed-note |
| 154 | +func Open(signedNote []byte, verifiers note.Verifiers) (*Checkpoint, *note.Note, error) { |
| 155 | + n, err := note.Open(signedNote, verifiers) |
| 156 | + if err != nil { |
| 157 | + return nil, nil, err |
| 158 | + } |
| 159 | + c, err := Unmarshal(n.Text) |
| 160 | + if err != nil { |
| 161 | + return nil, nil, err |
| 162 | + } |
| 163 | + return c, n, nil |
| 164 | +} |
0 commit comments