Go cipher.NewGCMWithRandomNonce 怎样让 Seal 自动携带随机 nonce

如果你使用 AES-GCM 时不想在每次调用 Seal 前手动创建 nonce，可以在 Go 1.24 及以上使用 cipher.NewGCMWithRandomNonce。它返回的 AEAD 会在 Seal 时自动生成随机 nonce，并把 nonce 放在密文前面；解密端调用 Open 时传入同样的 nil nonce，函数会从密文中取出 nonce。

官方文档：https://pkg.go.dev/crypto/cipher#NewGCMWithRandomNonce

最小调用形式是 ciphertext := aead.Seal(nil, nil, plaintext, nil)，对应的解密形式是 plaintext, err := aead.Open(nil, nil, ciphertext, nil)。这里的两个 nil 分别是 nonce 和附加认证数据；没有附加数据时才这样写。

NewGCMWithRandomNonce 改变了什么

传统的 cipher.NewGCM 要求调用者自己准备一个与 NonceSize() 匹配的 nonce，并保证同一把密钥不重复使用 nonce。NewGCMWithRandomNonce 把这段容易遗漏的管理动作收进 AEAD：它为每次 Seal 生成 96 位随机 nonce，写入结果的前部，Open 再从密文前部提取。

这个 API 有三个容易忽略的返回值特征：

• aead.NonceSize() 返回 0，因为调用者不再提供 nonce。
• aead.Overhead() 返回 28，包含 12 字节 nonce 和 16 字节认证标签。
• 它要求传入的 block cipher 由 crypto/aes.NewCipher 创建，不能把任意实现当作参数。

因此，输出密文长度大致是明文长度加 28。保存或传输时必须把完整的 Seal 返回值作为一个整体处理，不能只截取认证标签之后的部分。

创建支持随机 nonce 的 AES-GCM AEAD

先创建 AES block，再交给 NewGCMWithRandomNonce。示例使用 32 字节字符串生成 AES-256 密钥；真实项目应从密钥管理系统读取，不要把密钥硬编码进源码。

package main

import (
	"crypto/aes"
	"crypto/cipher"
	"fmt"
	"log"
)

func main() {
	// 这里只用固定长度示例密钥演示 API；生产代码应从安全的密钥管理系统读取。
	key := []byte("0123456789abcdef0123456789abcdef")
	block, err := aes.NewCipher(key)
	if err != nil {
		log.Fatal(err)
	}

	// 该构造器让 Seal 自动生成并携带随机 nonce。
	aead, err := cipher.NewGCMWithRandomNonce(block)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("nonce size:", aead.NonceSize())
	fmt.Println("overhead:", aead.Overhead())
}

如果项目仍需要兼容旧版本 Go，就不能直接假定这个函数存在，应在升级 Go 版本后再采用这套调用方式，或者继续使用传统的 NewGCM 并自行管理 nonce。

调用 Seal 让密文自动带上 nonce

随机 nonce 的关键在于第二个参数传入 nil。不要为了“填满参数”传入一段自己生成的 nonce，否则就偏离了这个 API 的设计。第四个参数是附加认证数据，如果协议中没有需要认证但不加密的元数据，也传入 nil。

plaintext := []byte("order:20261028;amount:199")

// nonce 由 AEAD 内部随机生成，并被放到返回密文的前部。
ciphertext := aead.Seal(nil, nil, plaintext, nil)
fmt.Printf("ciphertext bytes: %d\n", len(ciphertext))

// 同一份完整密文应原样保存或发送，不能丢弃前面的随机 nonce。
payload := append([]byte(nil), ciphertext...)
_ = payload

如果还要认证请求头、租户编号等不应加密的字段，可以把这些字段编码成稳定字节后作为第四个参数传入。解密时必须传入完全相同的附加数据，否则认证会失败。

调用 Open 自动提取 nonce

解密端不需要单独切出 nonce，也不需要调用 NonceSize 计算切片范围。把保存下来的完整密文传给 Open，并让 nonce 参数保持 nil 即可。

// ciphertext 必须是 Seal 返回的完整字节序列。
recovered, err := aead.Open(nil, nil, ciphertext, nil)
if err != nil {
	// 认证失败、密文过短或密钥不匹配时都不能继续使用结果。
	log.Fatal(err)
}

fmt.Println(string(recovered))

Open 不仅负责解密，还会校验认证标签。密文被修改、附加数据不同、密钥不同，都会返回错误。生产代码应把错误视为“数据不可接受”，不要把部分结果当成已解密内容继续处理。

密文存储时要注意哪些边界

这个方案适合把一条消息整体加密后存储或传输。可以直接保存二进制，也可以在协议层使用 Base64；无论采用哪种格式，都要保留 Seal 的全部输出。一个常见的记录结构是“版本号 + 密文”，其中密文内部已经包含随机 nonce。

官方文档给出的随机 nonce 复用边界是：同一把密钥不要加密超过 2^32 条消息。业务量较大的系统应设计密钥轮换和密文版本字段，轮换后仍要能够根据版本找到正确的解密密钥。

完整的最小示例

下面把创建、加密和解密串起来。示例用十六进制输出密文，便于观察每次加密都会得到不同的字节序列；它不是线上安全配置示例。

package main

import (
	"crypto/aes"
	"crypto/cipher"
	"encoding/hex"
	"fmt"
	"log"
)

func main() {
	// 示例密钥长度为 32 字节，对应 AES-256；生产环境不要硬编码。
	key := []byte("0123456789abcdef0123456789abcdef")
	block, err := aes.NewCipher(key)
	if err != nil {
		log.Fatal(err)
	}
	aead, err := cipher.NewGCMWithRandomNonce(block)
	if err != nil {
		log.Fatal(err)
	}

	plaintext := []byte("hello random nonce")
	// 传入 nil nonce，Seal 会把随机 nonce 放进返回值。
	ciphertext := aead.Seal(nil, nil, plaintext, nil)
	fmt.Println("ciphertext:", hex.EncodeToString(ciphertext))

	// Open 从完整密文中提取 nonce，并校验认证标签后返回明文。
	decoded, err := aead.Open(nil, nil, ciphertext, nil)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("plaintext:", string(decoded))
}

常见问题

为什么 Seal 和 Open 的 nonce 都是 nil？

这是 NewGCMWithRandomNonce 的专用约定：nonce 由 Seal 生成并随密文保存，Open 从密文读取。它和传统 NewGCM 的手动 nonce 模式不同。

能不能只保存加密正文，不保存前面的 nonce？

不能。前置 nonce 是解密所需的一部分，丢失后 Open 无法还原原始密文结构。

附加认证数据可以解密后再传吗？

不可以。附加认证数据参与认证但不进入密文，解密时必须从请求上下文或记录元数据中恢复完全相同的字节。

总结：在 Go 1.24 及以上，cipher.NewGCMWithRandomNonce 把随机 nonce 的生成、携带和提取固定成一套配对流程：创建 AEAD 后，Seal(nil, nil, plaintext, aad) 负责加密并携带 nonce，Open(nil, nil, ciphertext, aad) 负责提取 nonce、认证和解密。只要保留完整密文、保持附加数据一致，并做好密钥轮换，这种写法就能减少手动 nonce 管理的遗漏。