JS使用Web Crypto API实现AES加解密完整示例

作者:缓存笔记

时间:2026-11-19

浏览:151

详细讲解在现代浏览器中使用原生Web Crypto API(SubtleCrypto)实现AES-GCM 256位加解密的完整过程,包含密钥生成、IV处理、文本编码转换、异常处理与完整封装代码。

文章目录

现代浏览器内置的原生 Web Crypto API(挂载于 window.crypto.subtle)为前端开发者提供了硬件加速、抗内存窥探的高性能密码学接口。本文以工程落地标准最高的 AES-GCM(256 位) 为例,提供从密钥派生、IV(初始化向量)生成、数据格式转换到密文封包与解密的完整实现,代码零第三方依赖,可直接在主流浏览器与安全上下文中运行。

JS使用Web Crypto API实现AES加解密完整示例
图 1:Web Crypto API 实现 AES-GCM 加密核心架构与数据流向

一、为什么优先选择 Web Crypto API 与 AES-GCM?

在过去的前端开发中,若要在客户端执行 AES 加密,开发者往往会引入 CryptoJS 等纯 JavaScript 编写的第三方库。但在生产环境中,这类库存在两个显著缺陷:一是纯 JS 计算在大数据量时吞吐效率较低;二是私钥暴露在普通 JS 堆内存中,容易被同域 XSS 脚本提取。

W3C 制定的 Web Crypto API 弥补了这些短板。它直接由浏览器引擎和底层操作系统的加密服务提供支持,具备以下核心优势:

  • 硬件级加速:底层利用 CPU 的 AES-NI 指令集,速度比纯 JS 库高出数倍甚至数十倍。
  • 不可提取密钥保护:创建 CryptoKey 时可配置 extractable: false,这意味着密钥只能在浏览器内部用于加解密,任何 JS 脚本均无法导出原始密钥字节。
  • 认证加密(AEAD):采用 AES-GCM 模式,将数据加密(保密性)与消息认证码 GMAC(完整性)合二为一,不仅能防止数据被偷窥,还能在解密时即刻捕获任何微小的恶意篡改。

二、AES-GCM 加密与解密全流程梳理

AES-GCM 是目前密码学界最推荐的对称加密工作模式。在实施加解密时,必须严格处理好三个关键要素:密钥(Key)、初始化向量(IV)以及认证标签(Tag)。

JS使用Web Crypto API实现AES加解密完整示例
图 2:AES-GCM 加密与解密的端到端执行步骤与逻辑映射

三、核心数据类型与内存流转机制

初学者在使用 Web Crypto API 时最容易受挫的地方,通常并非算法本身,而是各种类型之间的转换。crypto.subtle.encrypt 与 decrypt 不直接接收字符串,而是接收并返回 ArrayBuffer。理解数据类型的流转路径是写出无 Bug 密码学代码的前提。

JS使用Web Crypto API实现AES加解密完整示例
图 3:Web Crypto API 全生命周期内的数据类型与转换映射

四、关键实现细节分析

1. 初始化向量(IV)的长度与安全性

在 AES-GCM 算法中,推荐的 IV 长度是 12 字节(96 位)。为什么不是常见的 16 字节?因为 GCM 内部采用 96 位的 IV 直接与 32 位的初始计数器拼接形成 128 位计数器块;若传入 16 字节或其它长度,算法底层会先执行额外的 GHASH 哈希计算将其压缩为 96 位,既损耗性能,又略微降低碰撞安全性。

重要安全禁忌:绝对不要重用 IV
在同一个密钥下,若两次加密使用了相同的 IV,攻击者可以通过异或密文直接恢复出明文间的差分关系,甚至伪造合法的数据包认证标签。因此,必须使用 crypto.getRandomValues(new Uint8Array(12)) 为每一次加密生成全新的随机 IV。

2. 为什么将 IV 与密文合并打包?

IV 并非密码,它无需保密,解密端必须知晓加密时使用的 IV 才能正确解密。最简洁优雅的工程实践是将 12 字节的 IV 直接置于密文字节数组的最前部(Prepend),组合为一个单一的二进制包,然后再编码为 Base64。解密端接收后,读取前 12 字节作为 IV,剩余字节作为密文传给解密函数。

JS使用Web Crypto API实现AES加解密完整示例
图 4:AES-GCM 自带认证标签(Tag)在面对数据篡改时的防御机制

五、完整代码实现与封装示例

以下提供一份结构整洁、即拷即用的 JavaScript 代码。它封装了 AESCrypto 类,同时支持直接生成随机密钥以及通过口令加盐派生密钥(PBKDF2)两种常见业务模式。

/**
 * 基于原生 Web Crypto API 的 AES-GCM 256 位加解密工具类
 * 无外部依赖,适用于现代浏览器 (Secure Context: HTTPS 或 localhost)
 */
class AESCrypto {
  // 推荐 GCM 参数:12字节 IV 与 128位 Tag
  static IV_LENGTH = 12;
  static TAG_LENGTH = 128;

  /**
   * 生成全新的随机 256 位 AES-GCM 密钥
   * @param {boolean} extractable 是否允许导出原始密钥(建议为 false 保证安全性)
   * @returns {Promise<CryptoKey>}
   */
  static async generateKey(extractable = false) {
    return await window.crypto.subtle.generateKey(
      {
        name: 'AES-GCM',
        length: 256,
      },
      extractable,
      ['encrypt', 'decrypt']
    );
  }

  /**
   * 通过用户密码/口令派生 CryptoKey(使用 PBKDF2 算法防范暴力破解)
   * @param {string} password 用户输入的密码口令
   * @param {Uint8Array} salt 盐值(至少16字节随机值)
   * @param {number} iterations 迭代次数(推荐至少 100,000 次)
   * @returns {Promise<CryptoKey>}
   */
  static async deriveKeyFromPassword(password, salt, iterations = 100000) {
    const encoder = new TextEncoder();
    const keyMaterial = await window.crypto.subtle.importKey(
      'raw',
      encoder.encode(password),
      { name: 'PBKDF2' },
      false,
      ['deriveKey']
    );

    return await window.crypto.subtle.deriveKey(
      {
        name: 'PBKDF2',
        salt: salt,
        iterations: iterations,
        hash: 'SHA-256'
      },
      keyMaterial,
      { name: 'AES-GCM', length: 256 },
      false,
      ['encrypt', 'decrypt']
    );
  }

  /**
   * 加密字符串
   * @param {string} plainText 待加密的明文字符串
   * @param {CryptoKey} key 加密密钥
   * @returns {Promise<string>} Base64 编码的封包数据 (包含 12B IV + 密文 + 16B Tag)
   */
  static async encrypt(plainText, key) {
    const encoder = new TextEncoder();
    const encodedData = encoder.encode(plainText);

    // 1. 每次加密生成独立的 12 字节 IV
    const iv = window.crypto.getRandomValues(new Uint8Array(this.IV_LENGTH));

    // 2. 调用 subtle.encrypt 执行加密
    const encryptedBuffer = await window.crypto.subtle.encrypt(
      {
        name: 'AES-GCM',
        iv: iv,
        tagLength: this.TAG_LENGTH
      },
      key,
      encodedData
    );

    // 3. 合并 IV 与加密结果为单一连续缓冲块
    const cipherBytes = new Uint8Array(encryptedBuffer);
    const combinedBuffer = new Uint8Array(iv.length + cipherBytes.length);
    combinedBuffer.set(iv, 0);
    combinedBuffer.set(cipherBytes, iv.length);

    // 4. 将合并后的字节数组编码为 Base64 字符串返回
    return this.bytesToBase64(combinedBuffer);
  }

  /**
   * 解密字符串
   * @param {string} cipherPackage Base64 格式的打包密文 (由 encrypt 输出)
   * @param {CryptoKey} key 解密密钥
   * @returns {Promise<string>} 解密后的明文字符串
   */
  static async decrypt(cipherPackage, key) {
    // 1. 将 Base64 解码为二进制字节
    const combinedBuffer = this.base64ToBytes(cipherPackage);

    // 检查长度合法性(至少包含 IV 12B + Tag 16B)
    if (combinedBuffer.length < this.IV_LENGTH + 16) {
      throw new Error('密文数据包长度异常,无法解析');
    }

    // 2. 切片拆包:前 12 字节为 IV,剩余字节为实际密文与认证标签
    const iv = combinedBuffer.slice(0, this.IV_LENGTH);
    const cipherBytes = combinedBuffer.slice(this.IV_LENGTH);

    // 3. 调用 subtle.decrypt 执行解密与完整性验证
    const decryptedBuffer = await window.crypto.subtle.decrypt(
      {
        name: 'AES-GCM',
        iv: iv,
        tagLength: this.TAG_LENGTH
      },
      key,
      cipherBytes
    );

    // 4. 将解密出的 ArrayBuffer 转码还原为 UTF-8 文本
    const decoder = new TextDecoder();
    return decoder.decode(decryptedBuffer);
  }

  // 辅助函数:Uint8Array 转 Base64
  static bytesToBase64(bytes) {
    let binary = '';
    const len = bytes.byteLength;
    for (let i = 0; i < len; i++) {
      binary += String.fromCharCode(bytes[i]);
    }
    return window.btoa(binary);
  }

  // 辅助函数:Base64 转 Uint8Array
  static base64ToBytes(base64) {
    const binary = window.atob(base64);
    const bytes = new Uint8Array(binary.length);
    for (let i = 0; i < binary.length; i++) {
      bytes[i] = binary.charCodeAt(i);
    }
    return bytes;
  }
}

六、执行测试与结果验证

可以在浏览器的开发者工具(F12 控制台)中直接粘贴并运行以下验证脚本:

// 运行示例
(async () => {
  try {
    // 1. 生成 256 位密钥
    const key = await AESCrypto.generateKey();
    console.log('✅ 密钥生成成功:', key);

    // 2. 测试加密
    const message = 'Hello, 这是通过原生 Web Crypto API 加密的敏感消息!';
    const encryptedPackage = await AESCrypto.encrypt(message, key);
    console.log('🔒 加密输出密文包 (Base64):', encryptedPackage);

    // 3. 测试解密
    const decryptedText = await AESCrypto.decrypt(encryptedPackage, key);
    console.log('🔓 解密成功还原文本:', decryptedText);
    console.log('🎯 验证结果一致性:', message === decryptedText ? '通过' : '失败');

    // 4. 测试篡改防御(修改密文最后一位)
    const tampered = encryptedPackage.slice(0, -2) + 'AA';
    await AESCrypto.decrypt(tampered, key);
  } catch (err) {
    console.warn('🛡️ 成功捕获异常(防篡改生效):', err.name, err.message);
  }
})();

预期控制台输出示例

✅ 密钥生成成功: CryptoKey {type: 'secret', extractable: false, algorithm: {name: 'AES-GCM', length: 256}, usages: Array(2)}
🔒 加密输出密文包 (Base64): s4b321F8k+YnC9qXy7L0xQkP4N...
🔓 解密成功还原文本: Hello, 这是通过原生 Web Crypto API 加密的敏感消息!
🎯 验证结果一致性: 通过
🛡️ 成功捕获异常(防篡改生效): OperationError The operation failed for an operation-specific reason

七、生产环境注意事项与快速核对清单

在将 Web Crypto API 投入实际项目前,请根据以下表格逐一核对安全与工程细节:

JS使用Web Crypto API实现AES加解密完整示例
图 5:Web Crypto API 工程落地的关键安全检查准则
检查维度 推荐做法 潜在风险 / 错误做法
运行环境 必须在 HTTPS 或 本地开发环境中执行 普通 HTTP 站点中 window.crypto.subtle 为 undefined
工作模式 优先选择 AES-GCM 使用 CBC 模式但未附加 HMAC,导致密文面临篡改风险
IV 管理 每次加密调用 getRandomValues 生成 12 字节随机数并随包附带 硬编码固定 IV,或使用不可靠的 Math.random()
密文存储与传递 将 IV 与密文拼接后转为 Base64 或 Hex 丢失 IV 导致接收端无法正确解密
密钥导出性 extractable: false 滥用 extractable: true 并在内存或日志中打印 Raw 密钥

通过原生 Web Crypto API,现代前端可以在完全不引入冗余外部依赖的前提下,以高安全性、硬件加速的性能标准完成 AES-GCM 数据的加密与解密。遵循规范中的 IV 独立性与异常捕获策略,能够有效保障传输与存储过程中的数据机密性与完整性。

实用工具推荐

电子包浆

绿化、压缩、噪点和虚拟水印,自由调节做旧程度。

使用 ›
图片压缩

选择画质和输出格式,预览压缩前后的大小。

使用 ›
相关文章