Go chacha20poly1305.New 怎样创建 AEAD 并检查密钥长度

我第一次把 Go 的 AEAD 接进加密存储时，最容易误判的不是算法名称，而是输入边界：密钥看起来像一段字符串，nonce 也能随手 make 出来，但 chacha20poly1305.New 要的是固定长度的 256 位密钥，Seal 和 Open 还要继续遵守 AEAD 自己的 nonce 约束。

这篇只处理构造和调用前准备，不讨论把口令直接当密钥，也不展开自定义密码派生。目标是把“创建失败”“参数不匹配”和“认证失败”拆成值班时能执行的几步。

官方文档：https://pkg.go.dev/golang.org/x/crypto/chacha20poly1305#New

结论先落地：先把输入密钥整理成 32 字节，再调用 chacha20poly1305.New；拿到 cipher.AEAD 后，用 aead.NonceSize() 分配 nonce，并确保同一密钥下每次加密都使用唯一 nonce。

先把 New 的输入边界说清楚

New 返回的是标准 ChaCha20-Poly1305 AEAD。当前官方文档把 KeySize 定义为 32 字节，标准变体的 NonceSize 为 12 字节，认证标签开销为 16 字节。也就是说，256 位密钥不是“建议值”，而是构造函数的输入边界。

值班时先看错误出现在哪一层：

触发信号：为什么会卡在创建或解密

最常见的触发信号有三个：配置里保存的是十六进制字符串，却忘了解码；把口令字节直接传给 New；或者加密端把 nonce 拼在密文前面，解密端却按另一种布局切分。它们表面上都像“加密库不能用”，实际分别属于密钥准备、构造边界和数据格式问题。

我会先记录三个长度，而不是先换算法：密钥解码后的字节数、nonce 字节数、密文总长度。这样能快速确认故障发生在 New 之前，还是已经进入 Seal/Open。

快速判断：用常量和方法返回值做第一道门

不要把字符串长度当成密钥长度。十六进制文本通常每两个字符表示一个字节，Base64 还会带填充字符；真正传给 New 的是解码后的 []byte。构造时保留错误返回值，方便把问题落到配置或密钥载入环节。

package main

import (
    "fmt"

    "golang.org/x/crypto/chacha20poly1305"
)

func newAEAD(key []byte) error {
    // 先检查字节长度，避免把配置错误拖到 Seal/Open 才暴露。
    if len(key) != chacha20poly1305.KeySize {
        return fmt.Errorf("key length = %d, want %d", len(key), chacha20poly1305.KeySize)
    }

    // New 会再次按库的规则构造 AEAD；错误必须保留给上层处理。
    aead, err := chacha20poly1305.New(key)
    if err != nil {
        return fmt.Errorf("create chacha20poly1305 AEAD: %w", err)
    }

    // 运行时以接口返回值为准，不把 nonce 长度硬编码到调用方。
    fmt.Printf("nonce=%d overhead=%d\n", aead.NonceSize(), aead.Overhead())
    return nil
}

这里的显式长度检查不是替代库检查，而是让日志更有上下文。短密钥如果来自口令或配置，应该回到密钥生成、解码或密钥管理流程修复，不应为了让构造成功而补零、截断或重复拼接。

处理步骤：按 NonceSize 完成一轮 Seal/Open

拿到 AEAD 后，最稳妥的做法是从方法读取 nonce 长度，生成一个只服务于当前密钥的 nonce，再把 nonce 和密文按约定布局保存。下面示例采用“nonce 前置、密文随后”的单条记录格式，解密时先切分，再调用 Open。

package main

import (
    "crypto/rand"
    "fmt"
    "io"

    "golang.org/x/crypto/chacha20poly1305"
)

func encrypt(key, plaintext, aad []byte) ([]byte, error) {
    // 只有固定的 32 字节密钥才允许进入标准构造路径。
    if len(key) != chacha20poly1305.KeySize {
        return nil, fmt.Errorf("invalid key length: %d", len(key))
    }
    aead, err := chacha20poly1305.New(key)
    if err != nil {
        return nil, err
    }

    // nonce 的长度由 AEAD 提供；随机源失败时不能继续使用半成品。
    nonce := make([]byte, aead.NonceSize())
    if _, err := io.ReadFull(rand.Reader, nonce); err != nil {
        return nil, fmt.Errorf("read nonce: %w", err)
    }

    // 先复制 nonce，再把 Seal 结果追加到 nonce 后面，形成可持久化记录。
    record := append([]byte(nil), nonce...)
    record = aead.Seal(record, nonce, plaintext, aad)
    return record, nil
}

func decrypt(key, record, aad []byte) ([]byte, error) {
    // 解密端必须使用同一套构造规则，不能只凭密文猜 nonce 长度。
    aead, err := chacha20poly1305.New(key)
    if err != nil {
        return nil, err
    }
    if len(record) 

这个示例把 nonce 放在记录里，所以解密端能先取出它；nonce 不需要保密，但在同一密钥下不能重复。附加数据 aad 不会被加密，却会参与认证，因此两端也必须保持一致。

回滚路径：构造失败和认证失败分别处理

当 New 失败时，回滚点应该是“拒绝加载这条密钥配置”，而不是切换到一个未知的填充规则。把错误密钥标成不可用，保留原密钥版本或回退到上一份已知可用配置，等密钥装载链路修复后再恢复写入。

当 Open 失败时，不能把旧缓存、空字节或部分输出当作明文。对单条数据可以返回可重试错误；对批量任务则记录记录 ID 和密钥版本，隔离坏数据，避免不断重试放大告警。

如果业务需要更长的随机 nonce，并且无法轻易保证 nonce 唯一，可以评估 chacha20poly1305.NewX。这不是为了绕过 32 字节密钥限制，而是选择 XChaCha20-Poly1305 的 24 字节 nonce 变体；现有数据格式已经固定为 12 字节时，不要直接替换而不做兼容设计。

告警确认：把三个信号分开看

• 构造失败：按密钥载入错误告警，附带来源配置、解码方式和字节长度，不记录密钥内容。
• 记录过短：按数据布局或传输截断告警，先判断是否缺少 nonce 或认证标签。
• 认证失败：按密文被篡改、附加数据不一致、密钥版本错误或记录损坏处理，不把它降级为普通解码失败。

日志只记录长度、版本、记录标识和错误类别，绝不打印 key、nonce 全文或明文。对于 nonce 重复风险，重点复盘随机源、计数器/租约设计和密钥轮换边界，而不是只看一次请求是否成功。

复盘清单：发布前后各看一次

1. 确认密钥在解码后是 32 字节，并且错误不会被忽略。
2. 确认 nonce 从 aead.NonceSize() 获取，记录格式能让解密端准确切分。
3. 确认同一密钥下每次 Seal 的 nonce 都唯一，随机读取失败会终止本次加密。
4. 确认 Open 的失败分支不会暴露或继续使用无效明文。
5. 确认日志不包含密钥、nonce、明文和附加数据原文。

记住这条顺序就够了：先检查 key，再创建 AEAD；再按接口读取 nonce 长度，最后让 Seal/Open 的两端共享同一套记录布局和认证输入。

相关问题

为什么不能把 16 字节密钥直接传给 New？因为标准构造要求 256 位密钥，16 字节输入应在密钥管理或派生环节解决，而不是在调用点补齐。

nonce 需要保存到数据库吗？如果解密时需要它，就要和密文一起保存或能从记录中恢复；它通常不需要保密，但同一密钥下不能重复。

Open 失败还能读取返回的切片吗？不能把失败路径上的内容当作明文使用；按错误处理并丢弃或隔离这条记录。

什么时候选择 NewX？当更长 nonce 能显著降低随机碰撞管理压力，且你能为新 nonce 长度和数据格式设计兼容边界时再评估。