tencent cloud

边缘安全加速平台 EO

Web Crypto

下载
聚焦模式
字号
最后更新时间: 2025-09-15 16:28:44
Web Crypto API 基于 Web APIs 标准 Web Crypto API 进行设计。提供了一组常见的加密操作接口,相比纯 JavaScript 实现的加密接口,Web Crypto API 的性能更高。
注意:
不支持直接构造 Crypto 对象,边缘函数运行时会在全局注入,直接使用全局 crypto 实例即可。

描述

// 编码
const encodeContent = new TextEncoder().encode('hello world');
// 使用 crypto,生成 SHA-256 哈希值 Promise<ArrayBuffer>
const sha256Content = await crypto.subtle.digest(
{ name: 'SHA-256' },
encodeContent
);
const result = new Uint8Array(sha256Content);

属性

// crypto.subtle
readonly subtle: SubtleCrypto;
提供常见的加密操作, 例如: 哈希、签名/验签、加解密等,详情参见 SubtleCrypto。

方法

getRandomValues

crypto.getRandomValues(buffer: TypedArray): TypedArray;
生成随机数填充 buffer, 并返回 buffer。

参数

属性名
类型
必填
说明
buffer
是
随机数缓冲区,不超过 65536 字节。详情参见 TypedArray。

randomUUID

crypto.randomUUID(): string;
返回随机 UUID(v4)。

SubtleCrypto

提供常见的加密操作, 例如: 哈希、签名/验签、加解密等,详情参见 MDN 官方文档:SubtleCrypto。
说明:
SubtleCrypto 加密接口按功能分为两类:
加密功能,包含 encrypt/decrypt、sign/verify、digest, 可以用来实现隐私和身份验证等安全功能。
密钥管理功能,包含 generateKey、deriveKey、importKey/exportKey, 可以用来管理密钥。

digest

crypto.subtle.digest(algorithm: string | object, data: ArrayBuffer): Promise<ArrayBuffer>;
返回 Promise 对象,包含生成的数据摘要(hash),详情参见 MDN 官方文档:SubtleCrypto.digest。

encrypt

crypto.subtle.encrypt(algorithm: object, key: CryptoKey, data: ArrayBuffer): Promise<ArrayBuffer>;
返回 Promise 对象,包含加密数据,详情参见 MDN 官方文档:SubtleCrypto.encrypt。
对于 RSA-OAEP 算法,要求 data 长度不能超过 modulusLength/8 - 2*hLen -2,其中 hLen 的取值逻辑为:
SHA-1: hLen = 20 byte
SHA-256: hLen = 32 byte
SHA-384: hLen = 48 byte
SHA-512: hLen = 64 byte
对于 AES-CTR,AES-CBC,AES-GCM,限制 data 长度 1MB。

decrypt

crypto.subtle.decrypt(algorithm: object, key: CryptoKey, data: ArrayBuffer): Promise<ArrayBuffer>;
返回 Promise 对象,包含解密数据,详情参见 MDN 官方文档:SubtleCrypto.decrypt。
对于 RSA-OAEP 算法, data 长度为 modulusLength/8。
对于 AES-CTR,AES-CBC,AES-GCM,限制 data 长度 1MB。

sign

crypto.subtle.sign(algorithm: string | object, key: CryptoKey, data: ArrayBuffer): Promise<ArrayBuffer>;
返回 Promise 对象,包含数据签名,详情参见 MDN 官方文档:SubtleCrypto.sign。

verify

crypto.subtle.verify(algorithm: string | object, key: CryptoKey, signature: BufferSource, data: ArrayBuffer): Promise<boolean>;
返回 Promise 对象,包含签名验证结果,详情参见 MDN 官方文档:SubtleCrypto.verify。

generateKey

crypto.subtle.generateKey(algorithm: object, extractable: boolean, keyUsages: Array<string>): Promise<CryptoKey | CryptoKeyPair>;
返回 Promise 对象,包含密钥 CryptoKey或密钥对 CryptoKeyPair,详情参见 MDN 官方文档:SubtleCrypto.generateKey。

deriveKey

crypto.subtle.deriveKey(algorithm: object, baseKey: CryptoKey, derivedKeyAlgorithm: object, extractable: boolean, keyUsages: Array<string>): Promise<CryptoKey>;
返回 Promise 对象,包含密钥 CryptoKey,详情参见 MDN 官方文档:SubtleCrypto.deriveKey。

importKey

crypto.subtle.importKey(format: string, keyData: BufferSource, algorithm: string | object, extractable: boolean, keyUsages: Array<string>): Promise<CryptoKey>;
返回 Promise 对象,包含密钥 CryptoKey,详情参见 MDN 官方文档:SubtleCrypto.importKey。

exportKey

crypto.subtle.exportKey(format: string, key: CryptoKey): Promise<ArrayBuffer>;
返回 Promise 对象,包含导出密钥 ArrayBuffer,详情参见 MDN 官方文档:SubtleCrypto.exportKey。

deriveBits

crypto.subtle.deriveBits(algorithm: object, baseKey: CryptoKey, length: integer): Promise<ArrayBuffer>;
返回 Promise 对象,包含伪随机字节 ArrayBuffer,详情参见 MDN 官方文档:SubtleCrypto.deriveBits。

wrapKey

crypto.subtle.wrapKey(format: string, key: CryptoKey, wrappingKey: CryptoKey, wrapAlgo: string | object): Promise<ArrayBuffer>;;
返回 Promise 对象,包含封装密钥 ArrayBuffer,详情参见 MDN 官方文档:SubtleCrypto.wrapKey。

unwrapKey

crypto.subtle.unwrapKey(format: string, wrappedKey: ArrayBuffer, unwrappingKey: CryptoKey, unwrapAlgo: string | object, unwrappedKeyAlgo: string | object, extractable: boolean, keyUsages: Array<string>): Promise<CryptoKey>;
返回 Promise 对象,包含解封密钥 CryptoKey,详情参见 MDN 官方文档:SubtleCrypto.unwrapKey。

CryptoKey

CryptoKey 表示用加密算法生成的密钥,详细参见 MDN 官方文档 CryptoKey。不支持直接构造 CryptoKey 对象,使用下述接口生成密钥:
CryptoKey 属性描述如下。
属性名
类型
只读
说明
type
string
是
密钥类型。
extractable
boolean
是
密钥是否可导出。
algorithm
object
是
算法相关, 包含算法需要的字段。
usages
Array<string>
是
密钥的用途。

CryptoKeyPair

CryptoKeyPair 表示用加密算法生成的密钥对,详细参见 MDN 官方文档:CryptoKeyPair。不支持直接构造 CryptoKeyPair 对象,使用下述接口生成密钥对:
CryptoKeyPair 属性描述如下。
属性名
类型
只读
说明
privateKey
CryptoKey
是
对于加解密算法, 私钥用于解密。对于签名算法, 私钥用于签名。
publicKey
CryptoKey
是
对于加解密算法, 公钥用于加密。对于签名算法, 公钥用于验签。

支持算法

边缘函数支持 Web APIs 标准 WebCrypto 定义的所有算法,详细如下表所示。
Algorithm
encrypt() decrypt()
sign() verify()
wrapKey() unwrapKey()
deriveKey() deriveBits()
generateKey()
importKey()
exportKey()
digest()
RSASSA-PKCS1-v1_5
-
✓
-
-
✓
✓
✓
-
RSA-PSS
-
✓
-
-
✓
✓
✓
-
RSA-OAEP
✓
-
✓
-
✓
✓
✓
-
ECDSA
-
✓
-
-
✓
✓
✓
-
ECDH
-
-
-
✓
✓
✓
✓
-
HMAC
-
✓
-
-
✓
✓
✓
-
AES-CTR
✓
-
✓
-
✓
✓
✓
-
AES-CBC
✓
-
✓
-
✓
✓
✓
-
AES-GCM
✓
-
✓
-
✓
✓
✓
-
AES-KW
-
-
✓
-
✓
✓
✓
-
HKDF
-
-
-
✓
-
✓
-
-
PBKDF2
-
-
-
✓
-
✓
-
-
SHA-1
-
-
-
-
-
-
-
✓
SHA-256
-
-
-
-
-
-
-
✓
SHA-384
-
-
-
-
-
-
-
✓
SHA-512
-
-
-
-
-
-
-
✓
MD5
-
-
-
-
-
-
-
✓

示例代码

function uint8ArrayToHex(arr) {
return Array.prototype.map.call(arr, (x) => ((`0${x.toString(16)}`).slice(-2))).join('');
}

async function handleEvent(event) {
const encodeArr = TextEncoder().encode('hello world');
// 执行 md5
const md5Buffer = await crypto.subtle.digest({ name: 'MD5' }, encodeArr);
// 输出十六进制字符串
const md5Str = uint8ArrayToHex(new Uint8Array(md5Buffer));

const response = new Response(md5Str);
return response;
}

addEventListener('fetch', async (event) => {
event.respondWith(handleEvent(event));
});

相关参考

帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈