age,cmd/age,cmd/age-keygen: add post-quantum hybrid keys

Author: FiloSottile

README.md

@@ -12,7 +12,7 @@
 
 age is a simple, modern and secure file encryption tool, format, and Go library.
 
-It features small explicit keys, no config options, and UNIX-style composability.
+It features small explicit keys, post-quantum support, no config options, and UNIX-style composability.
 
 ```
 $ age-keygen -o key.txt
@@ -25,13 +25,13 @@ $ age --decrypt -i key.txt data.tar.gz.age > data.tar.gz
 
 🦀 An alternative interoperable Rust implementation is available at [github.com/str4d/rage](https://github.com/str4d/rage).
 
-🌍 [Typage](https://github.com/FiloSottile/typage) is a TypeScript implementation. It works in the browser, in Node.js, and in Bun.
+🌍 [Typage](https://github.com/FiloSottile/typage) is a TypeScript implementation. It works in the browser, Node.js, Deno, and Bun.
 
 🔑 Hardware PIV tokens such as YubiKeys are supported through the [age-plugin-yubikey](https://github.com/str4d/age-plugin-yubikey) plugin.
 
 ✨ For more plugins, implementations, tools, and integrations, check out the [awesome age](https://github.com/FiloSottile/awesome-age) list.
 
-💬 The author pronounces it `[aɡe̞]` [with a hard *g*](https://translate.google.com/?sl=it&text=aghe), like GIF, and is always spelled lowercase.
+💬 The author pronounces it `[aɡe̞]` [with a hard *g*](https://translate.google.com/?sl=it&text=aghe), like GIF, and it's always spelled lowercase.
 
 ## Installation
 
@@ -229,6 +229,28 @@ $ age -R recipients.txt example.jpg > example.jpg.age
 
 If the argument to `-R` (or `-i`) is `-`, the file is read from standard input.
 
+### Post-quantum keys
+
+To generate hybrid post-quantum keys, which are secure against future quantum
+computer attacks, use the `-pq` flag with `age-keygen`. This may become the
+default in the future.
+
+Post-quantum identities start with `AGE-SECRET-KEY-PQ-1...` and recipients with
+`age1pq1...`. The recipients are unfortunately ~2000 characters long.
+
+```
+$ age-keygen -pq -o key.txt
+$ age-keygen -y key.txt > recipient.txt
+$ age -R recipient.txt example.jpg > example.jpg.age
+$ age -d -i key.txt example.jpg.age > example.jpg
+```
+
+Support for post-quantum keys is built into age v1.3.0 and later. Alternatively,
+the `age-plugin-pq` binary can be installed and placed in `$PATH` to add support
+to any version and implementation of age that supports plugins. Recipients will
+work out of the box, while identities will have to be converted to plugin
+identities with `age-plugin-pq -identity`.
+
 ### Passphrases
 
 Files can be encrypted with a passphrase by using `-p/--passphrase`. By default age will automatically generate a secure passphrase. Passphrase protected files are automatically detected at decrypt time.

age.go

@@ -6,9 +6,9 @@
 // specification.
 //
 // For most use cases, use the [Encrypt] and [Decrypt] functions with
-// [X25519Recipient] and [X25519Identity]. If passphrase encryption is required, use
-// [ScryptRecipient] and [ScryptIdentity]. For compatibility with existing SSH keys
-// use the filippo.io/age/agessh package.
+// [HybridRecipient] and [HybridIdentity]. If passphrase encryption is
+// required, use [ScryptRecipient] and [ScryptIdentity]. For compatibility with
+// existing SSH keys use the filippo.io/age/agessh package.
 //
 // age encrypted files are binary and not malleable. For encoding them as text,
 // use the filippo.io/age/armor package.
@@ -26,13 +26,13 @@
 // There is no default path for age keys. Instead, they should be stored at
 // application-specific paths. The CLI supports files where private keys are
 // listed one per line, ignoring empty lines and lines starting with "#". These
-// files can be parsed with ParseIdentities.
+// files can be parsed with [ParseIdentities].
 //
 // When integrating age into a new system, it's recommended that you only
-// support X25519 keys, and not SSH keys. The latter are supported for manual
-// encryption operations. If you need to tie into existing key management
-// infrastructure, you might want to consider implementing your own Recipient
-// and Identity.
+// support native (X25519 and hybrid) keys, and not SSH keys. The latter are
+// supported for manual encryption operations. If you need to tie into existing
+// key management infrastructure, you might want to consider implementing your
+// own [Recipient] and [Identity].
 //
 // # Backwards compatibility
 //
@@ -52,14 +52,15 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"slices"
 	"sort"
 
 	"filippo.io/age/internal/format"
 	"filippo.io/age/internal/stream"
 )
 
 // An Identity is passed to [Decrypt] to unwrap an opaque file key from a
-// recipient stanza. It can be for example a secret key like [X25519Identity], a
+// recipient stanza. It can be for example a secret key like [HybridIdentity], a
 // plugin, or a custom implementation.
 type Identity interface {
 	// Unwrap must return an error wrapping [ErrIncorrectIdentity] if none of
@@ -76,7 +77,7 @@ type Identity interface {
 var ErrIncorrectIdentity = errors.New("incorrect identity for recipient block")
 
 // A Recipient is passed to [Encrypt] to wrap an opaque file key to one or more
-// recipient stanza(s). It can be for example a public key like [X25519Recipient],
+// recipient stanza(s). It can be for example a public key like [HybridRecipient],
 // a plugin, or a custom implementation.
 type Recipient interface {
 	// Most age API users won't need to interact with this method directly, and
@@ -142,7 +143,7 @@ func Encrypt(dst io.Writer, recipients ...Recipient) (io.WriteCloser, error) {
 		if i == 0 {
 			labels = l
 		} else if !slicesEqual(labels, l) {
-			return nil, fmt.Errorf("incompatible recipients")
+			return nil, incompatibleLabelsError(labels, l)
 		}
 		for _, s := range stanzas {
 			hdr.Recipients = append(hdr.Recipients, (*format.Stanza)(s))
@@ -188,6 +189,15 @@ func slicesEqual(s1, s2 []string) bool {
 	return true
 }
 
+func incompatibleLabelsError(l1, l2 []string) error {
+	hasPQ1 := slices.Contains(l1, "postquantum")
+	hasPQ2 := slices.Contains(l2, "postquantum")
+	if hasPQ1 != hasPQ2 {
+		return fmt.Errorf("incompatible recipients: can't mix post-quantum and classic recipients, or the file would be vulnerable to quantum computers")
+	}
+	return fmt.Errorf("incompatible recipients: %q and %q can't be mixed", l1, l2)
+}
+
 // NoIdentityMatchError is returned by [Decrypt] when none of the supplied
 // identities match the encrypted file.
 type NoIdentityMatchError struct {

agessh/agessh.go

@@ -7,7 +7,7 @@
 // encryption with age-encryption.org/v1.
 //
 // These recipient types should only be used for compatibility with existing
-// keys, and native X25519 keys should be preferred otherwise.
+// keys, and native keys should be preferred otherwise.
 //
 // Note that these recipient types are not anonymous: the encrypted message will
 // include a short 32-bit ID of the public key.

cmd/age-keygen/keygen.go

@@ -18,15 +18,18 @@ import (
 )
 
 const usage = `Usage:
-    age-keygen [-o OUTPUT]
+    age-keygen [-pq] [-o OUTPUT]
     age-keygen -y [-o OUTPUT] [INPUT]
 
 Options:
+    -pq                       Generate a post-quantum hybrid ML-KEM-768 + X25519 key pair.
+                              (This might become the default in the future.)
     -o, --output OUTPUT       Write the result to the file at path OUTPUT.
     -y                        Convert an identity file to a recipients file.
 
-age-keygen generates a new native X25519 key pair, and outputs it to
-standard output or to the OUTPUT file.
+age-keygen generates a new native X25519 or, with the -pq flag, post-quantum
+hybrid ML-KEM-768 + X25519 key pair, and outputs it to standard output or to
+the OUTPUT file.
 
 If an OUTPUT file is specified, the public key is printed to standard error.
 If OUTPUT already exists, it is not overwritten.
@@ -42,6 +45,11 @@ Examples:
     # public key: age1lvyvwawkr0mcnnnncaghunadrqkmuf9e6507x9y920xxpp866cnql7dp2z
     AGE-SECRET-KEY-1N9JEPW6DWJ0ZQUDX63F5A03GX8QUW7PXDE39N8UYF82VZ9PC8UFS3M7XA9
 
+    $ age-keygen -pq
+    # created: 2025-11-17T12:15:17+01:00
+    # public key: age1pq1pd[... 1950 more characters ...]
+    AGE-SECRET-KEY-PQ-1XXC4XS9DXHZ6TREKQTT3XECY8VNNU7GJ83C3Y49D0GZ3ZUME4JWS6QC3EF
+
     $ age-keygen -o key.txt
     Public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
 
@@ -52,12 +60,11 @@ func main() {
 	log.SetFlags(0)
 	flag.Usage = func() { fmt.Fprintf(os.Stderr, "%s\n", usage) }
 
-	var (
-		versionFlag, convertFlag bool
-		outFlag                  string
-	)
+	var outFlag string
+	var pqFlag, versionFlag, convertFlag bool
 
 	flag.BoolVar(&versionFlag, "version", false, "print the version")
+	flag.BoolVar(&pqFlag, "pq", false, "generate a post-quantum key pair")
 	flag.BoolVar(&convertFlag, "y", false, "convert identities to recipients")
 	flag.StringVar(&outFlag, "o", "", "output to `FILE` (default stdout)")
 	flag.StringVar(&outFlag, "output", "", "output to `FILE` (default stdout)")
@@ -68,6 +75,9 @@ func main() {
 	if len(flag.Args()) > 1 && convertFlag {
 		errorf("too many arguments")
 	}
+	if pqFlag && convertFlag {
+		errorf("-pq cannot be used with -y")
+	}
 	if versionFlag {
 		if buildInfo, ok := debug.ReadBuildInfo(); ok {
 			fmt.Println(buildInfo.Main.Version)
@@ -107,23 +117,36 @@ func main() {
 		if fi, err := out.Stat(); err == nil && fi.Mode().IsRegular() && fi.Mode().Perm()&0004 != 0 {
 			warning("writing secret key to a world-readable file")
 		}
-		generate(out)
+		generate(out, pqFlag)
 	}
 }
 
-func generate(out *os.File) {
-	k, err := age.GenerateX25519Identity()
-	if err != nil {
-		errorf("internal error: %v", err)
+func generate(out *os.File, pq bool) {
+	var i age.Identity
+	var r age.Recipient
+	if pq {
+		k, err := age.GenerateHybridIdentity()
+		if err != nil {
+			errorf("internal error: %v", err)
+		}
+		i = k
+		r = k.Recipient()
+	} else {
+		k, err := age.GenerateX25519Identity()
+		if err != nil {
+			errorf("internal error: %v", err)
+		}
+		i = k
+		r = k.Recipient()
 	}
 
 	if !term.IsTerminal(int(out.Fd())) {
-		fmt.Fprintf(os.Stderr, "Public key: %s\n", k.Recipient())
+		fmt.Fprintf(os.Stderr, "Public key: %s\n", r)
 	}
 
 	fmt.Fprintf(out, "# created: %s\n", time.Now().Format(time.RFC3339))
-	fmt.Fprintf(out, "# public key: %s\n", k.Recipient())
-	fmt.Fprintf(out, "%s\n", k)
+	fmt.Fprintf(out, "# public key: %s\n", r)
+	fmt.Fprintf(out, "%s\n", i)
 }
 
 func convert(in io.Reader, out io.Writer) {
@@ -135,11 +158,15 @@ func convert(in io.Reader, out io.Writer) {
 		errorf("no identities found in the input")
 	}
 	for _, id := range ids {
-		id, ok := id.(*age.X25519Identity)
-		if !ok {
+		switch id := id.(type) {
+		case *age.X25519Identity:
+			fmt.Fprintf(out, "%s\n", id.Recipient())
+		case *age.HybridIdentity:
+			fmt.Fprintf(out, "%s\n", id.Recipient())
+		default:
 			errorf("internal error: unexpected identity type: %T", id)
 		}
-		fmt.Fprintf(out, "%s\n", id.Recipient())
+
 	}
 }