解密失败概述：错误类型与排查入口
解密失败这事儿，说大不大，说小不小。但一旦碰上，排查起来能让人抓狂。我干了这么多年，见得最多的就是——开发者对着一个 "Decryption Failed" 的提示，完全不知道从哪里下手。
咱们这一章，先把解密失败的常见类型理清楚，再给你一个排查入口的地图。说白了，就是先把敌人长什么样搞明白，才能对症下药。
常见的解密失败类型
我个人习惯把解密失败归为三大类。你想想看，是不是也逃不出这几种？
| 类型 | 典型表现 | 错误码示例 |
|---|---|---|
| 密钥错误 | 解密后数据乱码，或直接抛出无效密钥异常 | ERR_KEY_INVALID, WRONG_KEY_SIZE |
| 数据损坏 | 密文长度不对，校验失败，或部分解密成功但内容缺失 | ERR_CIPHER_CORRUPT, TAG_MISMATCH |
| 算法/模式不匹配 | 明文被截断，填充异常，或解密时崩溃 | ERR_PADDING, UNSUPPORTED_MODE |
我在项目中遇到过很多次，明明是同一个用户，换个环境就解密失败。检查半天，发现是密钥存储时多了个换行符——这种“伪密钥错误”最坑。
错误类型详解
1. 密钥错误
这是最常见的。密钥错了，神仙也救不了。但密钥“错”有很多种：
- 长度错误：AES-128需要16字节，给了32字节？很多库会直接报错。
- 内容错误：密钥本身是错的，但长度正确，解密后得到一堆乱码。
- 编码错误：密钥经过Base64传输，解码时忘了还原？我见过有人把Base64字符串当密钥直接传进去。
2. 数据损坏
密文在传输或存储过程中被修改了。比特位翻转、截断、尾部多出字节……都算。对于带认证的加密（如AES-GCM），认证标签会直接告诉你数据被改过。
我曾经调试过一个夜间任务，偶尔解密失败。后来发现是消息队列超长截断，密文只收到了前80字节，后面少了16字节。这种问题，你光看错误码根本想不到。
3. 算法/模式不匹配
加密用AES-256-CBC，解密却用了AES-128-ECB。这就像用美式电源插头去插欧式插座，插不进去是小事，插进去烧了才麻烦。具体表现：
- 填充异常（PKCS7填充不匹配）
- IV长度或内容不一致
- 模式不对导致数据截断
排查入口：一张图看清全局
下面这张图，是我自己总结的核心排查路径。你把解密失败想象成一条流水线，每个环节都有可能出问题。
排查入口：从错误码开始
很多库会返回错误码。别忽略它。你花30秒查一下错误码含义，可能省下3小时瞎猜。我整理了一张常用对照表：
| 错误码 | 典型含义 | 建议排查方向 |
|---|---|---|
| ERR_KEY_INVALID | 密钥格式或长度非法 | 检查密钥二进制长度、是否含有非法字符 |
| ERR_CIPHER_TOO_SHORT | 密文长度小于最小要求 | 检查传输过程是否截断，确认加密模式所需最小长度 |
| TAG_MISMATCH | 认证标签不匹配 | 数据在传输中被修改，或密钥不同 |
| PADDING_INVALID | 填充数据无效 | 解密模式与加密模式不匹配，或密钥错误 |
黄金排查入口：复现与隔离
不管什么错误类型，第一步永远是：复现。能稳定复现的问题，才值得排查。我通常用三步走：
- 固定输入：用同一个加密样本、同一个密钥，在不同环境跑。
- 二分法：把解密过程拆成“密钥加载”“算法初始化”“解密执行”“结果处理”，每一步加日志。
- 对照实验：用标准工具（比如OpenSSL命令行）手动解密同一个密文，看结果是否一致。
避坑指南
我曾经犯过一个低级错误：在调试时用的密钥是从配置文件读的，但配置文件被版本管理工具改了换行符。Windows的\r\n和Linux的\n差一个字节，密钥长度刚好错位。从那以后，我所有密钥文件都用十六进制字符串存储，再也不碰二进制文本。
还有一次，密文前加了自定义头部（版本号、算法标识），但我解密时忘了跳过头部。结果呢？解密出来的前16字节全是乱码。这种“自定义协议”没文档，坑死人。
好了，解密失败的类型和入口你已经清楚了。下一层，我们就要深入每个环节，拿起手术刀了。