Go cipher.AEAD.Open 认证失败时怎样安全处理输出缓冲区

如果 cipher.AEAD.Open 返回错误，调用方应该把这次输出当成不可用数据：不要解析返回切片，不要把它写入日志，也不要把失败后的底层数组继续交给下一层。成功路径才可以使用返回的明文；失败路径统一返回 nil 或业务错误，并按需要清理自己拥有的缓冲区。

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

Open 不只是“把密文解出来”，还要同时验证 nonce、密文和 additionalData。认证失败时，返回值不能被当作部分明文；即使为了减少分配复用了 dst，失败后的存储也必须视为不可用。

• 先检查 nonce 长度，避免把格式错误带进解密层。
• 把 AAD 当作协议字段的一部分，编码和解码必须完全一致。
• 只在 err == nil 时读取返回切片。
• 使用 ciphertext[:0] 原地解密时，失败后不要再使用原密文缓冲区。

先看懂 AEAD.Open 的返回边界

AEAD 的 Open(dst, nonce, ciphertext, additionalData) 会把认证成功后的明文追加到 dst，返回更新后的切片。这里的 dst 不是“只读的输出参数”，而是一个可能被复用的目标存储：如果容量足够，结果可能写进它的底层数组；如果容量不足，则可能重新分配。

官方接口还明确了两个容易被忽略的边界：nonce 必须满足当前 AEAD 的 NonceSize()，additionalData 必须与 Seal 时使用的值一致；另外，Open 失败时，dst 在其容量范围内的内容可能已经被覆盖。因此，不能写出“即使报错也先读取返回值”的兜底代码。

用一个小实验区分三类失败

为了让错误处理有清晰边界，可以先构造一份 AES-GCM 密文，再分别修改 AAD 和密文。示例只展示接口关系，不依赖真实服务或外部数据。

package main

import (
    "crypto/aes"
    "crypto/cipher"
    "crypto/rand"
    "fmt"
    "io"
)

func seal(aead cipher.AEAD, plaintext, aad []byte) ([]byte, []byte, error) {
    // 每个密钥下的 nonce 必须唯一；这里用随机源生成实验 nonce。
    nonce := make([]byte, aead.NonceSize())
    if _, err := io.ReadFull(rand.Reader, nonce); err != nil {
        return nil, nil, err
    }
    // Seal 把认证标签附加到密文末尾，调用方同时保存 nonce。
    ciphertext := aead.Seal(nil, nonce, plaintext, aad)
    return nonce, ciphertext, nil
}

func main() {
    // 32 字节密钥只用于演示 AES-256-GCM 的调用关系。
    key := []byte("01234567890123456789012345678901")
    block, err := aes.NewCipher(key)
    if err != nil {
        panic(err)
    }
    aead, err := cipher.NewGCM(block)
    if err != nil {
        panic(err)
    }

    nonce, ciphertext, err := seal(aead, []byte("订单摘要"), []byte("订单:v1"))
    if err != nil {
        panic(err)
    }

    // AAD 不一致会导致认证失败，不能把 returned 当作可用明文。
    plaintext, err := aead.Open(nil, nonce, ciphertext, []byte("订单:v2"))
    fmt.Printf("aad mismatch: plaintext=%q err=%v\n", plaintext, err)

    // 修改密文也会使认证标签不匹配；复制后再改，避免改变原实验数据。
    tampered := append([]byte(nil), ciphertext...)
    tampered[0] ^= 1
    plaintext, err = aead.Open(nil, nonce, tampered, []byte("订单:v1"))
    fmt.Printf("ciphertext mismatch: plaintext=%q err=%v\n", plaintext, err)

    // 只有认证成功且错误为 nil 时，才允许进入业务解析。
    plaintext, err = aead.Open(nil, nonce, ciphertext, []byte("订单:v1"))
    if err != nil {
        // 失败原因可能来自认证或输入格式，统一按不可接受密文处理。
        fmt.Println("ciphertext rejected")
        return
    }
    fmt.Printf("success: %s\n", plaintext)
}

上面的分支重点是调用顺序，而不是打印具体错误文本。不同 AEAD 实现对失败原因的区分粒度可能不同，业务层通常只需要把它归入“密文不可接受”，避免向外暴露过细的判断信息。若项目使用的 Go 版本没有可直接匹配的统一错误值，就记录受控的业务错误，不要依赖错误字符串。

把安全边界收进 safeOpen

业务代码最容易出错的地方，是在多个接口层重复写 Open，某个调用点忘记检查错误就继续反序列化。可以用一个小封装集中处理 nonce 长度、失败返回和可选清理。

package safeaead

import (
    "crypto/cipher"
    "errors"
    "fmt"
)

var ErrRejectedCiphertext = errors.New("ciphertext rejected")

func Open(aead cipher.AEAD, nonce, ciphertext, aad []byte) ([]byte, error) {
    // 提前拒绝错误长度，避免把格式错误混入认证失败分支。
    if len(nonce) != aead.NonceSize() {
        return nil, fmt.Errorf("%w: nonce length %d", ErrRejectedCiphertext, len(nonce))
    }

    plaintext, err := aead.Open(nil, nonce, ciphertext, aad)
    if err != nil {
        // 失败时不向调用方返回可能被覆盖或不可信的输出切片。
        return nil, fmt.Errorf("%w: %v", ErrRejectedCiphertext, err)
    }
    // 只有这里返回的切片才允许交给 JSON、CBOR 等上层解析器。
    return plaintext, nil
}

这个封装选择 nil 作为目标缓冲区，代码最容易审查，但每次成功解密可能产生一次新的输出分配。如果已经确认需要复用内存，可以把复用策略放到更窄的底层函数中，而不是让所有业务调用点都直接操作 dst。

原地解密时，失败后的底层数组也要丢弃

官方接口允许把 ciphertext[:0] 作为 dst，这样成功时明文会覆盖密文所在的底层数组，适合对分配敏感的路径。但这是一种明确的存储所有权选择：认证失败后，原密文和可能写入的中间内容都不能继续当作可靠数据。

func openInPlace(aead cipher.AEAD, nonce, ciphertext, aad []byte) ([]byte, error) {
    // ciphertext[:0] 只复用容量，不保留原切片长度。
    dst := ciphertext[:0]
    plaintext, err := aead.Open(dst, nonce, ciphertext, aad)
    if err != nil {
        // 失败后底层数组可能已被改写；不返回它，也不再尝试解析原密文。
        clear(ciphertext)
        return nil, ErrRejectedCiphertext
    }
    return plaintext, nil
}

clear 是对当前切片可见元素做的普通清理，适合表达“这块内存不再交给业务层”的意图，但它不是硬件级的秘密擦除保证。若缓冲区还被其他切片或对象引用，调用方仍需梳理所有权；如果后续还需要原密文做审计或重试，就不要采用原地复用。

排查时按输入、认证、存储三层看

常见问题

Open 返回错误时，返回切片一定是 nil 吗？

不要把 nil 与否当作安全契约。调用方真正应该依赖的是 err != nil，然后丢弃返回值；失败时目标缓冲区内容也不能继续使用。

为什么 AAD 只改了一个字段也会失败？

AAD 会参与认证但不会出现在密文正文中。编码版本、字段顺序、大小写或字节序只要不一致，接收端看到的认证输入就不同。

为了性能可以一直使用 ciphertext[:0] 吗？

可以，但必须把它当成一次性的存储转移：成功后只使用返回明文，失败后整块底层数组作废。需要保留原密文、支持重试或跨层传递时，使用独立 dst 更容易维护。

日志里应该记录什么？

记录请求关联 ID、算法配置版本和失败分类即可，不要记录 nonce、密文、AAD 或疑似明文的完整内容。调试时也应使用脱敏后的长度和哈希摘要，并确保不会把失败缓冲区送入日志格式化器。

总结：把 AEAD.Open 看成“认证成功才提交明文”的事务边界。先校验 nonce，保证 AAD 编码一致；调用后先判断错误，再允许上层解析；一旦失败，无论使用独立 dst 还是 ciphertext[:0]，都不要继续读取那块输出存储。