密码学与证书 / 系统课时

排查加解密不一致

排查加解密不一致

跨语言联调时,发送端加密成功、接收端却无法解密,问题往往出在字节编码、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 不加密,但参与认证。

沿接收链路定位格式错误

解密前按数据实际流动顺序检查,发现第一处不一致就先修正,不要一次修改多个参数。

  1. 传输层:先确定 Base64 包裹的是 ciphertext,还是 nonce || ciphertext || tag。Base64 必须按照约定解码一次,不能把 Base64 字符串的 UTF-8 字节直接送入解密器。
  2. 封装层:明确各字段的字节长度和位置。有的语言库把 Tag 单独返回,而 Java JCE 的 GCM doFinal 接收和返回的密文形式通常是 ciphertext || tag;Nonce 通过初始化参数传入,不在这段结果里。
  3. 密钥层:根据 keyId 在各自受控环境中取得正确 Key,核对长度和编码。十六进制、Base64 与原始二进制不能混用。
  4. 认证层:核对 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 只供测试,绝不可用于真实数据加密。

java
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,得到以下结果。

text
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,并按协议携带它。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

排查加解密不一致

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通