如何使用JavaScript SubtleCrypto与AES-GCM实现大文件流式解密？

当然可以！AES-GCM底层基于CTR流模式，完全支持边下载边解密的流式处理，这样就能避免将完整的密文和明文同时存在内存中，完美解决大文件的内存占用问题。不过有个关键细节要注意：AES-GCM是认证加密算法，密文末尾会附带一个认证标签（通常16字节，对应128比特），解密时必须用这个标签验证数据完整性，所以流式处理需要先分离标签再完成解密验证。

核心实现思路 #

• 利用浏览器的ReadableStream处理response.body的下载流
• 通过TransformStream拦截流数据，分离出末尾的认证标签
• 使用Web Crypto API的流式解密接口（createDecryptor）分块处理密文
• 最后用分离出的标签完成认证验证，确保数据未被篡改
• 将解密后的流直接转换为Blob触发下载，全程无大内存占用

完整代码示例 #

async function download_file(folder, file) {
  const response = await fetch(file.url);
  if (!response.body) {
    throw new Error("当前浏览器不支持流式响应");
  }

  // AES-GCM默认认证标签长度为128比特（16字节），可根据你的加密配置调整
  const tagBitLength = 128;
  const tagByteLength = tagBitLength / 8;

  let decryptor;
  let pendingTag = null;

  const decryptTransform = new TransformStream({
    start(controller) {
      // 初始化AES-GCM解密器
      decryptor = window.crypto.subtle.createDecryptor(
        {
          name: "AES-GCM",
          iv: Uint8Array.fromBase64(file.iv), // 注意：确保fromBase64方法正确实现
          tagLength: tagBitLength
        },
        folder.key
      );
    },

    async transform(chunk, controller) {
      // 如果还没分离出标签，检查当前块是否足够取出标签
      if (!pendingTag && chunk.length >= tagByteLength) {
        // 从块末尾截取标签
        pendingTag = chunk.slice(-tagByteLength);
        // 剩下的部分作为密文块处理
        const ciphertextChunk = chunk.slice(0, chunk.length - tagByteLength);
        const decryptedChunk = await decryptor.process(ciphertextChunk);
        controller.enqueue(decryptedChunk);
      } else {
        // 还不够标签长度，直接处理整个块
        const decryptedChunk = await decryptor.process(chunk);
        controller.enqueue(decryptedChunk);
      }
    },

    async flush(controller) {
      try {
        // 最后传入标签完成解密和验证
        const finalChunk = await decryptor.final(pendingTag);
        controller.enqueue(finalChunk);
      } catch (error) {
        controller.error(new Error("文件解密失败：数据可能已被篡改或密钥错误"));
      }
    }
  });

  // 将下载流通过解密转换流处理
  const decryptedStream = response.body.pipeThrough(decryptTransform);

  // 将解密后的流转换为Blob并触发下载
  const blob = await new Response(decryptedStream).blob();
  const downloadUrl = URL.createObjectURL(blob);
  
  const downloadLink = document.createElement("a");
  downloadLink.href = downloadUrl;
  downloadLink.download = file.name;
  downloadLink.click();

  // 清理URL对象，释放内存
  URL.revokeObjectURL(downloadUrl);
}

关键注意事项 #

• 浏览器兼容性：createDecryptor是Web Crypto API的流式扩展，需要Chrome 80+、Firefox 74+或Edge 80+以上版本支持。如果需要兼容旧浏览器，可以改用分块读取+逐块解密的方式（手动管理每块64KB左右的密文，解密后拼接成Blob）。
• 标签位置：确保你的加密逻辑是将认证标签附加在密文末尾（这是AES-GCM的标准做法），如果你的标签存储在其他位置，需要调整代码中的分离逻辑。
• 错误处理：如果数据被篡改、密钥错误或IV不匹配，decryptor.final()会抛出异常，一定要捕获并提示用户，避免下载损坏文件。
• 内存优化：这种流式处理方式下，每个数据块会被即时解密并传递，不会在内存中缓存完整的密文或明文，即使是GB级别的大文件也能流畅处理。

内容的提问来源于stack exchange，提问作者user2233709