Node.js v26.0.0 文档

Console#

node:console 模块提供了一个类似于 Web 浏览器提供的 JavaScript 控制台机制的简单调试控制台。

该模块导出了两个特定组件

• 一个 Console 类，包含 console.log()、console.error() 和 console.warn() 等方法，可用于写入任何 Node.js 流。
• 一个全局 console 实例，配置为写入 process.stdout 和 process.stderr。全局 console 无需调用 require('node:console') 即可使用。

警告: 全局 console 对象的方法既不像它们所模仿的浏览器 API 那样具有一致的同步性，也不像所有其他 Node.js 流那样具有一致的异步性。希望依赖控制台函数同步/异步行为的程序应首先确定控制台底层流的性质。这是因为该流取决于底层平台和当前进程的标准流配置。有关更多信息，请参阅 进程 I/O 的说明。

使用全局 console 的示例

console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
copy

使用 Console 类的示例

const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
copy

类: Console#

Console 类可用于创建具有可配置输出流的简单记录器，可以通过 require('node:console').Console 或 console.Console（或其解构形式）进行访问

import { Console } from 'node:console';
const { Console } = require('node:console');
copy

const { Console } = console;
copy

new Console(stdout[, stderr][, ignoreErrors])#

new Console(options)#

• options <Object>
• stdout <stream.Writable>
• stderr <stream.Writable>
• ignoreErrors <boolean> 写入底层流时忽略错误。 默认: true。
• colorMode <boolean> | <string> 为此 Console 实例设置颜色支持。设置为 true 可在检查值时启用颜色。设置为 false 可在检查值时禁用颜色。设置为 'auto' 会使颜色支持取决于 isTTY 属性的值以及相应流上 getColorDepth() 返回的值。如果也设置了 inspectOptions.colors，则此选项不可用。 默认: 'auto'。
• inspectOptions <Object> | <Map> 指定传递给 util.inspect() 的选项。可以是选项对象，或者如果需要为 stdout 和 stderr 设置不同的选项，则可以是从流对象到选项的 Map。
• groupIndentation <number> 设置分组缩进。 默认: 2。

创建一个带有 1 或 2 个可写流实例的新 Console。stdout 是用于打印日志或信息输出的可写流。stderr 用于警告或错误输出。如果没有提供 stderr，则使用 stdout 作为 stderr。

import { createWriteStream } from 'node:fs';
import { Console } from 'node:console';
// Alternatively
// const { Console } = console;

const output = createWriteStream('./stdout.log');
const errorOutput = createWriteStream('./stderr.log');
// Custom simple logger
const logger = new Console({ stdout: output, stderr: errorOutput });
// use it like console
const count = 5;
logger.log('count: %d', count);
// In stdout.log: count 5
const fs = require('node:fs');
const { Console } = require('node:console');
// Alternatively
// const { Console } = console;

const output = fs.createWriteStream('./stdout.log');
const errorOutput = fs.createWriteStream('./stderr.log');
// Custom simple logger
const logger = new Console({ stdout: output, stderr: errorOutput });
// use it like console
const count = 5;
logger.log('count: %d', count);
// In stdout.log: count 5
copy

全局 console 是一个特殊的 Console，其输出被发送到 process.stdout 和 process.stderr。它等同于调用

new Console({ stdout: process.stdout, stderr: process.stderr });
copy

console.assert(value[, ...message])#

• value <any> 测试是否为真值的待测值。
• ...message <any> 除 value 之外的所有参数都用作错误消息。

如果 value 为 假值 或被省略，console.assert() 会写入一条消息。它仅写入一条消息，不会以其他方式影响执行。输出始终以 "Assertion failed" 开头。如果提供了 message，则使用 util.format() 对其进行格式化。

如果 value 为 真值，则什么也不会发生。

console.assert(true, 'does nothing');

console.assert(false, 'Whoops %s work', 'didn\'t');
// Assertion failed: Whoops didn't work

console.assert();
// Assertion failed
copy

console.clear()#

当 stdout 是 TTY 时，调用 console.clear() 将尝试清除 TTY。当 stdout 不是 TTY 时，此方法不执行任何操作。

console.clear() 的具体操作在不同的操作系统和终端类型之间可能有所不同。对于大多数 Linux 操作系统，console.clear() 的操作类似于 clear shell 命令。在 Windows 上，console.clear() 只会清除 Node.js 二进制文件当前终端视口中的输出。

console.count([label])#

• label <string> 计数器的显示标签。 默认: 'default'。

维护一个特定于 label 的内部计数器，并将调用 console.count() 的次数输出到 stdout。

> console.count()
default: 1
undefined
> console.count('default')
default: 2
undefined
> console.count('abc')
abc: 1
undefined
> console.count('xyz')
xyz: 1
undefined
> console.count('abc')
abc: 2
undefined
> console.count()
default: 3
undefined
>
copy

console.countReset([label])#

• label <string> 计数器的显示标签。 默认: 'default'。

重置特定于 label 的内部计数器。

> console.count('abc');
abc: 1
undefined
> console.countReset('abc');
undefined
> console.count('abc');
abc: 1
undefined
>
copy

console.debug(data[, ...args])#

• data <any>
• ...args <any>

console.debug() 函数是 console.log() 的别名。

console.dir(obj[, options])#

• obj <any>
• options <Object>
• showHidden <boolean> 如果为 true，则还会显示对象的不可枚举和符号属性。 默认: false。
• depth <number> 告诉 util.inspect() 在格式化对象时递归多少次。这对于检查大型复杂对象非常有用。要使其无限递归，请传递 null。 默认: 2。
• colors <boolean> 如果为 true，则输出将使用 ANSI 颜色代码进行样式设置。颜色是可定制的；请参见 自定义 util.inspect() 颜色。 默认: false。

在 obj 上使用 util.inspect() 并将生成的字符串打印到 stdout。此函数绕过在 obj 上定义的任何自定义 inspect() 函数。

console.dirxml(...data)#

• ...data <any>

此方法调用 console.log() 并将接收到的参数传递给它。此方法不产生任何 XML 格式化。

console.error([data][, ...args])#

• data <any>
• ...args <any>

打印到 stderr 并换行。可以传递多个参数，第一个用作主消息，所有附加参数用作替换值，类似于 printf(3)（所有参数都传递给 util.format()）。

const code = 5;
console.error('error #%d', code);
// Prints: error #5, to stderr
console.error('error', code);
// Prints: error 5, to stderr
copy

如果在第一个字符串中未找到格式化元素（例如 %d），则对每个参数调用 util.inspect()，并将结果字符串值连接起来。有关更多信息，请参阅 util.format()。

console.group([...label])#

• ...label <any>

将后续行的缩进量增加 groupIndentation 长度。

如果提供了一个或多个 label，则先打印这些标签，且不带额外的缩进。

console.groupCollapsed()#

console.group() 的别名。

console.groupEnd()#

将后续行的缩进量减少 groupIndentation 长度。

console.info([data][, ...args])#

• data <any>
• ...args <any>

console.info() 函数是 console.log() 的别名。

console.log([data][, ...args])#

• data <any>
• ...args <any>

打印到 stdout 并换行。可以传递多个参数，第一个用作主消息，所有附加参数用作替换值，类似于 printf(3)（所有参数都传递给 util.format()）。

const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
copy

有关更多信息，请参阅 util.format()。

console.table(tabularData[, properties])#

• tabularData <any>
• properties <string[]> 用于构建表的替代属性。

尝试构建一个表格，列为 tabularData 的属性（或使用 properties），行为 tabularData 并将其记录下来。如果无法解析为表格格式，则回退到仅记录该参数。

// These can't be parsed as tabular data
console.table(Symbol());
// Symbol()

console.table(undefined);
// undefined

console.table([{ a: 1, b: 'Y' }, { a: 'Z', b: 2 }]);
// ┌─────────┬─────┬─────┐
// │ (index) │ a   │ b   │
// ├─────────┼─────┼─────┤
// │ 0       │ 1   │ 'Y' │
// │ 1       │ 'Z' │ 2   │
// └─────────┴─────┴─────┘

console.table([{ a: 1, b: 'Y' }, { a: 'Z', b: 2 }], ['a']);
// ┌─────────┬─────┐
// │ (index) │ a   │
// ├─────────┼─────┤
// │ 0       │ 1   │
// │ 1       │ 'Z' │
// └─────────┴─────┘
copy

console.time([label])#

• label <string> 默认: 'default'

启动一个计时器，用于计算操作的持续时间。计时器由唯一的 label 标识。调用 console.timeEnd() 时使用相同的 label 停止计时器并将经过的时间以适当的时间单位输出到 stdout。例如，如果经过的时间是 3869ms，console.timeEnd() 将显示 "3.869s"。

console.timeEnd([label])#

• label <string> 默认: 'default'

停止之前通过调用 console.time() 启动的计时器，并将结果打印到 stdout

console.time('bunch-of-stuff');
// Do a bunch of stuff.
console.timeEnd('bunch-of-stuff');
// Prints: bunch-of-stuff: 225.438ms
copy

console.timeLog([label][, ...data])#

• label <string> 默认: 'default'
• ...data <any>

对于之前通过调用 console.time() 启动的计时器，将经过的时间和其他 data 参数打印到 stdout

console.time('process');
const value = expensiveProcess1(); // Returns 42
console.timeLog('process', value);
// Prints "process: 365.227ms 42".
doExpensiveProcess2(value);
console.timeEnd('process');
copy

console.trace([message][, ...args])#

• message <any>
• ...args <any>

将字符串 'Trace: ' 以及 util.format() 格式化的消息和当前代码位置的堆栈跟踪打印到 stderr。

console.trace('Show me');
// Prints: (stack trace will vary based on where trace is called)
//  Trace: Show me
//    at repl:2:9
//    at REPLServer.defaultEval (repl.js:248:27)
//    at bound (domain.js:287:14)
//    at REPLServer.runBound [as eval] (domain.js:300:12)
//    at REPLServer.<anonymous> (repl.js:412:12)
//    at emitOne (events.js:82:20)
//    at REPLServer.emit (events.js:169:7)
//    at REPLServer.Interface._onLine (readline.js:210:10)
//    at REPLServer.Interface._line (readline.js:549:8)
//    at REPLServer.Interface._ttyWrite (readline.js:826:14)
copy

console.warn([data][, ...args])#

• data <any>
• ...args <any>

console.warn() 函数是 console.error() 的别名。

仅 Inspector 使用的方法#

以下方法由 V8 引擎在通用 API 中暴露，但除非与 inspector (--inspect 标志) 一起使用，否则不会显示任何内容。

console.profile([label])#

• label <string>

除非在 inspector 中使用，否则此方法不会显示任何内容。console.profile() 方法启动一个 JavaScript CPU 分析文件（带有可选标签），直到调用 console.profileEnd()。然后分析文件会被添加到 inspector 的 Profile 面板中。

console.profile('MyLabel');
// Some code
console.profileEnd('MyLabel');
// Adds the profile 'MyLabel' to the Profiles panel of the inspector.
copy

console.profileEnd([label])#

• label <string>

除非在 inspector 中使用，否则此方法不会显示任何内容。停止当前的 JavaScript CPU 分析会话（如果已启动），并将报告打印到 inspector 的 Profiles 面板。有关示例，请参阅 console.profile()。

如果调用此方法时未指定标签，则停止最近启动的分析文件。

console.timeStamp([label])#

• label <string>

除非在 inspector 中使用，否则此方法不会显示任何内容。console.timeStamp() 方法将一个带有 'label' 标签的事件添加到 inspector 的 Timeline 面板中。

加密 (Crypto)#

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

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

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

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

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

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

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

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

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

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

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

非对称密钥类型#

下表列出了 KeyObject API 可识别的非对称密钥类型以及每种密钥类型支持的导出/导入格式。

密钥格式#

非对称密钥可以用几种格式表示。推荐的方法是将密钥材料导入到 KeyObject 中一次并重用它，因为这避免了重复解析并提供最佳性能。

当 KeyObject 不切实际时——例如，当密钥材料到达协议消息中且仅使用一次时——大多数加密函数也接受 PEM 字符串或直接指定格式和密钥材料的对象。有关每种格式接受的完整选项，请参阅 crypto.createPublicKey()、crypto.createPrivateKey() 和 keyObject.export()。

KeyObject#

KeyObject 是解析后的密钥的内存中表示。它由 crypto.createPublicKey()、crypto.createPrivateKey()、crypto.createSecretKey() 或密钥生成函数（如 crypto.generateKeyPair()）创建。使用给定的 KeyObject 进行的第一次加密操作可能比后续操作慢，因为 OpenSSL 在首次使用时会延迟初始化内部缓存。

PEM 和 DER#

PEM 和 DER 是基于 ASN.1 结构的非对称密钥的传统编码格式。

• PEM 是一种文本编码，将 Base64 编码的 DER 数据包裹在页眉和页脚行之间（例如 -----BEGIN PUBLIC KEY-----）。PEM 字符串可以直接传递给大多数加密操作。
• DER 是相同 ASN.1 结构的二进制编码。提供 DER 输入时，必须显式指定 type（通常为 'spki' 或 'pkcs8'）。

JSON Web Key (JWK)#

JSON Web Key (JWK) 是 RFC 7517 中定义的基于 JSON 的密钥表示。JWK 将每个密钥组件编码为 JSON 对象内部单个 Base64url 编码的值。对于 RSA 密钥，JWK 避免了 ASN.1 解析开销，是最快的序列化导入格式。

原始密钥格式#

'raw-public'、'raw-private' 和 'raw-seed' 密钥格式允许导入和导出原始密钥材料，无需任何编码包装器。有关使用详情，请参阅 keyObject.export()、crypto.createPublicKey() 和 crypto.createPrivateKey()。

'raw-public' 通常是导入公钥的最快方式。'raw-private' 和 'raw-seed' 不一定比其他格式更快，因为它们只包含私有标量或种子——导入它们需要导出公钥组件（例如椭圆曲线点乘或种子扩展），这可能会很昂贵。其他格式包括私有和公共组件，避免了该计算。

选择密钥格式#

始终优先使用 KeyObject——从你拥有的任何格式创建一个并重用它。以下指导仅适用于在序列化格式之间进行选择时，无论是为了导入到 KeyObject 中，还是在 KeyObject 不切实际时内联传递密钥材料。

导入密钥#

当为重复使用创建 KeyObject 时，导入成本仅需支付一次，因此选择更快的格式可减少启动延迟。

导入成本分为两部分：解析开销（解码序列化包装器）和 密钥计算（重建完整密钥所需的任何数学工作，例如从私有标量推导公钥或扩展种子）。哪部分占主导地位取决于密钥类型。例如

• 公钥 - 'raw-public' 是最快的序列化格式，因为原始格式跳过了所有 ASN.1 和 Base64 解码。
• EC 私钥 - 'raw-private' 比 PEM 或 DER 快，因为它避免了 ASN.1 解析。然而，对于更大的曲线（例如 P-384, P-521），从私有标量推导公共点的要求变得昂贵，降低了优势。
• RSA 密钥 - 'jwk' 是最快的序列化格式。JWK 将 RSA 密钥组件表示为单个 Base64url 编码的整数，完全避免了 ASN.1 解析的开销。

操作中的内联密钥材料#

当 KeyObject 无法重用时（例如密钥作为原始字节到达协议消息中且仅使用一次），大多数加密函数也接受 PEM 字符串或直接指定格式和密钥材料的对象。在这种情况下，总成本是密钥导入和加密计算本身之和。

对于加密计算占主导地位的操作（例如使用 RSA 签名或使用 P-384 或 P-521 的 ECDH 密钥协商），序列化格式对总体吞吐量的影响微乎其微，因此选择最方便的格式即可。对于像 Ed25519 签名或验证这样的轻量级操作，导入成本占总数的一大部分，因此更快的格式（如 'raw-public' 或 'raw-private'）可以显著提高吞吐量。

即使相同的密钥材料只使用几次，也值得将其导入到 KeyObject 中，而不是重复传递原始或 PEM 表示。

示例#

示例: 在签名和验证操作中重用 KeyObject

import { promisify } from 'node:util';
const { generateKeyPair, sign, verify } = await import('node:crypto');

const { publicKey, privateKey } = await promisify(generateKeyPair)('ed25519');

// A KeyObject holds the parsed key in memory and can be reused
// across multiple operations without re-parsing.
const data = new TextEncoder().encode('message to sign');
const signature = sign(null, data, privateKey);
verify(null, data, publicKey, signature);
copy

示例: 将各种格式的密钥导入到 KeyObject 中

import { promisify } from 'node:util';
const {
  createPrivateKey, createPublicKey, generateKeyPair,
} = await import('node:crypto');

const generated = await promisify(generateKeyPair)('ed25519');

// PEM
const privatePem = generated.privateKey.export({ format: 'pem', type: 'pkcs8' });
const publicPem = generated.publicKey.export({ format: 'pem', type: 'spki' });
createPrivateKey(privatePem);
createPublicKey(publicPem);

// DER - requires explicit type
const privateDer = generated.privateKey.export({ format: 'der', type: 'pkcs8' });
const publicDer = generated.publicKey.export({ format: 'der', type: 'spki' });
createPrivateKey({ key: privateDer, format: 'der', type: 'pkcs8' });
createPublicKey({ key: publicDer, format: 'der', type: 'spki' });

// JWK
const privateJwk = generated.privateKey.export({ format: 'jwk' });
const publicJwk = generated.publicKey.export({ format: 'jwk' });
createPrivateKey({ key: privateJwk, format: 'jwk' });
createPublicKey({ key: publicJwk, format: 'jwk' });

// Raw
const rawPriv = generated.privateKey.export({ format: 'raw-private' });
const rawPub = generated.publicKey.export({ format: 'raw-public' });
createPrivateKey({ key: rawPriv, format: 'raw-private', asymmetricKeyType: 'ed25519' });
createPublicKey({ key: rawPub, format: 'raw-public', asymmetricKeyType: 'ed25519' });
copy

示例: 在不先创建 KeyObject 的情况下将密钥材料直接传递给 crypto.sign() 和 crypto.verify()

import { promisify } from 'node:util';
const { generateKeyPair, sign, verify } = await import('node:crypto');

const generated = await promisify(generateKeyPair)('ed25519');

const data = new TextEncoder().encode('message to sign');

// PEM strings
const privatePem = generated.privateKey.export({ format: 'pem', type: 'pkcs8' });
const publicPem = generated.publicKey.export({ format: 'pem', type: 'spki' });
const sig1 = sign(null, data, privatePem);
verify(null, data, publicPem, sig1);

// JWK objects
const privateJwk = generated.privateKey.export({ format: 'jwk' });
const publicJwk = generated.publicKey.export({ format: 'jwk' });
const sig2 = sign(null, data, { key: privateJwk, format: 'jwk' });
verify(null, data, { key: publicJwk, format: 'jwk' }, sig2);

// Raw key bytes
const rawPriv = generated.privateKey.export({ format: 'raw-private' });
const rawPub = generated.publicKey.export({ format: 'raw-public' });
const sig3 = sign(null, data, {
  key: rawPriv, format: 'raw-private', asymmetricKeyType: 'ed25519',
});
verify(null, data, {
  key: rawPub, format: 'raw-public', asymmetricKeyType: 'ed25519',
}, sig3);
copy

示例: 对于 EC 密钥，导入原始密钥时需要 namedCurve 选项

import { promisify } from 'node:util';
const {
  createPrivateKey, createPublicKey, generateKeyPair, sign, verify,
} = await import('node:crypto');

const generated = await promisify(generateKeyPair)('ec', {
  namedCurve: 'P-256',
});

// Export the raw EC public key (uncompressed by default).
const rawPublicKey = generated.publicKey.export({ format: 'raw-public' });

// The following is equivalent.
const rawPublicKeyUncompressed = generated.publicKey.export({
  format: 'raw-public',
  type: 'uncompressed',
});

// Export compressed point format.
const rawPublicKeyCompressed = generated.publicKey.export({
  format: 'raw-public',
  type: 'compressed',
});

// Export the raw EC private key.
const rawPrivateKey = generated.privateKey.export({ format: 'raw-private' });

// Import the raw EC keys.
// Both compressed and uncompressed point formats are accepted.
const publicKey = createPublicKey({
  key: rawPublicKey,
  format: 'raw-public',
  asymmetricKeyType: 'ec',
  namedCurve: 'P-256',
});
const privateKey = createPrivateKey({
  key: rawPrivateKey,
  format: 'raw-private',
  asymmetricKeyType: 'ec',
  namedCurve: 'P-256',
});

const data = new TextEncoder().encode('message to sign');
const signature = sign('sha256', data, privateKey);
verify('sha256', data, publicKey, signature);
copy

示例: 导出原始种子并导入它们

import { promisify } from 'node:util';
const {
  createPrivateKey, decapsulate, encapsulate, generateKeyPair,
} = await import('node:crypto');

const generated = await promisify(generateKeyPair)('ml-kem-768');

// Export the raw seed (64 bytes for ML-KEM).
const seed = generated.privateKey.export({ format: 'raw-seed' });

// Import the raw seed.
const privateKey = createPrivateKey({
  key: seed,
  format: 'raw-seed',
  asymmetricKeyType: 'ml-kem-768',
});

const { ciphertext } = encapsulate(generated.publicKey);
decapsulate(privateKey, ciphertext);
copy

类: Certificate#

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

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

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

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

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

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

静态方法: 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 false
const { Buffer } = require('node:buffer');
const { Certificate } = require('node:crypto');

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

遗留 API#

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

new crypto.Certificate()#

Certificate 类的实例可以使用 new 关键字创建，或者通过将 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

certificate.exportChallenge(spkac[, encoding])#

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

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

certificate.exportPublicKey(spkac[, encoding])#

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

const { Certificate } = await import('node:crypto');
const cert = Certificate();
const spkac = getSpkacSomehow();
const publicKey = cert.exportPublicKey(spkac);
console.log(publicKey);
// 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

certificate.verifySpkac(spkac[, encoding])#

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

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

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

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

类: Cipheriv#

• 扩展: <stream.Transform>

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

• 作为既可读又可写的 流，将普通未加密数据写入，以在可读端产生加密数据，或者
• 使用 cipher.update() 和 cipher.final() 方法来生成加密数据。

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

示例: 将 Cipheriv 对象用作流

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

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

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

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

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

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

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

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

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

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

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

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

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

示例: 使用 Cipheriv 和管道流

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 是字符串时使用的字符串编码。

当使用认证加密模式（目前支持 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() 将导致抛出错误。

类：Decipheriv#

• 扩展: <stream.Transform>

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

• 作为既可读又可写的流，将纯加密数据写入，在可读侧产生未加密的数据，或者
• 使用 decipher.update() 和 decipher.final() 方法来产生未加密的数据。

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

示例：将 Decipheriv 对象用作流

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

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

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

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

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

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

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

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

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

示例：使用 Decipheriv 和管道流

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 是字符串时使用的字符串编码。

当使用认证加密模式（目前支持 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() 将抛出错误。

decipher.setAuthTag() 方法必须在 CCM 模式的 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#

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

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

import assert from 'node:assert';

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

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

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

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

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

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

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

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

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

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

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

类：DiffieHellmanGroup#

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

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

支持以下组

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

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

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

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

类：ECDH#

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

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

import assert from 'node:assert';

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

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

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

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

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

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

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

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

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

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

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