Go crypto/aes 怎样处理可选字段

在 Go 里遇到“可选字段”时，最容易误判的是把 crypto/aes 当成了业务配置解析器。实际上，aes.NewCipher 只接收 AES 密钥并返回分组密码；模式、nonce 和附加认证数据由 crypto/cipher 的封装层处理。正确做法是先把字段分成必填、条件必填和可省略，再决定缺省值是否安全。

官方地址：https://pkg.go.dev/crypto/aes

模式接口：https://pkg.go.dev/crypto/cipher

密钥不能省略，长度只能是 16、24 或 32 字节；GCM 的 nonce 不是“随便可选”，固定协议需要调用方提供或生成后保存，随机 nonce 模式则可以由封装层生成并放进密文；AAD 可以为空，但解密时必须和加密侧保持一致。

先看清故障影响：aes.NewCipher 不认识业务可选字段

一个常见的加密请求大致会带有 key、mode、nonce 和 aad。这些字段看起来都可以做成可选，但它们的责任并不相同：

因此，所谓“处理可选字段”不是给每个字段都填一个默认值，而是先在业务层做一次明确判断，再把已经满足契约的参数交给标准库。这样 aes.NewCipher 返回的错误只表示密钥本身不符合 AES 要求，不会混入请求格式问题。

问题通常怎样触发：缺 key、错 nonce 和不一致的 AAD

故障现场通常有三种表现。第一种是请求没有传密钥，或者把口令字符串未经派生直接当作 AES key；NewCipher 只接受 16、24、32 字节，其他长度会返回 KeySizeError。第二种是 nonce 作为可选字段被静默填成空切片，但标准 GCM 的 Seal 和 Open 仍要求正确长度。第三种是加密时把请求 ID 放进 AAD，解密时没有复用同一个请求 ID，结果会表现为认证失败。

最小的密钥入口应该保留错误，而不是把错误吞掉：

package main

import (
    "crypto/aes"
    "fmt"
)

func newBlock(key []byte) (cipherBlock interface{}, err error) {
    // 让标准库检查 16、24、32 字节密钥，业务层只补充字段来源信息。
    block, err := aes.NewCipher(key)
    if err != nil {
        return nil, fmt.Errorf("AES 密钥无效: %w", err)
    }
    return block, nil
}

上面的示例只演示边界判断，真实代码应把返回类型写成 cipher.Block，而不是为了省略导入把它写成接口。更重要的是，不要把 err 改成下划线：密钥错误是输入问题，继续创建 AEAD 只会让错误更晚、更难定位。

根因在哪里：AES 分组、工作模式和可选数据是三层

crypto/aes 提供的是 AES 分组密码。它知道密钥是否为合法长度，也提供固定的 16 字节分组大小，但它不知道你的业务是要做 GCM、CTR 还是其他模式，更不知道某个请求字段是不是可选。

crypto/cipher 才负责把 cipher.Block 包成 AEAD 或其他工作模式。以 GCM 为例，Seal 和 Open 接收 nonce、明文或密文以及 AAD。AAD 不会被加密，但会参与认证；因此“可以为空”不等于“加密和解密可以各传各的”。

把三层职责写进结构体后，缺省处理会更直观：

type EncryptRequest struct {
    Key   []byte
    Mode  string
    Nonce []byte
    AAD   []byte
}

type preparedRequest struct {
    key   []byte
    mode  string
    nonce []byte
    aad   []byte
}

func prepare(req EncryptRequest) (preparedRequest, error) {
    // 空 key 不能被当成“可选”，否则会把配置错误拖到更深的调用层。
    if len(req.Key) == 0 {
        return preparedRequest{}, fmt.Errorf("缺少 AES key")
    }
    mode := req.Mode
    if mode == "" {
        // 默认模式只解决请求兼容，不替代 nonce 和 key 的安全要求。
        mode = "gcm"
    }
    switch mode {
    case "gcm", "gcm-random-nonce":
        return preparedRequest{key: req.Key, mode: mode, nonce: req.Nonce, aad: req.AAD}, nil
    default:
        return preparedRequest{}, fmt.Errorf("不支持的 AES 模式: %s", mode)
    }
}

修复动作：在 GCM 入口统一决定 nonce 是否由外部管理

下面的实现把两种合法情况分开。gcm 适合已经有协议格式的系统：nonce 可以由调用方传入，或者在加密时随机生成后由上层保存。gcm-random-nonce 适合希望减少 nonce 字段管理的接口：随机 nonce 由 NewGCMWithRandomNonce 处理，并随密文一起封装。

package main

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

func buildAEAD(req preparedRequest) (cipher.AEAD, error) {
    // 先创建 AES 分组，key 的长度错误在这里尽早暴露。
    block, err := aes.NewCipher(req.key)
    if err != nil {
        return nil, fmt.Errorf("创建 AES 分组失败: %w", err)
    }
    switch req.mode {
    case "gcm":
        // 标准 GCM 的 nonce 由调用方管理，适合兼容已有密文协议。
        return cipher.NewGCM(block)
    case "gcm-random-nonce":
        // 随机 nonce 会被封装到 Seal 产生的密文前部，调用方不再单独保存 nonce。
        return cipher.NewGCMWithRandomNonce(block)
    default:
        return nil, fmt.Errorf("不支持的 AES 模式: %s", req.mode)
    }
}

func seal(req preparedRequest, plaintext []byte) ([]byte, []byte, error) {
    aead, err := buildAEAD(req)
    if err != nil {
        return nil, nil, err
    }
    if req.mode == "gcm-random-nonce" {
        // 该模式的 NonceSize 为 0，返回值已经包含随机 nonce。
        return aead.Seal(nil, nil, plaintext, req.aad), nil, nil
    }

    nonce := req.nonce
    if len(nonce) == 0 {
        // 缺省 nonce 只在加密端生成，并把它作为独立字段返回给存储层。
        nonce = make([]byte, aead.NonceSize())
        if _, err := io.ReadFull(rand.Reader, nonce); err != nil {
            return nil, nil, fmt.Errorf("生成 nonce 失败: %w", err)
        }
    }
    if len(nonce) != aead.NonceSize() {
        return nil, nil, fmt.Errorf("nonce 长度为 %d，需要 %d", len(nonce), aead.NonceSize())
    }
    return aead.Seal(nil, nonce, plaintext, req.aad), nonce, nil
}

func open(req preparedRequest, ciphertext, nonce []byte) ([]byte, error) {
    aead, err := buildAEAD(req)
    if err != nil {
        return nil, err
    }
    if req.mode == "gcm-random-nonce" {
        // 随机 nonce 已经在 ciphertext 中，Open 的 nonce 参数保持为 nil。
        return aead.Open(nil, nil, ciphertext, req.aad)
    }
    if len(nonce) != aead.NonceSize() {
        return nil, fmt.Errorf("解密 nonce 长度为 %d，需要 %d", len(nonce), aead.NonceSize())
    }
    // AAD 必须复用加密时的值，否则认证会失败。
    return aead.Open(nil, nonce, ciphertext, req.aad)
}

这个入口有三个刻意的选择：没有 key 直接报错；标准 GCM 的 nonce 缺省时只在加密侧随机生成；随机 nonce 模式不再接受外部 nonce。这样可以避免同一个请求在不同路径上同时“猜测”字段含义。

两个模式怎样选：看协议是否已经规定 nonce 字段

如果只是想让 aad 变成可选字段，可以把它保持为 nil 或空切片；关键是保存业务规则：同一份密文的解密调用必须拿到相同的 AAD。AAD 适合绑定非机密但必须防篡改的元数据，例如对象类型或协议版本，不应被当作隐藏字段。

防止复发：把字段契约和错误分类写进接口

1. 在请求解析层区分“缺少 key”“未知 mode”“nonce 长度错误”和“认证失败”，不要统一返回“加密失败”。
2. 把默认模式写在接口文档中；默认值可以减少兼容分支，但不能替密钥、nonce 唯一性或 AAD 一致性背书。
3. 标准 GCM 路径保存 nonce 与密文的对应关系；随机 nonce 路径保存完整封装后的密文，避免只保存密文主体。
4. 不要用口令原文直接当 AES key。口令到密钥需要独立的密钥派生方案，本文的 key 字段指已经准备好的字节密钥。
5. 把 cipher.AEAD 的创建和字段检查集中起来，业务处理函数只接收已满足契约的输入。

常见问题

aes.NewCipher 能不能接受任意长度的字符串？

不能。字符串转成字节后仍必须是 16、24 或 32 字节。若输入是口令，应先使用适合项目协议的密钥派生方案得到固定长度密钥，再交给 NewCipher。

nonce 缺省时直接传 nil 可以吗？

只有随机 nonce 封装模式明确要求这样调用时才可以。标准 GCM 的 Seal/Open 仍然需要正确长度的 nonce，缺省时应生成并持久化，而不是把 nil 当作安全默认值。

AAD 不传会不会影响解密？

如果加密和解密两侧都使用空 AAD，可以正常匹配；如果加密时传了 AAD，解密时必须传同样的字节内容，否则认证会失败。

为什么不把所有字段都放进一个“默认配置”里？

因为 key、nonce 和 AAD 的安全语义不同。统一填默认值会掩盖输入错误，甚至让不同请求复用不该复用的 nonce。更稳妥的做法是用模式分支表达字段责任，用错误返回表达不可恢复的缺省。

总结一下：crypto/aes 处理的是合法 AES key 与分组，crypto/cipher 处理的是模式层字段。只要把“可选”改写成“在哪一层、在什么模式下可省略”，就能让 Go 的 AES 代码既兼容业务请求，又不会用静默默认值掩盖加密配置问题。