KMS密钥轮换与Envelope Encryption最佳实践

一、数据与主密钥import crypto from 'crypto' function genDataKey(): Buffer { return crypto.randomBytes(32) } function genIv(): Buffer { return crypto.randomBytes(12) } type Envelope = { cmkId: string; iv: string; aad: string; tag: string; ciphertext: string; wrappedKey: string } 二、加密与包裹function encryptEnvelope(plain: Buffer, cmkId: string, cmk: Buffer, aad: Buffer): Envelope { const dk = genDataKey() const iv = genIv() const cipher = crypto.createCipheriv('aes-256-gcm', dk, iv) cipher.setAAD(aad) const ct = Buffer.concat([cipher.update(plain), cipher.final()]) const tag = cipher.getAuthTag() const wrapped = crypto.createCipheriv('aes-256-gcm', cmk, iv).update(dk) return { cmkId, iv: iv.toString('base64'), aad: aad.toString('base64'), tag: tag.toString('base64'), ciphertext: ct.toString('base64'), wrappedKey: wrapped.toString('base64') } } 三、解密与验证function decryptEnvelope(env: Envelope, cmk: Buffer): Buffer | null { const iv = Buffer.from(env.iv, 'base64') const aad = Buffer.from(env.aad, 'base64') const tag = Buffer.from(env.tag, 'base64') const wrapped = Buffer.from(env.wrappedKey, 'base64') const unwrap = crypto.createDecipheriv('aes-256-gcm', cmk, iv) const dk = Buffer.concat([unwrap.update(wrapped), unwrap.final()]) const dec = crypto.createDecipheriv('aes-256-gcm', dk, iv) dec.setAAD(aad) dec.setAuthTag(tag) const ct = Buffer.from(env.ciphertext, 'base64') try { return Buffer.concat([dec.update(ct), dec.final()]) } catch { return null } } 四、轮换示例type Meta = { cmkId: string } function rotateEnvelope(env: Envelope, meta: Meta, oldCmk: Buffer, newCmkId: string, newCmk: Buffer): Envelope | null { const plain = decryptEnvelope(env, oldCmk) if (!plain) return null const aad = Buffer.from(env.aad, 'base64') return encryptEnvelope(plain, newCmkId, newCmk, aad) } 五、验收清单数据密钥长度32字节（AES-256）与IV长度12字节（GCM）；AAD参与认证；标签校验通过。包裹与解包均基于CMK；轮换后更新`cmkId`与`wrappedKey`，解密成功校验。元数据包含`cmkId/iv/aad/tag`等字段；异常返回`null`并记录审计。