Cloudflare Docs
Workers
Cloudflare Docs
Workers
Search icon (depiction of a magnifying glass)
GitHub icon
Visit Workers on GitHub
Set theme to dark (⇧+D)

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:

​​ Constructors

  • crypto.DigestStream(algorithm) DigestStream

    • A non-standard extension to the crypto API that supports generating a hash digest from streaming data. The DigestStream itself is a WritableStream that does not retain the data written into it. Instead, it generates a hash digest automatically when the flow of data has ended.

      Parameters:

      Usage:

export default {
  async fetch(req) {
    // Fetch from origin
    const res = await fetch(req);
    
    // We need to read the body twice so we `tee` it (get two instances)
    const [bodyOne, bodyTwo] = res.body.tee();
    // Make a new response so we can set the headers (responses from `fetch` are immutable)
    const newRes = new Response(bodyOne, res);
    // Create a SHA-256 digest stream and pipe the body into it
    const digestStream = new crypto.DigestStream("SHA-256");
    bodyTwo.pipeTo(digestStream);
    // Get the final result
    const digest = await digestStream.digest;
    // Turn it into a hex string
    const hexString = [...new Uint8Array(digest)]
      .map(b => b.toString(16).padStart(2, '0'))
      .join('')
    // Set a header with the SHA-256 hash and return the response
    newRes.headers.set("x-content-digest", `SHA-256=${hexString}`);
    return newRes;
  }

}

const handler: ExportedHandler = {
  async fetch(req) {
    // Fetch from origin
    const res = await fetch(req);
    
    // We need to read the body twice so we `tee` it (get two instances)
    const [bodyOne, bodyTwo] = res.body.tee();
    // Make a new response so we can set the headers (responses from `fetch` are immutable)
    const newRes = new Response(bodyOne, res);
    // Create a SHA-256 digest stream and pipe the body into it
    const digestStream = new crypto.DigestStream("SHA-256");
    bodyTwo.pipeTo(digestStream);
    // Get the final result
    const digest = await digestStream.digest;
    // Turn it into a hex string
    const hexString = [...new Uint8Array(digest)]
      .map(b => b.toString(16).padStart(2, '0'))
      .join('')
    // Set a header with the SHA-256 hash and return the response
    newRes.headers.set("x-content-digest", `SHA-256=${hexString}`);
    return newRes;
  }

}

export default handler;

​​ Methods

  • crypto.getRandomValues(bufferArrayBufferView) ArrayBufferView

    • Fills the passed ArrayBufferView with cryptographically sound random values and returns the buffer.

      Parameters:

      • bufferArrayBufferView

        • Must be an Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | BigInt64Array | BigUint64Array.

  • crypto.randomUUID() string

​​ SubtleCrypto Methods

These methods are all accessed via crypto.subtle, which is also documented in detail on MDN.

  • encrypt(algorithm, key, data) Promise<ArrayBuffer>

  • decrypt(algorithm, key, data) Promise<ArrayBuffer>

  • sign(algorithm, key, data) Promise<ArrayBuffer>

  • verify(algorithm, key, signature, data) Promise<boolean>

    • 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:

  • digest(algorithm, data) Promise<ArrayBuffer>

  • generateKey(algorithm, extractable, keyUsages) Promise<CryptoKey> | Promise<CryptoKeyPair>

    • Returns a Promise that fulfills with a newly-generated CryptoKey, for symmetrical algorithms, or a CryptoKeyPair, containing two newly generated keys, for asymmetrical algorithms. For example, to generate a new AES-GCM key:
let keyPair = await crypto.subtle.generateKey(
  {
    name: 'AES-GCM',
    length: '256',
  },
  true,
  ['encrypt', 'decrypt']

);

Parameters:

​​ Supported algorithms

Workers implements all operation of the WebCrypto standard, as shown in the following table. The Workers team continuously adds support for more algorithms — share your use case with the community.

A checkmark (✓) indicates that this feature is believed to be fully supported according to the spec.
An x (✘) indicates that this feature is part of the specification but not implemented.
If a feature only implements the operation partially, details are listed.

Algorithmsign()
verify()		encrypt()
decrypt()		digest()deriveBits()
deriveKey()		generateKey()wrapKey()
unwrapKey()		exportKey()importKey()
RSASSA PKCS1 v1.5✓✓✓✓
RSA PSS✓✓✓✓
RSA OAEP✓✓✓✓✓
ECDSA✓✓✓✓
ECDH✓✓✓✓
NODE ED255191✓✓✓✓
AES CTR✓✓✓✓✓
AES CBC✓✓✓✓✓
AES GCM✓✓✓✓✓
AES KW✓✓✓✓
HMAC✓✓✓✓
SHA 1✓
SHA 256✓
SHA 384✓
SHA 512✓
MD52✓
HKDF✓✓
PBKDF2✓✓

Footnotes:

  1. Non-standard EdDSA is supported for the Ed25519 curve. Since this algorithm is non-standard, a few things to keep in mind while using it:

    • Use NODE-ED25519 as the algorithm and namedCurve parameters.
    • Unlike NodeJS, Cloudflare will not support raw import of private keys.
    • The algorithm implementation may change over time. While Cloudflare cannot guarantee it at this time, Cloudflare will strive to maintain backward compatibility and compatibility with NodeJS’s behavior. Any notable compatibility notes will be communicated in release notes and via this developer document.

  2. 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.