编程 Tink 的密钥代际就在密文前 5 字节:0x01 加 key ID,以及 rotate() 为什么被弃用

2026-11-23 00:07:54

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 的取值:

值名称含义
0UNKNOWN_STATUS未知
1ENABLED可用于密码操作
2DISABLED不可用但仍在 keyset 中,可以再启用
3DESTROYED密钥材料已不在 keyset 中

OutputPrefixType 的取值:

值名称前缀行为
0UNKNOWN_PREFIX未知
1TINK5 字节,0x01 开头 + 4 字节随机生成的 key ID
2LEGACY5 字节,0x00 开头 + 4 字节由密钥材料派生的 key ID;签名方案与 MAC 还会在被签/被 MAC 数据末尾追加一个 0x00 字节
3RAW0 字节,即空前缀
4CRUNCHY5 字节,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() 的弃用

轮换必须谨慎,顺序是:

  1. 由 KMS 向 keyset 加入新 key,但暂不设为 primary;
  2. 把新 keyset 下发到所有二进制;
  3. 新 key 设为 primary;
  4. 再下发一次。

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 的 entry
  • build() 只能调用一次;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,可用于日志和监控。

复制全文 生成海报 密钥代际 Tink 密钥轮换 密码学 Go Java

推荐文章

程序员茄子在线接单