Node.js Reference ยท crypto
Node.js crypto.pbkdf2() function
Reference for crypto.pbkdf2() and pbkdf2Sync() in Node.js: deriving keys from passwords with iterations, salts and digest choices, plus current iteration guidance.
crypto.pbkdf2(password, salt, iterations, keylen, digest, callback) implements PBKDF2 (password-based key derivation function 2). It applies an HMAC repeatedly, iterations times, to turn a password and a salt into keylen bytes of key material. crypto.pbkdf2Sync() is the blocking version.
PBKDF2 is widely supported and approved by many standards (FIPS, for example), so you meet it when interoperating with other systems. It is CPU-bound only, so it resists GPU attacks less well than scrypt; pick a high iteration count to compensate.
import { pbkdf2Sync } from 'node:crypto'; const key = pbkdf2Sync('password', 'salt', 100000, 32, 'sha256');
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.pbkdf2(password, salt, iterations, keylen, digest, callback): void crypto.pbkdf2Sync(password, salt, iterations, keylen, digest): Buffer
| Name | Description |
|---|---|
password |
String, Buffer, typed array or DataView. |
salt |
Same types. Should be random, at least 16 bytes. |
iterations |
Positive integer. More is slower for you and for an attacker. |
keylen |
Number of bytes to derive. |
digest |
HMAC hash name such as 'sha256' or 'sha512'. |
callback |
(err, derivedKey). |
Returns: pbkdf2Sync returns a Buffer; pbkdf2 returns undefined.
Errors: ERR_INVALID_ARG_TYPE or ERR_OUT_OF_RANGE for bad arguments, ERR_CRYPTO_INVALID_DIGEST when the digest name is unknown. The digest parameter has been required since Node.js 8.
Usage notes
- Iteration counts. OWASP currently recommends 600,000 iterations for PBKDF2-HMAC-SHA256 and 210,000 for SHA-512 when used for password storage. Measure on your hardware and aim for something noticeable but acceptable per login.
- Salt every password. A unique random salt defeats precomputed tables and makes identical passwords hash differently.
- Output length. Asking for more bytes than the digest produces makes the work for each extra block repeat, which helps the attacker more than you. Derive at most one digest length for password hashes.
- Prefer the asynchronous form on servers. The synchronous call blocks the event loop for the entire derivation.
- Store parameters. Keep the digest, iteration count and salt with each hash so you can upgrade later.
- Use
crypto.timingSafeEqual()to compare derived keys. - Not a replacement for HKDF. If your input is already a high-entropy secret (a shared key, for example), use
crypto.hkdf(); PBKDF2 would only waste time.