Web Crypto
The Web Crypto API is designed based on the standard Web API Web Crypto API. The Web Crypto API provides a set of functions for common cryptographic operations. Performing cryptographic operations by using the Web Crypto API is significantly faster than performing them purely in JavaScript.
Note:
The
Crypto
object cannot be constructed directly. It is globally injected during the runtime of edge functions. Directly use the global crypto instance.Overview
// Perform encoding.const encodeContent = new TextEncoder().encode('hello world');// Use crypto to perform SHA-256 hashing. The resulting hash is a promise that fulfills with an ArrayBuffer.const sha256Content = await crypto.subtle.digest({ name: 'SHA-256' },encodeContent);const result = new Uint8Array(sha256Content);
Attributes
// crypto.subtlereadonly subtle: SubtleCrypto;
The Web Crypto API supports common cryptographic operations, such as hashing, signature signing and verification, and encryption and decryption. For more information, see SubtleCrypto.
Methods
getRandomValues
crypto.getRandomValues(buffer: TypedArray): TypedArray;
The getRandomValues() method generates a random value, fills the buffer with the random value, and returns the buffer.
Parameters
Parameter | Type | Required | Description |
buffer | Yes | The buffer of random values. The value cannot exceed 65,536 bytes in length. For more information, see TypedArray. |
randomUUID
crypto.randomUUID(): string;
The randomUUID() method generates a new random (version 4) UUID.
SubtleCrypto
The SubtleCrypto API supports common cryptographic operations, such as hashing, signature signing and verification, and encryption and decryption. For more information, see SubtleCrypto.
Note:
SubtleCrypto methods are classified into the following types based on features:
Encryption methods:
encrypt/decrypt
, sign/verify
, and digest
. Such methods can be used to implement security-related features such as privacy and identity verification.Key management methods:
generateKey
, deriveKey
, and importKey/exportKey
. Such methods can be used to manage keys.digest
crypto.subtle.digest(algorithm: string | object, data: ArrayBuffer): Promise<ArrayBuffer>;
The decrypt() method returns a Promise object that fulfills with the generated data digest (hash). For more information, see SubtleCrypto.digest.
encrypt
crypto.subtle.encrypt(algorithm: object, key: CryptoKey, data: ArrayBuffer): Promise<ArrayBuffer>;
The encrypt() method returns a Promise object that fulfills with the encrypted data. For more information, see SubtleCrypto.encrypt.
For the
RSA-OAEP
algorithm, the data length must not exceed modulusLength/8 - (2 * hLen) - 2, where hLen is determined as follows:SHA-1: hLen = 20 bytes
SHA-256: hLen = 32 bytes
SHA-384: hLen = 48 bytes
SHA-512: hLen = 64 bytes
For the
AES-CTR
, AES-CBC
++++, and AES-GCM
algorithms, the data length is limited to 1 MB.decrypt
crypto.subtle.decrypt(algorithm: object, key: CryptoKey, data: ArrayBuffer): Promise<ArrayBuffer>;
The decrypt() method returns a Promise object that fulfills with the decrypted data. For more information, see SubtleCrypto.decrypt.
For the
RSA-OAEP
algorithm, the data length is modulusLength/8.For the
AES-CTR
, AES-CBC
++++, and AES-GCM
algorithms, the data length is limited to 1 MB.sign
crypto.subtle.sign(algorithm: string | object, key: CryptoKey, data: ArrayBuffer): Promise<ArrayBuffer>;
The sign() method returns a Promise object that fulfills with the signature. For more information, see SubtleCrypto.sign.
verify
crypto.subtle.verify(algorithm: string | object, key: CryptoKey, signature: BufferSource, data: ArrayBuffer): Promise<boolean>;
The verify() method returns a Promise object that fulfills with the signature verification result. For more information, see SubtleCrypto.verify.
generateKey
crypto.subtle.generateKey(algorithm: object, extractable: boolean, keyUsages: Array<string>): Promise<CryptoKey | CryptoKeyPair>;
The generateKey() method returns a Promise object that fulfills with a CryptoKey or a CryptoKeyPair. For more information, see SubtleCrypto.generateKey.
deriveKey
crypto.subtle.deriveKey(algorithm: object, baseKey: CryptoKey, derivedKeyAlgorithm: object, extractable: boolean, keyUsages: Array<string>): Promise<CryptoKey>;
The deriveKey() method returns a Promise object that fulfills with a CryptoKey. For more information, see SubtleCrypto.deriveKey.
importKey
crypto.subtle.importKey(format: string, keyData: BufferSource, algorithm: string | object, extractable: boolean, keyUsages: Array<string>): Promise<CryptoKey>;
The importKey() method returns a Promise object that fulfills with a CryptoKey. For more information, see SubtleCrypto.importKey.
exportKey
crypto.subtle.exportKey(format: string, key: CryptoKey): Promise<ArrayBuffer>;
The exportKey() method returns a Promise object that fulfills with an ArrayBuffer containing the key. For more information, see SubtleCrypto.exportKey.
deriveBits
crypto.subtle.deriveBits(algorithm: object, baseKey: CryptoKey, length: integer): Promise<ArrayBuffer>;
The deriveBits() method returns a Promise object that fulfills with an ArrayBuffer of pseudo-random bits. For more information, see SubtleCrypto.deriveBits.
wrapKey
crypto.subtle.wrapKey(format: string, key: CryptoKey, wrappingKey: CryptoKey, wrapAlgo: string | object): Promise<ArrayBuffer>;;
The wrapKey() method returns a Promise object that fulfills with an ArrayBuffer containing the wrapped key. For more information, see 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>;
The unwrapKey() method returns a Promise object that fulfills with the unwrapped CryptoKey. For more information, see SubtleCrypto.unwrapKey.
CryptoKey
A
CryptoKey
represents a key that is generated by using an encryption algorithm. For more information, see CryptoKey. The CryptoKey object cannot be constructed directly. You can use the following methods to generate CryptoKey objects:The following table describes the
CryptoKey
attributes.Attribute | Type | Read-only | Description |
type | string | Yes | The type of the key. |
extractable | boolean | Yes | Specifies whether the key can be exported. |
algorithm | object | Yes | The algorithm for which this key can be used and the associated parameters. |
usages | Array<string> | Yes | The usage of the key. |
CryptoKeyPair
A
CryptoKeyPair
represents a key pair that is generated by using an encryption algorithm. For more information, see CryptoKeyPair. The CryptoKeyPair object cannot be constructed directly. You can use the following method to generate CryptoKeyPair objects:The following table describes the
CryptoKeyPair
attributes.Attribute | Type | Read-only | Description |
privateKey | Yes | The private key. For encryption and decryption algorithms, this key is used for decryption. For signature signing and verification algorithms, this key is used for signature signing. | |
publicKey | Yes | The public key. For encryption and decryption algorithms, this key is used for encryption. For signature signing and verification algorithms, this key is used for signature verification. |
Supported Algorithms
Edge Functions supports all algorithms that are defined in the WebCrypto specification. The following table describes the algorithms.
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 | - | - | - | - | - | - | - | ✓ |
Sample Code
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');// Execute MD5.const md5Buffer = await crypto.subtle.digest({ name: 'MD5' }, encodeArr);// Generate a hexadecimal string.const md5Str = uint8ArrayToHex(new Uint8Array(md5Buffer));const response = new Response(md5Str);return response;}addEventListener('fetch', async (event) => {event.respondWith(handleEvent(event));});