Node.js v18.15.0 文档

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

中英对照

可以在不支持 node:crypto 模块的情况下构建 Node.js。 在这种情况下，尝试 import 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 类#

中英对照

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

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

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

Certificate.exportChallenge(spkac[, encoding])#

中英对照

• spkac <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• encoding <string> spkac 字符串的编码。
• 返回: <Buffer> spkac 数据结构的挑战组件，包括公钥和挑战。

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

Certificate.exportPublicKey(spkac[, encoding])#

中英对照

• spkac <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• encoding <string> spkac 字符串的编码。
• 返回: <Buffer> spkac 数据结构的公钥组件，包括公钥和挑战。

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

Certificate.verifySpkac(spkac[, encoding])#

中英对照

• spkac <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• encoding <string> spkac 字符串的编码。
• 返回: <boolean> 如果给定的 spkac 数据结构有效，则为 true，否则为 false。

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

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

const spkac = getSpkacSomehow();
console.log(Certificate.verifySpkac(Buffer.from(spkac)));
// 打印: true 或 false

旧版的 API#

中英对照

作为旧版接口，可以创建 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])#

中英对照

• spkac <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• encoding <string> spkac 字符串的编码。
• 返回: <Buffer> spkac 数据结构的挑战组件，包括公钥和挑战。

const { Certificate } = await import('node:crypto');
const cert = Certificate();
const spkac = getSpkacSomehow();
const challenge = cert.exportChallenge(spkac);
console.log(challenge.toString('utf8'));
// 打印: 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'));
// 打印: the challenge as a UTF8 string

certificate.exportPublicKey(spkac[, encoding])#

中英对照

• spkac <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• encoding <string> spkac 字符串的编码。
• 返回: <Buffer> spkac 数据结构的公钥组件，包括公钥和挑战。

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

certificate.verifySpkac(spkac[, encoding])#

中英对照

• spkac <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• encoding <string> spkac 字符串的编码。
• 返回: <boolean> 如果给定的 spkac 数据结构有效，则为 true，否则为 false。

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

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

const cert = Certificate();
const spkac = getSpkacSomehow();
console.log(cert.verifySpkac(Buffer.from(spkac)));
// 打印: true 或 false

Cipher 类#

中英对照

• 继承自: <stream.Transform>

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

• 作为既可读又可写的流，其中写入未加密的纯数据以在可读端生成加密的数据，或
• 使用 cipher.update() 和 cipher.final() 方法生成加密的数据。

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

示例：使用 Cipher 对象作为流：

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

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

// 首先，将生成密钥。密钥长度取决于算法。
// 在此示例中，用于 aes192，长度是 24 个字节（192 位）。
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err;
  // 然后，将生成随机的初始化向量
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err;

    // 一旦有了密钥和 iv，则可以创建和使用加密...
    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';

// 首先，将生成密钥。密钥长度取决于算法。
// 在此示例中，用于 aes192，长度是 24 个字节（192 位）。
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err;
  // 然后，将生成随机的初始化向量
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err;

    // 一旦有了密钥和 iv，则可以创建和使用加密...
    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';

// 首先，将生成密钥。密钥长度取决于算法。
// 在此示例中，用于 aes192，长度是 24 个字节（192 位）。
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err;
  // 然后，将生成随机的初始化向量
  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';

// 首先，将生成密钥。密钥长度取决于算法。
// 在此示例中，用于 aes192，长度是 24 个字节（192 位）。
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err;
  // 然后，将生成随机的初始化向量
  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';

// 首先，将生成密钥。密钥长度取决于算法。
// 在此示例中，用于 aes192，长度是 24 个字节（192 位）。
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err;
  // 然后，将生成随机的初始化向量
  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';

// 首先，将生成密钥。密钥长度取决于算法。
// 在此示例中，用于 aes192，长度是 24 个字节（192 位）。
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err;
  // 然后，将生成随机的初始化向量
  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])#

中英对照

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

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

cipher.getAuthTag()#

中英对照

• 返回: <Buffer> 当使用认证的加密模式时（当前支持 GCM、CCM、OCB 和 chacha20-poly1305），则cipher.getAuthTag() 方法返回 Buffer，其中包含根据给定数据计算的认证标签。

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

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

cipher.setAAD(buffer[, options])#

中英对照

• buffer <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• options <Object> stream.transform 选项
  • plaintextLength <number>
  • encoding <string> 当 buffer 是字符串时使用的字符串编码。
• 返回: <Cipher> 用于方法链。

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

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

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

cipher.setAutoPadding([autoPadding])#

中英对照

• autoPadding <boolean> 默认值: true
• 返回: <Cipher> 用于方法链。

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

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

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

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

中英对照

• data <string> | <Buffer> | <TypedArray> | <DataView>
• inputEncoding <string> 数据的编码。
• outputEncoding <string> 返回值的编码。
• 返回: <Buffer> | <string>

使用 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 类#

中英对照

• 继承自: <stream.Transform>

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

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

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

示例：使用 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';
// 密钥长度取决于算法。
// 在这种情况下，对于 aes192，它是 24 字节（192 位）。
// 请改用异步的 `crypto.scrypt()`。
const key = scryptSync(password, 'salt', 24);
// IV 通常与密文一起传入。
const iv = Buffer.alloc(16, 0); // 初始化向量。

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);
  // 打印: some clear text data
});

// 使用相同的算法、密钥和 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';
// 密钥长度取决于算法。
// 在这种情况下，对于 aes192，它是 24 字节（192 位）。
// 请改用异步的 `crypto.scrypt()`。
const key = scryptSync(password, 'salt', 24);
// IV 通常与密文一起传入。
const iv = Buffer.alloc(16, 0); // 初始化向量。

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);
  // 打印: some clear text data
});

// 使用相同的算法、密钥和 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';
// 请改用异步的 `crypto.scrypt()`。
const key = scryptSync(password, 'salt', 24);
// IV 通常与密文一起传入。
const iv = Buffer.alloc(16, 0); // 初始化向量。

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';
// 请改用异步的 `crypto.scrypt()`。
const key = scryptSync(password, 'salt', 24);
// IV 通常与密文一起传入。
const iv = Buffer.alloc(16, 0); // 初始化向量。

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';
// 请改用异步的 `crypto.scrypt()`。
const key = scryptSync(password, 'salt', 24);
// IV 通常与密文一起传入。
const iv = Buffer.alloc(16, 0); // 初始化向量。

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

// 使用相同的算法、密钥和 iv 加密。
const encrypted =
  'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa';
let decrypted = decipher.update(encrypted, 'hex', 'utf8');
decrypted += decipher.final('utf8');
console.log(decrypted);
// 打印: 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';
// 请改用异步的 `crypto.scrypt()`。
const key = scryptSync(password, 'salt', 24);
// IV 通常与密文一起传入。
const iv = Buffer.alloc(16, 0); // 初始化向量。

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

// 使用相同的算法、密钥和 iv 加密。
const encrypted =
  'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa';
let decrypted = decipher.update(encrypted, 'hex', 'utf8');
decrypted += decipher.final('utf8');
console.log(decrypted);
// 打印: some clear text data

decipher.final([outputEncoding])#

中英对照

• outputEncoding <string> 返回值的编码。
• 返回: <Buffer> | <string> 任何剩余的解密内容。 如果指定了 outputEncoding，则返回字符串。 如果未提供 outputEncoding，则返回 Buffer。

一旦调用了 decipher.final() 方法，就不能再使用 Decipher 对象来解密数据。 多次尝试调用 decipher.final() 将导致抛出错误。

decipher.setAAD(buffer[, options])#

中英对照

• buffer <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• options <Object> stream.transform 选项
  • plaintextLength <number>
  • encoding <string> 当 buffer 是字符串时使用的字符串编码。
• 返回: <Decipher> 用于方法链。

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

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

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

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

decipher.setAuthTag(buffer[, encoding])#

中英对照

• buffer <string> | <Buffer> | <ArrayBuffer> | <TypedArray> | <DataView>
• encoding <string> 当 buffer 是字符串时使用的字符串编码。
• 返回: <Decipher> 用于方法链。

当使用认证的加密方式时（目前支持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])#

中英对照

• autoPadding <boolean> 默认值: true
• 返回: <Decipher> 用于方法链。

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

仅当输入数据的长度是密码块大小的倍数时，关闭自动填充才会起作用。

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

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

中英对照

• data <string> | <Buffer> | <TypedArray> | <DataView>
• inputEncoding <string> data 字符串的编码。
• outputEncoding <string> 返回值的编码。
• 返回: <Buffer> | <string>

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

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

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

DiffieHellman 类#

中英对照

DiffieHellman 类是用于创建 Diffie-Hellman 密钥交换的实用工具。

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

import assert from 'node:assert';

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

// 生成 Alice 的密钥...
const alice = createDiffieHellman(2048);
const aliceKey = alice.generateKeys();

// 生成 Bob 的密钥...
const bob = createDiffieHellman(alice.getPrime(), alice.getGenerator());
const bobKey = bob.generateKeys();

// 交换并生成密钥...
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');

// 生成 Alice 的密钥...
const alice = createDiffieHellman(2048);
const aliceKey = alice.generateKeys();

// 生成 Bob 的密钥...
const bob = createDiffieHellman(alice.getPrime(), alice.getGenerator());
const bobKey = bob.generateKeys();

// 交换并生成密钥...
const aliceSecret = alice.computeSecret(bobKey);
const bobSecret = bob.computeSecret(aliceKey);

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

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

中英对照

• otherPublicKey <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• inputEncoding <string> otherPublicKey 字符串的编码。
• outputEncoding <string> 返回值的编码。
• 返回: <Buffer> | <string>

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

如果给定 outputEncoding，则返回字符串； 否则，返回 Buffer。

diffieHellman.generateKeys([encoding])#

中英对照

• encoding <string> 返回值的编码。
• 返回: <Buffer> | <string>

生成私钥和公钥 Diffie-Hellman 密钥值，并返回指定 encoding 中的公钥。 此密钥应转让给另一方。 如果提供了 encoding，则返回字符串；否则返回 Buffer。

diffieHellman.getGenerator([encoding])#

中英对照

• encoding <string> 返回值的编码。
• 返回: <Buffer> | <string>

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

diffieHellman.getPrime([encoding])#

中英对照

• encoding <string> 返回值的编码。
• 返回: <Buffer> | <string>

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

diffieHellman.getPrivateKey([encoding])#

中英对照

• encoding <string> 返回值的编码。
• 返回: <Buffer> | <string>

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

diffieHellman.getPublicKey([encoding])#

中英对照

• encoding <string> 返回值的编码。
• 返回: <Buffer> | <string>

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

diffieHellman.setPrivateKey(privateKey[, encoding])#

中英对照

• privateKey <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• encoding <string> privateKey 字符串的编码。

设置 Diffie-Hellman 私钥。 如果提供了 encoding 参数，则 privateKey 应该是字符串。 如果未提供 encoding，则 privateKey 应为 Buffer、TypedArray 或 DataView。

diffieHellman.setPublicKey(publicKey[, encoding])#

中英对照

• publicKey <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• encoding <string> publicKey 字符串的编码。

设置 Diffie-Hellman 公钥。 如果提供了 encoding 参数，则 publicKey 应该是字符串。 如果未提供 encoding，则 publicKey 应为 Buffer、TypedArray 或 DataView。

diffieHellman.verifyError#

中英对照

包含在 DiffieHellman 对象初始化期间执行的检查所产生的任何警告和/或错误的位字段。

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

• DH_CHECK_P_NOT_SAFE_PRIME
• DH_CHECK_P_NOT_PRIME
• DH_UNABLE_TO_CHECK_GENERATOR
• DH_NOT_SUITABLE_GENERATOR

DiffieHellmanGroup 类#

中英对照

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 类#

中英对照

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

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

import assert from 'node:assert';

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

// 生成 Alice 的密钥...
const alice = createECDH('secp521r1');
const aliceKey = alice.generateKeys();

// 生成 Bob 的密钥...
const bob = createECDH('secp521r1');
const bobKey = bob.generateKeys();

// 交换并生成密钥...
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');

// 生成 Alice 的密钥...
const alice = createECDH('secp521r1');
const aliceKey = alice.generateKeys();

// 生成 Bob 的密钥...
const bob = createECDH('secp521r1');
const bobKey = bob.generateKeys();

// 交换并生成密钥...
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]]])#

中英对照

• key <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• curve <string>
• inputEncoding <string> key 字符串的编码。
• outputEncoding <string> 返回值的编码。
• format <string> 默认值: 'uncompressed'
• 返回: <Buffer> | <string>

将 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');

// 转换后的密钥和未压缩的公钥应该是一样的
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');

// 转换后的密钥和未压缩的公钥应该是一样的
console.log(uncompressedKey === ecdh.getPublicKey('hex'));

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

中英对照

• otherPublicKey <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• inputEncoding <string> otherPublicKey 字符串的编码。
• outputEncoding <string> 返回值的编码。
• 返回: <Buffer> | <string>

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

如果给定 outputEncoding，将返回字符串；否则返回 Buffer。

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

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

中英对照

• encoding <string> 返回值的编码。
• format <string> 默认值: 'uncompressed'
• 返回: <Buffer> | <string>

生成私有和公共 EC Diffie-Hellman 密钥值，并返回指定 format 和 encoding 中的公钥。 此密钥应转让给另一方。

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

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

ecdh.getPrivateKey([encoding])#

中英对照

• encoding <string> 返回值的编码。
• 返回: <Buffer> | <string> 指定 encoding 中的 EC Diffie-Hellman。

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

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

中英对照

• encoding <string> 返回值的编码。
• format <string> 默认值: 'uncompressed'
• 返回: <Buffer> | <string> 指定 encoding 和 format 中的 EC Diffie-Hellman 公钥。

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

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

ecdh.setPrivateKey(privateKey[, encoding])#

中英对照

• privateKey <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• encoding <string> privateKey 字符串的编码。

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

如果 privateKey 对于创建 ECDH 对象时指定的曲线无效，则会引发错误。 在设置私钥时，相关的公共点（密钥）也会生成并设置在 ECDH 对象中。

ecdh.setPublicKey(publicKey[, encoding])#

中英对照

• publicKey <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• encoding <string> publicKey 字符串的编码。

设置 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');

// 这是指定 Alice 以前的私钥之一的快捷方式。
// 在实际应用中使用这种可预测的私钥是不明智的。
alice.setPrivateKey(
  createHash('sha256').update('alice', 'utf8').digest(),
);

// Bob 使用新生成的加密强伪随机密钥对
bob.generateKeys();

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

// aliceSecret 和 bobSecret 应该是相同的共享秘密值
console.log(aliceSecret === bobSecret);const {
  createECDH,
  createHash,
} = require('node:crypto');

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

// 这是指定 Alice 以前的私钥之一的快捷方式。
// 在实际应用中使用这种可预测的私钥是不明智的。
alice.setPrivateKey(
  createHash('sha256').update('alice', 'utf8').digest(),
);

// Bob 使用新生成的加密强伪随机密钥对
bob.generateKeys();

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

// aliceSecret 和 bobSecret 应该是相同的共享秘密值
console.log(aliceSecret === bobSecret);

Hash 类#

中英对照

• 继承自: <stream.Transform>

Hash 类是用于创建数据的哈希摘要的实用工具。 它可以通过以下两种方式之一使用：

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

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

示例：使用 Hash 对象作为流：

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

const hash = createHash('sha256');

hash.on('readable', () => {
  // 哈希流只生成
  // 一个元素。
  const data = hash.read();
  if (data) {
    console.log(data.toString('hex'));
    // 打印:
    //   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50
  }
});

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

const hash = createHash('sha256');

hash.on('readable', () => {
  // 哈希流只生成
  // 一个元素。
  const data = hash.read();
  if (data) {
    console.log(data.toString('hex'));
    // 打印:
    //   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'));
// 打印:
//   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50const {
  createHash,
} = require('node:crypto');

const hash = createHash('sha256');

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

hash.copy([options])#

中英对照

• options <Object> stream.transform 选项
• 返回: <Hash>

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

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

在调用 hash.digest() 方法后尝试复制 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'));

// 等等。// 计算滚动哈希。
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'));

// 等等。

hash.digest([encoding])#

中英对照

• encoding <string> 返回值的编码。
• 返回: <Buffer> | <string>

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

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

hash.update(data[, inputEncoding])#

中英对照

• data <string> | <Buffer> | <TypedArray> | <DataView>
• inputEncoding <string> data 字符串的编码。

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

这可以在流式传输时使用新数据多次调用。

Hmac 类#

中英对照

• 继承自: <stream.Transform>

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', () => {
  // 哈希流只生成
  // 一个元素。
  const data = hmac.read();
  if (data) {
    console.log(data.toString('hex'));
    // 打印:
    //   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
  }
});

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

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

hmac.on('readable', () => {
  // 哈希流只生成
  // 一个元素。
  const data = hmac.read();
  if (data) {
    console.log(data.toString('hex'));
    // 打印:
    //   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'));
// 打印:
//   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77econst {
  createHmac,
} = require('node:crypto');

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

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

hmac.digest([encoding])#

中英对照

• encoding <string> 返回值的编码。
• 返回: <Buffer> | <string>

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

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

hmac.update(data[, inputEncoding])#

中英对照

• data <string> | <Buffer> | <TypedArray> | <DataView>
• inputEncoding <string> data 字符串的编码。

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

这可以在流式传输时使用新数据多次调用。

KeyObject 类#

中英对照

Node.js 使用 KeyObject 类来表示对称或非对称密钥，每种密钥暴露不同的功能。 crypto.createSecretKey()、crypto.createPublicKey() 和 crypto.createPrivateKey() 方法用于创建 KeyObject 实例。 KeyObject 对象不能直接使用 new 关键字创建。

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

KeyObject 实例可以通过 postMessage() 传给其他线程。 接收者获得克隆的 KeyObject，KeyObject 不需要在 transferList 参数中列出。

KeyObject.from(key)#

中英对照

• key <CryptoKey>
• 返回: <KeyObject>

示例：将 CryptoKey 实例转换为 KeyObject：

const { webcrypto, KeyObject } = await import('node:crypto');
const { subtle } = webcrypto;

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

const keyObject = KeyObject.from(key);
console.log(keyObject.symmetricKeySize);
// 打印: 32 (（以字节为单位的对称密钥大小）)const {
  webcrypto: {
    subtle,
  },
  KeyObject,
} = require('node: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);
  // 打印: 32 (（以字节为单位的对称密钥大小）)
})();

keyObject.asymmetricKeyDetails#

中英对照

• <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#

中英对照

• <string>

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

• '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])#

中英对照

• options: <Object>
• 返回: <string> | <Buffer> | <Object>

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

• 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）。 当使用 PEM format 时，PKCS#1 和 SEC1 只能通过指定 cipher 来加密。 为了获得最大的兼容性，对加密的私钥使用 PKCS#8。 由于 PKCS#8 定义了自己的加密机制，因此在加密 PKCS#8 密钥时不支持 PEM 级加密。 PKCS#8 加密参见 RFC 5208，PKCS#1 和 SEC1 加密参见 RFC 1421。

keyObject.equals(otherKeyObject)#

中英对照

• otherKeyObject: <KeyObject> 与 keyObject 比较的 KeyObject。
• 返回: <boolean>

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

keyObject.symmetricKeySize#

中英对照

• <number>

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

keyObject.type#

中英对照

• <string>

根据此 KeyObject 的类型，此属性是 'secret' 表示秘密（对称）密钥，'public' 表示公共（非对称）密钥或 'private' 表示私有（非对称）密钥。

Sign 类#

中英对照

• 继承自: <stream.Writable>

Sign 类是用于生成签名的实用工具。 它可以通过以下两种方式之一使用：

• 作为可写流，写入要签名的数据，使用 sign.sign() 方法生成并返回签名，或者
• 使用 sign.update() 和 sign.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'));
// 打印: 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'));
// 打印: 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));
// 打印: 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));
// 打印: true

sign.sign(privateKey[, outputEncoding])#

中英对照

• privateKey <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
  • dsaEncoding <string>
  • padding <integer>
  • saltLength <integer>
• outputEncoding <string> 返回值的编码。
• 返回: <Buffer> | <string>

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

如果 privateKey 不是 KeyObject，则此函数的行为就像将 privateKey 传给 crypto.createPrivateKey() 一样。 如果是对象，则可以传入以下额外属性：

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

  • 'der'（默认）：DER 编码的 ASN.1 签名结构编码 (r, s)。
  • 'ieee-p1363': IEEE-P1363 中提议的签名格式 r || s。

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

  • crypto.constants.RSA_PKCS1_PADDING（默认）
  • crypto.constants.RSA_PKCS1_PSS_PADDING

  RSA_PKCS1_PSS_PADDING 将使用具有与 RFC 4055 的第 3.1 章节中指定的消息签名相同的散列函数的 MGF1，除非 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])#

中英对照

• data <string> | <Buffer> | <TypedArray> | <DataView>
• inputEncoding <string> data 字符串的编码。

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

这可以在流式传输时使用新数据多次调用。

Verify 类#

中英对照

• 继承自: <stream.Writable>

Verify 类是用于验证签名的实用工具。 它可以通过以下两种方式之一使用：

• 作为可写流，其中写入的数据用于根据提供的签名进行验证，或者
• 使用 verify.update() 和 verify.verify() 方法来验证签名。

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

有关示例，请参见 Sign。

verify.update(data[, inputEncoding])#

中英对照

• data <string> | <Buffer> | <TypedArray> | <DataView>
• inputEncoding <string> data 字符串的编码。

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

这可以在流式传输时使用新数据多次调用。

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

中英对照

• object <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
  • dsaEncoding <string>
  • padding <integer>
  • saltLength <integer>
• signature <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• signatureEncoding <string> signature 字符串的编码。
• 返回: <boolean> true 或 false 取决于数据和公钥签名的有效性。

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

如果 object 不是 KeyObject，则此函数的行为就像将 object 传给 crypto.createPublicKey() 一样。 如果是对象，则可以传入以下额外属性：

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

  • 'der'（默认）：DER 编码的 ASN.1 签名结构编码 (r, s)。
  • 'ieee-p1363': IEEE-P1363 中提议的签名格式 r || s。

• 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 类#

中英对照

封装 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)#

中英对照

• buffer <string> | <TypedArray> | <Buffer> | <DataView> PEM 或 DER 编码的 X509 证书。

x509.ca#

中英对照

• 类型: <boolean> 如果这是证书颁发机构（CA）证书，则为 true。

x509.checkEmail(email[, options])#

中英对照

• email <string>
• options <Object>
  • subject <string> 'default'、'always' 或 'never'。 默认值: 'default'。
• 返回: <string> | <undefined> 如果证书匹配，则返回 email，如果不匹配，则返回 undefined。

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

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

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

如果 'subject' 选项设置为 'never'，则从不考虑证书主题，即使证书不包含主题替代名称。

x509.checkHost(name[, options])#

中英对照

• 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)#

中英对照

• ip <string>
• 返回: <string> | <undefined> 如果证书匹配，则返回 ip，如果不匹配，则返回 undefined。

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

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

x509.checkIssued(otherCert)#

中英对照

• otherCert <X509Certificate>
• 返回: <boolean>

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

x509.checkPrivateKey(privateKey)#

中英对照

• privateKey <KeyObject> 私钥。
• 返回: <boolean>

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

x509.fingerprint#

中英对照

• 类型: <string>

此证书的 SHA-1 指纹。

由于 SHA-1 被加密破解，并且由于 SHA-1 的安全性明显低于通常用于签署证书的算法，因此请考虑使用 x509.fingerprint256。

x509.fingerprint256#

中英对照

• 类型: <string>

此证书的 SHA-256 指纹。

x509.fingerprint512#

中英对照

• 类型: <string>

此证书的 SHA-512 指纹。

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

x509.infoAccess#

中英对照

• 类型: <string>

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

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

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

x509.issuer#

中英对照

• 类型: <string>

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

x509.issuerCertificate#

中英对照

• 类型: <X509Certificate>

颁发者证书或 undefined（如果颁发者证书不可用）。

x509.keyUsage#

中英对照

• 类型: <string[]>

详细说明此证书的密钥用法的数组。

x509.publicKey#

中英对照

• 类型: <KeyObject>

此证书的公钥 <KeyObject>。

x509.raw#

中英对照

• 类型: <Buffer>

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

x509.serialNumber#

中英对照

• 类型: <string>

此证书的序列号。

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

x509.subject#

中英对照

• 类型: <string>

本证书的完整主题。

x509.subjectAltName#

中英对照

• 类型: <string>

为此证书指定的使用者备用名称。

这是一个以逗号分隔的主题替代名称列表。 每个条目都以一个字符串开头，该字符串标识主题替代名称的种类，后跟一个冒号以及与该条目关联的值。

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

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

x509.toJSON()#

中英对照

• 类型: <string>

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

x509.toLegacyObject()#

中英对照

• 类型: <Object>

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

x509.toString()#

中英对照

• 类型: <string>

返回 PEM 编码的证书。

x509.validFrom#

中英对照

• 类型: <string>

此证书被视为有效的起始日期/时间。

x509.validTo#

中英对照

• 类型: <string>

此证书被视为有效的结束日期/时间。

x509.verify(publicKey)#

中英对照

• publicKey <KeyObject> 公钥。
• 返回: <boolean>

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

node:crypto 模块方法和属性#

crypto.constants#

中英对照

• <Object>

包含用于加密和安全相关操作的常用常量的对象。 当前定义的特定常量在加密常量中进行了描述。

crypto.DEFAULT_ENCODING#

中英对照

用于可以采用字符串或缓冲区的函数的默认编码。 默认值为 'buffer'，这使得方法默认为 Buffer 对象。

提供 crypto.DEFAULT_ENCODING 机制是为了与期望 'latin1' 作为默认编码的遗留程序向后兼容。

新应用程序应该期望默认值为 'buffer'。

此属性已弃用。

crypto.fips#

中英对照

用于检查和控制当前是否正在使用符合 FIPS 的加密提供程序的属性。 设置为 true 需要 Node.js 的 FIPS 构建。

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

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

中英对照

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

检查 candidate 的素性。

crypto.checkPrimeSync(candidate[, options])#

中英对照

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

检查 candidate 的素性。

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

中英对照

• algorithm <string>
• password <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• options <Object> stream.transform 选项
• 返回: <Cipher>

创建并返回使用给定 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，一次迭代，不加盐。 缺少盐允许字典攻击，因为相同的密码总是创建相同的密钥。 低迭代次数和非加密安全散列算法允许非常快速地测试密码。

根据 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])#

中英对照

• algorithm <string>
• key <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
• iv <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <null>
• options <Object> stream.transform 选项
• 返回: <Cipher>

使用给定的 algorithm、key 和初始化向量（iv）创建并返回 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 将显示可用的密码算法。

key 是 algorithm 使用的原始密钥，iv 是初始化向量。 两个参数都必须是 'utf8' 编码的字符串、缓冲区、TypedArray 或 DataView。 key 可以是 secret 类型的 KeyObject。 如果加密不需要初始化向量，则 iv 可以是 null。

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

初始化向量应该是不可预测的和独特的；理想情况下，它们将是加密随机的。 它们不必是机密的：IV 通常不加密就添加到密文消息中。 必须是不可预测的和独特的，但不必是机密的，这听起来可能有些矛盾。请记住，一定不能让攻击者提前预测到给定的 IV。

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

中英对照

• algorithm <string>
• password <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• options <Object> stream.transform 选项
• 返回: <Decipher>

创建并返回使用给定的 algorithm 和 password（键）的 Decipher 对象。

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

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

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

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

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

中英对照

• algorithm <string>
• key <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
• iv <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <null>
• options <Object> stream.transform 选项
• 返回: <Decipher>

创建并返回使用给定的 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' 编码的字符串、缓冲区、TypedArray 或 DataView。 key 可以是 secret 类型的 KeyObject。 如果加密不需要初始化向量，则 iv 可以是 null。

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

初始化向量应该是不可预测的和独特的；理想情况下，它们将是加密随机的。 它们不必是机密的：IV 通常不加密就添加到密文消息中。 必须是不可预测的和独特的，但不必是机密的，这听起来可能有些矛盾。请记住，一定不能让攻击者提前预测到给定的 IV。

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

中英对照

• prime <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• primeEncoding <string> prime 字符串的编码。
• generator <number> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> 默认值: 2
• generatorEncoding <string> generator 字符串的编码。
• 返回: <DiffieHellman>

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

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

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

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

crypto.createDiffieHellman(primeLength[, generator])#

中英对照

• primeLength <number>
• generator <number> 默认值: 2
• 返回: <DiffieHellman>

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

crypto.createDiffieHellmanGroup(name)#

中英对照

• name <string>
• 返回: <DiffieHellmanGroup>

crypto.getDiffieHellman() 的别名

crypto.createECDH(curveName)#

中英对照

• curveName <string>
• 返回: <ECDH>

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

crypto.createHash(algorithm[, options])#

中英对照

• algorithm <string>
• options <Object> stream.transform 选项
• 返回: <Hash>

创建并返回 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', () => {
  // 哈希流只生成
  // 一个元素。
  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', () => {
  // 哈希流只生成
  // 一个元素。
  const data = input.read();
  if (data)
    hash.update(data);
  else {
    console.log(`${hash.digest('hex')} ${filename}`);
  }
});

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

中英对照

• algorithm <string>
• key <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
• options <Object> stream.transform 选项
  • encoding <string> 当 key 是字符串时使用的字符串编码。
• 返回: <Hmac>

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

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

key 是用于生成加密 HMAC 哈希的 HMAC 密钥。 如果是 KeyObject，则其类型必须是 secret。

示例：生成文件的 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', () => {
  // 哈希流只生成
  // 一个元素。
  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', () => {
  // 哈希流只生成
  // 一个元素。
  const data = input.read();
  if (data)
    hmac.update(data);
  else {
    console.log(`${hmac.digest('hex')} ${filename}`);
  }
});

crypto.createPrivateKey(key)#

中英对照

• key <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
  • key: <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <Object> 密钥材料，采用 PEM、DER 或 JWK 格式。
  • format: <string> 必须是 'pem'、'der' 或 ''jwk'。 默认值: 'pem'。
  • type: <string> 必须是 'pkcs1'、'pkcs8' 或 'sec1'。 仅当 format 为 'der' 时才需要此选项，否则将被忽略。
  • passphrase: <string> | <Buffer> 用于解密的密码。
  • encoding: <string> 当 key 是字符串时使用的字符串编码。
• 返回: <KeyObject>

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

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

crypto.createPublicKey(key)#

中英对照

• key <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
  • key: <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <Object> 密钥材料，采用 PEM、DER 或 JWK 格式。
  • format: <string> 必须是 'pem'、'der' 或 'jwk'。 默认值: 'pem'。
  • type: <string> 必须是 'pkcs1' 或 'spki'。 仅当 format 为 'der' 时才需要此选项，否则将被忽略。
  • encoding <string> 当 key 是字符串时使用的字符串编码。
• 返回: <KeyObject>

创建并返回包含公钥的新密钥对象。 如果 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])#

中英对照

• key <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• encoding <string> key 为字符串时的字符串编码。
• 返回: <KeyObject>

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

crypto.createSign(algorithm[, options])#

中英对照

• algorithm <string>
• options <Object> stream.Writable 选项
• 返回: <Sign>

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

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

crypto.createVerify(algorithm[, options])#

中英对照

• algorithm <string>
• options <Object> stream.Writable 选项
• 返回: <Verify>

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

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

crypto.diffieHellman(options)#

中英对照

• options: <Object>
  • privateKey: <KeyObject>
  • publicKey: <KeyObject>
• 返回: <Buffer>

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

crypto.generateKey(type, options, callback)#

中英对照

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

异步生成给定 length 的新随机密钥。 type 将确定将在 length 上执行哪些验证。

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

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

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

crypto.generateKeyPair(type, options, callback)#

中英对照

• type: <string> 必须是 'rsa'、'rsa-pss'、'dsa'、'ec'、'ed25519'、'ed448'、'x25519'、'x448'、或 'dh'。
• options: <Object>
  • modulusLength: <number> 以位为单位的密钥大小（RSA、DSA）。
  • publicExponent: <number> 公共指数 (RSA)。 默认值: 0x10001。
  • hashAlgorithm: <string> 消息摘要的名称（RSA-PSS）。
  • mgf1HashAlgorithm: <string> MGF1 使用的消息摘要的名称（RSA-PSS）。
  • saltLength: <number> 以字节为单位的最小盐长度（RSA-PSS）。
  • divisorLength: <number> q 的比特大小 (DSA)。
  • namedCurve: <string> 要使用的曲线名称 (EC)。
  • prime: <Buffer> 素数参数 (DH)。
  • primeLength: <number> 以比特为单位的质数长度 (DH)。
  • generator: <number> 自定义生成器 (DH)。 默认值: 2。
  • groupName: <string> Diffie-Hellman 组名 (DH)。 参见 crypto.getDiffieHellman()。
  • paramEncoding: <string> 必须是 'named' 或 'explicit' (EC)。 默认值: 'named'。
  • publicKeyEncoding: <Object> 参见 keyObject.export()。
  • privateKeyEncoding: <Object> 参见 keyObject.export()。
• callback: <Function>
  • err: <Error>
  • publicKey: <string> | <Buffer> | <KeyObject>
  • privateKey: <string> | <Buffer> | <KeyObject>

生成给定 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) => {
  // 处理错误并使用生成的密钥对。
});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) => {
  // 处理错误并使用生成的密钥对。
});

完成后，callback 将被调用，err 设置为 undefined，publicKey / privateKey 代表生成的密钥对。

如果此方法作为其 util.promisify() 版本被调用，则其将为具有 publicKey 和 privateKey 属性的 Object 返回 Promise。

crypto.generateKeyPairSync(type, options)#

中英对照

• type: <string> 必须是 'rsa'、'rsa-pss'、'dsa'、'ec'、'ed25519'、'ed448'、'x25519'、'x448'、或 'dh'。
• options: <Object>
  • modulusLength: <number> 以位为单位的密钥大小（RSA、DSA）。
  • publicExponent: <number> 公共指数 (RSA)。 默认值: 0x10001。
  • hashAlgorithm: <string> 消息摘要的名称（RSA-PSS）。
  • mgf1HashAlgorithm: <string> MGF1 使用的消息摘要的名称（RSA-PSS）。
  • saltLength: <number> 以字节为单位的最小盐长度（RSA-PSS）。
  • divisorLength: <number> q 的比特大小 (DSA)。
  • namedCurve: <string> 要使用的曲线名称 (EC)。
  • prime: <Buffer> 素数参数 (DH)。
  • primeLength: <number> 以比特为单位的质数长度 (DH)。
  • generator: <number> 自定义生成器 (DH)。 默认值: 2。
  • groupName: <string> Diffie-Hellman 组名 (DH)。 参见 crypto.getDiffieHellman()。
  • paramEncoding: <string> 必须是 'named' 或 'explicit' (EC)。 默认值: 'named'。
  • publicKeyEncoding: <Object> 参见 keyObject.export()。
  • privateKeyEncoding: <Object> 参见 keyObject.export()。
• 返回: <Object>
  • publicKey: <string> | <Buffer> | <KeyObject>
  • privateKey: <string> | <Buffer> | <KeyObject>

生成给定 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)#

中英对照

• type: <string> 生成的密钥的预期用途。 当前接受的值为 'hmac' 和 'aes'。
• options: <Object>
  • length: <number> 要生成的密钥的位长。
    • 如果 type 为 'hmac'，则最小为 8，最大长度为 2³¹-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: 64 });
console.log(key.export().toString('hex'));  // e89..........41econst {
  generateKeySync,
} = require('node:crypto');

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

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

中英对照

• size <number> 要生成的素数的大小（以位为单位）。
• options <Object>
  • add <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint>
  • rem <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint>
  • safe <boolean> 默认值: false。
  • bigint <boolean> 当 true 时，生成的素数作为 bigint 返回。
• callback <Function>
  • err <Error>
  • prime <ArrayBuffer> | <bigint>

生成 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 都必须编码为大端序列。