使用 Tink Java AEAD 示例加密文件:从密钥生成到加解密实战

原创2026-09-21 13:24:481,949 阅读
文章标签:密码学

使用 Tink Java AEAD 示例加密文件:从密钥生成到加解密实战

导读

本文基于 Tink 仓库中的 Java AEAD 示例,完整讲解如何使用 Tink 的认证加密(Authenticated Encryption with Associated Data,AEAD)原语对文件进行加密与解密。你将掌握 Tink 使用的基本三步流程——加载密钥材料、获取原语(primitive)、调用原语完成加解密,并了解如何用 Tinkey 生成密钥集(keyset)、用 Bazel 构建运行命令行示例,以及 AEAD 的 associated data 在防篡改中的实际作用。读完本文,你可以直接复用这套示例构建自己的文件加密工具。

AEAD 是什么:为什么要用 Tink 做文件加密

AEAD(Authenticated Encryption with Associated Data)是一种同时保证机密性(confidentiality)与完整性/真实性(integrity/authenticity)的加密方案。与单纯的加密不同,AEAD 在加密明文的同时还会计算认证标签(authentication tag),任何对密文的篡改都会在解密时被检测出来,解密直接失败而不是返回被篡改的"垃圾"数据。

Tink 是一套多语言、跨平台的开源加密库,其设计目标是提供安全、易于正确使用、难以误用的加密 API。Tink 的核心设计理念包括:

  • 高层抽象:开发者面对的是 Aead、Mac、HybridEncrypt 等"原语"接口,而非底层密码算法细节;
  • 密钥管理与轮换:通过 keyset(密钥集)管理多个密钥,支持主密钥(primary key)和密钥轮换;
  • 防误用:默认采用安全算法组合与安全的实现方式,降低开发者误用风险。

本示例是理解 Tink 使用方式的最小完整闭环:加载 keyset → 获取 Aead 原语 → 调用 encrypt/decrypt。

示例文件结构

该示例位于 java_src/examples/aead 目录,包含以下文件:

文件 作用
AeadExample.java 命令行加解密程序主逻辑
BUILD.bazel Bazel 构建规则与测试规则
aead_example_test.sh 端到端 shell 测试脚本
aead_test_keyset.json 用 Tinkey 生成的 AES128_GCM 测试密钥集
README.md 官方使用说明

用 Tinkey 生成密钥集

Tinkey 是 Tink 官方的命令行工具,用于生成和管理密钥集。示例中的密钥材料正是用 Tinkey 生成的(参见 README.md):

tinkey create-keyset --key-template AES128_GCM --out-format JSON \
    --out aead_test_keyset.json

参数说明:

  • --key-template AES128_GCM:指定密钥模板为 AES-128-GCM,这是 Tink 预定义的最常用的 AEAD 密钥模板之一。Tink 还提供 AES256_GCM、AES128_CTR_HMAC_SHA256、AES128_EAX、AES128_GCM_SIV 等模板(可在 AeadKeyTemplates.java 中查看完整定义,例如 AES128_GCM 对应 16 字节 AES 密钥,AES256_GCM 对应 32 字节);
  • --out-format JSON:以 JSON 格式输出密钥集,便于阅读和版本管理;
  • --out aead_test_keyset.json:输出文件名。

生成的密钥集内容形如 aead_test_keyset.json:

{
  "primaryKeyId": 1931667682,
  "key": [{
    "keyData": {
      "typeUrl": "type.googleapis.com/google.crypto.tink.AesGcmKey",
      "value": "GhD+9l0RANZjzZEZ8PDp7LRW",
      "keyMaterialType": "SYMMETRIC"
    },
    "status": "ENABLED",
    "keyId": 1931667682,
    "outputPrefixType": "TINK"
  }]
}

各字段含义:

  • primaryKeyId:主密钥 ID,加解密时 Tink 默认使用该密钥;
  • keyData.typeUrl:密钥类型,这里是 AesGcmKey;
  • keyData.value:Base64 编码的密钥字节;
  • keyData.keyMaterialType:密钥材料类型,对称密钥为 SYMMETRIC;
  • status:密钥状态,ENABLED 表示可用;
  • outputPrefixType:输出前缀类型,TINK 表示密文前会带上密钥 ID 前缀,便于多密钥场景下识别使用哪个密钥。

⚠️ 安全提醒:示例中密钥是明文存储在磁盘上的。AeadExample.java 的注释明确提示"This loads cleartext keys from disk - this is not recommended!"。生产环境中应使用 KMS 加密的 keyset 或密钥管理系统,示例仅用于演示。

用 Bazel 构建示例

工作区配置

示例的构建依赖通过 java_src/examples/WORKSPACE 配置,它通过 local_repository 将上层目录(即 java_src)作为 @tink_java 依赖引入,并加载 tink_java_deps() 与 tink_java_deps_init() 拉取 Tink 的 Maven 依赖:

local_repository(
    name = "tink_java",
    path = "../",
)

如果你的工作区在独立仓库中,可将 local_repository 替换为 http_archive(文件中有注释掉的示例)。

构建命令

git clone https://github.com/google/tink
cd tink/examples/java_src
bazel build ...

bazel build ... 会构建 aead 等所有示例目标。构建产物为 ./bazel-bin/aead/aead_example 可执行文件。

构建规则解读

BUILD.bazel 定义了 Java 可执行目标:

java_binary(
    name = "aead_example",
    srcs = ["AeadExample.java"],
    main_class = "aead.AeadExample",
    deps = [
        "@tink_java//src/main/java/com/google/crypto/tink:aead",
        "@tink_java//src/main/java/com/google/crypto/tink:insecure_secret_key_access",
        "@tink_java//src/main/java/com/google/crypto/tink:registry_cluster",
        "@tink_java//src/main/java/com/google/crypto/tink:tink_json_proto_keyset_format",
        "@tink_java//src/main/java/com/google/crypto/tink/aead:aead_config",
    ],
)

依赖项对应代码中的核心 API:

  • aead:Aead 原语接口;
  • insecure_secret_key_access:InsecureSecretKeyAccess,读取明文密钥材料所需的安全令牌;
  • registry_cluster:Tink 运行时注册表;
  • tink_json_proto_keyset_format:TinkJsonProtoKeysetFormat,用于解析 JSON 格式 keyset;
  • aead_config:AeadConfig,注册所有 AEAD 密钥类型。

运行加解密:命令行实战

加密文件

echo "some data" > testdata.txt

./bazel-bin/aead/aead_example encrypt \
    ./aead/aead_test_keyset.json \
    testdata.txt testdata.txt.encrypted

命令格式为 aead_example <encrypt|decrypt> <key-file> <input-file> <output-file> [associated-data]。执行后 testdata.txt.encrypted 即为密文文件。

解密文件

./bazel-bin/aead/aead_example decrypt \
    ./aead/aead_test_keyset.json \
    testdata.txt.encrypted testdata.txt.decrypted

diff testdata.txt testdata.txt.decrypted

diff 输出为空即说明解密成功,原文与解密结果完全一致。

参数详解

AeadExample.java 的主函数要求 4 或 5 个参数:

位置 参数 说明
1 mode encrypt 或 decrypt
2 key-file 密钥集文件路径(JSON 格式)
3 input-file 输入文件路径
4 output-file 输出文件路径
5(可选) associated-data 关联数据,UTF-8 编码,缺省为空字节数组

源码拆解:Tink 使用三步走

AeadExample.java 完整展示了 Tink 的标准使用流程,共三步:

第一步:注册密钥类型

AeadConfig.register();

该调用向 Tink 运行时注册所有 AEAD 密钥类型。查看 AeadConfig.java 的实现可知,它会注册 AesCtrHmacAeadKeyManager 和 AesGcmKeyManager;在非 FIPS 模式下还会注册 AesEaxKeyManager、AesGcmSivKeyManager、ChaCha20Poly1305KeyManager、KmsAeadKeyManager、KmsEnvelopeAeadKeyManager、XChaCha20Poly1305KeyManager 等。由于 AEAD 密钥类型依赖 MAC 密钥类型,该方法同时会注册所有 MAC 密钥管理器(MacConfig.register())。

第二步:加载密钥集并获取原语

KeysetHandle handle =
    TinkJsonProtoKeysetFormat.parseKeyset(
        new String(Files.readAllBytes(keyFile), UTF_8), InsecureSecretKeyAccess.get());

Aead aead = handle.getPrimitive(Aead.class);

TinkJsonProtoKeysetFormat.parseKeyset 将 JSON 字符串解析为 KeysetHandle。第二个参数 InsecureSecretKeyAccess.get() 是一个访问令牌,用于明确声明"以不安全方式访问明文密钥",这是 Tink 的安全设计:任何涉及密钥材料访问的 API 都必须显式携带访问令牌,防止无意中泄露密钥。

handle.getPrimitive(Aead.class) 根据 keyset 中的密钥类型,从注册表找到对应的密钥管理器,构造出 Aead 原语实例。之后所有加解密都通过这个接口完成,不再接触底层算法细节。

第三步:调用原语完成加解密

if (MODE_ENCRYPT.equals(mode)) {
  byte[] plaintext = Files.readAllBytes(inputFile);
  byte[] ciphertext = aead.encrypt(plaintext, associatedData);
  Files.write(outputFile, ciphertext);
} else if (MODE_DECRYPT.equals(mode)) {
  byte[] ciphertext = Files.readAllBytes(inputFile);
  byte[] plaintext = aead.decrypt(ciphertext, associatedData);
  Files.write(outputFile, plaintext);
}
  • aead.encrypt(plaintext, associatedData):返回密文;
  • aead.decrypt(ciphertext, associatedData):返回明文;如果密文被篡改,或解密时传入的 associatedData 与加密时不同,解密会抛出异常直接失败。

深入理解 associated data(关联数据)

associated data 是 AEAD 的关键特性:它参与认证但不被加密。加密时传入的 associated data 会被绑定到认证标签中,解密时必须传入完全相同的 associated data 才能成功。

典型应用场景:在加密数据库字段时,把主键或用户 ID 作为 associated data,这样即使密文被整体迁移到其他用户记录下,解密也会失败,从而防止密文替换攻击。

aead_example_test.sh 用四个用例完整验证了这一特性:

  1. 正常加密解密:使用同一 keyset 加密后解密,内容一致;
  2. 篡改密文导致解密失败:对密文追加 "modified" 后解密,进程以退出码 1 失败(测试脚本断言 TEST_STATUS -eq 1);
  3. 正确 associated data 加解密成功:加密解密都传 "header information",成功;
  4. 修改 associated data 导致解密失败:解密时改传 "modified header information",进程以退出码 1 失败。

命令行中可这样传 associated data:

./bazel-bin/aead/aead_example encrypt \
    ./aead/aead_test_keyset.json \
    testdata.txt testdata.txt.encrypted "header information"

./bazel-bin/aead/aead_example decrypt \
    ./aead/aead_test_keyset.json \
    testdata.txt.encrypted testdata.txt.decrypted "header information"

若解密时 associated data 不一致,命令将直接失败退出。

运行自动化测试

除了手动验证,示例还提供了 Bazel 测试目标,一条命令即可跑完加解密全流程的自动化验证:

bazel test //aead:aead_example_test

BUILD.bazel 中定义了 sh_test,它把可执行文件和密钥集文件作为参数传给 aead_example_test.sh,测试覆盖了上面提到的全部四种场景,是学习 AEAD 行为边界的绝佳参考。

进一步阅读

登录后查看全文
tink