aes-gcm是文件加密默认选择，因其天然支持aead认证、一次调用完成加密与完整性校验，避免cbc需手动组合hmac的易错风险；标准库cipher.newgcm稳定免维护，但要求密钥严格32字节、nonce唯一12字节且不可复用。
为什么不能直接用 crypto/aes + crypto/cipher.NewGCM 处理会话字符串？
因为 GCM 模式本身只提供加密+认证，不处理编码、填充、随机 nonce 生成、密钥派生等会话场景必需环节。直接裸用会导致：invalid ciphertext（nonce 重用）、crypto/aes: invalid key size（密钥长度不对）、或解码后得到乱码字节而无法还原原始字符串。
常见错误是把明文字符串直接传给 aes.GCM.Seal，忽略 UTF-8 字节转换和 nonce 随机性要求；或者把密钥硬编码为字符串，没做 sha256.Sum256 或 hkdf 派生，导致实际密钥长度不匹配。
实操建议：
- 始终用
crypto/rand.Read生成 12 字节 nonce（GCM 推荐长度），不可复用 - 密钥必须是 16/24/32 字节（对应 AES-128/192/256），不能直接用用户口令字符串；推荐用
golang.org/x/crypto/pbkdf2或hkdf派生 - 加密后输出需将
nonce || ciphertext || auth_tag拼接，再经base64.StdEncoding.EncodeToString编码为 URL 安全字符串
如何安全地从字符串密钥派生 AES-GCM 密钥？
直接 []byte("my-secret-key") 当密钥大概率触发 crypto/aes: invalid key size 错误——AES-GCM 要求密钥严格为 16/24/32 字节，而中文或常见口令字符串长度不可控。
正确做法是使用密钥派生函数（KDF）：对任意长度的原始密钥加盐并迭代哈希，输出固定长度密钥。
实操建议：
- 用
pbkdf2.Key（推荐）：盐值固定为 16 字节随机数（存入加密结果前缀），迭代次数 ≥ 100000，输出 32 字节密钥用于 AES-256-GCM - 避免用
sha256.Sum256([]byte(key)).Sum(nil)—— 无盐无迭代，易被彩虹表攻击 - 若密钥已为 32 字节（如从环境变量读取 hex 字符串），可用
hex.DecodeString后直接校验长度，跳过 KDF
示例关键片段：
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
key := pbkdf2.Key([]byte(rawKey), salt, 100000, 32, sha256.New) block, _ := aes.NewCipher(key) aesgcm, _ := cipher.NewGCM(block)
解码时如何防止 crypto/cipher: message authentication failed？
这个错误几乎总是由以下三者之一引起：nonce 不匹配、密钥不一致、或 base64 解码后数据被截断/污染。不是算法问题，而是状态丢失。
会话字符串通常在 HTTP Cookie 或 URL 中传输，容易被前端 JS 误处理（比如未用 encodeURIComponent）、被代理截断、或被日志系统自动脱敏（删掉 = 符号）。
实操建议：
- 解码前先校验 base64 字符串长度是否为 4 的倍数，末尾是否含
=；不满足则直接返回错误，不要强行补码 - 从 base64 解码后的字节中，严格按约定切分：前 12 字节为 nonce，最后 16 字节为 auth tag，中间为 ciphertext
- 确保加解密使用完全相同的密钥——开发环境和生产环境密钥不同、或配置热加载未生效，都会导致此错
要不要在加密字符串里嵌入版本号或算法标识？
要。否则未来升级密钥长度、更换 KDF 参数或切换到 XChaCha20-Poly1305 时，老客户端无法识别新格式，只能静默失败。
最小可行方案是在 base64 编码前，在原始字节前加 1 字节版本头（如 \x01），解码时先检查该字节再分流处理。
实操建议：
- 版本号放在加密载荷最开头，不参与 GCM 认证（即不在
Seal输入中），避免破坏认证逻辑 - 不要用 JSON 或其他自描述格式包装——增加解析开销且可能引入 Unicode 归一化问题
- 如果服务端需兼容多套密钥（如滚动更新），可在版本号后紧跟 1 字节密钥 ID，查表获取对应密钥
真正麻烦的从来不是写对那几行 aes.NewCipher，而是密钥生命周期管理、nonce 存储位置、以及 base64 在 cookie 中的截断边界。这些细节不显眼，但出问题时最难排查。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
