AES/GCM 怎样处理 AEAD 标签

在 Java 里处理 AES/GCM 的 AEAD 标签，关键不是把标签当成另一把密钥，而是把它当成认证结果的一部分来管理：加密端保存并传输 IV、密文和标签，解密端用完全相同的标签长度与 AAD 重新组合输入，最后由 Cipher.doFinal() 完成校验。校验失败时会抛出 AEADBadTagException，这时不能继续使用返回的明文。

AES/GCM 使用 AES/GCM/NoPadding，标签长度在 GCMParameterSpec 中按 bit 指定。以常见的 128 bit 标签为例，Java 加密结果的最后 16 个字节可以按应用协议拆成标签；解密时必须把这 16 个字节拼回密文输入，并让 IV、AAD、密钥和标签长度保持一致。

官方文档：https://docs.oracle.com/en/java/javase/25/docs/api/java.base/javax/crypto/spec/GCMParameterSpec.html

先把 AEAD 标签放回正确的位置

GCM 同时提供加密和认证。Java 的 GCMParameterSpec 接收两个核心参数：IV，以及认证标签长度 tLen。这里的 tLen 单位是 bit，不是 byte；因此 128 bit 对应 16 byte。Java SE 文档列出的标准变换名是 AES/GCM/NoPadding，不要把 PKCS5Padding 再拼到 GCM 上。

应用层可以使用下面这样的封装格式：

IV | ciphertext | tag

这是一种便于接口传输的约定，不代表 Cipher 返回了三个独立对象。对常见 JCE 用法来说，doFinal(plainText) 返回的是密文和认证标签拼接后的字节数组；应用代码再按约定拆开，或者从始至终把它作为一个整体保存。无论选择哪种格式，协议都必须明确标签长度，不能让接收方靠猜测截取。

加密端怎样拆出标签

下面的示例把标签拆成独立字段，便于展示协议边界。示例固定使用 128 bit 标签，并把 AAD 作为只认证、不加密的元数据传入。真实项目还应保证每次加密使用新的 IV；同一密钥下重复使用 IV 会破坏 GCM 的安全边界。

import javax.crypto.Cipher;
import javax.crypto.spec.GCMParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.security.GeneralSecurityException;
import java.security.SecureRandom;
import java.util.Arrays;

record GcmPacket(byte[] iv, byte[] ciphertext, byte[] tag) {}

public final class AesGcmTags {
    private static final int TAG_BITS = 128;
    private static final int TAG_BYTES = TAG_BITS / 8;
    private static final int IV_BYTES = 12;

    private AesGcmTags() {}

    public static GcmPacket seal(byte[] key, byte[] aad, byte[] plainText)
            throws GeneralSecurityException {
        byte[] iv = new byte[IV_BYTES];
        // 每次加密都生成新的 IV；IV 不需要保密，但必须和密文一起保存。
        new SecureRandom().nextBytes(iv);

        Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
        SecretKeySpec secretKey = new SecretKeySpec(key, "AES");
        cipher.init(Cipher.ENCRYPT_MODE, secretKey,
                new GCMParameterSpec(TAG_BITS, iv));
        // AAD 只参加认证，不会出现在 ciphertext 中；解密时必须原样提供。
        cipher.updateAAD(aad);

        // JCE 的 GCM 输出通常是 ciphertext 后跟 tag，应用协议在此明确拆分。
        byte[] ciphertextAndTag = cipher.doFinal(plainText);
        int ciphertextBytes = ciphertextAndTag.length - TAG_BYTES;
        byte[] ciphertext = Arrays.copyOfRange(ciphertextAndTag, 0, ciphertextBytes);
        byte[] tag = Arrays.copyOfRange(ciphertextAndTag, ciphertextBytes,
                ciphertextAndTag.length);
        return new GcmPacket(iv, ciphertext, tag);
    }
}

这里的 TAG_BYTES 来自同一份协议定义，而不是从某次返回值临时推断。拆分前应至少确认输出长度不小于标签长度；如果上游协议使用 96 bit 或其他允许的标签长度，解密端也必须使用同一个数值，不能仍按 16 字节处理。

解密端为什么要把标签拼回去

解密时，标签不是通过另一个单独的“验证 API”提交的。应用层先把接收到的密文和标签拼接回 Cipher 所需的输入，再用相同的 IV、标签长度和 AAD 初始化解密 Cipher。updateAAD 要在处理密文前调用，并且 AAD 的字节内容必须完全一致，哪怕只是编码或字段顺序变化，也会导致认证失败。

public static byte[] open(byte[] key, byte[] aad, GcmPacket packet)
        throws GeneralSecurityException {
    Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
    SecretKeySpec secretKey = new SecretKeySpec(key, "AES");
    cipher.init(Cipher.DECRYPT_MODE, secretKey,
            new GCMParameterSpec(TAG_BITS, packet.iv()));
    // AAD 必须与加密侧逐字节一致，否则标签不会通过认证。
    cipher.updateAAD(aad);

    byte[] ciphertextAndTag = new byte[packet.ciphertext().length + packet.tag().length];
    System.arraycopy(packet.ciphertext(), 0, ciphertextAndTag, 0,
            packet.ciphertext().length);
    System.arraycopy(packet.tag(), 0, ciphertextAndTag, packet.ciphertext().length,
            packet.tag().length);
    // doFinal 会同时解密并校验 tag；不要在校验前把明文交给业务层。
    return cipher.doFinal(ciphertextAndTag);
}

如果采用整体字段存储，也可以直接把接收到的 ciphertextAndTag 传给 doFinal，不必人为拆分。拆分的价值主要是让协议字段清晰、方便序列化和排查长度问题；它不是 AES/GCM 的额外步骤。

标签校验失败时应该怎样处理

Oracle 对 AEADBadTagException 的定义是：AEAD 模式无法验证传入的认证标签时抛出的异常。常见原因包括标签被截断、密文被改动、AAD 不一致、IV 取错、密钥不一致或标签长度配置不同。它们都应该进入同一个“认证失败”边界，而不应被降级成“尝试解密后继续使用”。

try {
    byte[] plainText = AesGcmTags.open(key, aad, packet);
    // 只有 doFinal 成功返回后，明文才进入业务处理。
    consume(plainText);
} catch (javax.crypto.AEADBadTagException e) {
    // 认证失败时丢弃明文，并记录可关联但不泄露密钥的业务日志。
    rejectMessage("AES/GCM authentication failed");
} catch (GeneralSecurityException e) {
    // 算法、密钥或参数类错误按系统配置/执行错误单独处理。
    reportCryptoConfigurationError(e);
}

不要为了“兼容脏数据”而捕获异常后返回空字符串、使用部分明文，或改用另一把密钥再试一次。这样会把认证边界变成业务层难以察觉的数据错误，也会让攻击者获得更多试探机会。

一张表排查 AES/GCM 标签问题

最容易忽略的是“标签长度的单位”和“AAD 的字节一致性”。如果协议文档写的是 16 字节，传给 GCMParameterSpec 时应转换成 128；如果 AAD 来自 JSON、HTTP 头或字符串，必须先固定编码和字段顺序，再交给 Cipher，不能在两端各自重新格式化。

结论

处理 AES/GCM AEAD 标签可以归纳为五件事：用 AES/GCM/NoPadding 明确变换；用 bit 指定标签长度；把 IV、密文、标签的封装格式写进协议；解密时以相同参数拼回密文与标签；只在 doFinal 成功后使用明文。标签验证失败就拒绝消息，不要把它当成普通的字符串解码问题。

相关问题

GCM 标签长度应该写 16 还是 128？

协议存储时通常说 16 字节，但 GCMParameterSpec 构造函数要求的是 bit，所以对应值是 128。两端要同时统一表达和换算。

AAD 会不会出现在密文里？

不会。AAD 只参与认证，解密端必须重新提供同样的字节内容；如果业务需要读取它，仍要把它作为协议字段单独传输。

为什么只改一个标签字节也无法解密？

因为标签是认证结果的一部分，任何密文、AAD、IV、密钥或标签内容变化都会使最终计算值不匹配，Java 会在 doFinal 阶段抛出 AEADBadTagException。