前言
上一篇文章:密码敏捷性:把「密码终有一天会被攻破」作为系统设计前提提到了一种类似棘轮只能单向前进、防止逆转的机制,可以逐步推出新算法并淘汰旧算法,基于这个概念整理成了一个简单的 Go 库 riceball-tw/ratchet。
回顾背景与问题
每种算法与密钥都像一把额外的钥匙,没有统一管理时就会散落在各个地方:
// 加密:每个调用点自行决定算法与密钥ct, _ := EncryptCBC(plaintext, key, iv)
// 解密:每个调用点自行判断这条数据是哪种格式if isGCM(stored) { pt, _ = DecryptGCM(stored, newKey)} else { pt, _ = DecryptCBC(stored, key, iv)}这时遇到两种常见需求都会很麻烦:
- 升级算法:例如 CBC 没有完整性验证,想换成 AEAD 中的 GCM 时,每个调用点都要改,数据库里的 CBC 数据还得继续解密,所以要注意兼容旧数据。
- 轮换密钥:密钥泄露或定期更换时,新数据要用新密钥,旧密钥加密的数据也要能读取,同样每个调用点都要知道这些信息。
ratchet 就像一个钥匙圈,把所有钥匙收在一起,调用方只管「锁」和「开」,升级算法或轮换密钥,都只需修改钥匙圈的配置,调用代码一行都不用动:
env, _ := r.Encrypt(plaintext, aad) // 加密:始终使用最新的钥匙pt, _ := r.Decrypt(env, aad) // 解密:根据密文上的标签自动选择正确的钥匙| 需求 | 负责加密(Current) | 只负责解密(DecryptOnly) |
|---|---|---|
| CBC 升级为 GCM | GCM v1/keyA | 旧的 CBC |
| 轮换密钥 | GCM v1/keyB | GCM v1/keyA |
钥匙圈依靠两件事运作,并坚持棘轮式的策略:
- 规定格式:每条密文都标明使用了哪把钥匙(算法版本 + 密钥 ID)。
- 初始化时确定策略:哪一把负责加密,哪些只负责解密。
棘轮策略?
棘轮:只能朝单一方向转动的齿轮
在加解密中,这个概念就变成了生成新加密数据时只能使用新算法,旧方案可以读取,但永远不再用于加密。
- 加密始终只有一个方案,而且只会向前升级:旧方案 → v1 → v2
- 旧方案先降为仅解密,等旧数据迁移完再移除
库的核心概念
想通过具体使用场景来了解,可以查看下一节,本节从库的实现细节出发,分析使用方式与设计取舍。
初始化参数
v1, _ := aesgcm.New(ratchet.Ref{Version: 1, KeyID: "mk1"}, key)r, _ := aead.New(aead.Config{ Current: v1, DecryptOnly: []aead.Decrypter{ aead.DecrypterFunc(ratchet.Unversioned, legacyDecrypt), },})
env, _ := r.Encrypt([]byte("你好"), aad)| 角色 | 类型 | 加密 | 解密 | 含义 |
|---|---|---|---|---|
| Current | aead.Cipher | ✅ | ✅ | 所有新数据唯一使用的方案 |
| DecryptOnly | aead.Decrypter | ❌ | ✅ | 旧方案(或正在部署的下一个方案) |
描述算法的元数据
为了让算法具备「版本」与「使用的密钥」的概念,需要添加 Ref 元数据并将其附加到密文上,形成一个 Envelope:
type Ref struct { Version uint32 // 算法版本,例如 1 = AES-256-GCM KeyID string // 自定义密钥 ID,例如 mk1}
type Envelope struct { Ref Ciphertext []byte}Version 和 KeyID 分开管理,用于在不同场景下进行轮换:
- 换算法:
v1/mk1→v2/mk1 - 换密钥:
v1/mk1→v1/mk2
KeyID 只是标明所用密钥的名称,真正的密钥会在初始化 aead.Cipher 时传入,可以自行决定存放在 KMS 或环境变量中。ratchet 内部使用 map[Ref]Decrypter 查表,因此同一个 Ref 不能重复注册。
ratchet:1:mk1:aJHaGWyInGkfczT1HY3s3tNtyKU_mXRbKlyIRT1b0ogNjhc│ │ │ └ base64url(密文)│ │ └ KeyID:使用的密钥 ID│ └ Version:使用的算法└ 标明这是 ratchet 信封格式的数据(没有前缀就视为 Unversioned Ref)操作 Envelope
存入数据库前转换为字符串,读取后再转回 Envelope:
stored := env.String() // 存: 「ratchet:1:mk1:...」env, err := ratchet.ParseEnvelope(stored) // 读:转回 Envelope最小实用示例
创建 aead.Cipher
key := loadKey() // 32 字节,自行管理v1, err := aesgcm.New(ratchet.Ref{Version: 1, KeyID: "mk1"}, key)// aesgcm 包是基于 AES-GCM 的 aead.Cipher 参考实现,展示了如何// 将算法接入 ratchet;可以复制并修改它,也可以为其他算法编写自己的// Cipher。package aesgcm
import ( "crypto/aes" "crypto/cipher" "encoding/binary" "fmt"
"github.com/riceball-tw/ratchet" "github.com/riceball-tw/ratchet/aead")
// New 返回一个 AES-GCM Cipher。key 必须为 16、24 或 32 字节;对于长期保存的// 数据,建议使用 32 字节(AES-256)。//// Nonce 为随机值(96 位),因此单个密钥加密的消息数量不应超过// 约 2^32 条;应在远未达到此上限时就轮换密钥 ID。//// Ref 会绑定到认证数据中,因此信封的版本// 或密钥 ID 一旦被篡改,就会导致解密失败。func New(ref ratchet.Ref, key []byte) (aead.Cipher, error) { if ref == ratchet.Unversioned { return nil, fmt.Errorf("aesgcm: 需要带版本的 Ref") } if err := ref.Validate(); err != nil { return nil, err } block, err := aes.NewCipher(key) if err != nil { return nil, fmt.Errorf("aesgcm: %s: %w", ref, err) } gcm, err := cipher.NewGCMWithRandomNonce(block) if err != nil { return nil, fmt.Errorf("aesgcm: %s: %w", ref, err) } return &aesGCM{ref: ref, gcm: gcm}, nil}
type aesGCM struct { ref ratchet.Ref gcm cipher.AEAD}
func (c *aesGCM) Ref() ratchet.Ref { return c.ref }
func (c *aesGCM) Encrypt(plaintext, aad []byte) ([]byte, error) { return c.gcm.Seal(nil, nil, plaintext, bindAAD(c.ref, aad)), nil}
func (c *aesGCM) Decrypt(ciphertext, aad []byte) ([]byte, error) { return c.gcm.Open(nil, nil, ciphertext, bindAAD(c.ref, aad))}
// bindAAD 将 ref 的无歧义编码作为前缀添加到调用方的 AAD 前。func bindAAD(ref ratchet.Ref, aad []byte) []byte { b := make([]byte, 0, 8+len(ref.KeyID)+len(aad)) b = binary.BigEndian.AppendUint32(b, ref.Version) b = binary.BigEndian.AppendUint32(b, uint32(len(ref.KeyID))) b = append(b, ref.KeyID...) return append(b, aad...)}ratchet 不关心密钥如何生成和存储,只识别 Ref。aesgcm.New 将 Ref 和密钥绑定在同一个 aead.Cipher 中,所以 KeyID 就是你为这把密钥起的名字,让读取时能找到当初加密用的那一把。
封装旧的解密逻辑
func legacyDecrypt(ciphertext, _ []byte) ([]byte, error) { return oldDecryptCBC(ciphertext) // 原封不动}
legacy := aead.DecrypterFunc(ratchet.Unversioned, legacyDecrypt)组装 aead.Ratchet 实例
r, err := aead.New(aead.Config{ Current: v1, // 唯一负责加密的方案 DecryptOnly: []aead.Decrypter{legacy}, // 只负责解密 OnNewerData: func(found, current ratchet.Ref) {}, // 可选:读到比 Current 更新的版本时调用})if err != nil { log.Fatal(err) // 配置有误就拒绝启动}使用
aad := []byte("users/42/password")
// 写入:始终使用 Currentenv, _ := r.Encrypt([]byte("hunter2"), aad)db.Save(env.String()) // ratchet:1:mk1:...
// 读取:兼容新旧格式,根据标签自动分派env, _ = ratchet.ParseEnvelope(db.Load())plaintext, _ := r.Decrypt(env, aad)
// 迁移:用旧方案解密,再用 Current 重新加密env, changed, _ := r.Rewrap(env, aad)场景:多服务引入新规则
各服务并非同时更新,因此分两次部署:
// 部署 A:所有服务器先具备读取 v2 的能力,仍然写入 v1aead.Config{Current: v1, DecryptOnly: []aead.Decrypter{legacy, v2}}
// 部署 B:确认 A 全部完成后,改为写入 v2// v1 降级为只读aead.Config{Current: v2, DecryptOnly: []aead.Decrypter{legacy, v1}}如果跳过 A 直接部署,尚未更新的服务读到 v2 数据时就会报错: ratchet: unknown scheme: v2/mk1。
场景:使用 Rewrap 更新旧数据
切换到 v2 之后,只有新写入的数据是 v2,数据库中的 v1 数据不会自动更新。如果不处理,v1 就永远无法淘汰。Rewrap 就是用来处理这件事的:用信封记录的旧方案解密,再用 Current 重新加密。
newEnv, changed, err := r.Rewrap(env, aad)以 Current 为 v2 为例:
| 输入 | 输出 | changed |
|---|---|---|
Unversioned 旧数据 | ratchet:2:mk1:... | true |
ratchet:1:mk1:... | ratchet:2:mk1:... | true |
ratchet:2:mk1:... | 原样返回 | false |
使用方式有两种,通常配合使用:
// 1. 读取时顺便升级:经常被读取的数据会逐步完成转换plaintext, _ := r.Decrypt(env, aad)if newEnv, changed, err := r.Rewrap(env, aad); err == nil && changed { db.Save(id, newEnv.String())}
// 2. 批量迁移:将很少被读取的数据一次性转换完for _, row := range db.FindNotPrefixed("ratchet:2:") { env, _ := ratchet.ParseEnvelope(row.Value) newEnv, changed, err := r.Rewrap(env, row.AAD) if err != nil { return err // 无法解密的数据不要跳过,要查清原因 } if changed { db.Save(row.ID, newEnv.String()) }}执行完后,确认数据库中没有 ratchet:1: 的数据,再将 v1 从 DecryptOnly 中移除,棘轮就能向前转一格。
场景:多密钥管理与轮换
ratchet 不关心密钥从哪里来,但实际使用中通常需要满足两点:不同用途使用不同密钥、主密钥可以轮换。一种常见做法是只管理少数几把主密钥,用 KeyID 作为主密钥的名称,再用 HKDF 派生出各用途的密钥:
// 名称 → 主密钥,主密钥本身存放在 KMS 或环境变量中var masterKeys = map[string][]byte{ "mk1": load("MASTER_KEY_MK1"),}
func newCipher(purpose string, ref ratchet.Ref) (aead.Cipher, error) { master, ok := masterKeys[ref.KeyID] // 用 KeyID 找到主密钥 if !ok { return nil, fmt.Errorf("未知的密钥 ID %q", ref.KeyID) } // info 例如「myapp/mail.password/v1/mk1」:不同用途、不同 Ref 会得到互不相关的密钥 key, err := hkdf.Key(sha256.New, master, nil, "myapp/"+purpose+"/"+ref.String(), 32) if err != nil { return nil, err } return aesgcm.New(ref, key)}假设某天 mk1 泄露了,轮换主密钥和升级算法采用同一套流程,只是这次更换的是 KeyID 而不是 Version:
var masterKeys = map[string][]byte{ "mk1": load("MASTER_KEY_MK1"), // 旧密钥,仅保留用于解密 "mk2": load("MASTER_KEY_MK2"), // 新密钥}
current, _ := newCipher("mail.password", ratchet.Ref{Version: 1, KeyID: "mk2"})old, _ := newCipher("mail.password", ratchet.Ref{Version: 1, KeyID: "mk1"})
r, _ := aead.New(aead.Config{ Current: current, // 新数据使用 mk2 DecryptOnly: []aead.Decrypter{old}, // 旧数据仍然可读})- 数据库中同时存在
ratchet:1:mk1:...和ratchet:1:mk2:...,各自根据KeyID找到当初加密所用的主密钥 - 用
Rewrap将mk1的数据转换为mk2 - 确认没有
ratchet:1:mk1:的数据后,将mk1彻底淘汰
只改 KeyID 不算轮换
因为 Ref 也被传入 HKDF 的 info,只改 KeyID 而不更换主密钥,也会派生出不同的密钥。但派生规则本来就不是秘密(info 写在代码中,Ref 也标在每个信封上),唯一的秘密是主密钥。同一把主密钥一旦泄露,攻击者按照规则就能算出 mk1、mk2 的所有派生密钥,等于没有更换。因此,最佳实践应该是:
- 每个
KeyID对应一把独立生成的主密钥:由 KMS 或crypto/rand生成新的 32 字节密钥,而不是将旧密钥换个名字重新注册。 - 启动时检查主密钥是否重复,避免配置时不小心给两个名称填入同一把密钥。
总结
文档中的最佳实践会因为偷懒、求快而被忽略,写进程序的强制流程才会真正得到遵守
ratchet 的价值在于提供一个易于理解和使用的抽象,并确保整个系统只会朝着最佳实践演进,引入只是开始,持续收敛到最佳实践才是终点。