密码学与证书 / 系统课时
排查加解密不一致
排查加解密不一致
跨语言联调时,发送端加密成功、接收端却无法解密,问题往往出在字节编码、GCM 参数或密文封装,而不是算法名称。本课用固定 AES-GCM 测试向量复现成功与认证失败,并给出可以逐项核对的排查路径。
学习目标
- 按原始字节、算法参数和传输格式定位两端差异。
- 区分 Base64 编码错误、密文与 Tag 拼接错误及 GCM 认证失败。
- 用可运行的 Java 测试向量确认加密结果和失败行为。
先确认双方处理的是同一组字节
先比较待加密明文的字节长度和十六进制内容,不要只看控制台显示的字符串。例如,UTF-8 下 hello 是 68656c6c6f,末尾多一个 LF 换行后就变成 68656c6c6f0a。如果加密对象是 JSON,还要确认字段顺序、空格及序列化结果是否一致。
然后对齐完整算法约定。只写“AES”不足以互通;至少要明确以下项目:
- 加密方式:
AES/GCM/NoPadding,不能与 AES-CBC 混用。 - Key:128、192 或 256 位,以及使用哪个
keyId;32 个十六进制字符解码后才是 16 字节 Key,不能直接把这些字符当作原始 Key。 - Nonce:推荐 12 字节(96 位);Tag:这里约定 16 字节(128 位)。
- AAD:是否使用、哪些字段参与、字段顺序和实际 UTF-8 字节。AAD 不加密,但参与认证。
沿接收链路定位格式错误
解密前按数据实际流动顺序检查,发现第一处不一致就先修正,不要一次修改多个参数。
- 传输层:先确定 Base64 包裹的是
ciphertext,还是nonce || ciphertext || tag。Base64 必须按照约定解码一次,不能把 Base64 字符串的 UTF-8 字节直接送入解密器。 - 封装层:明确各字段的字节长度和位置。有的语言库把 Tag 单独返回,而 Java JCE 的 GCM
doFinal接收和返回的密文形式通常是ciphertext || tag;Nonce 通过初始化参数传入,不在这段结果里。 - 密钥层:根据
keyId在各自受控环境中取得正确 Key,核对长度和编码。十六进制、Base64 与原始二进制不能混用。 - 认证层:核对 Nonce、AAD、Ciphertext 和 Tag 的每个字节。
AEADBadTagException只能说明认证没有通过,不能单凭异常判断究竟是哪一项有误。
排查时可交换算法标识、keyId、测试 Nonce、AAD 的测试值、密文及 Tag 的十六进制或 Base64 表示;不要输出真实 Key,也避免在生产日志记录敏感明文。

使用固定测试向量验证实现
下面的完整 Java 17+ 示例使用公开的 AES-GCM 测试向量:128 位全零 Key、96 位全零 Nonce、16 字节全零明文、空 AAD、128 位 Tag。先对比固定结果,再篡改 Tag 的一个比特确认认证会失败。固定零 Key 和零 Nonce 只供测试,绝不可用于真实数据加密。
import java.util.Arrays;
import java.util.HexFormat;
import javax.crypto.AEADBadTagException;
import javax.crypto.Cipher;
import javax.crypto.spec.GCMParameterSpec;
import javax.crypto.spec.SecretKeySpec;
public class GcmInteropCheck {
public static void main(String[] args) throws Exception {
// 全零参数只用于验证公开测试向量,绝不可用于生产加密。
byte[] key = new byte[16];
byte[] nonce = new byte[12];
byte[] plaintext = new byte[16];
SecretKeySpec aesKey = new SecretKeySpec(key, "AES");
Cipher encrypt = Cipher.getInstance("AES/GCM/NoPadding");
encrypt.init(Cipher.ENCRYPT_MODE, aesKey, new GCMParameterSpec(128, nonce));
// Java 的 GCM doFinal 返回 ciphertext || tag。
byte[] sealed = encrypt.doFinal(plaintext);
String ciphertext = HexFormat.of().formatHex(Arrays.copyOfRange(sealed, 0, 16));
String tag = HexFormat.of().formatHex(Arrays.copyOfRange(sealed, 16, sealed.length));
System.out.println("ciphertext=" + ciphertext);
System.out.println("tag=" + tag);
Cipher decrypt = Cipher.getInstance("AES/GCM/NoPadding");
decrypt.init(Cipher.DECRYPT_MODE, aesKey, new GCMParameterSpec(128, nonce));
System.out.println("match=" + Arrays.equals(plaintext, decrypt.doFinal(sealed)));
// 篡改 Tag 的一个比特,认证应失败而不是返回明文。
sealed[sealed.length - 1] ^= 0x01;
Cipher tampered = Cipher.getInstance("AES/GCM/NoPadding");
tampered.init(Cipher.DECRYPT_MODE, aesKey, new GCMParameterSpec(128, nonce));
try {
tampered.doFinal(sealed);
} catch (AEADBadTagException e) {
System.out.println("tampered=AEADBadTagException");
}
}
}预期输出:保存为 GcmInteropCheck.java,用 JDK 17+ 执行 java GcmInteropCheck.java,得到以下结果。
ciphertext=0388dace60b6a392f328c2b971b2fe78
tag=ab6e47d42cec13bdf53a67b21257bddf
match=true
tampered=AEADBadTagException这组向量中的明文恰好是 16 字节,因此可以按前 16 字节和后 16 字节拆出密文与 Tag;实际项目必须根据数据协议和 Tag 长度拆分,不能固定认为密文永远是 16 字节。跨语言对照时还应分别比较两部分,而不只比较编码后的完整字符串。
固化联调结果并验证修复
让 Java、Go、Node.js 或 Flutter 的实现执行同一份测试向量,分别记录算法名称、Key 长度、Nonce、AAD、明文字节、Ciphertext、Tag 及封装规则。先保证这组无敏感信息的向量结果逐字节相同,再检查业务数据的序列化和传输。
如果 Base64 解码阶段报错,优先检查是否漏字符、URL-safe 变体或重复解码;如果能解码但 GCM 认证失败,就依次比对 Key、Nonce、AAD、Ciphertext、Tag 和 Tag 拼接位置。不要把认证失败改成忽略异常后继续处理明文。
修复的验收标准是:两端加密结果能按协议互解、固定向量与预期值一致、任意篡改密文或 Tag 都会被拒绝。生产代码仍应使用密码学安全随机数生成器产生不重复的 Nonce,并按协议携带它。