Web Cryptography API是现代浏览器提供的原生加密接口，允许开发者在js中直接执行加密、解密、签名、密钥生成等操作，无需引入额外的加密库，既减少了代码体积也降低了第三方库带来的安全风险。合理使用这个API可以有效保护前端传输和存储的敏感数据。
js操作Web Cryptography API基础步骤
1. 获取Crypto对象
所有操作都基于window.crypto对象，该对象是浏览器的原生属性，无需额外初始化：
// 检查浏览器是否支持Web Cryptography API
if (window.crypto && window.crypto.subtle) {
console.log('当前浏览器支持Web Cryptography API');
const cryptoSubtle = window.crypto.subtle;
} else {
console.log('当前浏览器不支持Web Cryptography API');
}
2. 生成密钥
以生成AES-GCM对称密钥为例，这是前端常用的加密算法，适合加密本地存储或传输的敏感数据：
async function generateAesKey() {
try {
// 生成256位AES-GCM密钥，可提取密钥用于后续存储或传输
const key = await window.crypto.subtle.generateKey(
{
name: 'AES-GCM',
length: 256
},
true, // 是否可提取
['encrypt', 'decrypt'] // 密钥用途
);
return key;
} catch (err) {
console.error('生成密钥失败:', err);
}
}
3. 数据加密与解密
AES-GCM算法需要随机初始化向量（IV），每次加密都需要生成新的IV，避免重复导致安全风险：
// 加密数据
async function encryptData(key, data) {
try {
// 生成12字节的随机IV，AES-GCM推荐IV长度为12字节
const iv = window.crypto.getRandomValues(new Uint8Array(12));
// 将字符串转为Uint8Array
const encoder = new TextEncoder();
const dataBuffer = encoder.encode(data);
// 执行加密
const encryptedBuffer = await window.crypto.subtle.encrypt(
{
name: 'AES-GCM',
iv: iv
},
key,
dataBuffer
);
// 返回IV和加密后的数据，解密时需要用到IV
return {
iv: Array.from(iv),
encryptedData: Array.from(new Uint8Array(encryptedBuffer))
};
} catch (err) {
console.error('加密失败:', err);
}
}
// 解密数据
async function decryptData(key, ivArray, encryptedArray) {
try {
const iv = new Uint8Array(ivArray);
const encryptedBuffer = new Uint8Array(encryptedArray).buffer;
// 执行解密
const decryptedBuffer = await window.crypto.subtle.decrypt(
{
name: 'AES-GCM',
iv: iv
},
key,
encryptedBuffer
);
// 将解密后的buffer转为字符串
const decoder = new TextDecoder();
return decoder.decode(decryptedBuffer);
} catch (err) {
console.error('解密失败:', err);
}
}
Web加密API的6个安全实践
1. 避免在不安全上下文使用
Web Cryptography API仅在安全上下文（HTTPS、localhost、127.0.0.1）中可用，生产环境必须部署HTTPS，防止加密操作被中间人劫持，避免密钥和明文数据在传输过程中泄露。
2. 密钥不硬编码在前端代码中
不要将加密密钥直接写在前端js文件里，攻击者可以通过查看源码获取密钥，失去加密意义。对称密钥可以通过安全接口从后端获取，非对称加密的公钥可以前端存储，但私钥必须放在后端。
3. 每次加密使用唯一随机IV
如上面的示例所示，每次调用加密方法都要生成新的随机IV，不要复用IV。对于AES-GCM算法，IV重复会导致加密安全性完全失效，攻击者可以轻易破解加密内容。
4. 严格限制密钥用途
生成密钥时明确指定密钥的用途，比如仅用于加密解密的密钥不要赋予签名权限，减少密钥被滥用的风险。如果密钥不需要提取，将extractable参数设为false，避免密钥被意外导出。
5. 敏感操作优先使用非对称加密
对于需要传输到后端的敏感数据，优先使用RSA-OAEP等非对称加密算法，前端用公钥加密，后端用私钥解密，避免对称密钥在前端暴露。非对称加密的密钥生成示例如下：
async function generateRsaKeyPair() {
try {
const keyPair = await window.crypto.subtle.generateKey(
{
name: 'RSA-OAEP',
modulusLength: 2048, // 密钥长度，推荐2048位及以上
publicExponent: new Uint8Array([0x01, 0x00, 0x01]), // 65537
hash: 'SHA-256'
},
false, // 私钥不可提取
['encrypt', 'decrypt'] // 公钥加密，私钥解密
);
return keyPair;
} catch (err) {
console.error('生成RSA密钥对失败:', err);
}
}
6. 加密结果做好完整性校验
AES-GCM等认证加密算法本身会附带完整性校验，不需要额外做哈希校验，但如果是使用AES-CBC等非认证加密算法，必须额外添加HMAC签名校验数据完整性，防止加密数据被篡改。
注意事项
Web Cryptography API不支持导出私钥为原始格式，如果需要在不同上下文使用同一密钥，要使用wrapKey方法用另一个密钥包装后再传输，避免私钥直接暴露。另外不同浏览器对API的支持细节略有差异，开发时做好兼容性判断。
Web_Cryptography_APIjs加密前端安全密钥管理数据加密修改时间：2026-07-20 08:03:30