Go crypto/aes.NewCipher 怎样判断密钥长度是否正确

调用 crypto/aes.NewCipher 时，密钥必须是 16、24 或 32 字节，分别对应 AES-128、AES-192 和 AES-256。长度不符合要求时，函数不会返回可用的 cipher.Block，而是返回一个长度错误。实际项目中最稳妥的做法是：先明确输入是字节，必要时提前检查 len(key)，同时保留并分类处理 NewCipher 返回的错误。

官方文档：https://pkg.go.dev/crypto/aes#NewCipher

AES 的合法密钥长度是什么

Go 的 AES 包把密钥长度和算法规格绑定在一起：

这里的单位是 byte。例如，字符串 "abcdefghijklmnop" 在 ASCII 场景下是 16 字节，但包含中文或其他多字节 UTF-8 字符时，字符个数和字节数可能不同。密钥如果来自十六进制文本，还要先明确它是“文本形式的密钥”还是“解码后的原始字节”。

在 NewCipher 前先把输入长度说清楚

如果密钥来自配置文件或环境变量，可以在进入加密模块时尽早拒绝非法输入。提前判断能让错误信息更贴近业务边界，但不要只依赖提前判断而忽略 NewCipher 的返回值，因为构造器仍然是最终的标准库契约。

package main

import (
    "crypto/aes"
    "fmt"
)

func newAESBlock(key []byte) (interface{ BlockSize() int }, error) {
    // 先把长度错误挡在业务边界，避免把任意文本当成 AES 密钥。
    switch len(key) {
    case 16, 24, 32:
        // 这三个长度分别对应 AES-128、AES-192、AES-256。
    default:
        return nil, fmt.Errorf("AES 密钥长度必须是 16、24 或 32 字节，当前是 %d", len(key))
    }

    block, err := aes.NewCipher(key)
    if err != nil {
        // 仍然保留构造器错误，避免未来输入路径变化后丢失边界。
        return nil, err
    }
    return block, nil
}

上面的返回类型只为了突出“成功后得到一个分组密码对象”。在真实项目中，通常直接返回 cipher.Block，这样后续可以把它交给 cipher.NewGCM 等模式构造函数。

怎样用 KeySizeError 识别长度错误

aes.KeySizeError 的底层类型是 int，用于携带收到的密钥长度。不要只用错误字符串做判断，因为字符串适合日志展示，不适合作为稳定的分支依据。可以使用 errors.As 将错误转换成具体类型：

package main

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

func describeKeyError(key []byte) error {
    // NewCipher 负责最终判断，返回的 block 在错误时不要继续使用。
    _, err := aes.NewCipher(key)
    if err == nil {
        return nil
    }

    var sizeErr aes.KeySizeError
    if errors.As(err, &sizeErr) {
        // sizeErr 是收到的字节数，可用于结构化日志或接口错误码。
        return fmt.Errorf("AES 密钥长度错误：收到 %d 字节", int(sizeErr))
    }

    // 保留未来可能出现的其他构造错误。
    return fmt.Errorf("创建 AES 分组密码失败：%w", err)
}

长度错误和后续模式错误是两层边界：NewCipher 解决的是“有没有合法 AES 密钥”，并不代表业务已经完成加密配置。

密钥长度和 AES 分组大小不是一回事

常见误区是看到 AES 的 BlockSize 也等于 16，就把它当成密钥长度。实际上，AES 的分组大小固定为 16 字节，而密钥可以是 16、24 或 32 字节。下面的代码分别读取这两个概念：

package main

import (
    "crypto/aes"
    "fmt"
)

func printAESShape(key []byte) error {
    // key 的长度决定 AES-128、AES-192 或 AES-256。
    block, err := aes.NewCipher(key)
    if err != nil {
        return err
    }

    // BlockSize 描述每个分组的字节数，不描述 key 的长度。
    fmt.Printf("key=%d bytes, block=%d bytes\\n", len(key), block.BlockSize())
    return nil
}

因此，len(key) == 24 且 block.BlockSize() == 16 完全正常：前者是 AES-192 的密钥，后者是 AES 固定的分组大小。

创建成功后再进入 GCM 等后续模式

拿到 cipher.Block 后，才进入工作模式构造。以 GCM 为例，密钥长度错误应该在更早的 NewCipher 阶段结束；cipher.NewGCM 关注的是如何把分组密码包装成 AEAD，而不是替你修复密钥。

package main

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

func newAEAD(key []byte) (cipher.AEAD, error) {
    // 先创建 AES 分组密码，非法长度会在这里返回错误。
    block, err := aes.NewCipher(key)
    if err != nil {
        return nil, err
    }

    // 只有 block 有效时，才交给 GCM 构造 AEAD。
    return cipher.NewGCM(block)
}

这段分层的好处是日志和接口错误更容易定位：密钥长度问题归入输入契约，GCM 构造问题归入模式配置，明文处理则属于更后面的业务层。

几个容易误判的输入场景

• 把十六进制文本长度当成密钥长度：32 个十六进制字符通常表示 16 个原始字节，是否解码取决于你的配置约定。
• 用字符数代替字节数：Go 的 len(string) 返回 UTF-8 字节数，不是用户感知的字符数；转成 []byte 后仍应按字节检查。
• 用散列结果长度猜 AES 规格：哈希输出可以作为材料，但是否截取或派生为 16/24/32 字节必须由明确的密钥方案决定，不能临时切片就当作安全设计。
• 错误后继续使用 block：NewCipher 返回错误时，分组密码对象不可用，应立即返回或转换错误。

速查结论

相关问题

24 字节密钥是不是无效？

不是。24 字节对应 AES-192，是 aes.NewCipher 接受的合法长度。

为什么 32 个十六进制字符不是 32 字节 AES-256？

十六进制字符通常两个字符表示一个字节，所以 32 个十六进制字符解码后通常是 16 字节。应先明确配置值是否已经完成十六进制解码。

KeySizeError 能不能代替业务错误码？

它适合在 Go 内部做类型判断；对外接口可以把它转换成稳定的业务错误码，同时保留原错误作为日志上下文。