JS使用Web Crypto API实现AES加解密完整示例
详细讲解在现代浏览器中使用原生Web Crypto API(SubtleCrypto)实现AES-GCM 256位加解密的完整过程,包含密钥生成、IV处理、文本编码转换、异常处理与完整封装代码。
现代浏览器内置的原生 Web Crypto API(挂载于 window.crypto.subtle)为前端开发者提供了硬件加速、抗内存窥探的高性能密码学接口。本文以工程落地标准最高的 AES-GCM(256 位) 为例,提供从密钥派生、IV(初始化向量)生成、数据格式转换到密文封包与解密的完整实现,代码零第三方依赖,可直接在主流浏览器与安全上下文中运行。
一、为什么优先选择 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)。
三、核心数据类型与内存流转机制
初学者在使用 Web Crypto API 时最容易受挫的地方,通常并非算法本身,而是各种类型之间的转换。crypto.subtle.encrypt 与 decrypt 不直接接收字符串,而是接收并返回 ArrayBuffer。理解数据类型的流转路径是写出无 Bug 密码学代码的前提。
四、关键实现细节分析
1. 初始化向量(IV)的长度与安全性
在 AES-GCM 算法中,推荐的 IV 长度是 12 字节(96 位)。为什么不是常见的 16 字节?因为 GCM 内部采用 96 位的 IV 直接与 32 位的初始计数器拼接形成 128 位计数器块;若传入 16 字节或其它长度,算法底层会先执行额外的 GHASH 哈希计算将其压缩为 96 位,既损耗性能,又略微降低碰撞安全性。
crypto.getRandomValues(new Uint8Array(12)) 为每一次加密生成全新的随机 IV。
2. 为什么将 IV 与密文合并打包?
IV 并非密码,它无需保密,解密端必须知晓加密时使用的 IV 才能正确解密。最简洁优雅的工程实践是将 12 字节的 IV 直接置于密文字节数组的最前部(Prepend),组合为一个单一的二进制包,然后再编码为 Base64。解密端接收后,读取前 12 字节作为 IV,剩余字节作为密文传给解密函数。
五、完整代码实现与封装示例
以下提供一份结构整洁、即拷即用的 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 投入实际项目前,请根据以下表格逐一核对安全与工程细节:
| 检查维度 | 推荐做法 | 潜在风险 / 错误做法 |
|---|---|---|
| 运行环境 | 必须在 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 独立性与异常捕获策略,能够有效保障传输与存储过程中的数据机密性与完整性。
何时使用indexOf而非正则?JS字符串匹配性能与适用性对比
2026-11-19 17:08:09
Web开发中JSP与JavaScript的分工与协作关系
2026-11-19 15:29:43
JavaScript前端安全设计:防御XSS与CSRF攻击的最佳实践
2026-11-18 23:50:09
JS怎么遍历三维数组:三重循环与flat方法对比
2026-11-18 21:23:44
优化HTML页面加载:JS脚本放置位置与加载策略
2026-11-18 21:00:16








