Web Crypto API 如何导入与导出 AES-GCM 密钥：ArrayBuffer 编码、IV 管理与解密验收

前端把 AES-GCM 密钥放在 localStorage 里再直接传给 crypto.subtle.importKey()，最容易遇到的不是算法报错，而是数据类型和参数对不上：Base64 还是字节数组、密钥是否允许导出、IV 有没有每次重新生成。下面用一组可以在浏览器控制台运行的最小代码，把这些边界一次对齐。

先把浏览器里的数据边界分清

Web Crypto API 的接口围绕二进制工作。页面接口、JSON 和 localStorage 却更习惯保存字符串，所以实际接线通常是“字符串 → Base64 → Uint8Array → ArrayBuffer → CryptoKey”。反方向导出时再把字节转成 Base64。

用 Base64 往返导入和导出 AES-GCM 密钥

先准备两个转换函数。这里使用浏览器原生 atob 和 btoa，它们处理的是字节字符串，不要把包含中文的普通 Unicode 文本直接塞进去。

function base64ToBytes(base64) {
  const binary = atob(base64);
  return Uint8Array.from(binary, ch => ch.charCodeAt(0));
}

function bytesToBase64(bytes) {
  let binary = "";
  for (const byte of bytes) binary += String.fromCharCode(byte);
  return btoa(binary);
}

async function importAesKey(base64Key) {
  const raw = base64ToBytes(base64Key);
  if (![16, 24, 32].includes(raw.byteLength)) {
    throw new Error("AES key must be 128, 192, or 256 bits");
  }
  return crypto.subtle.importKey(
    "raw",
    raw,
    { name: "AES-GCM" },
    true,
    ["encrypt", "decrypt"]
  );
}

async function exportAesKey(key) {
  const raw = new Uint8Array(await crypto.subtle.exportKey("raw", key));
  return bytesToBase64(raw);
}

导入时的第四个参数是 extractable。如果传入 false，加解密仍然可以用，但之后调用 exportKey 会失败。导出能力只应在确有需要的边界打开，不能把它当作默认配置。

用唯一 IV 完成一轮加密和解密验收

AES-GCM 推荐使用 12 字节 IV。IV 可以公开保存，但同一把密钥下不能重复使用；因此每轮加密都重新调用 crypto.getRandomValues()。密文返回值已经包含认证标签，保存时可直接和 IV 一起编码。

async function encryptText(key, text) {
  const iv = crypto.getRandomValues(new Uint8Array(12));
  const data = new TextEncoder().encode(text);
  const ciphertext = await crypto.subtle.encrypt(
    { name: "AES-GCM", iv },
    key,
    data
  );
  return {
    iv: bytesToBase64(iv),
    ciphertext: bytesToBase64(new Uint8Array(ciphertext))
  };
}

async function decryptText(key, packet) {
  const iv = base64ToBytes(packet.iv);
  const ciphertext = base64ToBytes(packet.ciphertext);
  const plaintext = await crypto.subtle.decrypt(
    { name: "AES-GCM", iv },
    key,
    ciphertext
  );
  return new TextDecoder().decode(plaintext);
}

const keyText = "0123456789abcdef0123456789abcdef";
const key = await importAesKey(bytesToBase64(new TextEncoder().encode(keyText)));
const packet = await encryptText(key, "订单草稿 v3");
const restored = await decryptText(key, packet);
console.assert(restored === "订单草稿 v3", "AES-GCM round trip failed");
console.log({ packet, restored });

控制台里看到 restored 与原文相同，只能说明这一轮参数匹配。把 packet.ciphertext 改动一个字符后再次解密，应当抛出异常；这一步能确认 GCM 的完整性校验确实参与了流程。

常见错误集中在这四个检查点

• 把 Base64 当成 raw key：importKey 的第二个参数要传解码后的字节，而不是 Base64 字符串。
• 密钥长度不对：AES 原始密钥只能是 16、24 或 32 字节，字符串字符数不一定等于字节数。
• IV 固定写死：示例里的 IV 只能用于测试，正式加密必须每次随机生成并随包保存。
• 误判导出失败：先检查导入时的 extractable，不要为了导出而在所有场景都打开它。

相关问题

IV 需要像密钥一样加密吗？

通常不需要保密，但必须保证唯一，并且和对应密文绑定保存。真正需要严格保护的是 AES 密钥。

为什么 JSON.stringify(CryptoKey) 得不到密钥内容？

CryptoKey 是受浏览器管理的密钥对象，不是普通 JSON 数据。需要可导出时，使用 exportKey("raw", key)，并在导入阶段明确设置可提取性。

修改密文后为什么解密会失败？

AES-GCM 会校验密文完整性。密文、IV 或附加认证数据任一部分不匹配，decrypt() 都应拒绝返回明文。

把验收结果留在代码旁边

这套最小实现适合验证浏览器参数是否接通，不等于完整的密钥管理方案。上线前至少再补上密钥生命周期、来源鉴权、密钥轮换和失败日志脱敏；尤其不要把可导出的长期密钥和用户输入一起写入普通前端存储。