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:

• Signing requests

​​ Methods

​​ SubtleCrypto Methods

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

Parameters:

• algorithmobject

  • Describes the algorithm to be used, including any required parameters, in an algorithm-specific format Open external link .

• extractablebool

• keyUsagesArray

  • An Array of strings indicating the possible usages of the new key Open external link .

• 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 Open external link .

    • baseKeyCryptoKey

    • derivedKeyAlgorithmobject

      • Defines the algorithm the derived key will be used for in an algorithm-specific format Open external link .

    • extractablebool

    • keyUsagesArray

      • An Array of strings indicating the possible usages of the new key Open external link

• 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 to deriveKey(), except that deriveKey() returns a CryptoKey object rather than an ArrayBuffer. Essentially, deriveKey() is composed of deriveBits() followed by importKey().

    Parameters:

    • algorithmobject

      • Describes the algorithm to be used, including any required parameters, in an algorithm-specific format Open external link .

    • 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 Open external link .

    • keyDataArrayBuffer

    • algorithmobject

      • Describes the algorithm to be used, including any required parameters, in an algorithm-specific format Open external link .

    • extractablebool

    • keyUsagesArray

      • An Array of strings indicating the possible usages of the new key Open external link

• exportKey(formatstring, keyCryptoKey) Promise<ArrayBuffer>

  • Transform a CryptoKey into a portable format, if the CryptoKey is extractable.

    Parameters:

    • formatstring

      • Describes the format in which the key will be exported Open external link .

    • keyCryptoKey

• wrapKey(format, key, wrappingKey, wrapAlgo) Promise<ArrayBuffer>

  • Transform a CryptoKey into a portable format, and then encrypt it with another key. This renders the CryptoKey suitable for storage or transmission in untrusted environments.

    Parameters:

    • formatstring

      • Describes the format in which the key will be exported Open external link 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 Open external link .

• unwrapKey(format, key, unwrappingKey, unwrapAlgo,
  unwrappedKeyAlgo, extractable, keyUsages) Promise<CryptoKey>

  • Transform a key that was wrapped by wrapKey() back into a CryptoKey.

    Parameters:

    • formatstring

      • Described the data format of the key to be unwrapped Open external link .

    • keyCryptoKey

    • unwrappingKeyCryptoKey

    • unwrapAlgoobject

      • Describes the algorithm that was used to encrypt the wrapped key, in an algorithm-specific format Open external link .

    • unwrappedKeyAlgoobject

      • Describes the key to be unwrapped, in an algorithm-specific format Open external link .

    • extractablebool

    • keyUsagesArray

      • An Array of strings indicating the possible usages of the new key Open external link

• timingSafeEqual(a, b) bool

  • Compare two buffers in a way that is resistant to timing attacks. This is a non-standard extension to the Web Crypto API.

    Parameters:

    • aArrayBuffer | TypedArray

    • bArrayBuffer | TypedArray