加密#

稳定性：2 - 稳定

源代码： lib/crypto.js

node:crypto 模块提供加密功能，包括 OpenSSL 的哈希、HMAC、密码、解密、签名和验证函数的一组包装器。

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

const secret = 'abcdefg';
const hash = createHmac('sha256', secret)
               .update('I love cupcakes')
               .digest('hex');
console.log(hash);
// Prints:
//   c0fa1bc00531bd78ef38c628449c5102aeabd49b5dc3a2a516ea6ea959d6658econst { createHmac } = require('node:crypto');

const secret = 'abcdefg';
const hash = createHmac('sha256', secret)
               .update('I love cupcakes')
               .digest('hex');
console.log(hash);
// Prints:
//   c0fa1bc00531bd78ef38c628449c5102aeabd49b5dc3a2a516ea6ea959d6658e

确定是否不可用加密支持#

Node.js 可以在不包含对 node:crypto 模块的支持的情况下构建。在这种情况下，尝试从 crypto 导入或调用 require('node:crypto') 将导致抛出错误。

当使用 CommonJS 时，可以使用 try/catch 捕获抛出的错误

let crypto;
try {
  crypto = require('node:crypto');
} catch (err) {
  console.error('crypto support is disabled!');
}

当使用词法 ESM import 关键字时，只有在尝试加载模块之前（例如，使用预加载模块）注册了 process.on('uncaughtException') 的处理程序，才能捕获错误。

当使用 ESM 时，如果代码可能在没有启用加密支持的 Node.js 版本上运行，请考虑使用 import() 函数而不是词法 import 关键字

let crypto;
try {
  crypto = await import('node:crypto');
} catch (err) {
  console.error('crypto support is disabled!');
}

类：Certificate#

添加于：v0.11.8

SPKAC 是一种证书签名请求机制，最初由 Netscape 实现，并作为 HTML5 的 keygen 元素的一部分正式指定。

<keygen> 自 HTML 5.2 起已弃用，新项目不再应使用此元素。

node:crypto 模块提供 Certificate 类用于处理 SPKAC 数据。最常见的用法是处理 HTML5 <keygen> 元素生成的输出。Node.js 在内部使用 OpenSSL 的 SPKAC 实现。

静态方法：Certificate.exportChallenge(spkac[, encoding])#

历史
版本更改
v15.0.0

spkac 参数可以是 ArrayBuffer。将 spkac 参数的大小限制为最大 2**31 - 1 字节。

v9.0.0

新增于：v9.0.0

const { Certificate } = await import('node:crypto');
const spkac = getSpkacSomehow();
const challenge = Certificate.exportChallenge(spkac);
console.log(challenge.toString('utf8'));
// Prints: the challenge as a UTF8 stringconst { Certificate } = require('node:crypto');
const spkac = getSpkacSomehow();
const challenge = Certificate.exportChallenge(spkac);
console.log(challenge.toString('utf8'));
// Prints: the challenge as a UTF8 string

静态方法：Certificate.exportPublicKey(spkac[, encoding])#

历史
版本更改
v15.0.0

spkac 参数可以是 ArrayBuffer。将 spkac 参数的大小限制为最大 2**31 - 1 字节。

v9.0.0

新增于：v9.0.0

const { Certificate } = await import('node:crypto');
const spkac = getSpkacSomehow();
const publicKey = Certificate.exportPublicKey(spkac);
console.log(publicKey);
// Prints: the public key as <Buffer ...>const { Certificate } = require('node:crypto');
const spkac = getSpkacSomehow();
const publicKey = Certificate.exportPublicKey(spkac);
console.log(publicKey);
// Prints: the public key as <Buffer ...>

静态方法：Certificate.verifySpkac(spkac[, encoding])#

历史
版本更改
v15.0.0

spkac 参数可以是 ArrayBuffer。添加了编码。将 spkac 参数的大小限制为最大 2**31 - 1 字节。

v9.0.0

新增于：v9.0.0

import { Buffer } from 'node:buffer';
const { Certificate } = await import('node:crypto');

const spkac = getSpkacSomehow();
console.log(Certificate.verifySpkac(Buffer.from(spkac)));
// Prints: true or falseconst { Buffer } = require('node:buffer');
const { Certificate } = require('node:crypto');

const spkac = getSpkacSomehow();
console.log(Certificate.verifySpkac(Buffer.from(spkac)));
// Prints: true or false

旧版 API#

稳定性：0 - 已弃用

作为旧版接口，可以创建 crypto.Certificate 类的新的实例，如下面的示例所示。

new crypto.Certificate()#

可以使用 new 关键字或通过将 crypto.Certificate() 作为函数调用来创建 Certificate 类的实例。

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

const cert1 = new Certificate();
const cert2 = Certificate();const { Certificate } = require('node:crypto');

const cert1 = new Certificate();
const cert2 = Certificate();
certificate.exportChallenge(spkac[, encoding])#
添加于：v0.11.8 
const { Certificate } = await import('node:crypto');
const cert = Certificate();
const spkac = getSpkacSomehow();
const challenge = cert.exportChallenge(spkac);
console.log(challenge.toString('utf8'));
// Prints: the challenge as a UTF8 stringconst { Certificate } = require('node:crypto');
const cert = Certificate();
const spkac = getSpkacSomehow();
const challenge = cert.exportChallenge(spkac);
console.log(challenge.toString('utf8'));
// Prints: the challenge as a UTF8 string
certificate.exportPublicKey(spkac[, encoding])#
添加于：v0.11.8 
const { Certificate } = await import('node:crypto');
const cert = Certificate();
const spkac = getSpkacSomehow();
const publicKey = cert.exportPublicKey(spkac);
console.log(publicKey);
// Prints: the public key as <Buffer ...>const { Certificate } = require('node:crypto');
const cert = Certificate();
const spkac = getSpkacSomehow();
const publicKey = cert.exportPublicKey(spkac);
console.log(publicKey);
// Prints: the public key as <Buffer ...>
certificate.verifySpkac(spkac[, encoding])#
添加于：v0.11.8 
import { Buffer } from 'node:buffer';
const { Certificate } = await import('node:crypto');

const cert = Certificate();
const spkac = getSpkacSomehow();
console.log(cert.verifySpkac(Buffer.from(spkac)));
// Prints: true or falseconst { Buffer } = require('node:buffer');
const { Certificate } = require('node:crypto');

const cert = Certificate();
const spkac = getSpkacSomehow();
console.log(cert.verifySpkac(Buffer.from(spkac)));
// Prints: true or false

类: Cipher#

添加于: v0.1.94

Cipher 类的实例用于加密数据。该类可以通过两种方式使用

  • 作为可读写 流，将明文数据写入流中，在可读端产生加密数据，或者
  • 使用 cipher.update() 和 cipher.final() 方法来生成加密数据。

使用 crypto.createCipher() 或 crypto.createCipheriv() 方法创建 Cipher 实例。不要直接使用 new 关键字创建 Cipher 对象。

示例: 使用 Cipher 对象作为流

const {
  scrypt,
  randomFill,
  createCipheriv,
} = await import('node:crypto');

const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';

// First, we'll generate the key. The key length is dependent on the algorithm.
// In this case for aes192, it is 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err;
  // Then, we'll generate a random initialization vector
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err;

    // Once we have the key and iv, we can create and use the cipher...
    const cipher = createCipheriv(algorithm, key, iv);

    let encrypted = '';
    cipher.setEncoding('hex');

    cipher.on('data', (chunk) => encrypted += chunk);
    cipher.on('end', () => console.log(encrypted));

    cipher.write('some clear text data');
    cipher.end();
  });
});const {
  scrypt,
  randomFill,
  createCipheriv,
} = require('node:crypto');

const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';

// First, we'll generate the key. The key length is dependent on the algorithm.
// In this case for aes192, it is 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err;
  // Then, we'll generate a random initialization vector
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err;

    // Once we have the key and iv, we can create and use the cipher...
    const cipher = createCipheriv(algorithm, key, iv);

    let encrypted = '';
    cipher.setEncoding('hex');

    cipher.on('data', (chunk) => encrypted += chunk);
    cipher.on('end', () => console.log(encrypted));

    cipher.write('some clear text data');
    cipher.end();
  });
});

示例: 使用 Cipher 和管道流

import {
  createReadStream,
  createWriteStream,
} from 'node:fs';

import {
  pipeline,
} from 'node:stream';

const {
  scrypt,
  randomFill,
  createCipheriv,
} = await import('node:crypto');

const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';

// First, we'll generate the key. The key length is dependent on the algorithm.
// In this case for aes192, it is 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err;
  // Then, we'll generate a random initialization vector
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err;

    const cipher = createCipheriv(algorithm, key, iv);

    const input = createReadStream('test.js');
    const output = createWriteStream('test.enc');

    pipeline(input, cipher, output, (err) => {
      if (err) throw err;
    });
  });
});const {
  createReadStream,
  createWriteStream,
} = require('node:fs');

const {
  pipeline,
} = require('node:stream');

const {
  scrypt,
  randomFill,
  createCipheriv,
} = require('node:crypto');

const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';

// First, we'll generate the key. The key length is dependent on the algorithm.
// In this case for aes192, it is 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err;
  // Then, we'll generate a random initialization vector
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err;

    const cipher = createCipheriv(algorithm, key, iv);

    const input = createReadStream('test.js');
    const output = createWriteStream('test.enc');

    pipeline(input, cipher, output, (err) => {
      if (err) throw err;
    });
  });
});

示例: 使用 cipher.update() 和 cipher.final() 方法

const {
  scrypt,
  randomFill,
  createCipheriv,
} = await import('node:crypto');

const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';

// First, we'll generate the key. The key length is dependent on the algorithm.
// In this case for aes192, it is 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err;
  // Then, we'll generate a random initialization vector
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err;

    const cipher = createCipheriv(algorithm, key, iv);

    let encrypted = cipher.update('some clear text data', 'utf8', 'hex');
    encrypted += cipher.final('hex');
    console.log(encrypted);
  });
});const {
  scrypt,
  randomFill,
  createCipheriv,
} = require('node:crypto');

const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';

// First, we'll generate the key. The key length is dependent on the algorithm.
// In this case for aes192, it is 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err;
  // Then, we'll generate a random initialization vector
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err;

    const cipher = createCipheriv(algorithm, key, iv);

    let encrypted = cipher.update('some clear text data', 'utf8', 'hex');
    encrypted += cipher.final('hex');
    console.log(encrypted);
  });
});

cipher.final([outputEncoding])#

添加于: v0.1.94
  • outputEncoding <string> 返回值的 编码。
  • 返回值: <Buffer> | <string> 任何剩余的加密内容。如果指定了 outputEncoding，则返回字符串。如果没有提供 outputEncoding，则返回 Buffer。

一旦调用了 cipher.final() 方法，Cipher 对象就不能再用于加密数据。尝试多次调用 cipher.final() 将导致抛出错误。

cipher.getAuthTag()#

添加于: v1.0.0
  • 返回值: <Buffer> 当使用经过身份验证的加密模式（目前支持 GCM、CCM、OCB 和 chacha20-poly1305）时，cipher.getAuthTag() 方法返回一个包含从给定数据计算出的身份验证标签的 Buffer。

cipher.getAuthTag() 方法只能在使用 cipher.final() 方法完成加密后调用。

如果在创建 cipher 实例时设置了 authTagLength 选项，则此函数将返回正好 authTagLength 字节。

cipher.setAAD(buffer[, options])#

添加于: v1.0.0

当使用经过身份验证的加密模式（目前支持 GCM、CCM、OCB 和 chacha20-poly1305）时，cipher.setAAD() 方法设置用于附加身份验证数据 (AAD) 输入参数的值。

plaintextLength 选项对于 GCM 和 OCB 是可选的。当使用 CCM 时，必须指定 plaintextLength 选项，并且其值必须与明文的字节长度匹配。请参阅 CCM 模式。

cipher.setAAD() 方法必须在 cipher.update() 之前调用。

cipher.setAutoPadding([autoPadding])#

添加于: v0.7.1
  • autoPadding <boolean> 默认值: true
  • 返回值: <Cipher> 用于方法链的相同 Cipher 实例。

当使用块加密算法时，Cipher 类会自动将填充添加到输入数据，使其达到适当的块大小。要禁用默认填充，请调用 cipher.setAutoPadding(false)。

当 autoPadding 为 false 时，整个输入数据的长度必须是密码块大小的倍数，否则 cipher.final() 将抛出错误。禁用自动填充对于非标准填充很有用，例如使用 0x0 而不是 PKCS 填充。

cipher.setAutoPadding() 方法必须在 cipher.final() 之前调用。

cipher.update(data[, inputEncoding][, outputEncoding])#

历史
版本更改
v6.0.0

默认的 inputEncoding 从 binary 更改为 utf8。

v0.1.94

添加于: v0.1.94

使用data更新密码。如果提供了inputEncoding参数，则data参数是使用指定编码的字符串。如果未提供inputEncoding参数，则data必须是Buffer、TypedArray或DataView。如果data是Buffer、TypedArray或DataView，则忽略inputEncoding。

outputEncoding指定加密数据的输出格式。如果指定了outputEncoding，则返回使用指定编码的字符串。如果没有提供outputEncoding，则返回Buffer。

可以多次使用新数据调用cipher.update()方法，直到调用cipher.final()。在调用cipher.final()之后调用cipher.update()将导致抛出错误。

类：Decipher#

添加于: v0.1.94

Decipher类的实例用于解密数据。该类可以用两种方式之一使用

  • 作为流，它既可读又可写，其中将明文加密数据写入以在可读端生成未加密数据，或者
  • 使用decipher.update()和decipher.final()方法来生成未加密数据。

crypto.createDecipher()或crypto.createDecipheriv()方法用于创建Decipher实例。不要使用new关键字直接创建Decipher对象。

示例：将Decipher对象用作流

import { Buffer } from 'node:buffer';
const {
  scryptSync,
  createDecipheriv,
} = await import('node:crypto');

const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';
// Key length is dependent on the algorithm. In this case for aes192, it is
// 24 bytes (192 bits).
// Use the async `crypto.scrypt()` instead.
const key = scryptSync(password, 'salt', 24);
// The IV is usually passed along with the ciphertext.
const iv = Buffer.alloc(16, 0); // Initialization vector.

const decipher = createDecipheriv(algorithm, key, iv);

let decrypted = '';
decipher.on('readable', () => {
  let chunk;
  while (null !== (chunk = decipher.read())) {
    decrypted += chunk.toString('utf8');
  }
});
decipher.on('end', () => {
  console.log(decrypted);
  // Prints: some clear text data
});

// Encrypted with same algorithm, key and iv.
const encrypted =
  'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa';
decipher.write(encrypted, 'hex');
decipher.end();const {
  scryptSync,
  createDecipheriv,
} = require('node:crypto');
const { Buffer } = require('node:buffer');

const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';
// Key length is dependent on the algorithm. In this case for aes192, it is
// 24 bytes (192 bits).
// Use the async `crypto.scrypt()` instead.
const key = scryptSync(password, 'salt', 24);
// The IV is usually passed along with the ciphertext.
const iv = Buffer.alloc(16, 0); // Initialization vector.

const decipher = createDecipheriv(algorithm, key, iv);

let decrypted = '';
decipher.on('readable', () => {
  let chunk;
  while (null !== (chunk = decipher.read())) {
    decrypted += chunk.toString('utf8');
  }
});
decipher.on('end', () => {
  console.log(decrypted);
  // Prints: some clear text data
});

// Encrypted with same algorithm, key and iv.
const encrypted =
  'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa';
decipher.write(encrypted, 'hex');
decipher.end();

示例：使用Decipher和管道流

import {
  createReadStream,
  createWriteStream,
} from 'node:fs';
import { Buffer } from 'node:buffer';
const {
  scryptSync,
  createDecipheriv,
} = await import('node:crypto');

const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';
// Use the async `crypto.scrypt()` instead.
const key = scryptSync(password, 'salt', 24);
// The IV is usually passed along with the ciphertext.
const iv = Buffer.alloc(16, 0); // Initialization vector.

const decipher = createDecipheriv(algorithm, key, iv);

const input = createReadStream('test.enc');
const output = createWriteStream('test.js');

input.pipe(decipher).pipe(output);const {
  createReadStream,
  createWriteStream,
} = require('node:fs');
const {
  scryptSync,
  createDecipheriv,
} = require('node:crypto');
const { Buffer } = require('node:buffer');

const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';
// Use the async `crypto.scrypt()` instead.
const key = scryptSync(password, 'salt', 24);
// The IV is usually passed along with the ciphertext.
const iv = Buffer.alloc(16, 0); // Initialization vector.

const decipher = createDecipheriv(algorithm, key, iv);

const input = createReadStream('test.enc');
const output = createWriteStream('test.js');

input.pipe(decipher).pipe(output);

示例：使用decipher.update()和decipher.final()方法

import { Buffer } from 'node:buffer';
const {
  scryptSync,
  createDecipheriv,
} = await import('node:crypto');

const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';
// Use the async `crypto.scrypt()` instead.
const key = scryptSync(password, 'salt', 24);
// The IV is usually passed along with the ciphertext.
const iv = Buffer.alloc(16, 0); // Initialization vector.

const decipher = createDecipheriv(algorithm, key, iv);

// Encrypted using same algorithm, key and iv.
const encrypted =
  'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa';
let decrypted = decipher.update(encrypted, 'hex', 'utf8');
decrypted += decipher.final('utf8');
console.log(decrypted);
// Prints: some clear text dataconst {
  scryptSync,
  createDecipheriv,
} = require('node:crypto');
const { Buffer } = require('node:buffer');

const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';
// Use the async `crypto.scrypt()` instead.
const key = scryptSync(password, 'salt', 24);
// The IV is usually passed along with the ciphertext.
const iv = Buffer.alloc(16, 0); // Initialization vector.

const decipher = createDecipheriv(algorithm, key, iv);

// Encrypted using same algorithm, key and iv.
const encrypted =
  'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa';
let decrypted = decipher.update(encrypted, 'hex', 'utf8');
decrypted += decipher.final('utf8');
console.log(decrypted);
// Prints: some clear text data

decipher.final([outputEncoding])#

添加于: v0.1.94
  • outputEncoding <string> 返回值的 编码。
  • 返回值：<Buffer> | <string> 任何剩余的解密内容。如果指定了outputEncoding，则返回字符串。如果没有提供outputEncoding，则返回Buffer。

调用decipher.final()方法后，Decipher对象将无法再用于解密数据。尝试多次调用decipher.final()将导致抛出错误。

decipher.setAAD(buffer[, options])#

历史
版本更改
v15.0.0

buffer 参数可以是字符串或 ArrayBuffer，大小限制为不超过 2 ** 31 - 1 字节。

v7.2.0

此方法现在返回对 decipher 的引用。

v1.0.0

添加于: v1.0.0

当使用经过身份验证的加密模式（目前支持 GCM、CCM、OCB 和 chacha20-poly1305）时，decipher.setAAD() 方法设置用于附加身份验证数据 (AAD) 输入参数的值。

对于 GCM，options 参数是可选的。当使用 CCM 时，必须指定 plaintextLength 选项，其值必须与密文的字节长度匹配。请参阅 CCM 模式。

必须在 decipher.update() 之前调用 decipher.setAAD() 方法。

当将字符串作为 buffer 传递时，请考虑 将字符串用作加密 API 输入时的注意事项。

decipher.setAuthTag(buffer[, encoding])#

历史
版本更改
v15.0.0

buffer 参数可以是字符串或 ArrayBuffer，大小限制为不超过 2 ** 31 - 1 字节。

v11.0.0

如果 GCM 标签长度无效，此方法现在会抛出异常。

v7.2.0

此方法现在返回对 decipher 的引用。

v1.0.0

添加于: v1.0.0

当使用经过身份验证的加密模式（目前支持 GCM、CCM、OCB 和 chacha20-poly1305）时，decipher.setAuthTag() 方法用于传入接收到的身份验证标签。如果没有提供标签，或者密文已被篡改，decipher.final() 将抛出异常，表明由于身份验证失败，密文应被丢弃。如果标签长度根据 NIST SP 800-38D 无效，或者与 authTagLength 选项的值不匹配，decipher.setAuthTag() 将抛出错误。

对于 CCM 模式，必须在 decipher.update() 之前调用 decipher.setAuthTag() 方法；对于 GCM 和 OCB 模式以及 chacha20-poly1305，必须在 decipher.final() 之前调用。decipher.setAuthTag() 只能调用一次。

当将字符串作为身份验证标签传递时，请考虑 将字符串用作加密 API 输入时的注意事项。

decipher.setAutoPadding([autoPadding])#

添加于: v0.7.1
  • autoPadding <boolean> 默认值: true
  • 返回值: <Decipher> 用于方法链的相同 Decipher。

当数据在没有使用标准块填充的情况下进行加密时，调用 decipher.setAutoPadding(false) 将禁用自动填充，以防止 decipher.final() 检查和删除填充。

关闭自动填充仅在输入数据的长度是密码块大小的倍数时才有效。

必须在调用 decipher.final() 之前调用 decipher.setAutoPadding() 方法。

decipher.update(data[, inputEncoding][, outputEncoding])#

历史
版本更改
v6.0.0

默认的 inputEncoding 从 binary 更改为 utf8。

v0.1.94

添加于: v0.1.94

使用 data 更新解密器。如果提供了 inputEncoding 参数，则 data 参数是使用指定编码的字符串。如果未提供 inputEncoding 参数，则 data 必须是 Buffer。如果 data 是 Buffer，则忽略 inputEncoding。

outputEncoding指定加密数据的输出格式。如果指定了outputEncoding，则返回使用指定编码的字符串。如果没有提供outputEncoding，则返回Buffer。

decipher.update() 方法可以多次调用新数据，直到调用 decipher.final()。在调用 decipher.final() 之后调用 decipher.update() 将导致抛出错误。

类：DiffieHellman#

添加于：v0.5.0

DiffieHellman 类是一个用于创建 Diffie-Hellman 密钥交换的实用程序。

可以使用 crypto.createDiffieHellman() 函数创建 DiffieHellman 类的实例。

import assert from 'node:assert';

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

// Generate Alice's keys...
const alice = createDiffieHellman(2048);
const aliceKey = alice.generateKeys();

// Generate Bob's keys...
const bob = createDiffieHellman(alice.getPrime(), alice.getGenerator());
const bobKey = bob.generateKeys();

// Exchange and generate the secret...
const aliceSecret = alice.computeSecret(bobKey);
const bobSecret = bob.computeSecret(aliceKey);

// OK
assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex'));const assert = require('node:assert');

const {
  createDiffieHellman,
} = require('node:crypto');

// Generate Alice's keys...
const alice = createDiffieHellman(2048);
const aliceKey = alice.generateKeys();

// Generate Bob's keys...
const bob = createDiffieHellman(alice.getPrime(), alice.getGenerator());
const bobKey = bob.generateKeys();

// Exchange and generate the secret...
const aliceSecret = alice.computeSecret(bobKey);
const bobSecret = bob.computeSecret(aliceKey);

// OK
assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex'));

diffieHellman.computeSecret(otherPublicKey[, inputEncoding][, outputEncoding])#

添加于：v0.5.0

使用 otherPublicKey 作为另一方的公钥计算共享密钥，并返回计算出的共享密钥。提供的密钥使用指定的 inputEncoding 解释，密钥使用指定的 outputEncoding 编码。如果未提供 inputEncoding，则 otherPublicKey 预计是 Buffer、TypedArray 或 DataView。

如果提供了 outputEncoding，则返回字符串；否则，返回 Buffer。

diffieHellman.generateKeys([encoding])#

添加于：v0.5.0

生成私钥和公钥 Diffie-Hellman 密钥值，除非它们已经生成或计算，并以指定的 encoding 返回公钥。此密钥应传输给另一方。如果提供了 encoding，则返回字符串；否则返回 Buffer。

此函数是 DH_generate_key() 的一个薄包装器。特别是，一旦生成了或设置了私钥，调用此函数只会更新公钥，而不会生成新的私钥。

diffieHellman.getGenerator([encoding])#

添加于：v0.5.0

以指定的 encoding 返回 Diffie-Hellman 生成器。如果提供了 encoding，则返回字符串；否则返回 Buffer。

diffieHellman.getPrime([encoding])#

添加于：v0.5.0

以指定的 encoding 返回 Diffie-Hellman 素数。如果提供了 encoding，则返回字符串；否则返回 Buffer。

diffieHellman.getPrivateKey([encoding])#

添加于：v0.5.0

以指定的 encoding 返回 Diffie-Hellman 私钥。如果提供了 encoding，则返回字符串；否则返回 Buffer。

diffieHellman.getPublicKey([encoding])#

添加于：v0.5.0

以指定的 encoding 返回 Diffie-Hellman 公钥。如果提供了 encoding，则返回字符串；否则返回 Buffer。

diffieHellman.setPrivateKey(privateKey[, encoding])#

添加于：v0.5.0

设置 Diffie-Hellman 私钥。如果提供了 encoding 参数，则 privateKey 预计为字符串。如果没有提供 encoding，则 privateKey 预计为 Buffer、TypedArray 或 DataView。

此函数不会自动计算关联的公钥。可以使用 diffieHellman.setPublicKey() 或 diffieHellman.generateKeys() 手动提供公钥或自动推导出公钥。

diffieHellman.setPublicKey(publicKey[, encoding])#

添加于：v0.5.0

设置 Diffie-Hellman 公钥。如果提供了 encoding 参数，则 publicKey 预计为字符串。如果没有提供 encoding，则 publicKey 预计为 Buffer、TypedArray 或 DataView。

diffieHellman.verifyError#

添加于：v0.11.12

一个位域，包含在DiffieHellman对象初始化期间执行的检查过程中产生的任何警告和/或错误。

此属性的有效值如下（如node:constants模块中定义）：

  • DH_CHECK_P_NOT_SAFE_PRIME
  • DH_CHECK_P_NOT_PRIME
  • DH_UNABLE_TO_CHECK_GENERATOR
  • DH_NOT_SUITABLE_GENERATOR

类：DiffieHellmanGroup#

添加于：v0.7.5

DiffieHellmanGroup类以一个众所周知的 modp 组作为参数。它的工作方式与DiffieHellman相同，只是它不允许在创建后更改其密钥。换句话说，它不实现setPublicKey()或setPrivateKey()方法。

const { createDiffieHellmanGroup } = await import('node:crypto');
const dh = createDiffieHellmanGroup('modp16');const { createDiffieHellmanGroup } = require('node:crypto');
const dh = createDiffieHellmanGroup('modp16');

支持以下组：

  • 'modp14'（2048 位，RFC 3526 第 3 节）
  • 'modp15'（3072 位，RFC 3526 第 4 节）
  • 'modp16'（4096 位，RFC 3526 第 5 节）
  • 'modp17'（6144 位，RFC 3526 第 6 节）
  • 'modp18'（8192 位，RFC 3526 第 7 节）

以下组仍然受支持，但已弃用（请参阅注意事项）：

  • 'modp1'（768 位，RFC 2409 第 6.1 节）
  • 'modp2'（1024 位，RFC 2409 第 6.2 节）
  • 'modp5'（1536 位，RFC 3526 第 2 节）

这些已弃用的组可能会在 Node.js 的未来版本中删除。

类：ECDH#

添加于：v0.11.14

ECDH类是用于创建椭圆曲线 Diffie-Hellman (ECDH) 密钥交换的实用程序。

可以使用crypto.createECDH()函数创建ECDH类的实例。

import assert from 'node:assert';

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

// Generate Alice's keys...
const alice = createECDH('secp521r1');
const aliceKey = alice.generateKeys();

// Generate Bob's keys...
const bob = createECDH('secp521r1');
const bobKey = bob.generateKeys();

// Exchange and generate the secret...
const aliceSecret = alice.computeSecret(bobKey);
const bobSecret = bob.computeSecret(aliceKey);

assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex'));
// OKconst assert = require('node:assert');

const {
  createECDH,
} = require('node:crypto');

// Generate Alice's keys...
const alice = createECDH('secp521r1');
const aliceKey = alice.generateKeys();

// Generate Bob's keys...
const bob = createECDH('secp521r1');
const bobKey = bob.generateKeys();

// Exchange and generate the secret...
const aliceSecret = alice.computeSecret(bobKey);
const bobSecret = bob.computeSecret(aliceKey);

assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex'));
// OK

静态方法：ECDH.convertKey(key, curve[, inputEncoding[, outputEncoding[, format]]])#

添加于：v10.0.0

将由 key 和 curve 指定的 EC Diffie-Hellman 公钥转换为 format 指定的格式。format 参数指定点编码，可以是 'compressed'、'uncompressed' 或 'hybrid'。提供的密钥使用指定的 inputEncoding 解释，返回的密钥使用指定的 outputEncoding 编码。

使用 crypto.getCurves() 获取可用曲线名称列表。在最近的 OpenSSL 版本中，openssl ecparam -list_curves 也会显示每个可用椭圆曲线的名称和描述。

如果未指定 format，则点将以 'uncompressed' 格式返回。

如果未提供 inputEncoding，则 key 预计是 Buffer、TypedArray 或 DataView。

示例（解压缩密钥）

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

const ecdh = createECDH('secp256k1');
ecdh.generateKeys();

const compressedKey = ecdh.getPublicKey('hex', 'compressed');

const uncompressedKey = ECDH.convertKey(compressedKey,
                                        'secp256k1',
                                        'hex',
                                        'hex',
                                        'uncompressed');

// The converted key and the uncompressed public key should be the same
console.log(uncompressedKey === ecdh.getPublicKey('hex'));const {
  createECDH,
  ECDH,
} = require('node:crypto');

const ecdh = createECDH('secp256k1');
ecdh.generateKeys();

const compressedKey = ecdh.getPublicKey('hex', 'compressed');

const uncompressedKey = ECDH.convertKey(compressedKey,
                                        'secp256k1',
                                        'hex',
                                        'hex',
                                        'uncompressed');

// The converted key and the uncompressed public key should be the same
console.log(uncompressedKey === ecdh.getPublicKey('hex'));

ecdh.computeSecret(otherPublicKey[, inputEncoding][, outputEncoding])#

历史
版本更改
v10.0.0

将错误格式更改为更好地支持无效公钥错误。

v6.0.0

默认的 inputEncoding 从 binary 更改为 utf8。

v0.11.14

添加于：v0.11.14

使用 otherPublicKey 作为对方公钥计算共享密钥，并返回计算出的共享密钥。提供的密钥使用指定的 inputEncoding 解释，返回的密钥使用指定的 outputEncoding 编码。如果未提供 inputEncoding，则 otherPublicKey 预计是 Buffer、TypedArray 或 DataView。

如果提供 outputEncoding，则将返回字符串；否则将返回 Buffer。

当 otherPublicKey 位于椭圆曲线之外时，ecdh.computeSecret 将抛出 ERR_CRYPTO_ECDH_INVALID_PUBLIC_KEY 错误。由于 otherPublicKey 通常是从远程用户通过不安全的网络提供的，因此请确保相应地处理此异常。

ecdh.generateKeys([encoding[, format]])#

添加于：v0.11.14

生成私钥和公钥 EC Diffie-Hellman 密钥值，并以指定的 format 和 encoding 格式返回公钥。此密钥应传输给另一方。

format 参数指定点编码，可以是 'compressed' 或 'uncompressed'。如果未指定 format，则点将以 'uncompressed' 格式返回。

如果提供了 encoding，则返回字符串；否则返回 Buffer。

ecdh.getPrivateKey([encoding])#

添加于：v0.11.14

如果指定了 encoding，则返回字符串；否则返回 Buffer。

ecdh.getPublicKey([encoding][, format])#

添加于：v0.11.14

format 参数指定点编码，可以是 'compressed' 或 'uncompressed'。如果未指定 format，则点将以 'uncompressed' 格式返回。

如果指定了 encoding，则返回字符串；否则返回 Buffer。

ecdh.setPrivateKey(privateKey[, encoding])#

添加于：v0.11.14

设置 EC Diffie-Hellman 私钥。如果提供了 encoding，则 privateKey 预计为字符串；否则 privateKey 预计为 Buffer、TypedArray 或 DataView。

如果 privateKey 对创建 ECDH 对象时指定的曲线无效，则会抛出错误。设置私钥后，关联的公钥（密钥）也会生成并设置在 ECDH 对象中。

ecdh.setPublicKey(publicKey[, encoding])#

添加于：v0.11.14自 v5.2.0 起已弃用

稳定性：0 - 已弃用

设置 EC Diffie-Hellman 公钥。如果提供了 encoding，则 publicKey 预计为字符串；否则预计为 Buffer、TypedArray 或 DataView。

通常没有理由调用此方法，因为ECDH只需要私钥和对方的公钥来计算共享密钥。通常，要么调用ecdh.generateKeys()，要么调用ecdh.setPrivateKey()。 ecdh.setPrivateKey()方法尝试生成与设置的私钥关联的公钥/点。

示例（获取共享密钥）

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

const alice = createECDH('secp256k1');
const bob = createECDH('secp256k1');

// This is a shortcut way of specifying one of Alice's previous private
// keys. It would be unwise to use such a predictable private key in a real
// application.
alice.setPrivateKey(
  createHash('sha256').update('alice', 'utf8').digest(),
);

// Bob uses a newly generated cryptographically strong
// pseudorandom key pair
bob.generateKeys();

const aliceSecret = alice.computeSecret(bob.getPublicKey(), null, 'hex');
const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex');

// aliceSecret and bobSecret should be the same shared secret value
console.log(aliceSecret === bobSecret);const {
  createECDH,
  createHash,
} = require('node:crypto');

const alice = createECDH('secp256k1');
const bob = createECDH('secp256k1');

// This is a shortcut way of specifying one of Alice's previous private
// keys. It would be unwise to use such a predictable private key in a real
// application.
alice.setPrivateKey(
  createHash('sha256').update('alice', 'utf8').digest(),
);

// Bob uses a newly generated cryptographically strong
// pseudorandom key pair
bob.generateKeys();

const aliceSecret = alice.computeSecret(bob.getPublicKey(), null, 'hex');
const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex');

// aliceSecret and bobSecret should be the same shared secret value
console.log(aliceSecret === bobSecret);

类：Hash#

添加于：v0.1.92

Hash类是一个用于创建数据哈希摘要的实用程序。它可以通过两种方式使用

  • 作为可读可写的流，将数据写入流以在可读端生成计算出的哈希摘要，或者
  • 使用hash.update()和hash.digest()方法来生成计算出的哈希值。

crypto.createHash()方法用于创建Hash实例。Hash对象不能直接使用new关键字创建。

示例：将Hash对象用作流

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

const hash = createHash('sha256');

hash.on('readable', () => {
  // Only one element is going to be produced by the
  // hash stream.
  const data = hash.read();
  if (data) {
    console.log(data.toString('hex'));
    // Prints:
    //   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50
  }
});

hash.write('some data to hash');
hash.end();const {
  createHash,
} = require('node:crypto');

const hash = createHash('sha256');

hash.on('readable', () => {
  // Only one element is going to be produced by the
  // hash stream.
  const data = hash.read();
  if (data) {
    console.log(data.toString('hex'));
    // Prints:
    //   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50
  }
});

hash.write('some data to hash');
hash.end();

示例：使用Hash和管道流

import { createReadStream } from 'node:fs';
import { stdout } from 'node:process';
const { createHash } = await import('node:crypto');

const hash = createHash('sha256');

const input = createReadStream('test.js');
input.pipe(hash).setEncoding('hex').pipe(stdout);const { createReadStream } = require('node:fs');
const { createHash } = require('node:crypto');
const { stdout } = require('node:process');

const hash = createHash('sha256');

const input = createReadStream('test.js');
input.pipe(hash).setEncoding('hex').pipe(stdout);

示例：使用hash.update()和hash.digest()方法

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

const hash = createHash('sha256');

hash.update('some data to hash');
console.log(hash.digest('hex'));
// Prints:
//   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50const {
  createHash,
} = require('node:crypto');

const hash = createHash('sha256');

hash.update('some data to hash');
console.log(hash.digest('hex'));
// Prints:
//   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50

hash.copy([options])#

添加于：v13.1.0

创建一个新的Hash对象，其中包含当前Hash对象的内部状态的深层副本。

可选的options参数控制流行为。对于像'shake256'这样的XOF哈希函数，outputLength选项可用于指定所需的输出长度（以字节为单位）。

当尝试在调用Hash对象的hash.digest()方法后复制Hash对象时，会抛出错误。

// Calculate a rolling hash.
const {
  createHash,
} = await import('node:crypto');

const hash = createHash('sha256');

hash.update('one');
console.log(hash.copy().digest('hex'));

hash.update('two');
console.log(hash.copy().digest('hex'));

hash.update('three');
console.log(hash.copy().digest('hex'));

// Etc.// Calculate a rolling hash.
const {
  createHash,
} = require('node:crypto');

const hash = createHash('sha256');

hash.update('one');
console.log(hash.copy().digest('hex'));

hash.update('two');
console.log(hash.copy().digest('hex'));

hash.update('three');
console.log(hash.copy().digest('hex'));

// Etc.

hash.digest([encoding])#

添加于：v0.1.92

计算传递到哈希函数的所有数据的摘要（使用hash.update()方法）。如果提供了encoding，则将返回字符串；否则将返回Buffer。

在调用hash.digest()方法后，Hash对象将无法再次使用。多次调用会导致抛出错误。

hash.update(data[, inputEncoding])#

历史
版本更改
v6.0.0

默认的 inputEncoding 从 binary 更改为 utf8。

v0.1.92

添加于：v0.1.92

使用给定的 data 更新哈希内容，其编码在 inputEncoding 中给出。如果未提供 encoding，并且 data 是字符串，则强制使用 'utf8' 编码。如果 data 是 Buffer、TypedArray 或 DataView，则忽略 inputEncoding。

可以多次调用此方法，并在数据流式传输时提供新数据。

类：Hmac#

添加于: v0.1.94

Hmac 类是用于创建加密 HMAC 摘要的实用程序。它可以通过两种方式之一使用

  • 作为可读和可写的 流，其中数据被写入以在可读端生成计算出的 HMAC 摘要，或者
  • 使用 hmac.update() 和 hmac.digest() 方法来生成计算出的 HMAC 摘要。

crypto.createHmac() 方法用于创建 Hmac 实例。Hmac 对象不能直接使用 new 关键字创建。

示例：使用 Hmac 对象作为流

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

const hmac = createHmac('sha256', 'a secret');

hmac.on('readable', () => {
  // Only one element is going to be produced by the
  // hash stream.
  const data = hmac.read();
  if (data) {
    console.log(data.toString('hex'));
    // Prints:
    //   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
  }
});

hmac.write('some data to hash');
hmac.end();const {
  createHmac,
} = require('node:crypto');

const hmac = createHmac('sha256', 'a secret');

hmac.on('readable', () => {
  // Only one element is going to be produced by the
  // hash stream.
  const data = hmac.read();
  if (data) {
    console.log(data.toString('hex'));
    // Prints:
    //   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
  }
});

hmac.write('some data to hash');
hmac.end();

示例：使用 Hmac 和管道流

import { createReadStream } from 'node:fs';
import { stdout } from 'node:process';
const {
  createHmac,
} = await import('node:crypto');

const hmac = createHmac('sha256', 'a secret');

const input = createReadStream('test.js');
input.pipe(hmac).pipe(stdout);const {
  createReadStream,
} = require('node:fs');
const {
  createHmac,
} = require('node:crypto');
const { stdout } = require('node:process');

const hmac = createHmac('sha256', 'a secret');

const input = createReadStream('test.js');
input.pipe(hmac).pipe(stdout);

示例：使用 hmac.update() 和 hmac.digest() 方法

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

const hmac = createHmac('sha256', 'a secret');

hmac.update('some data to hash');
console.log(hmac.digest('hex'));
// Prints:
//   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77econst {
  createHmac,
} = require('node:crypto');

const hmac = createHmac('sha256', 'a secret');

hmac.update('some data to hash');
console.log(hmac.digest('hex'));
// Prints:
//   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e

hmac.digest([encoding])#

添加于: v0.1.94

计算使用 hmac.update() 传递的所有数据的 HMAC 摘要。如果提供了 encoding，则返回字符串；否则返回 Buffer；

在调用 hmac.digest() 后，Hmac 对象将无法再次使用。多次调用 hmac.digest() 将导致抛出错误。

hmac.update(data[, inputEncoding])#

历史
版本更改
v6.0.0

默认的 inputEncoding 从 binary 更改为 utf8。

v0.1.94

添加于: v0.1.94

使用给定的 data 更新 Hmac 内容，其编码在 inputEncoding 中给出。如果未提供 encoding，并且 data 是字符串，则强制使用 'utf8' 编码。如果 data 是 Buffer、TypedArray 或 DataView，则忽略 inputEncoding。

可以多次调用此方法，并在数据流式传输时提供新数据。

类：KeyObject#

历史
版本更改
v14.5.0、v12.19.0

现在可以使用 postMessage 将此类的实例传递给工作线程。

v11.13.0

此类现在已导出。

v11.6.0

添加于：v11.6.0

Node.js 使用 KeyObject 类来表示对称或非对称密钥，并且每种密钥都公开不同的函数。 crypto.createSecretKey()、crypto.createPublicKey() 和 crypto.createPrivateKey() 方法用于创建 KeyObject 实例。不要使用 new 关键字直接创建 KeyObject 对象。

大多数应用程序应考虑使用新的 KeyObject API，而不是将密钥作为字符串或 Buffer 传递，因为新的 API 具有改进的安全功能。

可以使用 postMessage() 将 KeyObject 实例传递给其他线程。接收方将获得一个克隆的 KeyObject，并且 KeyObject 不需要列在 transferList 参数中。

静态方法：KeyObject.from(key)#

添加于：v15.0.0

示例：将 CryptoKey 实例转换为 KeyObject

const { KeyObject } = await import('node:crypto');
const { subtle } = globalThis.crypto;

const key = await subtle.generateKey({
  name: 'HMAC',
  hash: 'SHA-256',
  length: 256,
}, true, ['sign', 'verify']);

const keyObject = KeyObject.from(key);
console.log(keyObject.symmetricKeySize);
// Prints: 32 (symmetric key size in bytes)const { KeyObject } = require('node:crypto');
const { subtle } = globalThis.crypto;

(async function() {
  const key = await subtle.generateKey({
    name: 'HMAC',
    hash: 'SHA-256',
    length: 256,
  }, true, ['sign', 'verify']);

  const keyObject = KeyObject.from(key);
  console.log(keyObject.symmetricKeySize);
  // Prints: 32 (symmetric key size in bytes)
})();

keyObject.asymmetricKeyDetails#

历史
版本更改
v16.9.0

公开 RSA-PSS 密钥的 RSASSA-PSS-params 序列参数。

v15.7.0

添加于：v15.7.0

  • <Object>
    • modulusLength: <number> 密钥大小（以位计）（RSA、DSA）。
    • publicExponent: <bigint> 公共指数（RSA）。
    • hashAlgorithm: <string> 消息摘要的名称（RSA-PSS）。
    • mgf1HashAlgorithm: <string> MGF1（RSA-PSS）使用的消息摘要名称。
    • saltLength: <number> 盐的最小长度（以字节为单位）（RSA-PSS）。
    • divisorLength: <number> q 的大小（以位为单位）（DSA）。
    • namedCurve: <string> 曲线的名称（EC）。

此属性仅存在于非对称密钥上。根据密钥的类型，此对象包含有关密钥的信息。通过此属性获得的任何信息都不能用于唯一标识密钥或损害密钥的安全性。

对于 RSA-PSS 密钥，如果密钥材料包含 RSASSA-PSS-params 序列，则将设置 hashAlgorithm、mgf1HashAlgorithm 和 saltLength 属性。

其他密钥详细信息可能通过此 API 使用其他属性公开。

keyObject.asymmetricKeyType#

历史
版本更改
v13.9.0, v12.17.0

添加了对 'dh' 的支持。

v12.0.0

添加了对 'rsa-pss' 的支持。

v12.0.0

此属性现在对于无法识别的类型的 KeyObject 实例返回 undefined，而不是中止。

v12.0.0

添加了对 'x25519' 和 'x448' 的支持。

v12.0.0

添加了对 'ed25519' 和 'ed448' 的支持。

v11.6.0

添加于：v11.6.0

对于非对称密钥，此属性表示密钥的类型。支持的密钥类型为

  • 'rsa' (OID 1.2.840.113549.1.1.1)
  • 'rsa-pss' (OID 1.2.840.113549.1.1.10)
  • 'dsa' (OID 1.2.840.10040.4.1)
  • 'ec' (OID 1.2.840.10045.2.1)
  • 'x25519' (OID 1.3.101.110)
  • 'x448' (OID 1.3.101.111)
  • 'ed25519' (OID 1.3.101.112)
  • 'ed448' (OID 1.3.101.113)
  • 'dh' (OID 1.2.840.113549.1.3.1)

此属性对于无法识别的 KeyObject 类型和对称密钥为 undefined。

keyObject.export([options])#

历史
版本更改
v15.9.0

添加了对 'jwk' 格式的支持。

v11.6.0

添加于：v11.6.0

对于对称密钥，可以使用以下编码选项

  • format: <string> 必须为 'buffer'（默认）或 'jwk'。

对于公钥，可以使用以下编码选项

  • type: <string> 必须是 'pkcs1'（仅限 RSA）或 'spki' 之一。
  • format: <string> 必须是 'pem'、'der' 或 'jwk'。

对于私钥，可以使用以下编码选项

  • type: <string> 必须是 'pkcs1'（仅限 RSA）、'pkcs8' 或 'sec1'（仅限 EC）之一。
  • format: <string> 必须是 'pem'、'der' 或 'jwk'。
  • cipher: <string> 如果指定，私钥将使用给定的 cipher 和 passphrase 使用 PKCS#5 v2.0 基于密码的加密进行加密。
  • passphrase: <string> | <Buffer> 用于加密的密码，请参见 cipher。

结果类型取决于所选的编码格式，当 PEM 时结果为字符串，当 DER 时它将是一个包含以 DER 编码的数据的缓冲区，当 JWK 时它将是一个对象。

当选择 JWK 编码格式时，所有其他编码选项将被忽略。

PKCS#1、SEC1 和 PKCS#8 类型密钥可以通过使用 cipher 和 format 选项的组合进行加密。PKCS#8 type 可以与任何 format 一起使用，通过指定 cipher 来加密任何密钥算法（RSA、EC 或 DH）。PKCS#1 和 SEC1 只能通过在使用 PEM format 时指定 cipher 来加密。为了最大限度地兼容，请对加密的私钥使用 PKCS#8。由于 PKCS#8 定义了自己的加密机制，因此在加密 PKCS#8 密钥时不支持 PEM 级别的加密。请参见 RFC 5208 以了解 PKCS#8 加密，以及 RFC 1421 以了解 PKCS#1 和 SEC1 加密。

keyObject.equals(otherKeyObject)#

添加于：v17.7.0、v16.15.0
  • otherKeyObject: <KeyObject> 用于与 keyObject 进行比较的 KeyObject。
  • 返回值：<boolean>

根据密钥是否具有完全相同的类型、值和参数返回 true 或 false。此方法不是 恒定时间 的。

keyObject.symmetricKeySize#

添加于：v11.6.0

对于密钥，此属性表示密钥的大小（以字节为单位）。此属性对于非对称密钥为 undefined。

keyObject.type#

添加于：v11.6.0

根据此 KeyObject 的类型，此属性可以是秘密（对称）密钥的 'secret'、公钥（非对称）密钥的 'public' 或私钥（非对称）密钥的 'private'。

类：Sign#

添加于：v0.1.92

Sign 类是一个用于生成签名的实用程序。它可以以两种方式之一使用

crypto.createSign() 方法用于创建 Sign 实例。参数是要使用的哈希函数的字符串名称。Sign 对象不能直接使用 new 关键字创建。

示例：使用 Sign 和 Verify 对象作为流

const {
  generateKeyPairSync,
  createSign,
  createVerify,
} = await import('node:crypto');

const { privateKey, publicKey } = generateKeyPairSync('ec', {
  namedCurve: 'sect239k1',
});

const sign = createSign('SHA256');
sign.write('some data to sign');
sign.end();
const signature = sign.sign(privateKey, 'hex');

const verify = createVerify('SHA256');
verify.write('some data to sign');
verify.end();
console.log(verify.verify(publicKey, signature, 'hex'));
// Prints: trueconst {
  generateKeyPairSync,
  createSign,
  createVerify,
} = require('node:crypto');

const { privateKey, publicKey } = generateKeyPairSync('ec', {
  namedCurve: 'sect239k1',
});

const sign = createSign('SHA256');
sign.write('some data to sign');
sign.end();
const signature = sign.sign(privateKey, 'hex');

const verify = createVerify('SHA256');
verify.write('some data to sign');
verify.end();
console.log(verify.verify(publicKey, signature, 'hex'));
// Prints: true

示例：使用 sign.update() 和 verify.update() 方法

const {
  generateKeyPairSync,
  createSign,
  createVerify,
} = await import('node:crypto');

const { privateKey, publicKey } = generateKeyPairSync('rsa', {
  modulusLength: 2048,
});

const sign = createSign('SHA256');
sign.update('some data to sign');
sign.end();
const signature = sign.sign(privateKey);

const verify = createVerify('SHA256');
verify.update('some data to sign');
verify.end();
console.log(verify.verify(publicKey, signature));
// Prints: trueconst {
  generateKeyPairSync,
  createSign,
  createVerify,
} = require('node:crypto');

const { privateKey, publicKey } = generateKeyPairSync('rsa', {
  modulusLength: 2048,
});

const sign = createSign('SHA256');
sign.update('some data to sign');
sign.end();
const signature = sign.sign(privateKey);

const verify = createVerify('SHA256');
verify.update('some data to sign');
verify.end();
console.log(verify.verify(publicKey, signature));
// Prints: true

sign.sign(privateKey[, outputEncoding])#

历史
版本更改
v15.0.0

privateKey 也可以是 ArrayBuffer 和 CryptoKey。

v13.2.0, v12.16.0

此函数现在支持 IEEE-P1363 DSA 和 ECDSA 签名。

v12.0.0

此函数现在支持 RSA-PSS 密钥。

v11.6.0

此函数现在支持密钥对象。

v8.0.0

添加了对 RSASSA-PSS 和其他选项的支持。

v0.1.92

添加于：v0.1.92

使用 sign.update() 或 sign.write() 计算通过的所有数据的签名。

如果 privateKey 不是 KeyObject，则此函数的行为就好像 privateKey 已传递给 crypto.createPrivateKey() 一样。如果它是一个对象，则可以传递以下附加属性

  • dsaEncoding <string> 对于 DSA 和 ECDSA，此选项指定生成的签名的格式。它可以是以下之一

    • 'der' (默认)：DER 编码的 ASN.1 签名结构编码 (r, s)。
    • 'ieee-p1363'：签名格式 r || s，如 IEEE-P1363 中所述。

  • padding <integer> RSA 的可选填充值，以下之一

    • crypto.constants.RSA_PKCS1_PADDING (默认)
    • crypto.constants.RSA_PKCS1_PSS_PADDING

    RSA_PKCS1_PSS_PADDING 将使用 MGF1，该函数使用与用于签署消息的相同哈希函数，如 RFC 4055 第 3.1 节中所述，除非 MGF1 哈希函数已在密钥中指定，符合 RFC 4055 第 3.3 节。

  • saltLength <integer> 当填充为 RSA_PKCS1_PSS_PADDING 时的盐长度。特殊值 crypto.constants.RSA_PSS_SALTLEN_DIGEST 将盐长度设置为摘要大小，crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (默认) 将其设置为最大允许值。

如果提供了 outputEncoding，则返回字符串；否则返回 Buffer。

在调用 sign.sign() 方法后，Sign 对象将无法再次使用。多次调用 sign.sign() 将导致抛出错误。

sign.update(data[, inputEncoding])#

历史
版本更改
v6.0.0

默认的 inputEncoding 从 binary 更改为 utf8。

v0.1.92

添加于：v0.1.92

使用给定的 data 更新 Sign 内容，其编码在 inputEncoding 中给出。如果未提供 encoding，并且 data 是字符串，则强制使用 'utf8' 编码。如果 data 是 Buffer、TypedArray 或 DataView，则忽略 inputEncoding。

可以多次调用此方法，并在数据流式传输时提供新数据。

类：Verify#

添加于：v0.1.92

Verify 类是用于验证签名的实用程序。它可以通过两种方式使用

crypto.createVerify() 方法用于创建 Verify 实例。Verify 对象不能使用 new 关键字直接创建。

请参见 Sign 获取示例。

verify.update(data[, inputEncoding])#

历史
版本更改
v6.0.0

默认的 inputEncoding 从 binary 更改为 utf8。

v0.1.92

添加于：v0.1.92

使用给定的 data 更新 Verify 内容，其编码在 inputEncoding 中给出。如果未提供 inputEncoding，并且 data 是字符串，则强制使用 'utf8' 编码。如果 data 是 Buffer、TypedArray 或 DataView，则忽略 inputEncoding。

可以多次调用此方法，并在数据流式传输时提供新数据。

verify.verify(object, signature[, signatureEncoding])#

历史
版本更改
v15.0.0

对象也可以是 ArrayBuffer 和 CryptoKey。

v13.2.0, v12.16.0

此函数现在支持 IEEE-P1363 DSA 和 ECDSA 签名。

v12.0.0

此函数现在支持 RSA-PSS 密钥。

v11.7.0

密钥现在可以是私钥。

v8.0.0

添加了对 RSASSA-PSS 和其他选项的支持。

v0.1.92

添加于：v0.1.92

使用给定的 object 和 signature 验证提供的数据。

如果object不是一个KeyObject，则此函数的行为就好像object已传递给crypto.createPublicKey()。如果它是一个对象，则可以传递以下附加属性

  • dsaEncoding <string> 对于 DSA 和 ECDSA，此选项指定签名的格式。它可以是以下之一

    • 'der' (默认)：DER 编码的 ASN.1 签名结构编码 (r, s)。
    • 'ieee-p1363'：签名格式 r || s，如 IEEE-P1363 中所述。

  • padding <integer> RSA 的可选填充值，以下之一

    • crypto.constants.RSA_PKCS1_PADDING (默认)
    • crypto.constants.RSA_PKCS1_PSS_PADDING

    RSA_PKCS1_PSS_PADDING 将使用 MGF1，使用与用于验证消息的相同哈希函数，如RFC 4055 的第 3.1 节中所述，除非已将 MGF1 哈希函数指定为密钥的一部分，符合RFC 4055 的第 3.3 节。

  • saltLength <integer> 当填充为RSA_PKCS1_PSS_PADDING 时的盐长度。特殊值crypto.constants.RSA_PSS_SALTLEN_DIGEST 将盐长度设置为摘要大小，crypto.constants.RSA_PSS_SALTLEN_AUTO（默认）会导致自动确定。

signature 参数是先前为数据计算的签名，以signatureEncoding 格式。如果指定了signatureEncoding，则signature 预计为字符串；否则，signature 预计为Buffer、TypedArray 或 DataView。

verify 对象在调用verify.verify() 后不能再次使用。多次调用verify.verify() 将导致抛出错误。

由于可以从私钥派生公钥，因此可以传递私钥而不是公钥。

类：X509Certificate#

添加于：v15.6.0

封装 X509 证书并提供对其信息的只读访问。

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

const x509 = new X509Certificate('{... pem encoded cert ...}');

console.log(x509.subject);const { X509Certificate } = require('node:crypto');

const x509 = new X509Certificate('{... pem encoded cert ...}');

console.log(x509.subject);

new X509Certificate(buffer)#

添加于：v15.6.0

x509.ca#

添加于：v15.6.0
  • 类型：<boolean> 如果这是证书颁发机构 (CA) 证书，则为true。

x509.checkEmail(email[, options])#

历史
版本更改
v18.0.0

现在，主题选项默认值为 'default'。

v17.5.0, v16.15.0

现在，主题选项可以设置为 'default'。

v17.5.0, v16.14.1

由于 wildcards、partialWildcards、multiLabelWildcards 和 singleLabelSubdomains 选项没有效果，因此已将其删除。

v15.6.0

添加于：v15.6.0

检查证书是否与给定的电子邮件地址匹配。

如果 'subject' 选项未定义或设置为 'default'，则仅当主题备用名称扩展名不存在或不包含任何电子邮件地址时，才会考虑证书主题。

如果 'subject' 选项设置为 'always'，并且主题备用名称扩展名不存在或不包含匹配的电子邮件地址，则会考虑证书主题。

如果 'subject' 选项设置为 'never'，则永远不会考虑证书主题，即使证书不包含主题备用名称。

x509.checkHost(name[, options])#

历史
版本更改
v18.0.0

现在，主题选项默认值为 'default'。

v17.5.0, v16.15.0

现在，主题选项可以设置为 'default'。

v15.6.0

添加于：v15.6.0

  • name <string>
  • options <Object>
    • subject <string> 'default'、'always' 或 'never'。默认值： 'default'。
    • wildcards <boolean> 默认值： true。
    • partialWildcards <boolean> 默认值： true。
    • multiLabelWildcards <boolean> 默认值： false。
    • singleLabelSubdomains <boolean> 默认值： false。
  • 返回值：<string> | <undefined> 返回与name匹配的主题名称，如果没有任何主题名称与name匹配，则返回undefined。

检查证书是否与给定的主机名匹配。

如果证书与给定的主机名匹配，则返回匹配的主题名称。返回的名称可能是完全匹配（例如，foo.example.com），也可能包含通配符（例如，*.example.com）。由于主机名比较不区分大小写，因此返回的主题名称也可能与给定的name在大小写方面有所不同。

如果'subject'选项未定义或设置为'default'，则仅当主题备用名称扩展名不存在或不包含任何 DNS 名称时，才会考虑证书主题。此行为与RFC 2818（“HTTP Over TLS”）一致。

如果'subject'选项设置为'always'，并且主题备用名称扩展名不存在或不包含匹配的 DNS 名称，则会考虑证书主题。

如果 'subject' 选项设置为 'never'，则永远不会考虑证书主题，即使证书不包含主题备用名称。

x509.checkIP(ip)#

历史
版本更改
v17.5.0, v16.14.1

options参数已被移除，因为它没有效果。

v15.6.0

添加于：v15.6.0

检查证书是否与给定的 IP 地址（IPv4 或 IPv6）匹配。

仅考虑RFC 5280 iPAddress 主题备用名称，并且它们必须与给定的ip地址完全匹配。其他主题备用名称以及证书的主题字段将被忽略。

x509.checkIssued(otherCert)#

添加于：v15.6.0

检查此证书是否由给定的otherCert颁发。

x509.checkPrivateKey(privateKey)#

添加于：v15.6.0

检查此证书的公钥是否与给定的私钥一致。

x509.fingerprint#

添加于：v15.6.0

此证书的 SHA-1 指纹。

由于 SHA-1 在密码学上已被破解，并且 SHA-1 的安全性远低于通常用于签署证书的算法，因此请考虑使用 x509.fingerprint256 代替。

x509.fingerprint256#

添加于：v15.6.0

此证书的 SHA-256 指纹。

x509.fingerprint512#

新增于: v17.2.0, v16.14.0

此证书的 SHA-512 指纹。

由于计算 SHA-256 指纹通常更快，并且它的大小只有 SHA-512 指纹的一半，因此 x509.fingerprint256 可能是更好的选择。虽然 SHA-512 通常可能提供更高的安全级别，但 SHA-256 的安全性与大多数用于签署证书的算法相匹配。

x509.infoAccess#

历史
版本更改
v17.3.1, v16.13.2

此字符串的部分内容可能被编码为 JSON 字符串字面量，以响应 CVE-2021-44532。

v15.6.0

添加于：v15.6.0

证书的权限信息访问扩展的文本表示。

这是一个以换行符分隔的访问描述列表。每行以访问方法和访问位置的类型开头，后面跟着一个冒号和与访问位置关联的值。

在表示访问方法和访问位置类型的代码前缀之后，每行的其余部分可能用引号括起来，以指示该值是一个 JSON 字符串字面量。为了向后兼容，Node.js 仅在必要时才在此属性中使用 JSON 字符串字面量，以避免歧义。第三方代码应准备处理两种可能的条目格式。

x509.issuer#

添加于：v15.6.0

此证书中包含的发行者标识。

x509.issuerCertificate#

新增于: v15.9.0

颁发者证书，如果颁发者证书不可用则为 undefined。

x509.extKeyUsage#

添加于：v15.6.0

一个数组，详细说明此证书的密钥扩展用途。

x509.publicKey#

添加于：v15.6.0

此证书的公钥 <KeyObject>。

x509.raw#

添加于：v15.6.0

一个包含此证书 DER 编码的 Buffer。

x509.serialNumber#

添加于：v15.6.0

此证书的序列号。

序列号由证书颁发机构分配，不能唯一标识证书。请考虑使用 x509.fingerprint256 作为唯一标识符。

x509.subject#

添加于：v15.6.0

此证书的完整主体。

x509.subjectAltName#

历史
版本更改
v17.3.1, v16.13.2

此字符串的部分内容可能被编码为 JSON 字符串字面量，以响应 CVE-2021-44532。

v15.6.0

添加于：v15.6.0

为此证书指定的主题备用名称。

这是一个以逗号分隔的主题备用名称列表。每个条目以标识主题备用名称类型的字符串开头，后跟一个冒号和与条目关联的值。

早期版本的 Node.js 错误地假设在以字符串形式表示时，在两个字符序列 ', ' 处分割此属性是安全的（参见 CVE-2021-44532）。但是，恶意和合法证书都可以在作为字符串表示时包含包含此序列的主题备用名称。

在表示条目类型的词缀之后，每个条目的其余部分可能用引号括起来，以指示该值是 JSON 字符串文字。为了向后兼容，Node.js 仅在必要时才在此属性中使用 JSON 字符串文字，以避免歧义。第三方代码应准备好处理两种可能的条目格式。

x509.toJSON()#

添加于：v15.6.0

X509 证书没有标准的 JSON 编码。toJSON() 方法返回一个包含 PEM 编码证书的字符串。

x509.toLegacyObject()#

添加于：v15.6.0

使用旧版 证书对象 编码返回有关此证书的信息。

x509.toString()#

添加于：v15.6.0

返回 PEM 编码的证书。

x509.validFrom#

添加于：v15.6.0

此证书生效的日期/时间。

x509.validTo#

添加于：v15.6.0

此证书有效的截止日期/时间。

x509.verify(publicKey)#

添加于：v15.6.0

验证此证书是否由给定的公钥签名。不执行对证书的任何其他验证检查。

node:crypto 模块方法和属性#

crypto.constants#

添加于: v6.3.0

一个包含与加密和安全相关的操作常用的常量的对象。当前定义的特定常量在 加密常量 中描述。

crypto.fips#

添加于: v6.0.0已弃用: v10.0.0

稳定性：0 - 已弃用

用于检查和控制当前是否使用 FIPS 兼容加密提供程序的属性。设置为 true 需要 Node.js 的 FIPS 版本。

此属性已弃用。请改用 crypto.setFips() 和 crypto.getFips()。

crypto.checkPrime(candidate[, options], callback)#

历史
版本更改
v18.0.0

将无效回调传递给 callback 参数现在会抛出 ERR_INVALID_ARG_TYPE 而不是 ERR_INVALID_CALLBACK。

v15.8.0

添加于: v15.8.0

  • candidate <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint> 一个可能的素数，编码为任意长度的大端字节序列。
  • options <Object>
    • checks <number> 要执行的 Miller-Rabin 概率素数迭代次数。当值为 0（零）时，使用的检查次数会导致随机输入的误报率最多为 2-64。选择检查次数时必须谨慎。有关更多详细信息，请参阅 OpenSSL 文档中的 BN_is_prime_ex 函数 nchecks 选项。默认值： 0
  • callback <Function>
    • err <Error> 如果检查过程中发生错误，则设置为 <Error> 对象。
    • result <boolean> 如果候选者是素数，且错误概率小于 0.25 ** options.checks，则为 true。

检查 candidate 的素数性。

crypto.checkPrimeSync(candidate[, options])#

添加于: v15.8.0
  • candidate <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint> 一个可能的素数，编码为任意长度的大端字节序列。
  • options <Object>
    • checks <number> 要执行的 Miller-Rabin 概率素数迭代次数。当值为 0（零）时，使用的检查次数会导致随机输入的误报率最多为 2-64。选择检查次数时必须谨慎。有关更多详细信息，请参阅 OpenSSL 文档中的 BN_is_prime_ex 函数 nchecks 选项。默认值： 0
  • 返回值：<boolean> 如果候选者是素数，且错误概率小于 0.25 ** options.checks，则为 true。

检查 candidate 的素数性。

crypto.createCipher(algorithm, password[, options])#

历史
版本更改
v17.9.0, v16.17.0

使用 chacha20-poly1305 密码时，authTagLength 选项现在是可选的，默认值为 16 字节。

v15.0.0

密码参数可以是 ArrayBuffer，并且限制为最大 2 ** 31 - 1 字节。

v10.10.0

现在支持 OCB 模式下的密码。

v10.2.0

authTagLength 选项现在可用于在 GCM 模式下生成更短的认证标签，默认值为 16 字节。

v10.0.0

已弃用：v10.0.0

v0.1.94

添加于: v0.1.94

稳定性：0 - 已弃用：请使用 crypto.createCipheriv() 代替。

创建并返回一个使用给定 algorithm 和 password 的 Cipher 对象。

options 参数控制流行为，是可选的，除非使用 CCM 或 OCB 模式（例如 'aes-128-ccm'）的密码。在这种情况下，authTagLength 选项是必需的，它指定身份验证标签的字节长度，请参阅 CCM 模式。在 GCM 模式下，authTagLength 选项不是必需的，但可以用来设置 getAuthTag() 返回的身份验证标签的长度，默认值为 16 字节。对于 chacha20-poly1305，authTagLength 选项默认为 16 字节。

algorithm 依赖于 OpenSSL，例如 'aes192' 等。在最新的 OpenSSL 版本中，openssl list -cipher-algorithms 将显示可用的密码算法。

password 用于推导出密码密钥和初始化向量 (IV)。该值必须是 'latin1' 编码的字符串、Buffer、TypedArray 或 DataView。

对于所有支持的密码，此函数在语义上是不安全的，对于计数器模式（如 CTR、GCM 或 CCM）的密码来说是致命的缺陷。

crypto.createCipher() 的实现使用 OpenSSL 函数 EVP_BytesToKey 推导出密钥，其中摘要算法设置为 MD5，迭代次数为 1，没有盐。缺少盐允许字典攻击，因为相同的密码总是创建相同的密钥。迭代次数少和非加密安全的哈希算法允许非常快速地测试密码。

与 OpenSSL 的建议一致，建议开发人员使用更现代的算法来代替 EVP_BytesToKey，建议开发人员使用 crypto.scrypt() 自行推导出密钥和 IV，并使用 crypto.createCipheriv() 创建 Cipher 对象。用户不应在 crypto.createCipher() 中使用计数器模式（例如 CTR、GCM 或 CCM）的密码。当它们被使用时，会发出警告，以避免 IV 重用导致的漏洞风险。对于在 GCM 中重用 IV 的情况，请参阅 Nonce-Disrespecting Adversaries 以了解更多详细信息。

crypto.createCipheriv(algorithm, key, iv[, options])#

历史
版本更改
v17.9.0, v16.17.0

使用 chacha20-poly1305 密码时，authTagLength 选项现在是可选的，默认值为 16 字节。

v15.0.0

密码和 iv 参数可以是 ArrayBuffer，每个参数的最大限制为 2 ** 31 - 1 字节。

v11.6.0

key 参数现在可以是 KeyObject。

v11.2.0, v10.17.0

现在支持密码 chacha20-poly1305（ChaCha20-Poly1305 的 IETF 变体）。

v10.10.0

现在支持 OCB 模式下的密码。

v10.2.0

authTagLength 选项现在可用于在 GCM 模式下生成更短的认证标签，默认值为 16 字节。

v9.9.0

对于不需要初始化向量的密码，iv 参数现在可以是 null。

v0.1.94

添加于: v0.1.94

创建并返回一个 Cipher 对象，使用给定的 algorithm、key 和初始化向量 (iv)。

options 参数控制流行为，是可选的，除非使用 CCM 或 OCB 模式（例如 'aes-128-ccm'）的密码。在这种情况下，authTagLength 选项是必需的，它指定身份验证标签的字节长度，请参阅 CCM 模式。在 GCM 模式下，authTagLength 选项不是必需的，但可以用来设置 getAuthTag() 返回的身份验证标签的长度，默认值为 16 字节。对于 chacha20-poly1305，authTagLength 选项默认为 16 字节。

algorithm 依赖于 OpenSSL，例如 'aes192' 等。在最新的 OpenSSL 版本中，openssl list -cipher-algorithms 将显示可用的密码算法。

key 是 algorithm 使用的原始密钥，iv 是一个 初始化向量。这两个参数必须是 'utf8' 编码的字符串、Buffer、TypedArray 或 DataView。key 可以选择是一个类型为 secret 的 KeyObject。如果密码不需要初始化向量，iv 可以是 null。

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

初始化向量应该是不可预测且唯一的；理想情况下，它们应该是加密随机的。它们不必保密：IV 通常只是被添加到密文中，没有加密。听起来可能矛盾，即某样东西必须不可预测且唯一，但不必保密；请记住，攻击者不能提前预测给定的 IV 将是什么。

crypto.createDecipher(algorithm, password[, options])#

历史
版本更改
v17.9.0, v16.17.0

使用 chacha20-poly1305 密码时，authTagLength 选项现在是可选的，默认值为 16 字节。

v10.10.0

现在支持 OCB 模式下的密码。

v10.0.0

已弃用：v10.0.0

v0.1.94

添加于: v0.1.94

稳定性：0 - 已弃用：请改用 crypto.createDecipheriv()。

创建并返回一个使用给定algorithm和password（密钥）的Decipher对象。

options参数控制流行为，是可选的，除非使用CCM或OCB模式的密码（例如'aes-128-ccm'）。在这种情况下，authTagLength选项是必需的，它指定身份验证标签的字节长度，请参见CCM模式。对于chacha20-poly1305，authTagLength选项默认为16字节。

对于所有支持的密码，此函数在语义上是不安全的，对于计数器模式（如 CTR、GCM 或 CCM）的密码来说是致命的缺陷。

crypto.createDecipher()的实现使用OpenSSL函数EVP_BytesToKey来派生密钥，其中摘要算法设置为MD5，迭代次数为1，没有盐。没有盐允许字典攻击，因为相同的密码总是创建相同的密钥。低迭代次数和非加密安全的哈希算法允许非常快速地测试密码。

与OpenSSL的建议一致，建议开发人员使用更现代的算法而不是EVP_BytesToKey，建议开发人员使用crypto.scrypt()自行派生密钥和IV，并使用crypto.createDecipheriv()创建Decipher对象。

crypto.createDecipheriv(algorithm, key, iv[, options])#

历史
版本更改
v17.9.0, v16.17.0

使用 chacha20-poly1305 密码时，authTagLength 选项现在是可选的，默认值为 16 字节。

v11.6.0

key 参数现在可以是 KeyObject。

v11.2.0, v10.17.0

现在支持密码 chacha20-poly1305（ChaCha20-Poly1305 的 IETF 变体）。

v10.10.0

现在支持 OCB 模式下的密码。

v10.2.0

现在可以使用authTagLength选项来限制接受的GCM身份验证标签长度。

v9.9.0

对于不需要初始化向量的密码，iv 参数现在可以是 null。

v0.1.94

添加于: v0.1.94

创建并返回一个使用给定algorithm、key和初始化向量（iv）的Decipher对象。

options参数控制流行为，是可选的，除非使用CCM或OCB模式的密码（例如'aes-128-ccm'）。在这种情况下，authTagLength选项是必需的，它指定身份验证标签的字节长度，请参见CCM模式。在GCM模式下，authTagLength选项不是必需的，但可以用来将接受的身份验证标签限制为指定长度的标签。对于chacha20-poly1305，authTagLength选项默认为16字节。

algorithm 依赖于 OpenSSL，例如 'aes192' 等。在最新的 OpenSSL 版本中，openssl list -cipher-algorithms 将显示可用的密码算法。

key 是 algorithm 使用的原始密钥，iv 是一个 初始化向量。这两个参数必须是 'utf8' 编码的字符串、Buffer、TypedArray 或 DataView。key 可以选择是一个类型为 secret 的 KeyObject。如果密码不需要初始化向量，iv 可以是 null。

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

初始化向量应该是不可预测且唯一的；理想情况下，它们应该是加密随机的。它们不必保密：IV 通常只是被添加到密文中，没有加密。听起来可能矛盾，即某样东西必须不可预测且唯一，但不必保密；请记住，攻击者不能提前预测给定的 IV 将是什么。

crypto.createDiffieHellman(prime[, primeEncoding][, generator][, generatorEncoding])#

历史
版本更改
v8.0.0

prime参数现在可以是任何TypedArray或DataView。

v8.0.0

prime参数现在可以是Uint8Array。

v6.0.0

编码参数的默认值已从binary更改为utf8。

v0.11.12

添加于：v0.11.12

使用提供的 prime 和可选的特定 generator 创建一个 DiffieHellman 密钥交换对象。

generator 参数可以是数字、字符串或 Buffer。如果未指定 generator，则使用值 2。

如果指定了 primeEncoding，则 prime 预计为字符串；否则，预计为 Buffer、TypedArray 或 DataView。

如果指定了 generatorEncoding，则 generator 预计为字符串；否则，预计为数字、Buffer、TypedArray 或 DataView。

crypto.createDiffieHellman(primeLength[, generator])#

添加于：v0.5.0

创建一个 DiffieHellman 密钥交换对象，并使用可选的特定数字 generator 生成 primeLength 位的素数。如果未指定 generator，则使用值 2。

crypto.createDiffieHellmanGroup(name)#

添加于: v0.9.3

crypto.getDiffieHellman() 的别名 crypto.getDiffieHellman()

crypto.createECDH(curveName)#

添加于：v0.11.14

使用由 curveName 字符串指定的预定义曲线创建椭圆曲线 Diffie-Hellman (ECDH) 密钥交换对象。使用 crypto.getCurves() 获取可用曲线名称列表。在最近的 OpenSSL 版本中，openssl ecparam -list_curves 也会显示每个可用椭圆曲线的名称和描述。

crypto.createHash(algorithm[, options])#

历史
版本更改
v12.8.0

为 XOF 哈希函数添加了 outputLength 选项。

v0.1.92

添加于：v0.1.92

创建并返回一个 Hash 对象，该对象可用于使用给定的 algorithm 生成哈希摘要。可选的 options 参数控制流行为。对于 XOF 哈希函数（如 'shake256'），outputLength 选项可用于指定所需的输出长度（以字节为单位）。

algorithm 取决于平台上 OpenSSL 版本支持的可用算法。例如 'sha256'、'sha512' 等。在最近的 OpenSSL 版本中，openssl list -digest-algorithms 将显示可用的摘要算法。

示例：生成文件的 sha256 校验和

import {
  createReadStream,
} from 'node:fs';
import { argv } from 'node:process';
const {
  createHash,
} = await import('node:crypto');

const filename = argv[2];

const hash = createHash('sha256');

const input = createReadStream(filename);
input.on('readable', () => {
  // Only one element is going to be produced by the
  // hash stream.
  const data = input.read();
  if (data)
    hash.update(data);
  else {
    console.log(`${hash.digest('hex')} ${filename}`);
  }
});const {
  createReadStream,
} = require('node:fs');
const {
  createHash,
} = require('node:crypto');
const { argv } = require('node:process');

const filename = argv[2];

const hash = createHash('sha256');

const input = createReadStream(filename);
input.on('readable', () => {
  // Only one element is going to be produced by the
  // hash stream.
  const data = input.read();
  if (data)
    hash.update(data);
  else {
    console.log(`${hash.digest('hex')} ${filename}`);
  }
});

crypto.createHmac(algorithm, key[, options])#

历史
版本更改
v15.0.0

密钥也可以是 ArrayBuffer 或 CryptoKey。添加了编码选项。密钥不能包含超过 2 ** 32 - 1 个字节。

v11.6.0

key 参数现在可以是 KeyObject。

v0.1.94

添加于: v0.1.94

创建并返回一个 Hmac 对象，该对象使用给定的 algorithm 和 key。可选的 options 参数控制流行为。

algorithm 取决于平台上 OpenSSL 版本支持的可用算法。例如 'sha256'、'sha512' 等。在最近的 OpenSSL 版本中，openssl list -digest-algorithms 将显示可用的摘要算法。

key 是用于生成加密 HMAC 哈希的 HMAC 密钥。如果它是 KeyObject，则其类型必须为 secret。如果它是字符串，请考虑 使用字符串作为加密 API 输入时的注意事项。如果它是从加密安全的熵源（如 crypto.randomBytes() 或 crypto.generateKey()）获得的，则其长度不应超过 algorithm 的块大小（例如，SHA-256 为 512 位）。

示例：生成文件的 sha256 HMAC

import {
  createReadStream,
} from 'node:fs';
import { argv } from 'node:process';
const {
  createHmac,
} = await import('node:crypto');

const filename = argv[2];

const hmac = createHmac('sha256', 'a secret');

const input = createReadStream(filename);
input.on('readable', () => {
  // Only one element is going to be produced by the
  // hash stream.
  const data = input.read();
  if (data)
    hmac.update(data);
  else {
    console.log(`${hmac.digest('hex')} ${filename}`);
  }
});const {
  createReadStream,
} = require('node:fs');
const {
  createHmac,
} = require('node:crypto');
const { argv } = require('node:process');

const filename = argv[2];

const hmac = createHmac('sha256', 'a secret');

const input = createReadStream(filename);
input.on('readable', () => {
  // Only one element is going to be produced by the
  // hash stream.
  const data = input.read();
  if (data)
    hmac.update(data);
  else {
    console.log(`${hmac.digest('hex')} ${filename}`);
  }
});

crypto.createPrivateKey(key)#

历史
版本更改
v15.12.0

密钥也可以是 JWK 对象。

v15.0.0

密钥也可以是 ArrayBuffer。添加了编码选项。密钥不能超过 2 ** 32 - 1 字节。

v11.6.0

添加于：v11.6.0

创建并返回一个包含私钥的新密钥对象。如果 `key` 是字符串或 `Buffer`，则 `format` 假设为 `'pem'`；否则，`key` 必须是具有上述属性的对象。

如果私钥已加密，则必须指定 `passphrase`。密码长度限制为 1024 字节。

crypto.createPublicKey(key)#

历史
版本更改
v15.12.0

密钥也可以是 JWK 对象。

v15.0.0

密钥也可以是 ArrayBuffer。添加了编码选项。密钥不能超过 2 ** 32 - 1 字节。

v11.13.0

`key` 参数现在可以是类型为 `private` 的 `KeyObject`。

v11.7.0

`key` 参数现在可以是私钥。

v11.6.0

添加于：v11.6.0

创建并返回一个包含公钥的新密钥对象。如果 `key` 是字符串或 `Buffer`，则 `format` 假设为 `'pem'`；如果 `key` 是类型为 `'private'` 的 `KeyObject`，则公钥将从给定的私钥派生；否则，`key` 必须是具有上述属性的对象。

如果格式为 `'pem'`，则 `'key'` 也可以是 X.509 证书。

由于公钥可以从私钥派生，因此可以传递私钥而不是公钥。在这种情况下，此函数的行为就像调用了 crypto.createPrivateKey() 一样，只是返回的 `KeyObject` 的类型将为 `'public'`，并且无法从返回的 `KeyObject` 中提取私钥。类似地，如果给定类型为 `'private'` 的 `KeyObject`，则将返回类型为 `'public'` 的新 `KeyObject`，并且无法从返回的对象中提取私钥。

crypto.createSecretKey(key[, encoding])#

历史
版本更改
v18.8.0, v16.18.0

密钥现在可以为空。

v15.0.0

密钥也可以是 ArrayBuffer 或字符串。添加了编码参数。密钥不能包含超过 2 ** 32 - 1 个字节。

v11.6.0

添加于：v11.6.0

创建并返回一个新的密钥对象，其中包含用于对称加密或 Hmac 的密钥。

crypto.createSign(algorithm[, options])#

添加于：v0.1.92

创建并返回一个 Sign 对象，该对象使用给定的 algorithm。使用 crypto.getHashes() 获取可用摘要算法的名称。可选的 options 参数控制 stream.Writable 行为。

在某些情况下，可以使用签名算法的名称（例如 'RSA-SHA256'）而不是摘要算法来创建 Sign 实例。这将使用相应的摘要算法。这并不适用于所有签名算法，例如 'ecdsa-with-SHA256'，因此最好始终使用摘要算法名称。

crypto.createVerify(algorithm[, options])#

添加于：v0.1.92

创建并返回一个 Verify 对象，该对象使用给定的算法。使用 crypto.getHashes() 获取可用签名算法名称的数组。可选的 options 参数控制 stream.Writable 行为。

在某些情况下，可以使用签名算法的名称（例如 'RSA-SHA256'）而不是摘要算法来创建 Verify 实例。这将使用相应的摘要算法。这并不适用于所有签名算法，例如 'ecdsa-with-SHA256'，因此最好始终使用摘要算法名称。

crypto.diffieHellman(options)#

添加于: v13.9.0, v12.17.0

根据 privateKey 和 publicKey 计算 Diffie-Hellman 密钥。两个密钥必须具有相同的 asymmetricKeyType，它必须是以下之一：'dh'（用于 Diffie-Hellman）、'ec'（用于 ECDH）、'x448' 或 'x25519'（用于 ECDH-ES）。

crypto.hash(algorith, data[, outputEncoding])#

添加于: v21.7.0

稳定性: 1.2 - 发布候选

用于创建数据的单次哈希摘要的实用程序。当哈希少量数据（<= 5MB）且数据易于获取时，它可能比基于对象的 crypto.createHash() 更快。如果数据可能很大或需要流式传输，仍然建议使用 crypto.createHash()。

algorithm 取决于平台上 OpenSSL 版本支持的可用算法。例如 'sha256'、'sha512' 等。在最近的 OpenSSL 版本中，openssl list -digest-algorithms 将显示可用的摘要算法。

示例

const crypto = require('node:crypto');
const { Buffer } = require('node:buffer');

// Hashing a string and return the result as a hex-encoded string.
const string = 'Node.js';
// 10b3493287f831e81a438811a1ffba01f8cec4b7
console.log(crypto.hash('sha1', string));

// Encode a base64-encoded string into a Buffer, hash it and return
// the result as a buffer.
const base64 = 'Tm9kZS5qcw==';
// <Buffer 10 b3 49 32 87 f8 31 e8 1a 43 88 11 a1 ff ba 01 f8 ce c4 b7>
console.log(crypto.hash('sha1', Buffer.from(base64, 'base64'), 'buffer'));import crypto from 'node:crypto';
import { Buffer } from 'node:buffer';

// Hashing a string and return the result as a hex-encoded string.
const string = 'Node.js';
// 10b3493287f831e81a438811a1ffba01f8cec4b7
console.log(crypto.hash('sha1', string));

// Encode a base64-encoded string into a Buffer, hash it and return
// the result as a buffer.
const base64 = 'Tm9kZS5qcw==';
// <Buffer 10 b3 49 32 87 f8 31 e8 1a 43 88 11 a1 ff ba 01 f8 ce c4 b7>
console.log(crypto.hash('sha1', Buffer.from(base64, 'base64'), 'buffer'));

crypto.generateKey(type, options, callback)#

历史
版本更改
v18.0.0

将无效回调传递给 callback 参数现在会抛出 ERR_INVALID_ARG_TYPE 而不是 ERR_INVALID_CALLBACK。

v15.0.0

添加于：v15.0.0

  • type: <string> 生成的密钥的预期用途。目前接受的值为 'hmac' 和 'aes'。
  • options: <Object>
    • length: <number> 要生成的密钥的位长度。这必须是一个大于 0 的值。
      • 如果 type 为 'hmac'，则最小值为 8，最大长度为 231-1。如果该值不是 8 的倍数，则生成的密钥将被截断为 Math.floor(length / 8)。
      • 如果 type 为 'aes'，则长度必须为 128、192 或 256 之一。
  • callback: <Function>

异步生成一个新的随机密钥，长度为给定的 length。type 将确定对 length 执行哪些验证。

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

generateKey('hmac', { length: 512 }, (err, key) => {
  if (err) throw err;
  console.log(key.export().toString('hex'));  // 46e..........620
});const {
  generateKey,
} = require('node:crypto');

generateKey('hmac', { length: 512 }, (err, key) => {
  if (err) throw err;
  console.log(key.export().toString('hex'));  // 46e..........620
});

生成的 HMAC 密钥的大小不应超过底层哈希函数的块大小。有关更多信息，请参见 crypto.createHmac()。

crypto.generateKeyPair(type, options, callback)#

历史
版本更改
v18.0.0

将无效回调传递给 callback 参数现在会抛出 ERR_INVALID_ARG_TYPE 而不是 ERR_INVALID_CALLBACK。

v16.10.0

添加了为 RSA-PSS 密钥对定义 RSASSA-PSS-params 序列参数的能力。

v13.9.0, v12.17.0

添加了对 Diffie-Hellman 的支持。

v12.0.0

添加了对 RSA-PSS 密钥对的支持。

v12.0.0

添加了生成 X25519 和 X448 密钥对的能力。

v12.0.0

添加了生成 Ed25519 和 Ed448 密钥对的能力。

v11.6.0

如果未指定编码，generateKeyPair 和 generateKeyPairSync 函数现在将生成密钥对象。

v10.12.0

添加于：v10.12.0

生成一个给定 type 的新的非对称密钥对。目前支持 RSA、RSA-PSS、DSA、EC、Ed25519、Ed448、X25519、X448 和 DH。

如果指定了 publicKeyEncoding 或 privateKeyEncoding，则此函数的行为就好像在其结果上调用了 keyObject.export() 一样。否则，密钥的相应部分将作为 KeyObject 返回。

建议将公钥编码为 'spki'，并将私钥编码为 'pkcs8'，并使用加密进行长期存储。

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

generateKeyPair('rsa', {
  modulusLength: 4096,
  publicKeyEncoding: {
    type: 'spki',
    format: 'pem',
  },
  privateKeyEncoding: {
    type: 'pkcs8',
    format: 'pem',
    cipher: 'aes-256-cbc',
    passphrase: 'top secret',
  },
}, (err, publicKey, privateKey) => {
  // Handle errors and use the generated key pair.
});const {
  generateKeyPair,
} = require('node:crypto');

generateKeyPair('rsa', {
  modulusLength: 4096,
  publicKeyEncoding: {
    type: 'spki',
    format: 'pem',
  },
  privateKeyEncoding: {
    type: 'pkcs8',
    format: 'pem',
    cipher: 'aes-256-cbc',
    passphrase: 'top secret',
  },
}, (err, publicKey, privateKey) => {
  // Handle errors and use the generated key pair.
});

完成时，将调用 callback，并将 err 设置为 undefined，并将 publicKey / privateKey 设置为生成的密钥对。

如果此方法被调用为其 util.promisify() 版本，则它将返回一个 Promise，该 Promise 用于包含 publicKey 和 privateKey 属性的 Object。

crypto.generateKeyPairSync(type, options)#

历史
版本更改
v16.10.0

添加了为 RSA-PSS 密钥对定义 RSASSA-PSS-params 序列参数的能力。

v13.9.0, v12.17.0

添加了对 Diffie-Hellman 的支持。

v12.0.0

添加了对 RSA-PSS 密钥对的支持。

v12.0.0

添加了生成 X25519 和 X448 密钥对的能力。

v12.0.0

添加了生成 Ed25519 和 Ed448 密钥对的能力。

v11.6.0

如果未指定编码，generateKeyPair 和 generateKeyPairSync 函数现在将生成密钥对象。

v10.12.0

添加于：v10.12.0

生成一个给定 type 的新的非对称密钥对。目前支持 RSA、RSA-PSS、DSA、EC、Ed25519、Ed448、X25519、X448 和 DH。

如果指定了 publicKeyEncoding 或 privateKeyEncoding，则此函数的行为就好像在其结果上调用了 keyObject.export() 一样。否则，密钥的相应部分将作为 KeyObject 返回。

在对公钥进行编码时，建议使用 'spki'。在对私钥进行编码时，建议使用 'pkcs8' 并设置一个强密码，并对密码进行保密。

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

const {
  publicKey,
  privateKey,
} = generateKeyPairSync('rsa', {
  modulusLength: 4096,
  publicKeyEncoding: {
    type: 'spki',
    format: 'pem',
  },
  privateKeyEncoding: {
    type: 'pkcs8',
    format: 'pem',
    cipher: 'aes-256-cbc',
    passphrase: 'top secret',
  },
});const {
  generateKeyPairSync,
} = require('node:crypto');

const {
  publicKey,
  privateKey,
} = generateKeyPairSync('rsa', {
  modulusLength: 4096,
  publicKeyEncoding: {
    type: 'spki',
    format: 'pem',
  },
  privateKeyEncoding: {
    type: 'pkcs8',
    format: 'pem',
    cipher: 'aes-256-cbc',
    passphrase: 'top secret',
  },
});

返回值 { publicKey, privateKey } 表示生成的密钥对。当选择 PEM 编码时，相应的密钥将是一个字符串，否则它将是一个包含以 DER 编码的数据的缓冲区。

crypto.generateKeySync(type, options)#

添加于：v15.0.0
  • type: <string> 生成的密钥的预期用途。目前接受的值为 'hmac' 和 'aes'。
  • options: <Object>
    • length: <number> 要生成的密钥的位长度。
      • 如果 type 为 'hmac'，则最小值为 8，最大长度为 231-1。如果该值不是 8 的倍数，则生成的密钥将被截断为 Math.floor(length / 8)。
      • 如果 type 为 'aes'，则长度必须为 128、192 或 256 之一。
  • 返回：<KeyObject>

同步生成一个新的随机密钥，长度为给定的 length。type 将决定对 length 执行哪些验证。

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

const key = generateKeySync('hmac', { length: 512 });
console.log(key.export().toString('hex'));  // e89..........41econst {
  generateKeySync,
} = require('node:crypto');

const key = generateKeySync('hmac', { length: 512 });
console.log(key.export().toString('hex'));  // e89..........41e

生成的 HMAC 密钥的大小不应超过底层哈希函数的块大小。有关更多信息，请参见 crypto.createHmac()。

crypto.generatePrime(size[, options[, callback]])#

历史
版本更改
v18.0.0

将无效回调传递给 callback 参数现在会抛出 ERR_INVALID_ARG_TYPE 而不是 ERR_INVALID_CALLBACK。

v15.8.0

添加于: v15.8.0

生成一个 size 位的伪随机素数。

如果 options.safe 为 true，则素数将为安全素数 - 也就是说，(prime - 1) / 2 也将为素数。

options.add 和 options.rem 参数可用于强制执行其他要求，例如用于 Diffie-Hellman。

  • 如果同时设置了 options.add 和 options.rem，则素数将满足条件 prime % add = rem。
  • 如果仅设置了 options.add 且 options.safe 不为 true，则素数将满足条件 prime % add = 1。
  • 如果仅设置了 options.add 且 options.safe 设置为 true，则素数将满足条件 prime % add = 3。这是必要的，因为对于 options.add > 2，prime % add = 1 将与 options.safe 强制执行的条件相矛盾。
  • 如果未给出 options.add，则忽略 options.rem。

如果作为 ArrayBuffer、SharedArrayBuffer、TypedArray、Buffer 或 DataView 给出，则 options.add 和 options.rem 都必须以大端序序列编码。

默认情况下，素数以大端序的八位字节序列编码，存储在 <ArrayBuffer> 中。如果 bigint 选项为 true，则提供 <bigint>。

crypto.generatePrimeSync(size[, options])#

添加于: v15.8.0

生成一个 size 位的伪随机素数。

如果 options.safe 为 true，则素数将为安全素数 - 也就是说，(prime - 1) / 2 也将为素数。

options.add 和 options.rem 参数可用于强制执行其他要求，例如用于 Diffie-Hellman。

  • 如果同时设置了 options.add 和 options.rem，则素数将满足条件 prime % add = rem。
  • 如果仅设置了 options.add 且 options.safe 不为 true，则素数将满足条件 prime % add = 1。
  • 如果仅设置了 options.add 且 options.safe 设置为 true，则素数将满足条件 prime % add = 3。这是必要的，因为对于 options.add > 2，prime % add = 1 将与 options.safe 强制执行的条件相矛盾。
  • 如果未给出 options.add，则忽略 options.rem。

如果作为 ArrayBuffer、SharedArrayBuffer、TypedArray、Buffer 或 DataView 给出，则 options.add 和 options.rem 都必须以大端序序列编码。

默认情况下，素数以大端序的八位字节序列编码，存储在 <ArrayBuffer> 中。如果 bigint 选项为 true，则提供 <bigint>。

crypto.getCipherInfo(nameOrNid[, options])#

添加于：v15.0.0
  • nameOrNid: <string> | <number> 要查询的密码的名称或 nid。
  • options: <Object>
    • keyLength: <number> 测试密钥长度。
    • ivLength: <number> 测试 IV 长度。
  • 返回：<Object>
    • name <string> 密码的名称
    • nid <number> 密码的 nid
    • blockSize <number> 密码的块大小（以字节为单位）。当 mode 为 'stream' 时，此属性将被省略。
    • ivLength <number> 预期或默认的初始化向量长度（以字节为单位）。如果密码不使用初始化向量，则此属性将被省略。
    • keyLength <number> 预期或默认的密钥长度（以字节为单位）。
    • mode <string> 密码模式。其中之一：'cbc'、'ccm'、'cfb'、'ctr'、'ecb'、'gcm'、'ocb'、'ofb'、'stream'、'wrap'、'xts'。

返回有关给定密码的信息。

某些密码接受可变长度的密钥和初始化向量。默认情况下，crypto.getCipherInfo() 方法将返回这些密码的默认值。要测试给定密钥长度或 iv 长度是否对给定密码可接受，请使用 keyLength 和 ivLength 选项。如果给定的值不可接受，则将返回 undefined。

crypto.getCiphers()#

添加于: v0.9.3
  • 返回：<string[]> 包含支持的密码算法名称的数组。
const {
  getCiphers,
} = await import('node:crypto');

console.log(getCiphers()); // ['aes-128-cbc', 'aes-128-ccm', ...]const {
  getCiphers,
} = require('node:crypto');

console.log(getCiphers()); // ['aes-128-cbc', 'aes-128-ccm', ...]

crypto.getCurves()#

添加于：v2.3.0
  • 返回值：<string[]> 包含支持的椭圆曲线名称的数组。
const {
  getCurves,
} = await import('node:crypto');

console.log(getCurves()); // ['Oakley-EC2N-3', 'Oakley-EC2N-4', ...]const {
  getCurves,
} = require('node:crypto');

console.log(getCurves()); // ['Oakley-EC2N-3', 'Oakley-EC2N-4', ...]

crypto.getDiffieHellman(groupName)#

添加于：v0.7.5

创建一个预定义的 DiffieHellmanGroup 密钥交换对象。支持的组在 DiffieHellmanGroup 的文档中列出。

返回的对象模拟了由 crypto.createDiffieHellman() 创建的对象的接口，但不会允许更改密钥（例如，使用 diffieHellman.setPublicKey()）。使用此方法的优点是，各方无需事先生成或交换组模数，从而节省了处理器和通信时间。

示例（获取共享密钥）

const {
  getDiffieHellman,
} = await import('node:crypto');
const alice = getDiffieHellman('modp14');
const bob = getDiffieHellman('modp14');

alice.generateKeys();
bob.generateKeys();

const aliceSecret = alice.computeSecret(bob.getPublicKey(), null, 'hex');
const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex');

/* aliceSecret and bobSecret should be the same */
console.log(aliceSecret === bobSecret);const {
  getDiffieHellman,
} = require('node:crypto');

const alice = getDiffieHellman('modp14');
const bob = getDiffieHellman('modp14');

alice.generateKeys();
bob.generateKeys();

const aliceSecret = alice.computeSecret(bob.getPublicKey(), null, 'hex');
const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex');

/* aliceSecret and bobSecret should be the same */
console.log(aliceSecret === bobSecret);

crypto.getFips()#

添加于：v10.0.0
  • 返回值：<number> 当且仅当当前使用符合 FIPS 的加密提供程序时返回 1，否则返回 0。未来的主要版本可能会将此 API 的返回类型更改为 <boolean>。

crypto.getHashes()#

添加于: v0.9.3
  • 返回值：<string[]> 包含支持的哈希算法名称的数组，例如 'RSA-SHA256'。哈希算法也称为“摘要”算法。
const {
  getHashes,
} = await import('node:crypto');

console.log(getHashes()); // ['DSA', 'DSA-SHA', 'DSA-SHA1', ...]const {
  getHashes,
} = require('node:crypto');

console.log(getHashes()); // ['DSA', 'DSA-SHA', 'DSA-SHA1', ...]

crypto.getRandomValues(typedArray)#

添加于：v17.4.0

这是 crypto.webcrypto.getRandomValues() 的一个便捷别名。此实现不符合 Web Crypto 规范，要编写与 Web 兼容的代码，请使用 crypto.webcrypto.getRandomValues()。

crypto.hkdf(digest, ikm, salt, info, keylen, callback)#

历史
版本更改
v18.0.0

将无效回调传递给 callback 参数现在会抛出 ERR_INVALID_ARG_TYPE 而不是 ERR_INVALID_CALLBACK。

v18.8.0, v16.18.0

输入密钥材料现在可以为零长度。

v15.0.0

添加于：v15.0.0

HKDF 是一种简单的密钥派生函数，定义在 RFC 5869 中。给定的 ikm、salt 和 info 与 digest 一起使用，用于派生 keylen 字节的密钥。

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

import { Buffer } from 'node:buffer';
const {
  hkdf,
} = await import('node:crypto');

hkdf('sha512', 'key', 'salt', 'info', 64, (err, derivedKey) => {
  if (err) throw err;
  console.log(Buffer.from(derivedKey).toString('hex'));  // '24156e2...5391653'
});const {
  hkdf,
} = require('node:crypto');
const { Buffer } = require('node:buffer');

hkdf('sha512', 'key', 'salt', 'info', 64, (err, derivedKey) => {
  if (err) throw err;
  console.log(Buffer.from(derivedKey).toString('hex'));  // '24156e2...5391653'
});

crypto.hkdfSync(digest, ikm, salt, info, keylen)#

历史
版本更改
v18.8.0, v16.18.0

输入密钥材料现在可以为零长度。

v15.0.0

添加于：v15.0.0

提供一个同步 HKDF 密钥派生函数，如 RFC 5869 中所定义。给定的 ikm、salt 和 info 与 digest 一起使用，用于派生 keylen 字节的密钥。

成功生成的 derivedKey 将作为 <ArrayBuffer> 返回。

如果任何输入参数指定了无效的值或类型，或者无法生成派生密钥，将抛出错误。

import { Buffer } from 'node:buffer';
const {
  hkdfSync,
} = await import('node:crypto');

const derivedKey = hkdfSync('sha512', 'key', 'salt', 'info', 64);
console.log(Buffer.from(derivedKey).toString('hex'));  // '24156e2...5391653'const {
  hkdfSync,
} = require('node:crypto');
const { Buffer } = require('node:buffer');

const derivedKey = hkdfSync('sha512', 'key', 'salt', 'info', 64);
console.log(Buffer.from(derivedKey).toString('hex'));  // '24156e2...5391653'

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 参数现在限制为正值。早期版本将其他值视为 1。

v8.0.0

digest 参数现在始终是必需的。

v6.0.0

现在不传递 digest 参数调用此函数已弃用，并将发出警告。

v6.0.0

如果 password 是字符串，其默认编码已从 binary 更改为 utf8。

v0.5.5

添加于：v0.5.5

提供异步密码基密钥派生函数 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.getHashes() 检索支持的摘要函数数组。

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

crypto.pbkdf2Sync(password, salt, iterations, keylen, digest)#

历史
版本更改
v14.0.0

iterations 参数现在限制为正值。早期版本将其他值视为 1。

v6.0.0

现在不传递 digest 参数调用此函数已弃用，并将发出警告。

v6.0.0

如果 password 是字符串，其默认编码已从 binary 更改为 utf8。

v0.9.3

添加于: v0.9.3

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

如果发生错误，则会抛出 Error，否则会将派生密钥作为 Buffer 返回。

iterations 参数必须是一个尽可能高的数字。迭代次数越高，派生密钥越安全，但完成所需的时间越长。

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

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

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

const key = pbkdf2Sync('secret', 'salt', 100000, 64, 'sha512');
console.log(key.toString('hex'));  // '3745e48...08d59ae'const {
  pbkdf2Sync,
} = require('node:crypto');

const key = pbkdf2Sync('secret', 'salt', 100000, 64, 'sha512');
console.log(key.toString('hex'));  // '3745e48...08d59ae'

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

crypto.privateDecrypt(privateKey, buffer)#

历史
版本更改
v21.6.2、v20.11.1、v18.19.1

除非 OpenSSL 构建支持隐式拒绝，否则 RSA_PKCS1_PADDING 填充将被禁用。

v15.0.0

添加字符串、ArrayBuffer 和 CryptoKey 作为允许的密钥类型。oaepLabel 可以是 ArrayBuffer。缓冲区可以是字符串或 ArrayBuffer。所有接受缓冲区的类型都限制为最大 2 ** 31 - 1 字节。

v12.11.0

添加了 oaepLabel 选项。

v12.9.0

添加了 oaepHash 选项。

v11.6.0

此函数现在支持密钥对象。

v0.11.14

添加于：v0.11.14

使用 privateKey 解密 buffer。buffer 之前使用相应的公钥加密，例如使用 crypto.publicEncrypt()。

如果 privateKey 不是 KeyObject，则此函数的行为就像 privateKey 已传递给 crypto.createPrivateKey() 一样。如果它是对象，则可以传递 padding 属性。否则，此函数使用 RSA_PKCS1_OAEP_PADDING。

在 crypto.privateDecrypt() 中使用 crypto.constants.RSA_PKCS1_PADDING 需要 OpenSSL 支持隐式拒绝 (rsa_pkcs1_implicit_rejection)。如果 Node.js 使用的 OpenSSL 版本不支持此功能，则尝试使用 RSA_PKCS1_PADDING 将失败。

crypto.privateEncrypt(privateKey, buffer)#

历史
版本更改
v15.0.0

添加了字符串、ArrayBuffer 和 CryptoKey 作为允许的密钥类型。密码可以是 ArrayBuffer。缓冲区可以是字符串或 ArrayBuffer。所有接受缓冲区的类型都限制为最大 2 ** 31 - 1 字节。

v11.6.0

此函数现在支持密钥对象。

v1.1.0

添加于：v1.1.0

使用 privateKey 加密 buffer。返回的数据可以使用相应的公钥解密，例如使用 crypto.publicDecrypt()。

如果 privateKey 不是 KeyObject，则此函数的行为就像 privateKey 已传递给 crypto.createPrivateKey() 一样。如果它是对象，则可以传递 padding 属性。否则，此函数使用 RSA_PKCS1_PADDING。

crypto.publicDecrypt(key, buffer)#

历史
版本更改
v15.0.0

添加了字符串、ArrayBuffer 和 CryptoKey 作为允许的密钥类型。密码可以是 ArrayBuffer。缓冲区可以是字符串或 ArrayBuffer。所有接受缓冲区的类型都限制为最大 2 ** 31 - 1 字节。

v11.6.0

此函数现在支持密钥对象。

v1.1.0

添加于：v1.1.0

使用 key 解密 buffer。buffer 之前使用相应的私钥加密，例如使用 crypto.privateEncrypt()。

如果 key 不是 KeyObject，则此函数的行为就像将 key 传递给 crypto.createPublicKey() 一样。如果它是一个对象，则可以传递 padding 属性。否则，此函数使用 RSA_PKCS1_PADDING。

由于 RSA 公钥可以从私钥派生，因此可以传递私钥而不是公钥。

crypto.publicEncrypt(key, buffer)#

历史
版本更改
v15.0.0

添加了字符串、ArrayBuffer 和 CryptoKey 作为允许的密钥类型。oaepLabel 和 passphrase 可以是 ArrayBuffer。buffer 可以是字符串或 ArrayBuffer。所有接受缓冲区的类型都限制为最大 2 ** 31 - 1 字节。

v12.11.0

添加了 oaepLabel 选项。

v12.9.0

添加了 oaepHash 选项。

v11.6.0

此函数现在支持密钥对象。

v0.11.14

添加于：v0.11.14

使用 key 加密 buffer 的内容，并返回一个包含加密内容的新 Buffer。可以使用相应的私钥解密返回的数据，例如使用 crypto.privateDecrypt()。

如果 key 不是 KeyObject，则此函数的行为就像将 key 传递给 crypto.createPublicKey() 一样。如果它是一个对象，则可以传递 padding 属性。否则，此函数使用 RSA_PKCS1_OAEP_PADDING。

由于 RSA 公钥可以从私钥派生，因此可以传递私钥而不是公钥。

crypto.randomBytes(size[, callback])#

历史
版本更改
v18.0.0

将无效回调传递给 callback 参数现在会抛出 ERR_INVALID_ARG_TYPE 而不是 ERR_INVALID_CALLBACK。

v9.0.0

现在将 null 作为 callback 参数传递将抛出 ERR_INVALID_CALLBACK。

v0.5.8

添加于：v0.5.8

生成密码学强伪随机数据。size参数是一个数字，表示要生成的字节数。

如果提供了callback函数，则异步生成字节，并使用两个参数调用callback函数：err和buf。如果发生错误，err将是一个Error对象；否则为null。buf参数是一个包含生成字节的Buffer。

// Asynchronous
const {
  randomBytes,
} = await import('node:crypto');

randomBytes(256, (err, buf) => {
  if (err) throw err;
  console.log(`${buf.length} bytes of random data: ${buf.toString('hex')}`);
});// Asynchronous
const {
  randomBytes,
} = require('node:crypto');

randomBytes(256, (err, buf) => {
  if (err) throw err;
  console.log(`${buf.length} bytes of random data: ${buf.toString('hex')}`);
});

如果未提供callback函数，则同步生成随机字节，并作为Buffer返回。如果生成字节时出现问题，将抛出错误。

// Synchronous
const {
  randomBytes,
} = await import('node:crypto');

const buf = randomBytes(256);
console.log(
  `${buf.length} bytes of random data: ${buf.toString('hex')}`);// Synchronous
const {
  randomBytes,
} = require('node:crypto');

const buf = randomBytes(256);
console.log(
  `${buf.length} bytes of random data: ${buf.toString('hex')}`);

crypto.randomBytes()方法在有足够的熵可用之前不会完成。这通常不会超过几毫秒。唯一可能导致生成随机字节阻塞更长时间的情况是在启动后立即，此时整个系统仍然熵不足。

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

crypto.randomBytes()的异步版本在单个线程池请求中执行。为了最大限度地减少线程池任务长度的变化，在将大型randomBytes请求作为满足客户端请求的一部分进行时，请对其进行分区。

crypto.randomFillSync(buffer[, offset][, size])#

历史
版本更改
v9.0.0

buffer参数可以是任何TypedArray或DataView。

v7.10.0, v6.13.0

添加于：v7.10.0, v6.13.0

crypto.randomFill()的同步版本。

import { Buffer } from 'node:buffer';
const { randomFillSync } = await import('node:crypto');

const buf = Buffer.alloc(10);
console.log(randomFillSync(buf).toString('hex'));

randomFillSync(buf, 5);
console.log(buf.toString('hex'));

// The above is equivalent to the following:
randomFillSync(buf, 5, 5);
console.log(buf.toString('hex'));const { randomFillSync } = require('node:crypto');
const { Buffer } = require('node:buffer');

const buf = Buffer.alloc(10);
console.log(randomFillSync(buf).toString('hex'));

randomFillSync(buf, 5);
console.log(buf.toString('hex'));

// The above is equivalent to the following:
randomFillSync(buf, 5, 5);
console.log(buf.toString('hex'));

任何ArrayBuffer、TypedArray或DataView实例都可以作为buffer传递。

import { Buffer } from 'node:buffer';
const { randomFillSync } = await import('node:crypto');

const a = new Uint32Array(10);
console.log(Buffer.from(randomFillSync(a).buffer,
                        a.byteOffset, a.byteLength).toString('hex'));

const b = new DataView(new ArrayBuffer(10));
console.log(Buffer.from(randomFillSync(b).buffer,
                        b.byteOffset, b.byteLength).toString('hex'));

const c = new ArrayBuffer(10);
console.log(Buffer.from(randomFillSync(c)).toString('hex'));const { randomFillSync } = require('node:crypto');
const { Buffer } = require('node:buffer');

const a = new Uint32Array(10);
console.log(Buffer.from(randomFillSync(a).buffer,
                        a.byteOffset, a.byteLength).toString('hex'));

const b = new DataView(new ArrayBuffer(10));
console.log(Buffer.from(randomFillSync(b).buffer,
                        b.byteOffset, b.byteLength).toString('hex'));

const c = new ArrayBuffer(10);
console.log(Buffer.from(randomFillSync(c)).toString('hex'));

crypto.randomFill(buffer[, offset][, size], callback)#

历史
版本更改
v18.0.0

将无效回调传递给 callback 参数现在会抛出 ERR_INVALID_ARG_TYPE 而不是 ERR_INVALID_CALLBACK。

v9.0.0

buffer参数可以是任何TypedArray或DataView。

v7.10.0, v6.13.0

添加于：v7.10.0, v6.13.0

此函数类似于 crypto.randomBytes()，但要求第一个参数为将要填充的 Buffer。它还要求传入回调函数。

如果未提供 callback 函数，则会抛出错误。

import { Buffer } from 'node:buffer';
const { randomFill } = await import('node:crypto');

const buf = Buffer.alloc(10);
randomFill(buf, (err, buf) => {
  if (err) throw err;
  console.log(buf.toString('hex'));
});

randomFill(buf, 5, (err, buf) => {
  if (err) throw err;
  console.log(buf.toString('hex'));
});

// The above is equivalent to the following:
randomFill(buf, 5, 5, (err, buf) => {
  if (err) throw err;
  console.log(buf.toString('hex'));
});const { randomFill } = require('node:crypto');
const { Buffer } = require('node:buffer');

const buf = Buffer.alloc(10);
randomFill(buf, (err, buf) => {
  if (err) throw err;
  console.log(buf.toString('hex'));
});

randomFill(buf, 5, (err, buf) => {
  if (err) throw err;
  console.log(buf.toString('hex'));
});

// The above is equivalent to the following:
randomFill(buf, 5, 5, (err, buf) => {
  if (err) throw err;
  console.log(buf.toString('hex'));
});

任何 ArrayBuffer、TypedArray 或 DataView 实例都可以作为 buffer 传入。

虽然这包括 Float32Array 和 Float64Array 的实例，但此函数不应用于生成随机浮点数。结果可能包含 +Infinity、-Infinity 和 NaN，即使数组仅包含有限数字，它们也不是从均匀随机分布中抽取的，并且没有有意义的下限或上限。

import { Buffer } from 'node:buffer';
const { randomFill } = await import('node:crypto');

const a = new Uint32Array(10);
randomFill(a, (err, buf) => {
  if (err) throw err;
  console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength)
    .toString('hex'));
});

const b = new DataView(new ArrayBuffer(10));
randomFill(b, (err, buf) => {
  if (err) throw err;
  console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength)
    .toString('hex'));
});

const c = new ArrayBuffer(10);
randomFill(c, (err, buf) => {
  if (err) throw err;
  console.log(Buffer.from(buf).toString('hex'));
});const { randomFill } = require('node:crypto');
const { Buffer } = require('node:buffer');

const a = new Uint32Array(10);
randomFill(a, (err, buf) => {
  if (err) throw err;
  console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength)
    .toString('hex'));
});

const b = new DataView(new ArrayBuffer(10));
randomFill(b, (err, buf) => {
  if (err) throw err;
  console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength)
    .toString('hex'));
});

const c = new ArrayBuffer(10);
randomFill(c, (err, buf) => {
  if (err) throw err;
  console.log(Buffer.from(buf).toString('hex'));
});

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

crypto.randomFill() 的异步版本在单个线程池请求中执行。为了最大程度地减少线程池任务长度的变化，在将此作为满足客户端请求的一部分时，将大型 randomFill 请求进行分区。

crypto.randomInt([min, ]max[, callback])#

历史
版本更改
v18.0.0

将无效回调传递给 callback 参数现在会抛出 ERR_INVALID_ARG_TYPE 而不是 ERR_INVALID_CALLBACK。

v14.10.0, v12.19.0

添加于：v14.10.0, v12.19.0

  • min <integer> 随机范围的开始（包含）。默认值： 0。
  • max <integer> 随机范围的结束（不包含）。
  • callback <Function> function(err, n) {}.

返回一个随机整数 n，使得 min <= n < max。此实现避免了 模偏差。

范围 (max - min) 必须小于 248。min 和 max 必须是 安全整数。

如果未提供 callback 函数，则会同步生成随机整数。

// Asynchronous
const {
  randomInt,
} = await import('node:crypto');

randomInt(3, (err, n) => {
  if (err) throw err;
  console.log(`Random number chosen from (0, 1, 2): ${n}`);
});// Asynchronous
const {
  randomInt,
} = require('node:crypto');

randomInt(3, (err, n) => {
  if (err) throw err;
  console.log(`Random number chosen from (0, 1, 2): ${n}`);
});
// Synchronous
const {
  randomInt,
} = await import('node:crypto');

const n = randomInt(3);
console.log(`Random number chosen from (0, 1, 2): ${n}`);// Synchronous
const {
  randomInt,
} = require('node:crypto');

const n = randomInt(3);
console.log(`Random number chosen from (0, 1, 2): ${n}`);
// With `min` argument
const {
  randomInt,
} = await import('node:crypto');

const n = randomInt(1, 7);
console.log(`The dice rolled: ${n}`);// With `min` argument
const {
  randomInt,
} = require('node:crypto');

const n = randomInt(1, 7);
console.log(`The dice rolled: ${n}`);

crypto.randomUUID([options])#

新增于：v15.6.0, v14.17.0
  • options <Object>
    • disableEntropyCache <boolean> 默认情况下，为了提高性能，Node.js 会生成并缓存足够多的随机数据，以生成最多 128 个随机 UUID。要生成不使用缓存的 UUID，请将 disableEntropyCache 设置为 true。默认值： false。
  • 返回值：<string>

生成一个随机的 RFC 4122 版本 4 UUID。UUID 使用密码学伪随机数生成器生成。

crypto.scrypt(password, salt, keylen[, options], callback)#

历史
版本更改
v18.0.0

将无效回调传递给 callback 参数现在会抛出 ERR_INVALID_ARG_TYPE 而不是 ERR_INVALID_CALLBACK。

v15.0.0

密码和盐参数也可以是 ArrayBuffer 实例。

v12.8.0, v10.17.0

maxmem 值现在可以是任何安全整数。

v10.9.0

已添加 cost、blockSize 和 parallelization 选项名称。

v10.5.0

新增于：v10.5.0

提供异步 scrypt 实现。Scrypt 是一种基于密码的密钥派生函数，旨在计算和内存方面都很昂贵，以使暴力攻击得不偿失。

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

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

callback 函数使用两个参数调用：err 和 derivedKey。err 是密钥派生失败时的异常对象，否则 err 为 null。derivedKey 作为 Buffer 传递给回调函数。

当任何输入参数指定无效值或类型时，将抛出异常。

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

// Using the factory defaults.
scrypt('password', 'salt', 64, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...08d59ae'
});
// Using a custom N parameter. Must be a power of two.
scrypt('password', 'salt', 64, { N: 1024 }, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...aa39b34'
});const {
  scrypt,
} = require('node:crypto');

// Using the factory defaults.
scrypt('password', 'salt', 64, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...08d59ae'
});
// Using a custom N parameter. Must be a power of two.
scrypt('password', 'salt', 64, { N: 1024 }, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...aa39b34'
});

crypto.scryptSync(password, salt, keylen[, options])#

历史
版本更改
v12.8.0, v10.17.0

maxmem 值现在可以是任何安全整数。

v10.9.0

已添加 cost、blockSize 和 parallelization 选项名称。

v10.5.0

新增于：v10.5.0

提供同步 scrypt 实现。Scrypt 是一种基于密码的密钥派生函数，旨在计算和内存方面都很昂贵，以使暴力攻击得不偿失。

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

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

密钥派生失败时会抛出异常，否则会将派生的密钥作为 Buffer 返回。

当任何输入参数指定无效值或类型时，将抛出异常。

const {
  scryptSync,
} = await import('node:crypto');
// Using the factory defaults.

const key1 = scryptSync('password', 'salt', 64);
console.log(key1.toString('hex'));  // '3745e48...08d59ae'
// Using a custom N parameter. Must be a power of two.
const key2 = scryptSync('password', 'salt', 64, { N: 1024 });
console.log(key2.toString('hex'));  // '3745e48...aa39b34'const {
  scryptSync,
} = require('node:crypto');
// Using the factory defaults.

const key1 = scryptSync('password', 'salt', 64);
console.log(key1.toString('hex'));  // '3745e48...08d59ae'
// Using a custom N parameter. Must be a power of two.
const key2 = scryptSync('password', 'salt', 64, { N: 1024 });
console.log(key2.toString('hex'));  // '3745e48...aa39b34'

crypto.secureHeapUsed()#

添加于：v15.6.0
  • 返回：<Object>
    • total <number> 使用 --secure-heap=n 命令行标志指定的总分配安全堆大小。
    • min <number> 使用 --secure-heap-min 命令行标志指定的来自安全堆的最小分配。
    • used <number> 当前从安全堆分配的总字节数。
    • utilization <number> 计算出的 used 与 total 分配字节的比率。

crypto.setEngine(engine[, flags])#

添加于：v0.11.11

加载并设置 engine 用于某些或所有 OpenSSL 函数（由 flags 选择）。

engine 可以是引擎的共享库的 ID 或路径。

可选的 flags 参数默认使用 ENGINE_METHOD_ALL。flags 是一个位域，它接受以下标志之一或混合（在 crypto.constants 中定义）

  • crypto.constants.ENGINE_METHOD_RSA
  • crypto.constants.ENGINE_METHOD_DSA
  • crypto.constants.ENGINE_METHOD_DH
  • crypto.constants.ENGINE_METHOD_RAND
  • crypto.constants.ENGINE_METHOD_EC
  • crypto.constants.ENGINE_METHOD_CIPHERS
  • crypto.constants.ENGINE_METHOD_DIGESTS
  • crypto.constants.ENGINE_METHOD_PKEY_METHS
  • crypto.constants.ENGINE_METHOD_PKEY_ASN1_METHS
  • crypto.constants.ENGINE_METHOD_ALL
  • crypto.constants.ENGINE_METHOD_NONE

crypto.setFips(bool)#

添加于：v10.0.0
  • bool <boolean> true 以启用 FIPS 模式。

在启用了 FIPS 的 Node.js 构建中启用符合 FIPS 的加密提供程序。如果 FIPS 模式不可用，则会抛出错误。

crypto.sign(algorithm, data, key[, callback])#

历史
版本更改
v18.0.0

将无效回调传递给 callback 参数现在会抛出 ERR_INVALID_ARG_TYPE 而不是 ERR_INVALID_CALLBACK。

v15.12.0

添加了可选的回调参数。

v13.2.0, v12.16.0

此函数现在支持 IEEE-P1363 DSA 和 ECDSA 签名。

v12.0.0

添加于：v12.0.0

使用给定的私钥和算法计算并返回 data 的签名。如果 algorithm 为 null 或 undefined，则算法取决于密钥类型（尤其是 Ed25519 和 Ed448）。

如果 key 不是 KeyObject，则此函数的行为就像 key 已传递给 crypto.createPrivateKey() 一样。如果它是一个对象，则可以传递以下附加属性

  • dsaEncoding <string> 对于 DSA 和 ECDSA，此选项指定生成的签名的格式。它可以是以下之一

    • 'der' (默认)：DER 编码的 ASN.1 签名结构编码 (r, s)。
    • 'ieee-p1363'：签名格式 r || s，如 IEEE-P1363 中所述。

  • padding <integer> RSA 的可选填充值，以下之一

    • crypto.constants.RSA_PKCS1_PADDING (默认)
    • crypto.constants.RSA_PKCS1_PSS_PADDING

    RSA_PKCS1_PSS_PADDING 将使用 MGF1，并使用与用于签署消息的相同哈希函数，如 RFC 4055 第 3.1 节中所述。

  • saltLength <integer> 当填充为 RSA_PKCS1_PSS_PADDING 时的盐长度。特殊值 crypto.constants.RSA_PSS_SALTLEN_DIGEST 将盐长度设置为摘要大小，crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (默认) 将其设置为最大允许值。

如果提供了 callback 函数，则此函数使用 libuv 的线程池。

crypto.subtle#

添加于：v17.4.0

crypto.webcrypto.subtle 的便捷别名。

crypto.timingSafeEqual(a, b)#

历史
版本更改
v15.0.0

a 和 b 参数也可以是 ArrayBuffer。

v6.6.0

添加于：v6.6.0

此函数使用恒定时间算法比较表示给定ArrayBuffer、TypedArray或DataView实例的底层字节。

此函数不会泄露时间信息，这些信息可能允许攻击者猜测其中一个值。这适用于比较HMAC摘要或秘密值，例如身份验证cookie或功能URL。

a和b必须都是Buffer、TypedArray或DataView，并且它们必须具有相同的字节长度。如果a和b具有不同的字节长度，则会抛出错误。

如果a和b中至少有一个是每个条目超过一个字节的TypedArray，例如Uint16Array，则结果将使用平台字节序计算。

当两个输入都是Float32Array或Float64Array时，此函数可能会返回意外结果，因为浮点数的IEEE 754编码。特别是，x === y或Object.is(x, y)并不意味着两个浮点数x和y的字节表示是相等的。

使用crypto.timingSafeEqual不能保证周围代码是时序安全的。应注意确保周围代码不会引入时序漏洞。

crypto.verify(algorithm, data, key, signature[, callback])#

历史
版本更改
v18.0.0

将无效回调传递给 callback 参数现在会抛出 ERR_INVALID_ARG_TYPE 而不是 ERR_INVALID_CALLBACK。

v15.12.0

添加了可选的回调参数。

v15.0.0

data、key和signature参数也可以是ArrayBuffer。

v13.2.0, v12.16.0

此函数现在支持 IEEE-P1363 DSA 和 ECDSA 签名。

v12.0.0

添加于：v12.0.0

使用给定的密钥和算法验证给定数据的签名。如果algorithm为null或undefined，则算法取决于密钥类型（尤其是Ed25519和Ed448）。

如果key不是KeyObject，则此函数的行为就好像key已传递给crypto.createPublicKey()。如果它是一个对象，则可以传递以下附加属性

  • dsaEncoding <string> 对于 DSA 和 ECDSA，此选项指定签名的格式。它可以是以下之一

    • 'der' (默认)：DER 编码的 ASN.1 签名结构编码 (r, s)。
    • 'ieee-p1363'：签名格式 r || s，如 IEEE-P1363 中所述。

  • padding <integer> RSA 的可选填充值，以下之一

    • crypto.constants.RSA_PKCS1_PADDING (默认)
    • crypto.constants.RSA_PKCS1_PSS_PADDING

    RSA_PKCS1_PSS_PADDING 将使用 MGF1，并使用与用于签署消息的相同哈希函数，如 RFC 4055 第 3.1 节中所述。

  • saltLength <integer> 当填充为 RSA_PKCS1_PSS_PADDING 时的盐长度。特殊值 crypto.constants.RSA_PSS_SALTLEN_DIGEST 将盐长度设置为摘要大小，crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (默认) 将其设置为最大允许值。

signature参数是先前为data计算的签名。

由于可以从私钥派生公钥，因此可以将私钥或公钥传递给key。

如果提供了 callback 函数，则此函数使用 libuv 的线程池。

crypto.webcrypto#

添加于：v15.0.0

类型：<Crypto> Web Crypto API 标准的实现。

有关详细信息，请参阅Web Crypto API 文档。

备注#

将字符串用作加密 API 的输入#

出于历史原因，Node.js 提供的许多加密 API 接受字符串作为输入，而底层加密算法在字节序列上运行。这些实例包括明文、密文、对称密钥、初始化向量、密码短语、盐、身份验证标签和附加身份验证数据。

将字符串传递给加密 API 时，请考虑以下因素。

  • 并非所有字节序列都是有效的 UTF-8 字符串。因此，当从字符串派生长度为n的字节序列时，其熵通常低于随机或伪随机n字节序列的熵。例如，没有 UTF-8 字符串会导致字节序列c0 af。密钥应几乎完全是随机或伪随机字节序列。

  • 类似地，将随机或伪随机字节序列转换为 UTF-8 字符串时，不代表有效代码点的子序列可能会被 Unicode 替换字符 (U+FFFD) 替换。因此，生成的 Unicode 字符串的字节表示可能不等于创建该字符串的字节序列。

    const original = [0xc0, 0xaf];
const bytesAsString = Buffer.from(original).toString('utf8');
const stringAsBytes = Buffer.from(bytesAsString, 'utf8');
console.log(stringAsBytes);
// Prints '<Buffer ef bf bd ef bf bd>'.

    密码、哈希函数、签名算法和密钥派生函数的输出是伪随机字节序列，不应作为 Unicode 字符串使用。

  • 当从用户输入获取字符串时，某些 Unicode 字符可以用多种等效方式表示，从而导致不同的字节序列。例如，将用户密码短语传递给密钥派生函数（如 PBKDF2 或 scrypt）时，密钥派生函数的结果取决于字符串使用的是组合字符还是分解字符。Node.js 不会规范化字符表示。开发人员应考虑在将用户输入传递给加密 API 之前，使用String.prototype.normalize()。

旧版流 API（在 Node.js 0.10 之前）#

Crypto 模块是在 Node.js 出现统一流 API 和用于处理二进制数据的 Buffer 对象之前添加的。因此，许多 crypto 类具有在其他实现 流 API 的 Node.js 类中通常找不到的方法（例如 update()、final() 或 digest()）。此外，许多方法默认情况下接受和返回 'latin1' 编码的字符串，而不是 Buffer。此默认值在 Node.js v0.8 之后更改为默认情况下使用 Buffer 对象。

对弱算法或已破解算法的支持#

node:crypto 模块仍然支持一些已经被破解并且不建议使用的算法。该 API 还允许使用密钥大小过小的密码和哈希，这些密码和哈希对于安全使用来说太弱了。

用户应根据其安全要求对选择加密算法和密钥大小负全部责任。

根据 NIST SP 800-131A 的建议

  • 在需要抗碰撞性的情况下，例如数字签名，MD5 和 SHA-1 不再被接受。
  • 建议用于 RSA、DSA 和 DH 算法的密钥至少有 2048 位，ECDSA 和 ECDH 的曲线至少有 224 位，才能在未来几年内安全使用。
  • modp1、modp2 和 modp5 的 DH 组的密钥大小小于 2048 位，不建议使用。

有关其他建议和详细信息，请参阅参考。

一些具有已知弱点并且在实践中几乎没有意义的算法只能通过 传统提供程序 获得，该提供程序默认情况下未启用。

CCM 模式#

CCM 是支持的 AEAD 算法 之一。使用此模式的应用程序在使用密码 API 时必须遵守某些限制。

  • 身份验证标签长度必须在创建密码时通过设置 authTagLength 选项来指定，并且必须是 4、6、8、10、12、14 或 16 字节之一。
  • 初始化向量 (nonce) N 的长度必须在 7 到 13 字节之间 (7 ≤ N ≤ 13)。
  • 明文的长度限制为 2 ** (8 * (15 - N)) 字节。
  • 在解密时，必须在调用 update() 之前通过 setAuthTag() 设置身份验证标签。否则，解密将失败，并且 final() 将根据 RFC 3610 的第 2.6 节抛出错误。
  • 在 CCM 模式下使用流方法，例如 write(data)、end(data) 或 pipe()，可能会失败，因为 CCM 无法处理每个实例超过一个数据块。
  • 当传递额外的身份验证数据 (AAD) 时，必须通过 plaintextLength 选项将实际消息的字节长度传递给 setAAD()。许多加密库将身份验证标签包含在密文中，这意味着它们会生成长度为 plaintextLength + authTagLength 的密文。Node.js 不包含身份验证标签，因此密文长度始终为 plaintextLength。如果未使用 AAD，则无需执行此操作。
  • 由于 CCM 同时处理整个消息，因此 update() 必须恰好调用一次。
  • 即使调用 update() 足以加密/解密消息，应用程序也必须调用 final() 来计算或验证身份验证标签。
import { Buffer } from 'node:buffer';
const {
  createCipheriv,
  createDecipheriv,
  randomBytes,
} = await import('node:crypto');

const key = 'keykeykeykeykeykeykeykey';
const nonce = randomBytes(12);

const aad = Buffer.from('0123456789', 'hex');

const cipher = createCipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16,
});
const plaintext = 'Hello world';
cipher.setAAD(aad, {
  plaintextLength: Buffer.byteLength(plaintext),
});
const ciphertext = cipher.update(plaintext, 'utf8');
cipher.final();
const tag = cipher.getAuthTag();

// Now transmit { ciphertext, nonce, tag }.

const decipher = createDecipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16,
});
decipher.setAuthTag(tag);
decipher.setAAD(aad, {
  plaintextLength: ciphertext.length,
});
const receivedPlaintext = decipher.update(ciphertext, null, 'utf8');

try {
  decipher.final();
} catch (err) {
  throw new Error('Authentication failed!', { cause: err });
}

console.log(receivedPlaintext);const { Buffer } = require('node:buffer');
const {
  createCipheriv,
  createDecipheriv,
  randomBytes,
} = require('node:crypto');

const key = 'keykeykeykeykeykeykeykey';
const nonce = randomBytes(12);

const aad = Buffer.from('0123456789', 'hex');

const cipher = createCipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16,
});
const plaintext = 'Hello world';
cipher.setAAD(aad, {
  plaintextLength: Buffer.byteLength(plaintext),
});
const ciphertext = cipher.update(plaintext, 'utf8');
cipher.final();
const tag = cipher.getAuthTag();

// Now transmit { ciphertext, nonce, tag }.

const decipher = createDecipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16,
});
decipher.setAuthTag(tag);
decipher.setAAD(aad, {
  plaintextLength: ciphertext.length,
});
const receivedPlaintext = decipher.update(ciphertext, null, 'utf8');

try {
  decipher.final();
} catch (err) {
  throw new Error('Authentication failed!', { cause: err });
}

console.log(receivedPlaintext);

FIPS 模式#

使用 OpenSSL 3 时，Node.js 在与适当的 OpenSSL 3 提供程序一起使用时支持 FIPS 140-2，例如来自 OpenSSL 3 的 FIPS 提供程序，可以通过按照 OpenSSL 的 FIPS 自述文件 中的说明进行安装。

要获得 Node.js 中的 FIPS 支持，您需要

  • 正确安装的 OpenSSL 3 FIPS 提供程序。
  • OpenSSL 3 FIPS 模块配置文件。
  • 引用 FIPS 模块配置文件的 OpenSSL 3 配置文件。

Node.js 需要使用指向 FIPS 提供程序的 OpenSSL 配置文件进行配置。示例配置文件如下所示

nodejs_conf = nodejs_init

.include /<absolute path>/fipsmodule.cnf

[nodejs_init]
providers = provider_sect

[provider_sect]
default = default_sect
# The fips section name should match the section name inside the
# included fipsmodule.cnf.
fips = fips_sect

[default_sect]
activate = 1

其中 fipsmodule.cnf 是从 FIPS 提供程序安装步骤生成的 FIPS 模块配置文件

openssl fipsinstall

将 OPENSSL_CONF 环境变量设置为指向您的配置文件，并将 OPENSSL_MODULES 设置为 FIPS 提供程序动态库的位置。例如

export OPENSSL_CONF=/<path to configuration file>/nodejs.cnf
export OPENSSL_MODULES=/<path to openssl lib>/ossl-modules

然后可以通过以下方式在 Node.js 中启用 FIPS 模式

  • 使用 --enable-fips 或 --force-fips 命令行标志启动 Node.js。
  • 以编程方式调用 crypto.setFips(true)。

可以选择通过 OpenSSL 配置文件在 Node.js 中启用 FIPS 模式。例如

nodejs_conf = nodejs_init

.include /<absolute path>/fipsmodule.cnf

[nodejs_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
default = default_sect
# The fips section name should match the section name inside the
# included fipsmodule.cnf.
fips = fips_sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

加密常量#

crypto.constants 导出的以下常量适用于 node:crypto、node:tls 和 node:https 模块的各种用途，通常特定于 OpenSSL。

OpenSSL 选项#

有关详细信息，请参阅 SSL OP 标志列表。

常量 描述
SSL_OP_ALL 在 OpenSSL 中应用多个错误修复。有关详细信息，请参阅 https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html。
SSL_OP_ALLOW_NO_DHE_KEX 指示 OpenSSL 允许 TLS v1.3 使用非 [EC]DHE 基密钥交换模式。
SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION 允许 OpenSSL 与未修补的客户端或服务器之间进行旧版不安全的重新协商。请参阅 https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html。
SSL_OP_CIPHER_SERVER_PREFERENCE 尝试在选择密码时使用服务器的偏好而不是客户端的偏好。行为取决于协议版本。请参阅 https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html。
SSL_OP_CISCO_ANYCONNECT 指示 OpenSSL 使用思科的“特殊”版本 DTLS_BAD_VER。
SSL_OP_COOKIE_EXCHANGE 指示 OpenSSL 打开 Cookie 交换。
SSL_OP_CRYPTOPRO_TLSEXT_BUG 指示 OpenSSL 添加来自早期版本的加密 pro 草案的服务器问候扩展。
SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS 指示 OpenSSL 禁用 OpenSSL 0.9.6d 中添加的 SSL 3.0/TLS 1.0 漏洞解决方法。
SSL_OP_LEGACY_SERVER_CONNECT 允许初始连接到不支持 RI 的服务器。
SSL_OP_NO_COMPRESSION 指示 OpenSSL 禁用对 SSL/TLS 压缩的支持。
SSL_OP_NO_ENCRYPT_THEN_MAC 指示 OpenSSL 禁用加密后 MAC。
SSL_OP_NO_QUERY_MTU
SSL_OP_NO_RENEGOTIATION 指示 OpenSSL 禁用重新协商。
SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION 指示 OpenSSL 在执行重新协商时始终启动新会话。
SSL_OP_NO_SSLv2 指示 OpenSSL 关闭 SSL v2
SSL_OP_NO_SSLv3 指示 OpenSSL 关闭 SSL v3
SSL_OP_NO_TICKET 指示 OpenSSL 禁用使用 RFC4507bis 票证。
SSL_OP_NO_TLSv1 指示 OpenSSL 关闭 TLS v1
SSL_OP_NO_TLSv1_1 指示 OpenSSL 关闭 TLS v1.1
SSL_OP_NO_TLSv1_2 指示 OpenSSL 关闭 TLS v1.2
SSL_OP_NO_TLSv1_3 指示 OpenSSL 关闭 TLS v1.3
SSL_OP_PRIORITIZE_CHACHA 指示 OpenSSL 服务器在客户端支持的情况下优先使用 ChaCha20-Poly1305。如果未启用 SSL_OP_CIPHER_SERVER_PREFERENCE，则此选项无效。
SSL_OP_TLS_ROLLBACK_BUG 指示 OpenSSL 禁用版本回滚攻击检测。

OpenSSL 引擎常量#

常量 描述
ENGINE_METHOD_RSA 将引擎使用限制为 RSA
ENGINE_METHOD_DSA 将引擎使用限制为 DSA
ENGINE_METHOD_DH 将引擎使用限制为 DH
ENGINE_METHOD_RAND 将引擎使用限制为 RAND
ENGINE_METHOD_EC 将引擎使用限制为 EC
ENGINE_METHOD_CIPHERS 将引擎使用限制为 CIPHERS
ENGINE_METHOD_DIGESTS 将引擎使用限制为 DIGESTS
ENGINE_METHOD_PKEY_METHS 将引擎使用限制为 PKEY_METHDS
ENGINE_METHOD_PKEY_ASN1_METHS 将引擎使用限制为 PKEY_ASN1_METHS
ENGINE_METHOD_ALL
ENGINE_METHOD_NONE

其他 OpenSSL 常量#

常量 描述
DH_CHECK_P_NOT_SAFE_PRIME
DH_CHECK_P_NOT_PRIME
DH_UNABLE_TO_CHECK_GENERATOR
DH_NOT_SUITABLE_GENERATOR
RSA_PKCS1_PADDING
RSA_SSLV23_PADDING
RSA_NO_PADDING
RSA_PKCS1_OAEP_PADDING
RSA_X931_PADDING
RSA_PKCS1_PSS_PADDING
RSA_PSS_SALTLEN_DIGEST 在签名或验证时将 RSA_PKCS1_PSS_PADDING 的盐长度设置为摘要大小。
RSA_PSS_SALTLEN_MAX_SIGN 在签名数据时将 RSA_PKCS1_PSS_PADDING 的盐长度设置为最大允许值。
RSA_PSS_SALTLEN_AUTO 在验证签名时自动确定 RSA_PKCS1_PSS_PADDING 的盐长度。
POINT_CONVERSION_COMPRESSED
POINT_CONVERSION_UNCOMPRESSED
POINT_CONVERSION_HYBRID

Node.js 加密常量#

常量 描述
defaultCoreCipherList 指定 Node.js 使用的内置默认密码列表。
defaultCipherList 指定当前 Node.js 进程使用的活动默认密码列表。