Tink Python 混合加密实战指南:从 Tinkey 密钥生成到 HybridEncrypt/HybridDecrypt 文件加解密
Tink Python 混合加密实战指南:从 Tinkey 密钥生成到 HybridEncrypt/HybridDecrypt 文件加解密
导读
本指南以 python/examples/hybrid/README.md 为核心,完整讲解如何在 Tink Python 生态中使用混合加密(Hybrid Encryption):先用 Tinkey 命令行工具生成公私钥 keyset,再用 Bazel 构建的 hybrid_cli 命令行工具对文件进行加密与解密,最后深入 hybrid_basic.py 与 hybrid_cli.py 源码,掌握 Tink 加载密钥材料、获取 primitive、执行加解密的标准三步流程。读完本文,你将能够在自己的 Python 项目中安全、正确地落地 Tink 混合加密方案。
一、混合加密是什么,Tink 如何抽象它
混合加密(Hybrid Encryption)结合了非对称加密与对称加密的优势:发送方使用公钥加密(HybridEncrypt),接收方使用私钥解密(HybridDecrypt)。公钥可以公开分发,私钥必须保密,因此特别适合"多方写入、单方读取"的场景,例如把数据加密后上传到云端存储。
Tink 对混合加密的抽象非常简洁,只暴露两个 primitive 接口:
HybridEncrypt:以明文和可选的上下文信息(context info)为输入,输出密文;HybridDecrypt:以密文和上下文信息为输入,还原明文。
在 python/tink/hybrid/init.py 中可以看到这两个抽象类与注册函数被统一导出:
HybridDecrypt = _hybrid_decrypt.HybridDecrypt
HybridEncrypt = _hybrid_encrypt.HybridEncrypt
register = _hybrid_key_manager.register
本示例使用的密钥模板是 DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_AES_256_GCM,即基于 HPKE(RFC 9180)标准的 X25519 KEM + HKDF-SHA256 KDF + AES-256-GCM AEAD 组合。仓库中还提供了同一体系的多个变体,见 python/tink/hybrid/_hybrid_key_templates.py:
| 模板名称 | 说明 |
|---|---|
DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_AES_128_GCM |
AES-128-GCM,TINK 输出前缀 |
DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_AES_128_GCM_RAW |
同上,RAW 输出前缀(无标识前缀) |
DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_AES_256_GCM |
AES-256-GCM,本示例所用模板 |
DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_AES_256_GCM_RAW |
同上,RAW 输出前缀 |
DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_CHACHA20_POLY1305 |
ChaCha20-Poly1305 版本 |
模板名称的命名规则为 KEM_KDF_AEAD:DHKEM_X25519_HKDF_SHA256 表示密钥封装机制(KEM)采用 X25519 曲线与 HKDF-SHA256,HKDF_SHA256 表示密钥派生函数(KDF),AES_256_GCM 表示数据封装机制(DEM)采用 AES-256-GCM。
二、用 Tinkey 生成公私钥 keyset
示例中的测试密钥对已经预生成并提交在仓库中(hybrid_test_private_keyset.json 与 hybrid_test_public_keyset.json)。README 明确说明,这些密钥材料是通过 Tinkey 生成的,操作分两步:
第一步:生成私钥 keyset(包含秘密密钥材料)
$ tinkey create-keyset \
--key-template DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_AES_256_GCM \
--out-format JSON --out hybrid_test_private_keyset.json
参数说明:
--key-template:指定密钥模板,这里使用 HPKE X25519 + HKDF-SHA256 + AES-256-GCM 的组合;--out-format JSON:以 JSON 格式输出,便于阅读与分发;--out:输出文件路径。
第二步:从私钥 keyset 派生公钥 keyset
$ tinkey create-public-keyset --in hybrid_test_private_keyset.json \
--in-format JSON --out-format JSON --out hybrid_test_public_keyset.json
--in/--in-format:指定输入的私钥 keyset 及其格式;--out-format/--out:指定输出的公钥 keyset 格式与路径。
公钥 keyset 不包含任何秘密材料,可以放心随应用分发;私钥 keyset 必须妥善保管。
keyset JSON 结构剖析
以仓库中实际的 hybrid_test_public_keyset.json 为例,其完整内容为:
{"primaryKeyId":958452012,"key":[{"keyData":{"typeUrl":"type.googleapis.com/google.crypto.tink.HpkePublicKey","value":"EgYIARABGAIaIFVkKZkKM++I3AKeVjg9+iogUO9TFQqZ9olnzs1i7Sle","keyMaterialType":"ASYMMETRIC_PUBLIC"},"status":"ENABLED","keyId":958452012,"outputPrefixType":"TINK"}]}
关键字段含义:
primaryKeyId:主密钥 ID,加解密时优先使用该密钥;key<a href="https://link.gitcode.com/i/0624cd718a60f4c4b7ef1786a3cb1fcc" target="_blank">].keyData.typeUrl:密钥类型,公钥为google.crypto.tink.HpkePublicKey,私钥为google.crypto.tink.HpkePrivateKey(见 [hybrid_basic.py 中的内嵌 keyset 示例);key[].keyData.value:Base64 编码的密钥序列化内容;key[].keyData.keyMaterialType:密钥材料类型,公钥为ASYMMETRIC_PUBLIC,私钥为ASYMMETRIC_PRIVATE;key[].status:密钥状态,ENABLED表示启用;key[].outputPrefixType:输出前缀类型,TINK表示密文带 Tink 前缀(用于多密钥场景下快速定位密钥)。
私钥 keyset 的结构与之相同,区别仅在于 keyMaterialType 为 ASYMMETRIC_PRIVATE、typeUrl 为 HpkePrivateKey,且 value 中包含秘密密钥材料,因此绝不可泄露。
三、Bazel 构建与命令行文件加解密
构建
示例代码位于 python/examples/hybrid/,构建方式与 README 给出的流程一致:
$ git clone https://github.com/google/tink
$ cd tink/python/examples
$ bazel build ...
bazel build ... 会构建该目录下的所有 target,其中包括 hybrid_cli 可执行文件(在 BUILD.bazel 中定义为 py_binary,依赖 absl-py、@tink_py//tink:tink_python 与 @tink_py//tink/hybrid)。构建产物路径为 ./bazel-bin/hybrid/hybrid_cli。
用公钥加密文件
$ echo "some data" > testdata.txt
$ ./bazel-bin/hybrid/hybrid_cli --mode encrypt \
--keyset_path ./hybrid/hybrid_test_public_keyset.json \
--input_path testdata.txt --output_path testdata.txt.encrypted
用私钥解密文件
$ ./bazel-bin/hybrid/hybrid_cli --mode decrypt \
--keyset_path ./hybrid/hybrid_test_private_keyset.json \
--input_path testdata.txt.encrypted --output_path testdata.txt.decrypted
$ diff testdata.txt testdata.txt.decrypted
diff 输出为空即说明解密后的文件与原文件完全一致,整个加解密闭环验证成功。
CLI 参数详解(源码级)
hybrid_cli 的全部参数定义在 hybrid_cli.py 中:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
--mode |
枚举 | 是 | encrypt 或 decrypt,指定执行的操作 |
--keyset_path |
字符串 | 是 | 用于加密/解密的 keyset 文件路径 |
--input_path |
字符串 | 是 | 输入文件路径 |
--output_path |
字符串 | 是 | 输出文件路径 |
--context_info |
字符串 | 否 | 加解密时使用的上下文信息,默认为空 |
其中前四个参数在 main 入口处通过 flags.mark_flags_as_required 强制必填(见 hybrid_cli.py)。context_info 参数会被转换为 UTF-8 字节串,未提供时为空字节串 b''。
CLI 的核心执行逻辑(见 hybrid_cli.py)遵循 Tink 的标准三步流程:
- 初始化:调用
hybrid.register()注册混合加密的 key manager; - 加载密钥材料:用
tink.json_proto_keyset_format.parse(text, secret_key_access.TOKEN)将 JSON keyset 解析为 keyset handle; - 获取 primitive 并执行加解密:
encrypt模式通过keyset_handle.primitive(hybrid.HybridEncrypt)获取加密原语并调用primitive.encrypt(data, context_info);decrypt模式则获取hybrid.HybridDecrypt并调用primitive.decrypt(data, context_info)。
值得注意的是,读取 keyset 或创建 primitive 失败时都会抛出 tink.TinkError,CLI 捕获后通过 logging.exception 记录错误并返回退出码 1(见 hybrid_cli.py),这为脚本化调用提供了可靠的错误判断依据。
四、Python API 编程示例:不依赖 CLI 直接加解密
如果希望在自己的 Python 程序中直接使用混合加密,而不经过命令行,可以参考 hybrid_basic.py 中的完整示例。该文件顶部注释标明了 [START hybrid-basic-example],代码以 def example() 形式组织,核心步骤逐行解读如下。
1. 注册 key manager
import tink
from tink import hybrid
from tink import secret_key_access
hybrid.register()
hybrid.register() 的作用是向 Tink 注册混合加密相关的 key manager,这是创建 HybridEncrypt / HybridDecrypt primitive 的前提。
2. 加载公钥 keyset(无需秘密访问权限)
public_keyset_handle = tink.json_proto_keyset_format.parse_without_secret(
public_keyset
)
enc_primitive = public_keyset_handle.primitive(hybrid.HybridEncrypt)
ciphertext = enc_primitive.encrypt(b'message', b'context_info')
公钥 keyset 不包含任何秘密材料,因此使用 parse_without_secret 解析即可,无需提供访问令牌。随后通过 keyset_handle.primitive(hybrid.HybridEncrypt) 获取加密原语并加密消息。encrypt 的第一个参数是明文,第二个参数是上下文信息(此处为 b'context_info')。
3. 加载私钥 keyset(需要秘密访问令牌)
private_keyset_handle = tink.json_proto_keyset_format.parse(
private_keyset, secret_key_access.TOKEN
)
dec_primitive = private_keyset_handle.primitive(hybrid.HybridDecrypt)
decrypted = dec_primitive.decrypt(ciphertext, b'context_info')
assert decrypted == b'message'
私钥 keyset 含有秘密密钥材料,解析时必须传入 secret_key_access.TOKEN 以显式声明访问权限。解密时传入与加密时完全相同的上下文信息,Tink 会自动在 keyset 中找到对应的密钥完成解密;若找不到匹配密钥或解密失败,会抛出异常。示例末尾的 assert decrypted == b'message' 验证了解密结果与原始明文一致。
4. 一个重要的安全提醒
hybrid_basic.py 中的注释明确警告:在生产环境中,通过 tink.json_proto_keyset_format.parse 以明文方式传入密钥材料本身就是一种安全风险。实际项目应使用 KMS 加密的 keyset、远程密钥服务等更安全的密钥管理方式。本示例的 keyset 是演示用途,切勿照搬到生产环境。
五、context_info(上下文信息)的作用与测试验证
context_info 是混合加密中的一项重要机制:它是一个可选的"关联数据",会参与加密过程但不会被加密。其价值在于将密文与特定的业务上下文绑定——如果解密时提供的上下文信息与加密时不一致,解密将失败。
这一点在 hybrid_cli_test.sh 中得到了完整的验证,测试脚本覆盖了四个典型场景:
test_encrypt_decrypt_succeeds:不使用 context_info 加解密,cmp比对明文与解密结果一致;test_encrypt_decrypt_succeeds_with_context:加密与解密均使用相同的CONTEXT_INFORMATION="context information",解密成功;test_encrypt_decrypt_fails_with_context:加密时使用 context_info,解密时不提供,解密命令返回码为 1(失败符合预期,见 hybrid_cli_test.sh);test_encrypt_fails_with_wrong_keyset:用私钥 keyset 执行加密,加密命令返回码为 1(失败符合预期,见 hybrid_cli_test.sh),因为加密只能使用公钥。
第三个场景尤其值得注意:它证明 context_info 是密文完整性的组成部分,只要解密方提供的上下文信息不匹配,即使持有正确的私钥也无法还原明文。因此可以将 context_info 用作"协议标识"或"会话标识",进一步缩小密文被滥用的范围。
此外,单元测试 hybrid_basic_test.py 通过 absltest 直接调用 hybrid_basic.example(),验证了上一节完整 API 流程的正确性。在 Bazel 环境下,这两个测试分别由 BUILD.bazel 中的 hybrid_test(sh_test)与 hybrid_basic_test(py_test)target 驱动。
六、依赖与运行环境说明
- Bazel 方式:进入 python/examples/ 后执行
bazel build ...,示例依赖在 python/examples/WORKSPACE 中声明,并引用@tink_py下的tink_python、secret_key_access、tink/hybrid等 target(见 BUILD.bazel)。 - pip 安装方式:仓库同时提供
hybrid_test_package测试 target,其注释表明可先通过pip3 install安装 Tink Python 包,再直接以python3 hybrid_cli.py运行(见 BUILD.bazel)。 - 运行时依赖:示例依赖
absl-py(提供 flags 与 logging 能力),声明于 python/examples/requirements.in。
七、总结
本示例演示了 Tink Python 混合加密的完整闭环:
- 密钥生成:用
tinkey create-keyset+create-public-keyset生成 HPKE 公私钥对,公钥公开分发、私钥严格保密; - 命令行加解密:
hybrid_cli --mode encrypt/decrypt对任意文件执行加解密,配合--context_info绑定业务上下文; - API 编程:
hybrid.register()→ 加载 keyset 生成 handle →handle.primitive(...)获取原语 → 调用encrypt/decrypt,全程只有三步; - 安全要点:私钥 keyset 的解析必须显式使用
secret_key_access.TOKEN,且生产环境应避免以明文形式传递密钥材料。
无论你是想在 Python 项目中快速验证混合加密,还是希望深入理解 Tink 的 primitive 抽象与 keyset 格式,都可以以此为起点,进一步阅读 python/tink/hybrid/ 下的模板定义与 key manager 实现,掌握更细粒度的控制能力。