Tink 的密钥代际就在密文前 5 字节:0x01 加 key ID,以及 rotate() 为什么被弃用
项目信息:
- Tink 主仓库:
- Java 实现:
- Wire format:
- Keysets design:
5 字节前缀:0x01 加 key ID
Tink 的大多数 primitive 会在输出前面放 5 字节前缀:1 字节版本号 0x01,后跟 4 字节的 key hint,也就是实际使用的 key ID。部分 legacy key 的版本字节是 0x00;Prehash primitive 使用 0xff。
这些前缀不参与认证,不能用于安全目的。它只是一个提示,用来加速解密/验签,或在签名场景下帮助选择签名密钥。
AEAD 的线上布局是:
prefix || IV || ciphertext || tag
其中 prefix 要么为空,要么是 5 字节。
tink.proto 里的 Keyset 与 Key
message Keyset {
uint32 primary_key_id = 1;
repeated Key key = 2;
}
message Key {
KeyData key_data = 1;
KeyStatusType status = 2;
uint32 key_id = 3;
OutputPrefixType output_prefix_type = 4;
}
KeyStatusType 的取值:
| 值 | 名称 | 含义 |
|---|---|---|
| 0 | UNKNOWN_STATUS | 未知 |
| 1 | ENABLED | 可用于密码操作 |
| 2 | DISABLED | 不可用但仍在 keyset 中,可以再启用 |
| 3 | DESTROYED | 密钥材料已不在 keyset 中 |
OutputPrefixType 的取值:
| 值 | 名称 | 前缀行为 |
|---|---|---|
| 0 | UNKNOWN_PREFIX | 未知 |
| 1 | TINK | 5 字节,0x01 开头 + 4 字节随机生成的 key ID |
| 2 | LEGACY | 5 字节,0x00 开头 + 4 字节由密钥材料派生的 key ID;签名方案与 MAC 还会在被签/被 MAC 数据末尾追加一个 0x00 字节 |
| 3 | RAW | 0 字节,即空前缀 |
| 4 | CRUNCHY | 5 字节,0x00 开头 + 4 字节随机 key ID |
KeyData 包含 type_url、value 和 key_material_type(SYMMETRIC / ASYMMETRIC_PRIVATE / ASYMMETRIC_PUBLIC / REMOTE)。
Key 里的 version 是“实现版本”,不是密钥代际
每个 Key proto 按约定带一个 uint32 version 字段,标识该 key 的实现版本。除特别说明外只有 version 0。实现必须只接受已知 version,遇到未知 version 要拒绝。
密钥代际不是这个字段,而是 keyset 里的 primary_key_id 与各 Key 的 key_id 关系,以及 status 的组合。
前缀只能当提示,不能当身份
keyset 是非空 key 列表,其中一个是 primary,用于加密/签名新数据。解密时会用所有 key 尝试,顺序有优化;key ID 在 keyset 内唯一,status 允许禁用而不删除。
key ID 前缀是 key 的一部分:同一 keyset 内 ID 唯一,所以前缀唯一,看似只需尝试一个 key。但前缀不被认证,可以被任何人改写,Tink 不把 key ID 密码学绑定到密文/签名上,因此不能只靠前缀判断密文是哪个 key 产出的。
RAW 的 idRequirement 为 null,没有前缀可用,解密需要遍历全部 key 尝试。有些 primitive(如 PRF)无法嵌入前缀。NO_PREFIX_WITH_PREHASH_ID 变体的签名 key 有 ID 要求但输出无前缀,Prehash primitive 会把 key ID 写进 prehash 值,方便远程签名方选择 key——这些都属于明文元数据。
轮换的四步与 rotate() 的弃用
轮换必须谨慎,顺序是:
- 由 KMS 向 keyset 加入新 key,但暂不设为 primary;
- 把新 keyset 下发到所有二进制;
- 新 key 设为 primary;
- 再下发一次。
KeysetManager.rotate(template) 内部调用 addNewKey(template, true),即加 key 并立即设为 primary;add(template) 是 addNewKey(template, false)。setPrimary 在 key 非 ENABLED 时抛 "cannot set key as primary because it's not enabled: " + keyId,找不到时抛 "key not found: " + keyId。newKeyId 用 Util.randKeyId 随机生成并在 keyset 内查重。
Go 侧的 go/keyset 里,Manager.Add 生成并加入新 key,保持 enabled 但不设 primary,返回 ID;Rotate 生成新 key 并立即设为 primary,已标记 Deprecated,注释说明做 keyset 轮换时几乎从不希望新加的 key 立刻成为 primary,应留出 key 传播时间;SetPrimary(keyID) 找不到或非 enabled 就报错。
issue tink-crypto/tink#562 里 juergw 的解释:如果一次下发同时“新增 key 并且设为主 key”,且有两台以上服务器,那么一台服务器会在其他服务器尚不知道如何用新 key 解密时就开始用新 key 加密。所以要拆成两步:先下发含新 key 但不设 primary 的 keyset;等所有服务器都有这份 keyset 后,再下发把新 key 设为 primary 的 keyset。
Java 示例:
KeysetHandle newKeyset = KeysetHandle.newBuilder(oldKeyset)
.addEntry(generateEntryFromParametersName("AES256_CMAC_RAW").withRandomId())
.build();
// 传播完成后再把新 key 设为主 key
builder.getAt(builder.size() - 1).makePrimary();
makePrimary() 需要 Tink 1.7。
KeysetHandle.Builder.build() 的校验与报错
- 没有任何 entry 标为主 key →
"No primary was set" - 重复设置 primaryId →
"Two primaries were set" - primary 状态非 ENABLED →
"Primary key is not enabled" - ID 重复 →
"Id " + id + " is used twice in the keyset" - 未设置 ID →
"No ID was set (with withFixedId or withRandomId)" withRandomId的 entry 之后不能再跟非withRandomId的 entrybuild()只能调用一次;withRandomId会让两次 build 产生不同 key ID- 导入的带 ID 要求的 key 必须使用其固定 ID,
withRandomId对其非法
getPrimary() 在 primary 非 ENABLED 时抛 IllegalStateException("Keyset has primary which isn't enabled"),无 primary 时抛 "Keyset has no valid primary"。
Builder 的注释也承认,目前仍接受重复 ID 与“没有 primary”的 keyset,将来会拒绝。
脱敏元数据:KeysetInfo 与 EncryptedKeyset
EncryptedKeyset 包含加密后的 serialized keyset,以及可选的未加密 KeysetInfo 元数据。KeysetInfo 是不含密钥材料的安全 keyset,可用于日志和监控。