Node.js v25.0.0 文档

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

• spkac <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• encoding <string> spkac 字符串的编码。
• 返回：<Buffer> spkac 数据结构中的 challenge 组件，包含公钥和质询。

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 stringcopy

静态方法：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);
// 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 ...>copy

静态方法：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)));
// 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 falsecopy

旧版 API#

作为旧版接口，可以创建 crypto.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();copy

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 stringcopy

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 ...>copy

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 falsecopy

cipher.final([outputEncoding])#

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

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

cipher.getAuthTag()#

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

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

如果在 cipher 实例创建期间设置了 authTagLength 选项，此函数将返回确切的 authTagLength 字节。

cipher.setAAD(buffer[, options])#

• buffer <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• options <Object> stream.transform 选项
  • plaintextLength <number>
  • encoding <string> 当 buffer 是字符串时使用的字符串编码。
• 返回：<Cipheriv> 同一个 Cipheriv 实例，用于方法链式调用。

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

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

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

cipher.setAutoPadding([autoPadding])#

• autoPadding <boolean> 默认值: true
• 返回：<Cipheriv> 同一个 Cipheriv 实例，用于方法链式调用。

当使用分组加密算法时，Cipheriv 类会自动向输入数据添加填充，使其达到适当的分组大小。要禁用默认填充，请调用 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.final([outputEncoding])#

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

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

decipher.setAAD(buffer[, options])#

• buffer <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• options <Object> stream.transform 选项
  • plaintextLength <number>
  • encoding <string> 当 buffer 是字符串时使用的字符串编码。
• 返回：<Decipheriv> 同一个 Decipher 实例，用于方法链式调用。

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

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

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

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

decipher.setAuthTag(buffer[, encoding])#

• buffer <string> | <Buffer> | <ArrayBuffer> | <TypedArray> | <DataView>
• encoding <string> 当 buffer 是字符串时使用的字符串编码。
• 返回：<Decipheriv> 同一个 Decipher 实例，用于方法链式调用。

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

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

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

decipher.setAutoPadding([autoPadding])#

• autoPadding <boolean> 默认值: true
• 返回：<Decipheriv> 同一个 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() 将导致抛出错误。

即使底层密码器实现了认证，此函数返回的明文的真实性和完整性此时可能不确定。对于认证加密算法，真实性通常只有在应用程序调用 decipher.final() 时才能确定。

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。

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

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() 或 diffieHellman.generateKeys() 来手动提供公钥或自动推导它。

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

静态方法：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');

// 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'));copy

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

// 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);copy

hash.copy([options])#

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

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

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

当在其 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.copy

hash.digest([encoding])#

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

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

在 hash.digest() 方法被调用后，Hash 对象不能再次使用。多次调用会引发错误。

hash.update(data[, inputEncoding])#

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

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

当新数据以流式传输时，可以多次调用此方法。

hmac.digest([encoding])#

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

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

在 hmac.digest() 被调用后，Hmac 对象不能再次使用。多次调用 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.from(key)#

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

示例：将 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)
})();copy

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>

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

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

keyObject.equals(otherKeyObject)#

• otherKeyObject <KeyObject> 一个与 keyObject 进行比较的 KeyObject。
• 返回：<boolean>

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

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

keyObject.symmetricKeySize#

• 类型：<number>

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

keyObject.toCryptoKey(algorithm, extractable, keyUsages)#

• algorithm <string> | <Algorithm> | <RsaHashedImportParams> | <EcKeyImportParams> | <HmacImportParams>

• extractable <boolean>
• keyUsages <string[]> 参见 密钥用途。
• 返回：<CryptoKey>

将 KeyObject 实例转换为 CryptoKey。

keyObject.type#

• 类型：<string>

根据此 KeyObject 的类型，此属性对于密钥（对称密钥）为 'secret'，对于公钥（非对称密钥）为 'public'，或对于私钥（非对称密钥）为 'private'。

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 将使用 MGF1，其哈希函数与用于签署消息的哈希函数相同，如 RFC 4055 第 3.1 节所述，除非已根据 RFC 4055 第 3.3 节的规定，在密钥中指定了 MGF1 哈希函数。

• 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.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 节所述，除非已根据 RFC 4055 第 3.3 节的规定，在密钥中指定了 MGF1 哈希函数。

• 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() 将导致抛出错误。

因为公钥可以从私钥派生，所以可以传递私钥来代替公钥。

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 颁发。

这对于修剪可能的颁发者证书列表非常有用，这些证书是使用更基本的过滤例程（即仅基于主题和颁发者名称）选择的。

最后，要验证此证书的签名是由与 otherCert 的公钥对应的私钥生成的，请使用 x509.verify(publicKey)，其中 otherCert 的公钥表示为一个 KeyObject，如下所示

if (!x509.verify(otherCert.publicKey)) {
  throw new Error('otherCert did not issue x509');
} copy

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.validFromDate#

• 类型：<Date>

此证书的有效起始日期/时间，封装在一个 Date 对象中。

x509.validTo#

• 类型：<string>

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

x509.validToDate#

• 类型：<Date>

此证书的有效截止日期/时间，封装在一个 Date 对象中。

x509.signatureAlgorithm#

• 类型：<string> | <undefined>

用于签署证书的算法，如果 OpenSSL 不知道该签名算法，则为 undefined。

x509.signatureAlgorithmOid#

• 类型：<string>

用于签署证书的算法的 OID。

x509.verify(publicKey)#

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

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

crypto.argon2(algorithm, parameters, callback)#

• algorithm <string> Argon2 的变体，为 "argon2d"、"argon2i" 或 "argon2id" 之一。
• parameters <Object>
  • message <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> 必需，这是 Argon2 密码哈希应用的密码。
  • nonce <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> 必需，必须至少为 8 字节长。这是 Argon2 密码哈希应用的盐。
  • parallelism <number> 必需，并行度决定了可以运行多少个计算链（通道）。必须大于 1 且小于 2**24-1。
  • tagLength <number> 必需，要生成的密钥长度。必须大于 4 且小于 2**32-1。
  • memory <number> 必需，以 1KiB 块为单位的内存成本。必须大于 8 * parallelism 且小于 2**32-1。实际块数会向下取整到最接近 4 * parallelism 的倍数。
  • passes <number> 必需，传递次数（迭代次数）。必须大于 1 且小于 2**32-1。
  • secret <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <undefined> 可选，随机的附加输入，类似于盐，不应与派生密钥一起存储。这在密码哈希应用中被称为“胡椒”（pepper）。如果使用，长度不得超过 2**32-1 字节。
  • associatedData <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <undefined> 可选，要添加到哈希中的附加数据，功能上等同于盐或秘密，但用于非随机数据。如果使用，长度不得超过 2**32-1 字节。
• callback <Function>
  • err <Error>
  • derivedKey <Buffer>

提供一个异步的 Argon2 实现。Argon2 是一种基于密码的密钥派生函数，旨在使计算和内存成本高昂，从而使暴力攻击变得不划算。

nonce 应该尽可能唯一。建议 nonce 是随机的且至少 16 字节长。详情请参阅 NIST SP 800-132。

当为 message、nonce、secret 或 associatedData 传递字符串时，请考虑将字符串用作加密 API 输入时的注意事项。

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

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

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

const parameters = {
  message: 'password',
  nonce: randomBytes(16),
  parallelism: 4,
  tagLength: 64,
  memory: 65536,
  passes: 3,
};

argon2('argon2id', parameters, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // 'af91dad...9520f15'
});const { argon2, randomBytes } = require('node:crypto');

const parameters = {
  message: 'password',
  nonce: randomBytes(16),
  parallelism: 4,
  tagLength: 64,
  memory: 65536,
  passes: 3,
};

argon2('argon2id', parameters, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // 'af91dad...9520f15'
});copy

crypto.argon2Sync(algorithm, parameters)#

• algorithm <string> Argon2 的变体，为 "argon2d"、"argon2i" 或 "argon2id" 之一。
• parameters <Object>
  • message <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> 必需，这是 Argon2 密码哈希应用的密码。
  • nonce <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> 必需，必须至少为 8 字节长。这是 Argon2 密码哈希应用的盐。
  • parallelism <number> 必需，并行度决定了可以运行多少个计算链（通道）。必须大于 1 且小于 2**24-1。
  • tagLength <number> 必需，要生成的密钥长度。必须大于 4 且小于 2**32-1。
  • memory <number> 必需，以 1KiB 块为单位的内存成本。必须大于 8 * parallelism 且小于 2**32-1。实际块数会向下取整到最接近 4 * parallelism 的倍数。
  • passes <number> 必需，传递次数（迭代次数）。必须大于 1 且小于 2**32-1。
  • secret <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <undefined> 可选，随机的附加输入，类似于盐，不应与派生密钥一起存储。这在密码哈希应用中被称为“胡椒”（pepper）。如果使用，长度不得超过 2**32-1 字节。
  • associatedData <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <undefined> 可选，要添加到哈希中的附加数据，功能上等同于盐或秘密，但用于非随机数据。如果使用，长度不得超过 2**32-1 字节。
• 返回：<Buffer>

提供一个同步的 Argon2 实现。Argon2 是一种基于密码的密钥派生函数，旨在使计算和内存成本高昂，从而使暴力攻击变得不划算。

nonce 应该尽可能唯一。建议 nonce 是随机的且至少 16 字节长。详情请参阅 NIST SP 800-132。

当为 message、nonce、secret 或 associatedData 传递字符串时，请考虑将字符串用作加密 API 输入时的注意事项。

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

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

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

const parameters = {
  message: 'password',
  nonce: randomBytes(16),
  parallelism: 4,
  tagLength: 64,
  memory: 65536,
  passes: 3,
};

const derivedKey = argon2Sync('argon2id', parameters);
console.log(derivedKey.toString('hex'));  // 'af91dad...9520f15'const { argon2Sync, randomBytes } = require('node:crypto');

const parameters = {
  message: 'password',
  nonce: randomBytes(16),
  parallelism: 4,
  tagLength: 64,
  memory: 65536,
  passes: 3,
};

const derivedKey = argon2Sync('argon2id', parameters);
console.log(derivedKey.toString('hex'));  // 'af91dad...9520f15'copy

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

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

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

• 类型：<Object>

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

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 选项
• 返回：<Cipheriv>

创建并返回一个 Cipheriv 对象，使用给定的 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' 编码的字符串、Buffers、TypedArray 或 DataView。key 也可以是类型为 secret 的 KeyObject。如果密码不需要初始化向量，iv 可以是 null。

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

初始化向量应该是不可预测且唯一的；理想情况下，它们应该是加密安全的随机数。它们不必是机密的：IV 通常只是以未加密的形式添加到密文消息中。某些事物必须是不可预测且唯一的，但又不必是机密的，这听起来可能有些矛盾；请记住，攻击者必须不能提前预测出给定的 IV 将是什么。

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 选项
• 返回：<Decipheriv>

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

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

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

key 是 algorithm 使用的原始密钥，iv 是初始化向量。两个参数都必须是 'utf8' 编码的字符串、Buffers、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 字符串指定的预定义曲线创建一个椭圆曲线迪菲-赫尔曼 (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', () => {
  // 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}`);
  }
});copy

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。如果它是一个字符串，请考虑将字符串用作加密 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}`);
  }
});copy

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.decapsulate(key, ciphertext[, callback])#

• key <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> 私钥
• ciphertext <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• callback <Function>
  • err <Error>
  • sharedKey <Buffer>
• 返回：如果未提供 callback 函数，则返回 <Buffer>。

使用 KEM 算法和私钥进行密钥解封装。

支持的密钥类型及其 KEM 算法如下

• 'rsa'² RSA 秘密值封装
• 'ec'³ DHKEM(P-256, HKDF-SHA256), DHKEM(P-384, HKDF-SHA256), DHKEM(P-521, HKDF-SHA256)
• 'x25519'³ DHKEM(X25519, HKDF-SHA256)
• 'x448'³ DHKEM(X448, HKDF-SHA512)
• 'ml-kem-512'¹ ML-KEM
• 'ml-kem-768'¹ ML-KEM
• 'ml-kem-1024'¹ ML-KEM

如果 key 不是 KeyObject，此函数的行为就好像将 key 传递给了 crypto.createPrivateKey() 一样。

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

crypto.diffieHellman(options[, callback])#

• options <Object>
  • privateKey <KeyObject>
  • publicKey <KeyObject>
• callback <Function>
  • err <Error>
  • secret <Buffer>
• 返回：如果未提供 callback 函数，则返回 <Buffer>。

根据 privateKey 和 publicKey 计算 Diffie-Hellman 共享密钥。两个密钥必须具有相同的 asymmetricKeyType，并且必须支持 DH 或 ECDH 操作。

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

crypto.encapsulate(key[, callback])#

• key <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> 公钥
• callback <Function>
  • err <Error>
  • result <Object>
    • sharedKey <Buffer>
    • ciphertext <Buffer>
• 返回：如果未提供 callback 函数，则返回 <Object>。
  • sharedKey <Buffer>
  • ciphertext <Buffer>

使用 KEM 算法和公钥进行密钥封装。

支持的密钥类型及其 KEM 算法如下

• 'rsa'² RSA 秘密值封装
• 'ec'³ DHKEM(P-256, HKDF-SHA256), DHKEM(P-384, HKDF-SHA256), DHKEM(P-521, HKDF-SHA256)
• 'x25519'³ DHKEM(X25519, HKDF-SHA256)
• 'x448'³ DHKEM(X448, HKDF-SHA512)
• 'ml-kem-512'¹ ML-KEM
• 'ml-kem-768'¹ ML-KEM
• 'ml-kem-1024'¹ ML-KEM

如果 key 不是 KeyObject，此函数的行为就好像将 key 传递给了 crypto.createPublicKey() 一样。

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

crypto.fips#

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

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

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: 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
});copy

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

crypto.generateKeyPair(type, options, callback)#

• type <string> 要生成的非对称密钥类型。请参阅支持的非对称密钥类型。
• 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) => {
  // 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.
});copy

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

如果此方法作为其 util.promisify() 版本被调用，它将返回一个 Promise，该 Promise 解析为一个具有 publicKey 和 privateKey 属性的对象。

crypto.generateKeyPairSync(type, options)#

• type <string> 要生成的非对称密钥类型。请参阅支持的非对称密钥类型。
• 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 和 ML-DSA¹。

如果指定了 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',
  },
});copy

返回值 { 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: 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..........41ecopy

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

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。

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

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

素数的 size 会直接影响生成素数所需的时间。size 越大，所需时间越长。因为我们使用 OpenSSL 的 BN_generate_prime_ex 函数，该函数对我们中断生成过程的能力控制很小，所以不建议生成过大的素数，因为这样做可能会使进程无响应。

crypto.generatePrimeSync(size[, options])#

• 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 返回。
• 返回：<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。

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

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

素数的 size 会直接影响生成素数所需的时间。size 越大，所需时间越长。因为我们使用 OpenSSL 的 BN_generate_prime_ex 函数，该函数对我们中断生成过程的能力控制很小，所以不建议生成过大的素数，因为这样做可能会使进程无响应。

crypto.getCipherInfo(nameOrNid[, options])#

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

• 返回：<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', ...]copy

crypto.getCurves()#

• 返回：<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', ...]copy

crypto.getDiffieHellman(groupName)#

• groupName <string>
• 返回：<DiffieHellmanGroup>

创建一个预定义的 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);copy

crypto.getFips()#

• 返回：<number> 当且仅当当前正在使用符合 FIPS 的加密提供程序时返回 1，否则返回 0。未来的 semver-major 版本可能会将此 API 的返回类型更改为 <boolean>。

crypto.getHashes()#

• 返回：<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', ...]copy

crypto.getRandomValues(typedArray)#

• typedArray <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer>
• 返回：<Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> 返回 typedArray。

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

crypto.hash(algorithm, data[, options])#

• algorithm <string> | <undefined>
• data <string> | <Buffer> | <TypedArray> | <DataView> 当 data 是字符串时，它将在哈希前被编码为 UTF-8。如果希望对字符串输入使用不同的输入编码，用户可以使用 TextEncoder 或 Buffer.from() 将字符串编码为 TypedArray，然后将编码后的 TypedArray 传递给此 API。
• options <Object> | <string>
  • outputEncoding <string> 用于编码返回的摘要的编码。默认值： 'hex'。
  • outputLength <number> 对于 XOF 哈希函数（如 'shake256'），可以使用 outputLength 选项来指定所需的输出长度（以字节为单位）。
• 返回：<string> | <Buffer>

一个用于创建数据的一次性哈希摘要的实用工具。在对较小量（<= 5MB）且已准备好的数据进行哈希时，它可能比基于对象的 crypto.createHash() 更快。如果数据可能很大或是流式数据，仍建议使用 crypto.createHash()。

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

如果 options 是一个字符串，则它指定了 outputEncoding。

示例

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

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

• digest <string> 要使用的摘要算法。
• ikm <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> 输入密钥材料。必须提供，但可以为零长度。
• salt <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> 盐值。必须提供，但可以为零长度。
• info <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> 附加信息值。必须提供，但可以为零长度，并且不能超过 1024 字节。
• keylen <number> 要生成的密钥的长度。必须大于 0。允许的最大值是所选摘要函数产生的字节数的 255 倍（例如，sha512 生成 64 字节的哈希，使得最大 HKDF 输出为 16320 字节）。
• callback <Function>
  • err <Error>
  • derivedKey <ArrayBuffer>

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'
});copy

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

• digest <string> 要使用的摘要算法。
• ikm <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> 输入密钥材料。必须提供，但可以为零长度。
• salt <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> 盐值。必须提供，但可以为零长度。
• info <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> 附加信息值。必须提供，但可以为零长度，并且不能超过 1024 字节。
• keylen <number> 要生成的密钥的长度。必须大于 0。允许的最大值是所选摘要函数产生的字节数的 255 倍（例如，sha512 生成 64 字节的哈希，使得最大 HKDF 输出为 16320 字节）。
• 返回：<ArrayBuffer>

提供一个同步的 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'copy

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