Web Crypto
Background
The Web Crypto API provides a set of low-level functions for common cryptographic tasks. The Workers Runtime implements the full surface of this API, but with some differences in the supported algorithms compared to those implemented in most browsers.
Performing cryptographic operations using the Web Crypto API is significantly faster than performing them purely in JavaScript. If you want to perform CPU-intensive cryptographic operations, you should consider using the Web Crypto API.
The Web Crypto API is implemented through the SubtleCrypto
interface, accessible via the global crypto.subtle
binding. A simple example of calculating a digest (also known as a hash) is:
const myText = new TextEncoder().encode("Hello world!")
const myDigest = await crypto.subtle.digest( { name: "SHA-256", }, myText, // The data you want to hash as an ArrayBuffer)
console.log(new Uint8Array(myDigest))
Some common uses include:
Methods
crypto.getRandomValues(bufferArrayBuffer)
ArrayBuffer
- Fills the passed ArrayBuffer with cryptographically sound random values.
SubtleCrypto Methods
These methods are all accessed via crypto.subtle
, which is also documented in detail on MDN.
encrypt(algorithm, key, data)
Promise<ArrayBuffer>
Returns a Promise that fulfills with the encrypted data corresponding to the clear text, algorithm, and key given as parameters.
Parameters:
algorithmobject
- Describes the algorithm to be used, including any required parameters, in an algorithm-specific format.
keyCryptoKey
dataBufferSource
decrypt(algorithm, key, data)
Promise<ArrayBuffer>
Returns a Promise that fulfills with the clear data corresponding to the ciphertext, algorithm, and key given as parameters.
Parameters:
algorithmobject
- Describes the algorithm to be used, including any required parameters, in an algorithm-specific format.
keyCryptoKey
dataBufferSource
sign(algorithm, key, data)
Promise<ArrayBuffer>
Returns a Promise that fulfills with the signature corresponding to the text, algorithm, and key given as parameters.
Parameters:
algorithmstring | object
- Describes the algorithm to be used, including any required parameters, in an algorithm-specific format.
keyCryptoKey
dataArrayBuffer
verify(algorithm, key, signature, data)
Promise<ArrayBuffer>
Returns a Promise that fulfills with a Boolean value indicating if the signature given as a parameter matches the text, algorithm, and key that are also given as parameters.
Parameters:
algorithmstring | object
- Describes the algorithm to be used, including any required parameters, in an algorithm-specific format.
keyCryptoKey
signatureArrayBuffer
dataArrayBuffer
digest(algorithm, data)
Promise<ArrayBuffer>
Returns a Promise that fulfills with a digest generated from the algorithm and text given as parameters.
Parameters:
algorithmstring | object
- Describes the algorithm to be used, including any required parameters, in an algorithm-specific format.
dataArrayBuffer
generateKey(algorithm, extractable, keyUsages)
Promise<CryptoKey> | Promise<CryptoKeyPair>
Returns a Promise that fulfills with a newly-generated
CryptoKey
, for symmetrical algorithms, or aCryptoKeyPair
, containing two newly generated keys, for asymmetrical algorithms. For example, to generate a new AES-GCM key:let keyPair = crypto.subtle.generateKey( { name: "AES-GCM", length: "256" }, true, ["encrypt", "decrypt"])
Parameters:
algorithmobject
- Describes the algorithm to be used, including any required parameters, in an algorithm-specific format.
extractablebool
keyUsagesArray
- An Array of strings indicating the possible usages of the new key.
deriveKey(algorithm, baseKey, derivedKeyAlgorithm, extractable, keyUsages)
Promise<CryptoKey>
Returns a Promise that fulfills with a newly generated
CryptoKey
derived from the base key and specific algorithm given as parameters.Parameters:
algorithmobject
- Describes the algorithm to be used, including any required parameters, in an algorithm-specific format.
baseKeyCryptoKey
derivedKeyAlgorithmobject
- Defines the algorithm the derived key will be used for in an algorithm-specific format.
extractablebool
keyUsagesArray
- An Array of strings indicating the possible usages of the new key
deriveBits(algorithm, baseKey, length)
Promise<ArrayBuffer>
Returns a Promise that fulfills with a newly generated buffer of pseudo-random bits derived from the base key and specific algorithm given as parameters. It returns a Promise which will be fulfilled with an
ArrayBuffer
containing the derived bits. This method is very similar toderiveKey()
, except thatderiveKey()
returns aCryptoKey
object rather than anArrayBuffer
. Essentially,deriveKey()
is composed ofderiveBits()
followed byimportKey()
.Parameters:
algorithmobject
- Describes the algorithm to be used, including any required parameters, in an algorithm-specific format.
baseKeyCryptoKey
lengthint
- Length of the bit string to derive.
importKey(format, keyData, algorithm, extractable, keyUsages)
Promise<CryptoKey>
Transform a key from some external, portable format into a
CryptoKey
for use with the Web Crypto API.Parameters:
formatstring
- Describes the format of the key to be imported.
keyDataArrayBuffer
algorithmobject
- Describes the algorithm to be used, including any required parameters, in an algorithm-specific format.
extractablebool
keyUsagesArray
- An Array of strings indicating the possible usages of the new key
exportKey(formatstring, keyCryptoKey)
Promise<ArrayBuffer>
Transform a
CryptoKey
into a portable format, if theCryptoKey
isextractable
.Parameters:
formatstring
- Describes the format in which the key will be exported.
keyCryptoKey
wrapKey(format, key, wrappingKey, wrapAlgo)
Promise<ArrayBuffer>
Transform a
CryptoKey
into a portable format, and then encrypt it with another key. This renders theCryptoKey
suitable for storage or transmission in untrusted environments.Parameters:
formatstring
- Describes the format in which the key will be exported before being encrypted.
keyCryptoKey
wrappingKeyCryptoKey
wrapAlgoobject
- Describes the algorithm to be used to encrypt the exported key, including any required parameters, in an algorithm-specific format.
unwrapKey(format, key, unwrappingKey, unwrapAlgo,
unwrappedKeyAlgo, extractable, keyUsages)Promise<CryptoKey>
Transform a key that was wrapped by
wrapKey()
back into aCryptoKey
.Parameters:
formatstring
- Described the data format of the key to be unwrapped.
keyCryptoKey
unwrappingKeyCryptoKey
unwrapAlgoobject
- Describes the algorithm that was used to encrypt the wrapped key, in an algorithm-specific format.
unwrappedKeyAlgoobject
- Describes the key to be unwrapped, in an algorithm-specific format.
extractablebool
keyUsagesArray
- An Array of strings indicating the possible usages of the new key
Supported algorithms
Workers implements a subset of the most common cryptographic algorithms, as shown in the following table. We are happy to add support for more algorithms — let us know about your use case.
Algorithm | sign() verify() | encrypt() decrypt() | digest() | deriveBits() deriveKey() | generateKey() | wrapKey() unwrapKey() | exportKey() |
---|---|---|---|---|---|---|---|
RSASSA-PKCS1-v1_5 | ✓ | ✓ | ✓ | ||||
RSA-PSS | ✓ | ✓ | ✓ | ||||
ECDSA | ✓ | ✓ | |||||
HMAC | ✓ | ✓ | |||||
AES-CBC | ✓ | ✓ | |||||
AES-GCM | ✓ | ✓ | ✓ | ||||
SHA-1 | ✓ | ||||||
SHA-256 | ✓ | ||||||
SHA-384 | ✓ | ||||||
SHA-512 | ✓ | ||||||
MD51 | ✓ | ||||||
PBKDF2 | ✓ |
Footnotes:
- MD5 is not part of the WebCrypto standard, but is supported in Cloudflare Workers for interacting with legacy systems that require MD5. MD5 is considered a weak algorithm. Do not rely upon MD5 for security.