AES-GCM加密方法及HTML crypto.subtle.encrypt使用教程

本文深入解析了在浏览器环境中使用Web Crypto API的`crypto.subtle.encrypt`进行AES-GCM加密的完整实践要点，强调其并非简单传入IV即可运行，而是必须严格满足安全上下文（HTTPS/localhost）、精确构造含`name`、`iv`（12字节不可复用Uint8Array）和显式`tagLength`的参数对象，并通过`importKey`导入合法CryptoKey（绝非字符串密钥）；同时澄清了密文与认证标签的拼接结构、安全提取方式、常见静默失败原因，以及`OperationError`背后真实的GCM验证失败场景——从密钥用途声明、IV一致性到Blob上传的MIME陷阱，为开发者避开高危误区、构建真正端到端安全的前端加密方案提供了清晰、可落地的技术指南。

crypto.subtle.encrypt 调用 AES-GCM 是可行的，但必须满足安全上下文（HTTPS 或 localhost）、正确参数结构和密钥生命周期管理，否则会静默失败或产生不安全输出。

必须传入的参数对象长什么样

AES-GCM 模式不是只填 iv 就能跑通的。浏览器要求参数对象至少包含三个字段： - name: "AES-GCM"（字符串字面量，大小写敏感） - iv：必须是 Uint8Array，长度建议 12 字节（96 位），也可用 8–120 字节，但同一密钥下绝对不可复用 - tagLength：默认 128，常用 128 或 96；若设为 96，解密时也必须显式传入相同值，否则抛 DataError

additionalData 是可选的，但业务中携带元数据（如请求 ID、时间戳）时应放这里——它参与认证但不加密，不能丢。

密钥不能是字符串，也不能硬编码

直接传 "my-secret-key" 给 encrypt() 会报错：TypeError: The provided value is not of type '(ArrayBuffer or ArrayBufferView)'。 正确做法是： - 用 crypto.subtle.importKey("raw", keyBytes, {name: "AES-GCM"}, false, ["encrypt"]) 导入密钥 - keyBytes 必须是 ArrayBuffer 或视图（如 Uint8Array），可通过口令派生（PBKDF2 + salt）或服务端下发的二进制密钥生成 - 禁止把密钥存在 localStorage 或拼进 URL；短期会话密钥建议绑定 JWT 的 jti 或 WebSocket 连接 ID

加密后怎么拿到可用的密文+标签

crypto.subtle.encrypt() 返回的是单个 ArrayBuffer，结构为「密文｜认证标签」拼接体（标签在末尾，默认 16 字节）。 常见错误是手动截取前 N 字节当密文、后 16 字节当 tag——这不可靠，因为： - tagLength 可能设为 96（即 12 字节） - 浏览器不保证标签严格附在末尾（虽然目前所有实现都如此，但规范未强制） 正确方式是：解密时原样传回整个 ArrayBuffer，由 Web Crypto 自动拆分并校验；若需单独传输，应在加密后显式提取：

const result = await crypto.subtle.encrypt({ name: "AES-GCM", iv, tagLength: 128 }, key, data);  
const buffer = result;  
const tag = buffer.slice(buffer.byteLength - 16); // 仅当 tagLength === 128 时成立  
const ciphertext = buffer.slice(0, buffer.byteLength - 16);

但更稳妥的做法是用 ArrayBuffer 整体 Base64 编码后与 iv 一起传给后端，由后端按标准 GCM 格式解析。

为什么 decrypt() 总是抛 OperationError

这个错误通常不是代码写错，而是底层验证失败的统一出口，真实原因包括： - iv 和加密时不一致（哪怕只差 1 字节） - 密钥对象用途不匹配（生成时没声明 ["decrypt"]，或 importKey() 时设了 false 用于 extractable 却又想复用） - 传给 decrypt() 的 ArrayBuffer 被意外修改（如用 TextDecoder 再转回 ArrayBuffer） - 后端篡改了密文或标签（GCM 会拒绝，这是正常行为，不是 bug）

最易忽略的一点：前端加密后若用 FormData.append("file", new Blob([encrypted])) 上传，Blob 的 MIME 类型可能被浏览器自动设为 application/octet-stream，但某些后端框架（如 Express multer）会因类型不符拒绝解析——此时应显式指定 new Blob([encrypted], {type: "application/octet-stream"})。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《AES-GCM加密方法及HTML crypto.subtle.encrypt使用教程》文章吧，也可关注golang学习网公众号了解相关技术文章。