Achieve Crypto Agility with Ratchet

實作棘輪機制達成強制密碼學敏捷性

前言

上一篇文章:密碼學敏捷性:把「密碼有天會被攻破」作為系統設計前提提到了一種類似棘輪只能單向前進防止逆轉的機制,可以逐步推出新算法並淡出舊算法,基於這個概念整理成一個簡單的 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 升級成 GCMGCM v1/keyA舊的 CBC
輪替金鑰GCM v1/keyBGCM v1/keyA

鑰匙圈靠兩件事運作,並堅持棘輪一樣的政策:

  1. 規定格式:每筆密文都標上用了哪把鑰匙(演算法版本 + 金鑰 ID)。
  2. 初始化時定好政策:哪一把負責加密,哪些只負責解密。

棘輪政策?

棘輪:只能往單一方向轉的齒輪

在加解密上概念就變成產生新加密資料的方案只能用新算法,舊方案可以讀,但永遠不再用來加密。

導入 ratchet

遷移舊資料

v2 上線

遷移 v1 資料

導入前
━━━━
加密:舊方案
解密:舊方案

過渡期
━━━━
加密:v1
解密:v1、沒有版本資訊

穩定
━━━━
加密:v1
解密:v1

過渡期
━━━━
加密:v2
解密:v2、v1

穩定
━━━━
加密:v2
解密:v2

  • 加密永遠只有一個方案,而且只會往前換:舊方案 → 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("Hello"), aad)
角色型別加密解密意義
Currentaead.Cipher✅✅所有新資料唯一使用的方案
DecryptOnlyaead.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 Envelope Demo
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

ratchet:2:...

ratchet:1:...

沒有 ratchet: 前綴

其他版本

寫入

v2
加密 + 解密

讀取

信封標籤

v1
只解密

Unversioned
只解密

ErrUnknownRef

最小實際案例

建立 aead.Cipher

key := loadKey() // 32 bytes 自行管理
v1, err := aesgcm.New(ratchet.Ref{Version: 1, KeyID: "mk1"}, key)
aesgcm.go
// Package aesgcm is a reference aead.Cipher built on AES-GCM. It shows how
// to plug an algorithm into the ratchet; copy and adapt it, or write your own
// Cipher for any other algorithm.
package aesgcm
import (
"crypto/aes"
"crypto/cipher"
"encoding/binary"
"fmt"
"github.com/riceball-tw/ratchet"
"github.com/riceball-tw/ratchet/aead"
)
// New returns an AES-GCM Cipher. key must be 16, 24 or 32 bytes; prefer 32
// (AES-256) for long-lived data.
//
// Nonces are random (96-bit), so a single key should not encrypt more than
// about 2^32 messages; rotate the key ID well before that.
//
// The Ref is bound into the authenticated data, so an envelope whose version
// or key ID was tampered with fails to decrypt.
func New(ref ratchet.Ref, key []byte) (aead.Cipher, error) {
if ref == ratchet.Unversioned {
return nil, fmt.Errorf("aesgcm: needs a versioned 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 prefixes the caller's AAD with an unambiguous encoding of ref.
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")
// 寫入:永遠是 Current
env, _ := 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,仍然寫 v1
aead.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("unknown key 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}, // 舊資料仍能讀
})
  1. 資料庫裡同時存在 ratchet:1:mk1:... 和 ratchet:1:mk2:...,各自依 KeyID 找回當初加密用的那把主金鑰
  2. 用 Rewrap 把 mk1 的資料轉成 mk2
  3. 確認沒有 ratchet:1:mk1: 的資料後,把 mk1 徹底淘汰

只改 KeyID 不算輪替

因為 Ref 也被帶進 HKDF 的 info,只改 KeyID 而不換主金鑰,也會衍生出不同的金鑰。但衍生規則本來就不是祕密(info 寫在程式碼裡,Ref 也印在每個信封上),唯一的祕密是主金鑰。同一把主金鑰外洩,攻擊者照著規則就能算出 mk1、mk2 所有衍生金鑰,等於沒換。因此最佳實踐應該:

  1. 每個 KeyID 對應一把獨立產生的主金鑰:由 KMS 或 crypto/rand 產生新的 32 bytes,而不是把舊的 key 換個名字重新註冊。
  2. 啟動時檢查主金鑰沒有重複,避免設定時不小心把同一把填給兩個名字。

總結

文件上的最佳實踐會因為懶惰求快被忽略,寫在程式的硬性流程才會真的被遵守

ratchet 的價值在於創造一個使用上易懂的抽象並確保整個系統只會朝向最佳實踐進行,導入只是開始,不斷的收斂為最佳實踐才是終點。

延伸閱讀