Node.js v24.0.0 文档

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

• spkac <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• encoding <string> spkac 字符串的编码。
• 返回：<Buffer> spkac 数据结构的 challenge 组件，包括公钥和 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.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 是字符串时要使用的字符串编码。
• 返回值：<Cipheriv> 用于方法链的同一个 Cipheriv 实例。

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

plaintextLength 选项对于 GCM 和 OCB 是可选的。 当使用 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) 输入参数的值。

options 参数对于 GCM 是可选的。 当使用 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 参数控制流行为。 对于诸如 'shake256' 之类的 XOF 哈希函数，可以使用 outputLength 选项来指定所需的输出长度（以字节为单位）。

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

// 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>

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

• '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.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）。 只有在使用 PEM format 时，才能通过指定 cipher 来加密 PKCS#1 和 SEC1。 为了获得最大的兼容性，请对加密的私钥使用 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: <AlgorithmIdentifier> | <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 节中所述，除非 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.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() 将导致抛出错误。

因为公钥可以从私钥派生，所以可以传递私钥而不是公钥。

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

• 类型: <string[]>

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

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.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.verify(publicKey)#

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

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

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 constants 中描述。

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' 编码的字符串、Buffer、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' 编码的字符串、Buffer、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', () => {
  // 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 options
• 返回: <Sign>

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

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

crypto.createVerify(algorithm[, options])#

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

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

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

crypto.diffieHellman(options[, callback])#

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

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

如果提供了 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> 必须是 '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) => {
  // 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()ed 版本调用，则它会返回一个具有 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',
  },
});copy

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

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

素数的大小将直接影响生成素数所需的时间。 大小越大，花费的时间越长。 因为我们使用 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>。

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

crypto.getCipherInfo(nameOrNid[, options])#

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

返回有关给定 cipher 的信息。

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

crypto.getCiphers()#

• 返回值: <string[]> 包含支持的 cipher 算法名称的数组。

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[, outputEncoding])#

• algorithm <string> | <undefined>
• data <string> | <Buffer> | <TypedArray> | <DataView> 当 data 是字符串时，它将在哈希之前编码为 UTF-8。 如果字符串输入需要不同的输入编码，则用户可以使用 TextEncoder 或 Buffer.from() 将字符串编码为 TypedArray，并将编码的 TypedArray 传递给此 API。
• outputEncoding <string> | <undefined> Encoding 用于编码返回的摘要。 默认: 'hex'。
• 返回值: <string> | <Buffer>

一种用于创建数据的一次性哈希摘要的实用程序。 当哈希较小数量的数据（<= 5MB）且这些数据随时可用时，它可能比基于对象的 crypto.createHash() 更快。 如果数据可能很大或以流式传输，仍然建议改用 crypto.createHash()。

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

示例

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

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

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

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

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

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

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

提供 RFC 5869 中定义的同步 HKDF 密钥派生函数。给定的 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)#

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

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

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

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

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

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

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

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

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

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

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

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

• password <string> | <Buffer> | <TypedArray> | <DataView>
• salt <string> | <Buffer> | <TypedArray> | <DataView>
• iterations <number>
• keylen <number>
• digest <string>
• 返回: <Buffer>

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

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

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

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

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

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

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

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

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

crypto.privateDecrypt(privateKey, buffer)#

• privateKey <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
  • oaepHash <string> 用于 OAEP 填充和 MGF1 的哈希函数。 默认值: 'sha1'
  • oaepLabel <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> 用于 OAEP 填充的标签。如果未指定，则不使用标签。
  • padding <crypto.constants> 在 crypto.constants 中定义的可选填充值，可以是： crypto.constants.RSA_NO_PADDING、crypto.constants.RSA_PKCS1_PADDING 或 crypto.constants.RSA_PKCS1_OAEP_PADDING。
• buffer <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• 返回: <Buffer> 具有解密内容的新 Buffer。

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

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

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

crypto.privateEncrypt(privateKey, buffer)#

• privateKey <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
  • key <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey> PEM 编码的私钥。
  • passphrase <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> 私钥的可选密码。
  • padding <crypto.constants> 在 crypto.constants 中定义的可选填充值，可以是：crypto.constants.RSA_NO_PADDING 或 crypto.constants.RSA_PKCS1_PADDING。
  • encoding <string> 当 buffer、key 或 passphrase 是字符串时使用的字符串编码。
• buffer <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• 返回：<Buffer> 包含加密内容的新 Buffer。

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

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

crypto.publicDecrypt(key, buffer)#

• key <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
  • passphrase <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> 私钥的可选密码。
  • padding <crypto.constants> 在 crypto.constants 中定义的可选填充值，可以是：crypto.constants.RSA_NO_PADDING 或 crypto.constants.RSA_PKCS1_PADDING。
  • encoding <string> 当 buffer、key 或 passphrase 是字符串时使用的字符串编码。
• buffer <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• 返回: <Buffer> 具有解密内容的新 Buffer。

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

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

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

crypto.publicEncrypt(key, buffer)#

• key <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
  • key <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey> PEM 编码的公钥或私钥，<KeyObject> 或 <CryptoKey>。
  • oaepHash <string> 用于 OAEP 填充和 MGF1 的哈希函数。 默认值: 'sha1'
  • oaepLabel <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> 用于 OAEP 填充的标签。如果未指定，则不使用标签。
  • passphrase <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> 私钥的可选密码。
  • padding <crypto.constants> 在 crypto.constants 中定义的可选填充值，可以是： crypto.constants.RSA_NO_PADDING、crypto.constants.RSA_PKCS1_PADDING 或 crypto.constants.RSA_PKCS1_OAEP_PADDING。
  • encoding <string> 当 buffer、key、oaepLabel 或 passphrase 是字符串时使用的字符串编码。
• buffer <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• 返回：<Buffer> 包含加密内容的新 Buffer。

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

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

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

crypto.randomBytes(size[, callback])#

• size <number> 要生成的字节数。 size 不得大于 2**31 - 1。
• callback <Function>
  • err <Error>
  • buf <Buffer>
• 返回: 如果未提供 callback 函数，则返回 <Buffer>。

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

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

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

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

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