crypto.pbkdf2(password, salt, iterations, keylen, digest, callback)

版本历史

版本	变更
v18.0.0	将无效回调传给 `callback` 参数现在会抛出 `ERR_INVALID_ARG_TYPE` 而不是 `ERR_INVALID_CALLBACK`。
v15.0.0	密码和盐参数也可以是 ArrayBuffer 实例。
v14.0.0	参数 `iterations` 现在限制为正值。早期版本将其他值视为一。
v8.0.0	现在总是需要 `digest` 参数。
v6.0.0	现在不推荐在不传入 `digest` 参数的情况下调用此函数，并将触发警告。
v6.0.0	`password` 的默认编码，如果它是从 `binary` 更改为 `utf8` 的字符串。
v0.5.5	新增于: v0.5.5

password <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
salt <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
iterations <number>
keylen <number>
digest <string>
callback <Function>
- err <Error>
- derivedKey <Buffer>

提供异步基于密码的密钥派生函数 2 (PBKDF2) 实现。应用由 digest 指定的选定 HMAC 摘要算法以从 password、salt 和 iterations 导出请求字节长度 (keylen) 的密钥。

提供的 callback 函数使用两个参数调用：err 和 derivedKey。如果在派生密钥时发生错误，则设置 err；否则 err 将是 null。默认情况下，成功生成的 derivedKey 将作为 Buffer 传给回调。如果任何输入参数指定了无效的值或类型，则会抛出错误。

iterations 参数必须是尽可能高的数字。迭代次数越多，派生密钥就越安全，但需要更长的时间才能完成。

salt 应该尽可能唯一。建议盐是随机的，长度至少为 16 字节。有关详细信息，请参阅 NIST SP 800-132。

当为 password 或 salt 传入字符串时，请考虑到当使用字符串作为加密 API 输入时的注意事项。

const {
  pbkdf2,
} = await import('node:crypto');

pbkdf2('secret', 'salt', 100000, 64, 'sha512', (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...08d59ae'
});const {
  pbkdf2,
} = require('node:crypto');

pbkdf2('secret', 'salt', 100000, 64, 'sha512', (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...08d59ae'
});

crypto.DEFAULT_ENCODING 属性可用于更改 derivedKey 传给回调的方式。但是，此属性已被弃用，应避免使用。

import crypto from 'node:crypto';
crypto.DEFAULT_ENCODING = 'hex';
crypto.pbkdf2('secret', 'salt', 100000, 512, 'sha512', (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey);  // '3745e48...aa39b34'
});const crypto = require('node:crypto');
crypto.DEFAULT_ENCODING = 'hex';
crypto.pbkdf2('secret', 'salt', 100000, 512, 'sha512', (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey);  // '3745e48...aa39b34'
});

可以使用 crypto.getHashes() 检索支持的摘要函数数组。

此 API 使用 libuv 的线程池，这对某些应用程序可能会产生意外的负面性能影响；有关更多信息，请参阅 UV_THREADPOOL_SIZE 文档。

History

Version	Changes
v18.0.0	Passing an invalid callback to the `callback` argument now throws `ERR_INVALID_ARG_TYPE` instead of `ERR_INVALID_CALLBACK`.
v15.0.0	The password and salt arguments can also be ArrayBuffer instances.
v14.0.0	The `iterations` parameter is now restricted to positive values. Earlier releases treated other values as one.
v8.0.0	The `digest` parameter is always required now.
v6.0.0	Calling this function without passing the `digest` parameter is deprecated now and will emit a warning.
v6.0.0	The default encoding for `password` if it is a string changed from `binary` to `utf8`.
v0.5.5	Added in: v0.5.5

password <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
salt <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
iterations <number>
keylen <number>
digest <string>
callback <Function>
- err <Error>
- derivedKey <Buffer>

Provides an asynchronous Password-Based Key Derivation Function 2 (PBKDF2) implementation. A selected HMAC digest algorithm specified by digest is applied to derive a key of the requested byte length (keylen) from the password, salt and iterations.

The supplied callback function is called with two arguments: err and derivedKey. If an error occurs while deriving the key, err will be set; otherwise err will be null. By default, the successfully generated derivedKey will be passed to the callback as a Buffer. An error will be thrown if any of the input arguments specify invalid values or types.

The iterations argument must be a number set as high as possible. The higher the number of iterations, the more secure the derived key will be, but will take a longer amount of time to complete.

The salt should be as unique as possible. It is recommended that a salt is random and at least 16 bytes long. See NIST SP 800-132 for details.

When passing strings for password or salt, please consider caveats when using strings as inputs to cryptographic APIs.

const {
  pbkdf2,
} = await import('node:crypto');

pbkdf2('secret', 'salt', 100000, 64, 'sha512', (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...08d59ae'
});const {
  pbkdf2,
} = require('node:crypto');

pbkdf2('secret', 'salt', 100000, 64, 'sha512', (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...08d59ae'
});

The crypto.DEFAULT_ENCODING property can be used to change the way the derivedKey is passed to the callback. This property, however, has been deprecated and use should be avoided.

import crypto from 'node:crypto';
crypto.DEFAULT_ENCODING = 'hex';
crypto.pbkdf2('secret', 'salt', 100000, 512, 'sha512', (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey);  // '3745e48...aa39b34'
});const crypto = require('node:crypto');
crypto.DEFAULT_ENCODING = 'hex';
crypto.pbkdf2('secret', 'salt', 100000, 512, 'sha512', (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey);  // '3745e48...aa39b34'
});

An array of supported digest functions can be retrieved using crypto.getHashes().

This API uses libuv's threadpool, which can have surprising and negative performance implications for some applications; see the UV_THREADPOOL_SIZE documentation for more information.