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 bits to derive. It returns a Promise which will be fulfilled with an ArrayBuffer containing the derived bits.

The base key is a CryptoKey created with SubtleCrypto.importKey() whose keyUsages include "deriveBits".

Syntax

deriveBits(algorithm, baseKey, length);

Parameters

• algorithm
  • : An object defining the derivation algorithm to use.
    • To use PBKDF2, pass a Pbkdf2Params object.
• baseKey
  • : A CryptoKey representing the input to the derivation algorithm. For PBKDF2 this is the password, imported with the "raw" format and the "PBKDF2" algorithm.
• length
  • : A number representing the number of bits to derive. It must be a multiple of 8.

Return value

A Promise that fulfills with an ArrayBuffer containing the derived bits.

Exceptions

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

• InvalidAccessError
  • : Raised when the base key is not a key for the requested derivation algorithm, or when its usages do not include "deriveBits".
• NotSupportedError
  • : Raised when trying to use an algorithm that is either unknown or isn't supported for deriving bits.
• OperationError
  • : Raised when length is null or not a multiple of 8, or when the iterations member of the algorithm is zero.

Supported algorithms

Only PBKDF2 is currently supported. HKDF, ECDH and X25519 are not yet supported and reject with a NotSupportedError.

PBKDF2

The PBKDF2 algorithm derives a key from a password using a pseudo-random function (HMAC with the configured digest), a salt and an iteration count, as specified in RFC 8018. A high iteration count makes brute-force attacks on the password more expensive.

Pbkdf2Params

The object passed as algorithm has the following properties:

• name
  • : A string. This should be set to PBKDF2.
• hash
  • : A string or an object with a single property name that is a string, naming the digest function to use. Supported values are:
    • "SHA-1" (but don't use this in cryptographic applications)
    • "SHA-256"
    • "SHA-384"
    • "SHA-512".
• salt
  • : An ArrayBuffer, a TypedArray or a DataView object containing the salt. This should be a random or pseudo-random value of at least 16 bytes.
• iterations
  • : A number representing the number of times the hash function will be executed. This must be greater than zero.

Examples

const password = new TextEncoder().encode('correct horse battery staple');
const salt = crypto.getRandomValues(new Uint8Array(16));

const baseKey = await crypto.subtle.importKey(
  'raw',
  password,
  'PBKDF2',
  false,
  ['deriveBits'],
);

const bits = await crypto.subtle.deriveBits(
  { name: 'PBKDF2', hash: 'SHA-256', salt, iterations: 100000 },
  baseKey,
  256,
);
// bits is a 32-byte ArrayBuffer