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.
import { hkdfSync } from 'node:crypto'; const key = hkdfSync('sha256', 'secret', 'salt', 'purpose', 32);
Try it
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.
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
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
infomeans different keys. Always use a distinct, descriptiveinfofor 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()orcrypto.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 withBuffer.from(result), or pass it tocrypto.createSecretKey()to get aKeyObject. - 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.