Go crypto/cipher NewGCMWithRandomNonce 如何自动生成 nonce：密文布局、Open 与迁移检查

如果一个 Go 服务还在手写 nonce，再把 nonce 和密文拼成字符串，最容易出错的地方不是 AES，而是保存格式和解密调用。crypto/cipher.NewGCMWithRandomNonce 把这一步收进 AEAD：每次 Seal 自动生成随机 nonce，并把它放在输出最前面；解密时把完整 payload 交给 Open。

这套 API 的关键规则是：不要再单独保存 nonce，也不要把 payload 拆成普通 GCM 的 nonce 参数和 ciphertext 参数；Seal 与 Open 的 nonce 参数都保持为 nil。

NewGCMWithRandomNonce 改变了哪一段数据格式

官方文档把它定义为“随机生成 nonce 的 GCM 包装器”，并要求传入的 cipher 由 crypto/aes.NewCipher 创建。与普通 NewGCM 不同，它的 Seal 会把随机 nonce 放到输出开头；调用者不需要再调用 gcm.NonceSize() 后自行分配 nonce。

因此，一条完整记录可以按下面的逻辑理解：payload = nonce(12) + ciphertext + tag(16)。一个容易踩坑的细节是：这个包装器的 NonceSize() 返回 0，调用者必须把 nonce 参数保持为 nil，不能照普通 GCM 那样先拆出 nonce 再传给 Open。12 字节随机 nonce 由包装器藏在 payload 前缀里。示例输出中的 nonce_size=0 payload_size=46 overhead=28 正好对应这层约定。

同一个示例怎样完成 Seal 与 Open

下面的示例固定使用 32 字节 AES 密钥、明文 order=42&amount=99 和附加数据 orders:v1。加密与解密共享 aad，但只把 payload 作为最终存储值；这样可以清楚观察随机 nonce 是否让两次相同明文产生不同结果。运行时会看到 NonceSize() 为 0，这不是没有 nonce，而是“由 Seal/Open 自己处理 nonce”的信号。

block, err := aes.NewCipher(key)
if err != nil { log.Fatal(err) }
aead, err := cipher.NewGCMWithRandomNonce(block)
if err != nil { log.Fatal(err) }

payload := aead.Seal(nil, nil, plaintext, aad)
nonceSize := aead.NonceSize()
opened, err := aead.Open(nil, nil, payload, aad)
if err != nil { log.Fatal(err) }
fmt.Printf("nonce_size=%d payload_size=%d overhead=%d\\n", nonceSize, len(payload), aead.Overhead())
fmt.Printf("opened=%s open_error=%v\\n", opened, err)

注意这里传给 Seal 和 Open 的 nonce 参数都是 nil，并且 Open 的 ciphertext 参数是完整 payload。这是这个包装器的特殊调用约定；如果沿用普通 GCM 的写法，先手动生成 12 字节 nonce、再把 payload 切片传入，反而会把两套格式混在一起。正确分支会输出 opened=order=42&amount=99 open_error=；把 AAD 改成 orders:v2 时，输出 tampered_error=cipher: message authentication failed。

Open 之前的三个检查点

先判断 payload 是否足够长

不要直接按普通 GCM 的方式切片。损坏、截断或空字段应在调用 Open 前被识别；当前格式至少要能容纳 12 字节 nonce、16 字节认证标签和业务明文。生产代码还应该把“输入格式错误”和“认证失败”记入不同的指标，便于判断是存储截断还是数据被修改。

附加数据是认证范围的一部分

aad 不会出现在密文中，却会参与认证。示例中的 orders:v1 只要改成 orders:v2，Open 就应返回错误。它适合绑定租户、协议版本或资源类型，但不能把每次请求都变化、解密时拿不到的值塞进去。

不要把认证失败当成“尝试解密”

Open 返回错误时，调用方应该丢弃明文结果并停止后续业务处理。不要打印 payload、key 或可能包含敏感内容的中间缓冲区；日志只保留记录 ID、错误分类和协议版本。

旧版 AES-GCM 格式怎么迁移

如果旧系统的格式是 nonce + ciphertext，且 nonce 由调用方生成，那么不能只替换构造函数就上线。新 API 的 Seal 会自己生成 nonce 并把它放进返回值，旧代码若还做一次拼接，会得到重复 nonce。稳妥做法是给记录加一个格式版本：旧版本继续由旧 reader 读取，新版本由 NewGCMWithRandomNonce 生成；等旧记录读完或完成离线迁移后，再删除旧写入分支。

常见问题：这几个误解怎么排除

每次 Seal 都会得到相同的 payload 吗？

不会。随机 nonce 不同，即使 key、明文和附加数据完全相同，输出也应不同；这正是该包装器要替调用方处理的部分。

能不能把 nonce 单独存一列？

可以，但那是业务自定义格式。使用该 API 时更简单的做法是原样保存返回值，并按 NonceSize() 读取前缀，避免字段和 payload 不一致。

Open 返回错误时还能使用返回的明文吗？

不能。认证未通过时，把返回切片当作无效数据处理，调用方只记录可检索的错误分类。

落地前的最小验收清单

• 运行两次相同输入，确认 payload 不相同且 NonceSize() 为 0、前缀实际占 12 字节。
• 用原始 aad 成功 Open，再修改一个字节确认返回认证错误。
• 输入短于 12 字节 nonce 加 16 字节标签的最小格式时不发生 panic。
• 迁移测试同时覆盖旧格式读取和新格式写入，不让 reader 依赖单一版本。