Go aes.NewCipher 报 invalid key size 怎么处理

Go 调用 aes.NewCipher(key) 报 invalid key size，先不要截断或补零。AES 的 key 必须正好是 16、24 或 32 个字节，对应 AES-128、AES-192 和 AES-256；len(key) 才是这里真正要检查的值。修复时要先确认输入是原始密钥、hex/base64 文本，还是用户密码，再决定解码或派生方式。

先看 NewCipher 实际收到多少字节

aes.NewCipher 的参数类型是 []byte。配置项看起来是 16 个字符，并不代表底层就是 16 字节；例如 UTF-8 中文会占用多个字节，hex 文本的两个字符只表示一个字节。

package main

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

func newAES(key []byte) (interface{}, error) {
	// 这里检查的是字节数；不要用字符串的视觉长度代替 len(key)。
	block, err := aes.NewCipher(key)
	if err != nil {
		var sizeErr aes.KeySizeError
		// KeySizeError 能把收到的非法长度带回排查日志。
		if errors.As(err, &sizeErr) {
			return nil, fmt.Errorf("AES 密钥收到 %d 字节，需要 16、24 或 32 字节: %w", int(sizeErr), err)
		}
		return nil, err
	}
	return block, nil
}

排查时同时记录 len(key)、来源和编码方式，不要把密钥正文写进日志。若输入来自环境变量，重点看是否把引号、换行、空格或前缀一起读进来了。

按输入来源选择正确的修复方式

如果协议规定的是原始 AES key，直接生成或读取 16、24、32 字节即可。如果配置保存的是 hex 或 base64，文本只是传输表示，应先解码：

package main

import (
	"crypto/aes"
	"encoding/base64"
	"encoding/hex"
	"fmt"
)

func decodeAESKey(encoded, format string) ([]byte, error) {
	var (
		key []byte
		err error
	)
	// 先还原传输编码，避免把 64 个 base64 字符误当成 64 字节密钥。
	switch format {
	case "hex":
		key, err = hex.DecodeString(encoded)
	case "base64":
		key, err = base64.StdEncoding.DecodeString(encoded)
	default:
		return nil, fmt.Errorf("不支持的密钥编码 %q", format)
	}
	if err != nil {
		return nil, fmt.Errorf("解码 AES 密钥失败: %w", err)
	}
	// 解码后再交给标准库，长度错误应在配置边界尽早暴露。
	if _, err := aes.NewCipher(key); err != nil {
		return nil, fmt.Errorf("解码后的 AES 密钥不可用: %w", err)
	}
	return key, nil
}

如果来源是用户密码，密码不是 AES key。工程上应采用双方约定的 KDF（例如带固定参数和随机 salt 的 PBKDF2、scrypt 或 Argon2id），输出 16/24/32 字节，并把 salt 与密文一起保存；不能为了让 API 通过而静默截断或补零。跨语言系统还要写清 KDF、迭代参数、salt 编码和 AES 模式。

把错误边界和 GCM 调用连起来

修好长度只解决了第一道门。新代码通常还要选择认证模式，例如把 AES block 交给 cipher.NewGCM，使用每条消息唯一的 nonce，并把解密失败当作完整性错误处理：

package main

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

func seal(key, plaintext, aad []byte) ([]byte, error) {
	block, err := aes.NewCipher(key)
	if err != nil {
		return nil, fmt.Errorf("创建 AES block 失败: %w", err)
	}
	gcm, err := cipher.NewGCM(block)
	if err != nil {
		return nil, fmt.Errorf("创建 GCM 失败: %w", err)
	}
	// 每次加密生成新的 nonce；Open 端需要拿到同一 nonce。
	nonce := make([]byte, gcm.NonceSize())
	if _, err := io.ReadFull(rand.Reader, nonce); err != nil {
		return nil, fmt.Errorf("生成 nonce 失败: %w", err)
	}
	sealed := gcm.Seal(nil, nonce, plaintext, aad)
	// 约定 nonce 放在密文前，解密时先取回它。
	return append(nonce, sealed...), nil
}

这里的 key 仍须在进入 seal 前满足长度契约；GCM 的 nonce 不能拿来“补齐”密钥，也不能重复使用同一 key 下的 nonce。

发布前用一张表排除重复报错

检查清单可以压缩成四步：打印非敏感的字节长度；确认编码与协议；让非法长度在配置加载时失败；为跨语言消费者固定 KDF、AES 模式、nonce 布局和版本字段。这样修复的是密钥契约，而不只是让某一次调用不再报错。

常见问题

为什么 16 个中文字符仍然会触发 invalid key size？

Go 字符串按 UTF-8 保存，len 返回字节数；中文通常不是一个字节。应改用明确的二进制密钥或编码后解码，不要按字符数猜测。

32 位 hex 字符串是不是 AES-256？

不是。32 个 hex 字符解码后只有 16 字节，实际对应 AES-128；AES-256 需要 64 个 hex 字符，解码后为 32 字节。

能不能用 SHA-256 把任意密码转成 AES-256？

单次 SHA-256 只能得到固定长度摘要，不等于适合密码存储或派生的 KDF。若输入确实是低熵密码，应按协议使用带 salt 和成本参数的 KDF；若输入本来就是高熵密钥，则直接按原始字节或编码格式传递。

官方参考：https://pkg.go.dev/crypto/aes