使用 Tink Java AEAD 示例加密文件:从密钥生成到加解密实战
使用 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 用四个用例完整验证了这一特性:
- 正常加密解密:使用同一 keyset 加密后解密,内容一致;
- 篡改密文导致解密失败:对密文追加
"modified"后解密,进程以退出码 1 失败(测试脚本断言TEST_STATUS -eq 1); - 正确 associated data 加解密成功:加密解密都传
"header information",成功; - 修改 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 行为边界的绝佳参考。
进一步阅读
- 密钥管理最佳实践:见 KEY-MANAGEMENT.md
- Tink Java 使用指南:JAVA-HOWTO.md
- 支持的 AEAD 密钥模板定义:AeadKeyTemplates.java
- 其他语言版本的同款示例:cc/examples/aead、python/examples/aead、go/aead