crypto —— 字段级加密(AES-256-GCM)+ 盲索引
敏感字段(手机号、身份证、银行卡)不能明文落库,但又不能丢: 需要能查、能比对、能改。 crypto 给两套原语 + 一套密钥分级机制。
功能
crypto 提供三组能力:
Cipher—— AES-256-GCM 字段级加密Encrypt/Decrypt/EncryptString/DecryptStringDecryptStringAudited/EncryptStringAudited:解密自动落 PII 访问审计- 密钥使用审计
BlindIndex—— HMAC-SHA256 盲索引Compute/ComputeNorm:不可逆派生值,可做"完全相等"查询
- 密钥分级 + 轮转 registry
- 三个 tier:
pii(手机/身份证/银行卡)/secret(密码哈希、API 密钥)/normal(一般业务字段)。不同 tier 用不同 key,一把泄漏不波及全部 - 每个 tier 可挂多把 key(
KeyVersion递增),只有Active=true的那把用于新加密, 老的保留用于解旧密文 - 密文是信封格式:
Base64(0x02 || key_version || nonce || ciphertext)—— 密文自己带着"哪把 key 加密的",不需要额外 DB 列
- 三个 tier:
不解决什么:不接 KMS(那是 kms);不做"谁看了 PII"的审计落库 (那是 piiaudit);不重写业务表里的历史密文 —— 每张表的密文列在哪、怎么批量 re-encrypt 只有业务自己知道。
配置
yaml 侧(crypto: 块)
crypto:
field_key: ${FIELD_AES_KEY} # AES-256-GCM 密钥,必须 32 字节
blind_key: ${FIELD_BLIND_KEY} # HMAC-SHA256 盲索引密钥,>=16 字节
⚠️ 两条 key 的解析规则不一样:
field_key:base64(标准 / 无 padding)或 32 字节原文都认;blind_key:原样使用,不做 base64 解码。
两种都不满足 → 启动时打 Error,字段加密不启用(PII 字段明文存取)—— "配了"不等于"加密了"。
yaml 侧(crypto_keys: 块)
crypto_keys:
enabled: true
warn_no_active: true
⚠️ 这一整块是死配置:crypto_keys / enabled / warn_no_active 在全仓
没有任何代码读取(没有对应的 mapstructure 字段,也没有读取点)。
分级密钥实际来自环境变量,由 KMS 的 local provider 装载(见 kms)。
写在 yaml 里不会生效。
代码侧(构造选项)
crypto.InitKeys(cfg crypto.KeysConfig) error // 分级密钥(KMS 路径)
crypto.InitFieldCipher(key []byte) error // 单把字段密钥
crypto.InitFieldCipherWithMeta(key []byte, meta crypto.KeyMeta) error
crypto.InitBlindIndex(key []byte) error
crypto.InitBlindIndexWithMeta(key []byte, meta crypto.KeyMeta) error
使用方法
分级密钥 + 加解密
err := crypto.InitKeys(crypto.KeysConfig{
PII: []crypto.KeyEntry{
{KeyID: "env:PII_KEY", KeyVersion: 1, Key: piiKey, Active: true},
},
Secret: []crypto.KeyEntry{
{KeyID: "env:SECRET_KEY", KeyVersion: 1, Key: secretKey, Active: true},
},
Normal: []crypto.KeyEntry{
{KeyID: "env:NORMAL_KEY", KeyVersion: 1, Key: normalKey, Active: true},
},
})
if err != nil { return err } // 配错 → 返 error,不 panic
ct, err := crypto.EncryptStringFor(ctx, crypto.TierPII, "110101199001011234")
pt, err := crypto.DecryptStringFor(ctx, crypto.TierPII, ct)
盲索引
bi, err := crypto.NewBlindIndex([]byte("blind-index-key-32-bytes-long!!"))
if err != nil { return err } // key < 16 字节直接拒绝
h1 := bi.Compute("13800001234")
h2 := bi.ComputeNorm("138 0000 1234") // 先归一化(去空格 / 转小写)再算
字段级 Cipher(带审计)
// main 启动期:InitFieldCipherWithMeta(key, crypto.KeyMeta{KeyID: "crypto.field", ...})
phone, err := crypto.Field().DecryptStringAudited(ctx, user.PhoneCipher, "user", user.ID, "phone")
轮转就绪状态
state, err := crypto.RotationState(crypto.TierPII)
// state.Configured / ActiveKeyID / ActiveVersion / RetainedVersions
// state.ActiveIsHighest / state.RoundTripOK / state.Problem
注意事项
- ⚠️
InitKeys是"要么全装上,要么一点不改"。三个 tier + legacy 全部先在局部 建好,成功才一次性换上去 —— 轮转中途失败不会留下"一半新一半旧"的 registry (那正是最需要原子性的时刻)。 - ⚠️ 每个 tier 必须恰好一把
Active的 key。0 把或 2 把都返 error (must have exactly 1 active key, got N)。轮转期的正确形态是 1 active + N-1 老 key 仅用于解密。key 版本重复也返 error。 - ⚠️
InitBlindIndex现在返 error(ErrBlindIndexKeyTooShort)。以前"key 至少 16 字节"只写在注释里,InitBlindIndex(nil)会造出一个空 key 的 HMAC —— 空 key 的 HMAC-SHA256 等价于"任何人都能算出来的公开哈希",拿到库的人直接对 候选明文算一遍就能把手机号反查出来,盲索引的意义当场归零。 - ⚠️
NewCipher要求 key 恰好 32 字节(不是"至少")。 - ⚠️ v1 / v2 的首字节歧义:v1 密文的首字节是随机 nonce 的第一个字节,而 v2
信封的首字节必须恰好是
0x02⇒ 每 256 份 v1 密文里就有 1 份被当成 v2 解析, 后面跟着的 nonce 字节被当成 key version → 查不到 key → 那份数据永久解不开 (不是报错,是丢数据)。批量加密的 PII 表里 1 万条大约中招 39 条。 解法是"不靠猜,靠试":v2 解不开就按 v1 再解一次(v2 带 GCM 认证,误判概率 ~2^-128)。 - ⚠️
crypto.Field()/crypto.Blind()未初始化时 panic。配错 key 时 main 打 Error 且不初始化 —— 真用到就 panic,而不是拿着错误的 key 把 PII 加密成解不开的 东西。要安全探测用TryField()/TryBlind()(返回 nil 而不 panic)。 - ⚠️ 两条加密路径的审计覆盖不一样。
crypto.Field()那条(DecryptStringAudited) 落 cryptaudit + piiaudit;tiered 那条(EncryptFor/DecryptFor)只落 cryptaudit。业务要"谁看了手机号"的审计,必须走Field()那条。 - ⚠️
RotationState查不出"历史数据还在用退役 key"。它只看 registry,不扫任何 业务表。一个天天报"一切正常"却看不见真问题的检查比没有检查更坏 —— 它会让人以为 轮转没问题。返回的error只表示"这个 tier 压根没初始化"(没配 ≠ 配坏了)。 - ⚠️ 轮转探针不写密钥使用审计。它会真的加解密一次(固定探针明文),但那是
体检不是业务读数据 —— 混进
sys_crypto_audit_log会让人误以为有人在读数据。 - ⚠️ 信封里的 key version 是 1..255 的单字节。
EnvelopeFormatVersion恒为0x02;老版本 v1 格式(裸nonce || ciphertext)本包可读不可写,解密时靠Legacykey 兜底。没注册 legacy key 时,任何 v1 格式密文都解不开 (HasLegacyKey()用来区分"没配"与"老部署丢了")。
相关
- 源码:
internal/pkg/crypto/ - 可运行示例:
examples/crypto/main.go——go run ./examples/crypto - KMS 装配(启动期把 keys 灌进本包)→ kms
- PII 访问审计 → ../audit/piiaudit.md
- 密钥使用审计 → ../audit/cryptaudit.md