SubtleCrypto.deriveBits()

The deriveBits() method of the SubtleCrypto interface can be used to derive an array of bits from a base key.

It takes as its arguments the base key, the derivation algorithm to use, and the length of the bit string to derive. It returns a Promise which will be fulfilled with an ArrayBuffer containing the derived bits.

This method is very similar to SubtleCrypto.deriveKey(), except that deriveKey() returns a CryptoKey object rather than an ArrayBuffer. Essentially deriveKey() is composed of deriveBits() followed by importKey().

This function supports the same derivation algorithms as deriveKey(): ECDH, HKDF, and PBKDF2. See Supported algorithms for some more detail on these algorithms.

Syntax

const result = crypto.subtle.deriveBits(
    algorithm,
    baseKey,
    length
);

Parameters

  • algorithm is an object defining the derivation algorithm to use.
  • baseKey is a CryptoKey representing the input to the derivation algorithm. If algorithm is ECDH, this will be the ECDH private key. Otherwise it will be the initial key material for the derivation function: for example, for PBKDF2 it might be a password, imported as a CryptoKey using SubtleCrypto.importKey().
  • length is a number representing the number of bits to derive.

Return value

Exceptions

The promise is rejected when one of the following exceptions are encountered:

InvalidAccessError
Raised when the base key is not a key for the requested derivation algorithm or if the CryptoKey.usages value of that key doesn't contain deriveKey.
NotSupported
Raised when trying to use an algorithm that is either unknown or isn't suitable for derivation, or if the algorithm requested for the derived key doesn't define a key length.

Supported algorithms

See the Supported algorithms section of the deriveKey() documentation.

Examples

Note: You can try the working examples on GitHub.

ECDH

In this example Alice and Bob each generate an ECDH key pair.

We then use Alice's private key and Bob's public key to derive a shared secret. See the complete code on GitHub.

async function deriveSharedSecret(privateKey, publicKey) {
  const sharedSecret = await window.crypto.subtle.deriveBits(
    {
      name: "ECDH",
      namedCurve: "P-384",
      public: publicKey
    },
    privateKey,
    128
  );

  const buffer = new Uint8Array(sharedSecret, 0, 5);
  const sharedSecretValue = document.querySelector(".ecdh .derived-bits-value");
  sharedSecretValue.classList.add("fade-in");
  sharedSecretValue.addEventListener("animationend", () => {
    sharedSecretValue.classList.remove("fade-in");
  });
  sharedSecretValue.textContent = `${buffer}...[${sharedSecret.byteLength} bytes total]`;
}

// Generate 2 ECDH key pairs: one for Alice and one for Bob
// In more normal usage, they would generate their key pairs
// separately and exchange public keys securely
const generateAlicesKeyPair = window.crypto.subtle.generateKey(
  {
    name: "ECDH",
    namedCurve: "P-384"
  },
  false,
  ["deriveBits"]
);

const generateBobsKeyPair = window.crypto.subtle.generateKey(
  {
    name: "ECDH",
    namedCurve: "P-384"
  },
  false,
  ["deriveBits"]
);

Promise.all([generateAlicesKeyPair, generateBobsKeyPair]).then(values => {
  const alicesKeyPair = values[0];
  const bobsKeyPair = values[1];

  const deriveBitsButton = document.querySelector(".ecdh .derive-bits-button");
  deriveBitsButton.addEventListener("click", () => {
    // Alice then generates a secret using her private key and Bob's public key.
    // Bob could generate the same secret using his private key and Alice's public key.
    deriveSharedSecret(alicesKeyPair.privateKey, bobsKeyPair.publicKey);
  });
});

PBKDF2

In this example we ask the user for a password, then use it to derive some bits using PBKDF2. See the complete code on GitHub.

let salt;

/*
Get some key material to use as input to the deriveBits method.
The key material is a password supplied by the user.
*/
function getKeyMaterial() {
  const password = window.prompt("Enter your password");
  const enc = new TextEncoder();
  return window.crypto.subtle.importKey(
    "raw",
    enc.encode(password),
    {name: "PBKDF2"},
    false,
    ["deriveBits", "deriveKey"]
  );
}

/*
Derive some bits from a password supplied by the user.
*/
async function getDerivedBits() {
  const keyMaterial = await getKeyMaterial();
  salt = window.crypto.getRandomValues(new Uint8Array(16));
  const derivedBits = await window.crypto.subtle.deriveBits(
    {
      "name": "PBKDF2",
      salt: salt,
      "iterations": 100000,
      "hash": "SHA-256"
    },
    keyMaterial,
    256
  );

  const buffer = new Uint8Array(derivedBits, 0, 5);
  const derivedBitsValue = document.querySelector(".pbkdf2 .derived-bits-value");
  derivedBitsValue.classList.add("fade-in");
  derivedBitsValue.addEventListener("animationend", () => {
    derivedBitsValue.classList.remove("fade-in");
  });
  derivedBitsValue.textContent = `${buffer}...[${derivedBits.byteLength} bytes total]`;
}

const deriveBitsButton = document.querySelector(".pbkdf2 .derive-bits-button");
deriveBitsButton.addEventListener("click", () => {
  getDerivedBits();
});

Specifications

Specification Status Comment
Web Cryptography API
The definition of 'SubtleCrypto.deriveBits()' in that specification.
Recommendation Initial definition.

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
deriveBitsChrome Full support 37Edge Partial support 12
Notes
Partial support 12
Notes
Notes Not supported: ECDH.
Notes Not supported: HKDF, PBKDF2.
Firefox Full support 34
Full support 34
No support 32 — 34
Disabled
Disabled From version 32 until version 34 (exclusive): this feature is behind the dom.webcrypto.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support 24Safari Full support 7WebView Android Full support 37Chrome Android Full support 37Firefox Android Full support 34
Full support 34
No support 32 — 34
Disabled
Disabled From version 32 until version 34 (exclusive): this feature is behind the dom.webcrypto.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Full support 24Safari iOS Full support 7Samsung Internet Android Full support 6.0

Legend

Full support  
Full support
Partial support  
Partial support
No support  
No support
See implementation notes.
See implementation notes.
User must explicitly enable this feature.
User must explicitly enable this feature.

See also

Document Tags and Contributors

Contributors to this page: mdnwebdocs-bot, wbamberg, chrisdavidmills
Last updated by: mdnwebdocs-bot,