SIGSUM.md: add release playbook

Updates #617

.github/workflows/build.yml

@@ -86,6 +86,11 @@ jobs:
           mkdir "$DIR/age"
           git archive --format=tar.gz HEAD | tar -xz -C "$DIR/age"
           ( cd "$DIR/age"; go mod vendor )
+          for cmd in "$DIR"/age/{cmd,extra}/*; do
+            echo "package main" >> "$cmd/version.go"
+            echo "" >> "$cmd/version.go"
+            echo "func init() { Version = \"$VERSION\" }" >> "$cmd/version.go"
+          done
           tar -cvzf "age-$VERSION-source.tar.gz" -C "$DIR" age
       - name: Upload workflow artifacts
         uses: actions/upload-artifact@v4

README.md

@@ -151,7 +151,7 @@ On Windows, Linux, macOS, and FreeBSD you can use the pre-built binaries.
 
 ```
 https://dl.filippo.io/age/latest?for=linux/amd64
-https://dl.filippo.io/age/v1.3.0?for=darwin/arm64
+https://dl.filippo.io/age/v1.3.1?for=darwin/arm64
 ...
 ```
 

SIGSUM.md

@@ -11,13 +11,32 @@ ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIM1WpnEswJLPzvXJDiswowy48U+G+G1kmgwUE2eaRHZG
 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAz2WM5CyPLqiNjk7CLl4roDXwKhQ0QExXLebukZEZFS
 EOF
 
-curl -JLO "https://dl.filippo.io/age/v1.3.0?for=darwin/arm64"
-curl -JLO "https://dl.filippo.io/age/v1.3.0?for=darwin/arm64&proof"
+curl -JLO "https://dl.filippo.io/age/v1.3.1?for=darwin/arm64"
+curl -JLO "https://dl.filippo.io/age/v1.3.1?for=darwin/arm64&proof"
 
 go install sigsum.org/sigsum-go/cmd/sigsum-verify@v0.13.1
 sigsum-verify -k age-sigsum-key.pub -P sigsum-generic-2025-1 \
-    age-v1.3.0-darwin-arm64.tar.gz.proof < age-v1.3.0-darwin-arm64.tar.gz
+    age-v1.3.1-darwin-arm64.tar.gz.proof < age-v1.3.1-darwin-arm64.tar.gz
 ```
 
 You can learn more about what's happening above in the [Sigsum
 docs](https://www.sigsum.org/getting-started/).
+
+### Release playbook
+
+Dear future me, to sign a new release and produce Sigsum proofs, run the following
+
+```
+VERSION=v1.3.1
+go install sigsum.org/sigsum-go/cmd/sigsum-verify@latest
+go install github.com/tillitis/tkey-ssh-agent/cmd/tkey-ssh-agent@latest
+tkey-ssh-agent --agent-socket tkey-ssh-agent.sock --uss
+SSH_AUTH_SOCK=tkey-ssh-agent.sock ssh-add -L > tkey-ssh-agent.pub
+passage other/sigsum-ratelimit > sigsum-ratelimit
+gh release download $VERSION --dir artifacts/
+SSH_AUTH_SOCK=tkey-ssh-agent.sock sigsum-submit -k tkey-ssh-agent.pub -P sigsum-generic-2025-1 -a sigsum-ratelimit -d filippo.io artifacts/*
+gh release upload $VERSION artifacts/*.proof
+```
+
+In the future, we will move to reproducing the artifacts locally, and signing
+those instead of the ones built by GitHub Actions.

cmd/age-inspect/inspect.go

@@ -24,6 +24,10 @@ Options:
 INPUT defaults to standard input. "-" may be used as INPUT to explicitly
 read from standard input.`
 
+// Version can be set at link time to override debug.BuildInfo.Main.Version when
+// building manually without git history. It should look like "v1.2.3".
+var Version string
+
 func main() {
 	flag.Usage = func() { fmt.Fprintf(os.Stderr, "%s\n", usage) }
 
@@ -37,11 +41,10 @@ func main() {
 	flag.Parse()
 
 	if versionFlag {
-		if buildInfo, ok := debug.ReadBuildInfo(); ok {
-			fmt.Println(buildInfo.Main.Version)
-			return
+		if buildInfo, ok := debug.ReadBuildInfo(); ok && Version == "" {
+			Version = buildInfo.Main.Version
 		}
-		fmt.Println("(unknown)")
+		fmt.Println(Version)
 		return
 	}
 

cmd/age-keygen/keygen.go

@@ -56,6 +56,10 @@ Examples:
     $ age-keygen -y key.txt
     age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p`
 
+// Version can be set at link time to override debug.BuildInfo.Main.Version when
+// building manually without git history. It should look like "v1.2.3".
+var Version string
+
 func main() {
 	log.SetFlags(0)
 	flag.Usage = func() { fmt.Fprintf(os.Stderr, "%s\n", usage) }
@@ -69,6 +73,15 @@ func main() {
 	flag.StringVar(&outFlag, "o", "", "output to `FILE` (default stdout)")
 	flag.StringVar(&outFlag, "output", "", "output to `FILE` (default stdout)")
 	flag.Parse()
+
+	if versionFlag {
+		if buildInfo, ok := debug.ReadBuildInfo(); ok && Version == "" {
+			Version = buildInfo.Main.Version
+		}
+		fmt.Println(Version)
+		return
+	}
+
 	if len(flag.Args()) != 0 && !convertFlag {
 		errorf("too many arguments")
 	}
@@ -78,14 +91,6 @@ func main() {
 	if pqFlag && convertFlag {
 		errorf("-pq cannot be used with -y")
 	}
-	if versionFlag {
-		if buildInfo, ok := debug.ReadBuildInfo(); ok {
-			fmt.Println(buildInfo.Main.Version)
-			return
-		}
-		fmt.Println("(unknown)")
-		return
-	}
 
 	out := os.Stdout
 	if outFlag != "" {

cmd/age-plugin-batchpass/plugin-batchpass.go

@@ -7,6 +7,7 @@ import (
 	"io"
 	"log"
 	"os"
+	"runtime/debug"
 	"strconv"
 	"strings"
 
@@ -73,6 +74,10 @@ When decrypting, you can set AGE_PASSPHRASE_MAX_WORK_FACTOR to limit the
 maximum scrypt work factor accepted (between 1 and 30, default 30). This can
 be used to avoid very slow decryptions.`
 
+// Version can be set at link time to override debug.BuildInfo.Main.Version when
+// building manually without git history. It should look like "v1.2.3".
+var Version string
+
 func main() {
 	flag.Usage = func() { fmt.Fprintf(os.Stderr, "%s\n", usage) }
 
@@ -80,6 +85,19 @@ func main() {
 	if err != nil {
 		log.Fatal(err)
 	}
+	p.RegisterFlags(nil)
+
+	versionFlag := flag.Bool("version", false, "print the version")
+	flag.Parse()
+
+	if *versionFlag {
+		if buildInfo, ok := debug.ReadBuildInfo(); ok && Version == "" {
+			Version = buildInfo.Main.Version
+		}
+		fmt.Println(Version)
+		return
+	}
+
 	p.HandleIdentityAsRecipient(func(data []byte) (age.Recipient, error) {
 		if len(data) != 0 {
 			return nil, fmt.Errorf("batchpass identity does not take any payload")

cmd/age/age.go

@@ -98,6 +98,10 @@ func (f *identityFlags) addPluginFlag(value string) error {
 	return nil
 }
 
+// Version can be set at link time to override debug.BuildInfo.Main.Version when
+// building manually without git history. It should look like "v1.2.3".
+var Version string
+
 func main() {
 	flag.Usage = func() { fmt.Fprintf(os.Stderr, "%s\n", usage) }
 
@@ -136,13 +140,10 @@ func main() {
 	flag.Parse()
 
 	if versionFlag {
-		if buildInfo, ok := debug.ReadBuildInfo(); ok {
-			// TODO: use buildInfo.Settings to prepare a pseudoversion such as
-			// v0.0.0-20210817164053-32db794688a5+dirty on Go 1.18+.
-			fmt.Println(buildInfo.Main.Version)
-			return
+		if buildInfo, ok := debug.ReadBuildInfo(); ok && Version == "" {
+			Version = buildInfo.Main.Version
 		}
-		fmt.Println("(unknown)")
+		fmt.Println(Version)
 		return
 	}
 

doc/age-keygen.1

@@ -53,7 +53,7 @@ AGE\-SECRET\-KEY\-1N9JEPW6DWJ0ZQUDX63F5A03GX8QUW7PXDE39N8UYF82VZ9PC8UFS3M7XA9
 Write a new post\-quantum identity to \fBkey\.txt\fR:
 .IP "" 4
 .nf
-$ age\-keygen \-o key\.txt
+$ age\-keygen \-pq \-o key\.txt
 Public key: age1pq1cd[\|\.\|\.\|\. 1950 more characters \|\.\|\.\|\.]
 .fi
 .IP "" 0

doc/age-keygen.1.html

@@ -130,7 +130,7 @@ AGE-SECRET-KEY-1N9JEPW6DWJ0ZQUDX63F5A03GX8QUW7PXDE39N8UYF82VZ9PC8UFS3M7XA9
 
 <p>Write a new post-quantum identity to <code>key.txt</code>:</p>
 
-<pre><code>$ age-keygen -o key.txt
+<pre><code>$ age-keygen -pq -o key.txt
 Public key: age1pq1cd[... 1950 more characters ...]
 </code></pre>
 

doc/age-keygen.1.ronn

@@ -52,7 +52,7 @@ Generate a new traditional identity:
 
 Write a new post-quantum identity to `key.txt`:
 
-    $ age-keygen -o key.txt
+    $ age-keygen -pq -o key.txt
     Public key: age1pq1cd[... 1950 more characters ...]
 
 Convert an identity to a recipient:

extra/age-plugin-pq/plugin-pq.go

@@ -30,12 +30,16 @@ implementation of age that supports plugins.
 Recipients work out of the box, while identities need to be converted to plugin
 identities with -identity. If OUTPUT already exists, it is not overwritten.`
 
+// Version can be set at link time to override debug.BuildInfo.Main.Version when
+// building manually without git history. It should look like "v1.2.3".
+var Version string
+
 func main() {
 	log.SetFlags(0)
 
 	p, err := plugin.New("pq")
 	if err != nil {
-		log.Fatal(err)
+		errorf("failed to create plugin: %v", err)
 	}
 	p.RegisterFlags(nil)
 
@@ -50,11 +54,10 @@ func main() {
 	flag.Parse()
 
 	if versionFlag {
-		if buildInfo, ok := debug.ReadBuildInfo(); ok {
-			fmt.Println(buildInfo.Main.Version)
-			return
+		if buildInfo, ok := debug.ReadBuildInfo(); ok && Version == "" {
+			Version = buildInfo.Main.Version
 		}
-		fmt.Println("(unknown)")
+		fmt.Println(Version)
 		return
 	}
 

extra/age-plugin-tag/plugin-tag.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"log"
 	"os"
+	"runtime/debug"
 
 	"filippo.io/age"
 	"filippo.io/age/plugin"
@@ -18,6 +19,10 @@ support to any version and implementation of age that supports plugins.
 Usually, tagged recipients are the public side of private keys held in hardware,
 where the identity side is handled by a different plugin.`
 
+// Version can be set at link time to override debug.BuildInfo.Main.Version when
+// building manually without git history. It should look like "v1.2.3".
+var Version string
+
 func main() {
 	flag.Usage = func() { fmt.Fprintf(os.Stderr, "%s\n", usage) }
 
@@ -25,8 +30,22 @@ func main() {
 	if err != nil {
 		log.Fatal(err)
 	}
+	p.RegisterFlags(nil)
+
+	versionFlag := flag.Bool("version", false, "print the version")
+	flag.Parse()
+
+	if *versionFlag {
+		if buildInfo, ok := debug.ReadBuildInfo(); ok && Version == "" {
+			Version = buildInfo.Main.Version
+		}
+		fmt.Println(Version)
+		return
+	}
+
 	p.HandleRecipient(func(b []byte) (age.Recipient, error) {
 		return tag.NewClassicRecipient(b)
 	})
+
 	os.Exit(p.Main())
 }

extra/age-plugin-tagpq/plugin-tagpq.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"log"
 	"os"
+	"runtime/debug"
 
 	"filippo.io/age"
 	"filippo.io/age/plugin"
@@ -19,6 +20,10 @@ implementation of age that supports plugins.
 Usually, tagged recipients are the public side of private keys held in hardware,
 where the identity side is handled by a different plugin.`
 
+// Version can be set at link time to override debug.BuildInfo.Main.Version when
+// building manually without git history. It should look like "v1.2.3".
+var Version string
+
 func main() {
 	flag.Usage = func() { fmt.Fprintf(os.Stderr, "%s\n", usage) }
 
@@ -26,8 +31,22 @@ func main() {
 	if err != nil {
 		log.Fatal(err)
 	}
+	p.RegisterFlags(nil)
+
+	versionFlag := flag.Bool("version", false, "print the version")
+	flag.Parse()
+
+	if *versionFlag {
+		if buildInfo, ok := debug.ReadBuildInfo(); ok && Version == "" {
+			Version = buildInfo.Main.Version
+		}
+		fmt.Println(Version)
+		return
+	}
+
 	p.HandleRecipient(func(b []byte) (age.Recipient, error) {
 		return tag.NewHybridRecipient(b)
 	})
+
 	os.Exit(p.Main())
 }