Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท crypto

Node.js crypto.hkdf() function

Reference for crypto.hkdf() and hkdfSync() in Node.js: deriving several independent keys from one secret with salt and info, output limits and ArrayBuffer results.

crypto.hkdf(digest, ikm, salt, info, keylen, callback) implements HKDF, the HMAC-based extract-and-expand key derivation function from RFC 5869. It takes input keying material that is already secret and random, and produces one or more strong keys from it. crypto.hkdfSync() is the blocking form.

Use HKDF to split one shared secret (the result of a key agreement, for example) into separate encryption and authentication keys, or to derive per-purpose subkeys. Do not use it for passwords: it is fast on purpose.

NODE
import { hkdfSync } from 'node:crypto';

const key = hkdfSync('sha256', 'secret', 'salt', 'purpose', 32);

Try it

Node.js Separate keys from one secret

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js The callback form and limits

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
crypto.hkdf(digest, ikm, salt, info, keylen, callback): void
crypto.hkdfSync(digest, ikm, salt, info, keylen): ArrayBuffer
Name Description
digest Hash name for the underlying HMAC, such as 'sha256'.
ikm Input keying material: string, Buffer, typed array, DataView or KeyObject. Must not be empty.
salt Non-secret random value. May be empty, but a random value of the digest's size is better.
info Context string that binds the key to its purpose. Up to 1024 bytes; may be empty.
keylen Bytes to produce, at most 255 times the digest output size.
callback (err, derivedKey) where derivedKey is an ArrayBuffer.

Returns: an ArrayBuffer (wrap it with Buffer.from() to read bytes). hkdf itself returns undefined.

Errors: ERR_CRYPTO_INVALID_DIGEST for an unknown digest, ERR_CRYPTO_INVALID_KEYLEN when keylen is too large, ERR_OUT_OF_RANGE when info is too long, ERR_INVALID_ARG_TYPE for wrong types.

Usage notes

  • Different info means different keys. Always use a distinct, descriptive info for each purpose ('encryption', 'authentication'), so a leaked key for one purpose does not weaken the others.
  • The input must already be high-entropy. HKDF does not slow guessing down. Passwords belong to crypto.scrypt() or crypto.pbkdf2().
  • Salt is optional but helpful. It need not be secret and may be reused for several derivations from the same input.
  • The result is an ArrayBuffer. Convert with Buffer.from(result), or pass it to crypto.createSecretKey() to get a KeyObject.
  • Deterministic. The same inputs always give the same output, so two parties who share a secret can derive matching keys independently.
  • Fast. HKDF is only a few HMAC calls; use the synchronous form freely.
  • Added in Node.js 15.0.0.