tencent cloud

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	Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | BigInt64Array | BigUint64Array	是	随机数缓冲区，不超过 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。

decrypt

crypto.subtle.decrypt(algorithm: object, key: CryptoKey, data: ArrayBuffer): Promise<ArrayBuffer>;

返回 Promise 对象，包含解密数据，详情参见 MDN 官方文档：SubtleCrypto.decrypt。

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 对象，使用下述接口生成密钥：

• crypto.subtle.generateKey
• crypto.subtle.importKey
• crypto.subtle.deriveKey
• crypto.subtle.unwrapKey

CryptoKey 属性描述如下。

属性名	类型	只读	说明
type	string	是	密钥类型。
extractable	boolean	是	密钥是否可导出。
algorithm	object	是	算法相关, 包含算法需要的字段。
usages	Array<string>	是	密钥的用途。

CryptoKeyPair

CryptoKeyPair 表示用加密算法生成的密钥对，详细参见 MDN 官方文档：CryptoKeyPair。不支持直接构造 CryptoKeyPair 对象，使用下述接口生成密钥对：

• crypto.subtle.generateKey

CryptoKeyPair 属性描述如下。

属性名	类型	只读	说明
privateKey	CryptoKey	是	对于加解密算法, 私钥用于解密。对于签名算法, 私钥用于签名。
publicKey	CryptoKey	是	对于加解密算法, 公钥用于加密。对于签名算法, 公钥用于验签。

支持算法

边缘函数支持 Web APIs 标准 WebCrypto 定义的所有算法，详细如下表所示。

lgorithm	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));
});

相关参考

• MDN 官方文档：Web Crypto API
• MDN 官方文档：SubtleCrypto
• MDN 官方文档：CryptoKey
• MDN 官方文档：CryptoKeyPair
• 示例函数：防篡改校验
• 示例函数：m3u8 改写与鉴权
• 示例函数：缓存 POST 请求