Node.js v25.0.0 文档

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

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

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

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

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

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

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

TLS/SSL 概念#

TLS/SSL 是一组协议，依赖于公钥基础设施 (PKI) 来实现客户端和服务器之间的安全通信。对于大多数常见情况，每个服务器都必须有一个私钥。

私钥可以通过多种方式生成。以下示例演示了如何使用 OpenSSL 命令行界面生成一个 2048 位的 RSA 私钥：

openssl genrsa -out ryans-key.pem 2048 copy

使用 TLS/SSL 时，所有服务器（以及某些客户端）都必须有一个证书。证书是与私钥对应的公钥，并由证书颁发机构或私钥所有者进行数字签名（此类证书称为“自签名”证书）。获取证书的第一步是创建一个证书签名请求 (CSR) 文件。

OpenSSL 命令行界面可用于为私钥生成 CSR：

openssl req -new -sha256 -key ryans-key.pem -out ryans-csr.pem copy

CSR 文件生成后，可以将其发送给证书颁发机构进行签名，或用于生成自签名证书。

以下示例演示了如何使用 OpenSSL 命令行界面创建自签名证书：

openssl x509 -req -in ryans-csr.pem -signkey ryans-key.pem -out ryans-cert.pem copy

证书生成后，可用于生成 .pfx 或 .p12 文件：

openssl pkcs12 -export -in ryans-cert.pem -inkey ryans-key.pem \
      -certfile ca-cert.pem -out ryans.pfx copy

其中：

• in：是已签名的证书
• inkey：是关联的私钥
• certfile：是所有证书颁发机构 (CA) 证书拼接成的一个文件，例如 cat ca1-cert.pem ca2-cert.pem > ca-cert.pem

openssl s_client -connect localhost:443 -reconnect copy

New, TLSv1.2, Cipher is ECDHE-RSA-AES128-GCM-SHA256 copy

Reused, TLSv1.2, Cipher is ECDHE-RSA-AES128-GCM-SHA256 copy

修改默认的 TLS 密码套件#

Node.js 内置了默认的已启用和已禁用的 TLS 密码套件。这个默认密码列表可以在构建 Node.js 时进行配置，以允许发行版提供自己的默认列表。

以下命令可用于显示默认的密码套件：

node -p crypto.constants.defaultCoreCipherList | tr ':' '\n'
TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256
TLS_AES_128_GCM_SHA256
ECDHE-RSA-AES128-GCM-SHA256
ECDHE-ECDSA-AES128-GCM-SHA256
ECDHE-RSA-AES256-GCM-SHA384
ECDHE-ECDSA-AES256-GCM-SHA384
DHE-RSA-AES128-GCM-SHA256
ECDHE-RSA-AES128-SHA256
DHE-RSA-AES128-SHA256
ECDHE-RSA-AES256-SHA384
DHE-RSA-AES256-SHA384
ECDHE-RSA-AES256-SHA256
DHE-RSA-AES256-SHA256
HIGH
!aNULL
!eNULL
!EXPORT
!DES
!RC4
!MD5
!PSK
!SRP
!CAMELLIA copy

可以使用 --tls-cipher-list 命令行开关（直接使用，或通过 NODE_OPTIONS 环境变量）完全替换此默认值。例如，以下命令使 ECDHE-RSA-AES128-GCM-SHA256:!RC4 成为默认的 TLS 密码套件：

node --tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4' server.js

export NODE_OPTIONS=--tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4'
node server.js copy

要进行验证，请使用以下命令显示设置的密码列表，注意 defaultCoreCipherList 和 defaultCipherList 之间的区别：

node --tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4' -p crypto.constants.defaultCipherList | tr ':' '\n'
ECDHE-RSA-AES128-GCM-SHA256
!RC4 copy

即，defaultCoreCipherList 列表在编译时设置，而 defaultCipherList 在运行时设置。

要从运行时内部修改默认密码套件，请修改 tls.DEFAULT_CIPHERS 变量，这必须在监听任何套接字之前执行，它不会影响已经打开的套接字。例如：

// Remove Obsolete CBC Ciphers and RSA Key Exchange based Ciphers as they don't provide Forward Secrecy
tls.DEFAULT_CIPHERS +=
  ':!ECDHE-RSA-AES128-SHA:!ECDHE-RSA-AES128-SHA256:!ECDHE-RSA-AES256-SHA:!ECDHE-RSA-AES256-SHA384' +
  ':!ECDHE-ECDSA-AES128-SHA:!ECDHE-ECDSA-AES128-SHA256:!ECDHE-ECDSA-AES256-SHA:!ECDHE-ECDSA-AES256-SHA384' +
  ':!kRSA'; copy

默认值也可以在每个客户端或服务器的基础上使用 tls.createSecureContext() 的 ciphers 选项来替换，该选项也存在于 tls.createServer()、tls.connect() 以及创建新的 tls.TLSSocket 时。

密码列表可以包含 TLSv1.3 密码套件名称（以 'TLS_' 开头）和 TLSv1.2 及以下密码套件规范的混合。TLSv1.2 密码支持传统的规范格式，详情请参阅 OpenSSL 密码列表格式 文档，但这些规范不适用于 TLSv1.3 密码。TLSv1.3 套件只能通过在密码列表中包含其全名来启用。例如，不能使用传统的 TLSv1.2 'EECDH' 或 '!EECDH' 规范来启用或禁用它们。

尽管 TLSv1.3 和 TLSv1.2 密码套件的相对顺序如何，TLSv1.3 协议比 TLSv1.2 安全得多，并且如果握手表明支持它，并且有任何 TLSv1.3 密码套件被启用，则总是会优先选择 TLSv1.3 而非 TLSv1.2。

Node.js 中包含的默认密码套件经过精心挑选，以反映当前的安全最佳实践和风险缓解。更改默认密码套件可能会对应用程序的安全性产生重大影响。只有在绝对必要时才应使用 --tls-cipher-list 开关和 ciphers 选项。

默认密码套件为 Chrome 的“现代加密”设置首选 GCM 密码，并为完全正向保密首选 ECDHE 和 DHE 密码，同时提供一些向后兼容性。

依赖于不安全且已弃用的 RC4 或基于 DES 的密码的旧客户端（如 Internet Explorer 6）无法使用默认配置完成握手过程。如果必须支持这些客户端，TLS 建议可能会提供一个兼容的密码套件。有关格式的更多详细信息，请参阅 OpenSSL 密码列表格式 文档。

只有五个 TLSv1.3 密码套件：

• 'TLS_AES_256_GCM_SHA384'
• 'TLS_CHACHA20_POLY1305_SHA256'
• 'TLS_AES_128_GCM_SHA256'
• 'TLS_AES_128_CCM_SHA256'
• 'TLS_AES_128_CCM_8_SHA256'

前三个默认启用。两个基于 CCM 的套件受 TLSv1.3 支持，因为它们在受限系统上可能性能更高，但默认情况下未启用，因为它们提供的安全性较低。

OpenSSL 安全级别#

OpenSSL 库强制执行安全级别，以控制加密操作的最低可接受安全级别。OpenSSL 的安全级别从 0 到 5，每个级别都强制执行更严格的安全要求。默认安全级别为 2，通常适用于大多数现代应用程序。然而，一些旧版功能和协议，如 TLSv1，需要较低的安全级别（SECLEVEL=0）才能正常工作。有关更详细的信息，请参阅 OpenSSL 关于安全级别的文档。

import { createServer, connect } from 'node:tls';
const port = 443;

createServer({ ciphers: 'DEFAULT@SECLEVEL=0', minVersion: 'TLSv1' }, function(socket) {
  console.log('Client connected with protocol:', socket.getProtocol());
  socket.end();
  this.close();
})
.listen(port, () => {
  connect(port, { ciphers: 'DEFAULT@SECLEVEL=0', maxVersion: 'TLSv1' });
});const { createServer, connect } = require('node:tls');
const port = 443;

createServer({ ciphers: 'DEFAULT@SECLEVEL=0', minVersion: 'TLSv1' }, function(socket) {
  console.log('Client connected with protocol:', socket.getProtocol());
  socket.end();
  this.close();
})
.listen(port, () => {
  connect(port, { ciphers: 'DEFAULT@SECLEVEL=0', maxVersion: 'TLSv1' });
});copy

X509 证书错误代码#

多个函数可能会因为 OpenSSL 报告的证书错误而失败。在这种情况下，该函数通过其回调提供一个 <Error>，该错误具有一个 code 属性，该属性可以取以下值之一：

• 'UNABLE_TO_GET_ISSUER_CERT'：无法获取颁发者证书。
• 'UNABLE_TO_GET_CRL'：无法获取证书 CRL。
• 'UNABLE_TO_DECRYPT_CERT_SIGNATURE'：无法解密证书签名。
• 'UNABLE_TO_DECRYPT_CRL_SIGNATURE'：无法解密 CRL 的签名。
• 'UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY'：无法解码颁发者公钥。
• 'CERT_SIGNATURE_FAILURE'：证书签名失败。
• 'CRL_SIGNATURE_FAILURE'：CRL 签名失败。
• 'CERT_NOT_YET_VALID'：证书尚未生效。
• 'CERT_HAS_EXPIRED'：证书已过期。
• 'CRL_NOT_YET_VALID'：CRL 尚未生效。
• 'CRL_HAS_EXPIRED'：CRL 已过期。
• 'ERROR_IN_CERT_NOT_BEFORE_FIELD'：证书的 notBefore 字段格式错误。
• 'ERROR_IN_CERT_NOT_AFTER_FIELD'：证书的 notAfter 字段格式错误。
• 'ERROR_IN_CRL_LAST_UPDATE_FIELD'：CRL 的 lastUpdate 字段格式错误。
• 'ERROR_IN_CRL_NEXT_UPDATE_FIELD'：CRL 的 nextUpdate 字段格式错误。
• 'OUT_OF_MEM'：内存不足。
• 'DEPTH_ZERO_SELF_SIGNED_CERT'：自签名证书。
• 'SELF_SIGNED_CERT_IN_CHAIN'：证书链中的自签名证书。
• 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY'：无法在本地获取颁发者证书。
• 'UNABLE_TO_VERIFY_LEAF_SIGNATURE'：无法验证第一个证书。
• 'CERT_CHAIN_TOO_LONG'：证书链太长。
• 'CERT_REVOKED'：证书已吊销。
• 'INVALID_CA'：无效的 CA 证书。
• 'PATH_LENGTH_EXCEEDED'：路径长度约束超出。
• 'INVALID_PURPOSE'：不支持的证书用途。
• 'CERT_UNTRUSTED'：证书不受信任。
• 'CERT_REJECTED'：证书被拒绝。
• 'HOSTNAME_MISMATCH'：主机名不匹配。

当发生像 UNABLE_TO_VERIFY_LEAF_SIGNATURE、DEPTH_ZERO_SELF_SIGNED_CERT 或 UNABLE_TO_GET_ISSUER_CERT 这样的证书错误时，Node.js 会附加一个提示，建议如果根 CA 已在本地安装，则尝试使用 --use-system-ca 标志运行，以引导开发者走向安全的解决方案，防止不安全的变通方法。

类：tls.Server#

• 继承自：<net.Server>

接受使用 TLS 或 SSL 的加密连接。

const logFile = fs.createWriteStream('/tmp/ssl-keys.log', { flags: 'a' });
// ...
server.on('keylog', (line, tlsSocket) => {
  if (tlsSocket.remoteAddress !== '...')
    return; // Only log keys for a particular IP
  logFile.write(line);
}); copy

const tlsSessionStore = {};
server.on('newSession', (id, data, cb) => {
  tlsSessionStore[id.toString('hex')] = data;
  cb();
});
server.on('resumeSession', (id, cb) => {
  cb(null, tlsSessionStore[id.toString('hex')] || null);
}); copy

类：tls.TLSSocket#

• 继承自: <net.Socket>

对写入的数据进行透明加密并执行所有必需的 TLS 协商。

tls.TLSSocket 的实例实现了双工 Stream 接口。

返回 TLS 连接元数据的方法（例如 tls.TLSSocket.getPeerCertificate()）只会在连接打开时返回数据。

const logFile = fs.createWriteStream('/tmp/ssl-keys.log', { flags: 'a' });
// ...
tlsSocket.on('keylog', (line) => logFile.write(line)); copy

tlsSocket.once('session', (session) => {
  // The session can be used immediately or later.
  tls.connect({
    session: session,
    // Other connect options...
  });
}); copy

const keyingMaterial = tlsSocket.exportKeyingMaterial(
  128,
  'client finished');

/*
 Example return value of keyingMaterial:
 <Buffer 76 26 af 99 c5 56 8e 42 09 91 ef 9f 93 cb ad 6c 7b 65 f8 53 f1 d8 d9
    12 5a 33 b8 b5 25 df 7b 37 9f e0 e2 4f b8 67 83 a3 2f cd 5d 41 42 4c 91
    74 ef 2c ... 78 more bytes>
*/ copy

{
    "name": "AES256-SHA",
    "standardName": "TLS_RSA_WITH_AES_256_CBC_SHA",
    "version": "SSLv3"
} copy

{ subject:
   { OU: [ 'Domain Control Validated', 'PositiveSSL Wildcard' ],
     CN: '*.nodejs.org' },
  issuer:
   { C: 'GB',
     ST: 'Greater Manchester',
     L: 'Salford',
     O: 'COMODO CA Limited',
     CN: 'COMODO RSA Domain Validation Secure Server CA' },
  subjectaltname: 'DNS:*.nodejs.org, DNS:nodejs.org',
  infoAccess:
   { 'CA Issuers - URI':
      [ 'http://crt.comodoca.com/COMODORSADomainValidationSecureServerCA.crt' ],
     'OCSP - URI': [ 'http://ocsp.comodoca.com' ] },
  modulus: 'B56CE45CB740B09A13F64AC543B712FF9EE8E4C284B542A1708A27E82A8D151CA178153E12E6DDA15BF70FFD96CB8A88618641BDFCCA03527E665B70D779C8A349A6F88FD4EF6557180BD4C98192872BCFE3AF56E863C09DDD8BC1EC58DF9D94F914F0369102B2870BECFA1348A0838C9C49BD1C20124B442477572347047506B1FCD658A80D0C44BCC16BC5C5496CFE6E4A8428EF654CD3D8972BF6E5BFAD59C93006830B5EB1056BBB38B53D1464FA6E02BFDF2FF66CD949486F0775EC43034EC2602AEFBF1703AD221DAA2A88353C3B6A688EFE8387811F645CEED7B3FE46E1F8B9F59FAD028F349B9BC14211D5830994D055EEA3D547911E07A0ADDEB8A82B9188E58720D95CD478EEC9AF1F17BE8141BE80906F1A339445A7EB5B285F68039B0F294598A7D1C0005FC22B5271B0752F58CCDEF8C8FD856FB7AE21C80B8A2CE983AE94046E53EDE4CB89F42502D31B5360771C01C80155918637490550E3F555E2EE75CC8C636DDE3633CFEDD62E91BF0F7688273694EEEBA20C2FC9F14A2A435517BC1D7373922463409AB603295CEB0BB53787A334C9CA3CA8B30005C5A62FC0715083462E00719A8FA3ED0A9828C3871360A73F8B04A4FC1E71302844E9BB9940B77E745C9D91F226D71AFCAD4B113AAF68D92B24DDB4A2136B55A1CD1ADF39605B63CB639038ED0F4C987689866743A68769CC55847E4A06D6E2E3F1',
  exponent: '0x10001',
  pubkey: <Buffer ... >,
  valid_from: 'Aug 14 00:00:00 2017 GMT',
  valid_to: 'Nov 20 23:59:59 2019 GMT',
  fingerprint: '01:02:59:D9:C3:D2:0D:08:F7:82:4E:44:A4:B4:53:C5:E2:3A:87:4D',
  fingerprint256: '69:AE:1A:6A:D4:3D:C6:C1:1B:EA:C6:23:DE:BA:2A:14:62:62:93:5C:7A:EA:06:41:9B:0B:BC:87:CE:48:4E:02',
  fingerprint512: '19:2B:3E:C3:B3:5B:32:E8:AE:BB:78:97:27:E4:BA:6C:39:C9:92:79:4F:31:46:39:E2:70:E5:5F:89:42:17:C9:E8:64:CA:FF:BB:72:56:73:6E:28:8A:92:7E:A3:2A:15:8B:C2:E0:45:CA:C3:BC:EA:40:52:EC:CA:A2:68:CB:32',
  ext_key_usage: [ '1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2' ],
  serialNumber: '66593D57F20CBC573E433381B5FEC280',
  raw: <Buffer ... > } copy

tls.checkServerIdentity(hostname, cert)#

• hostname <string> 用于验证证书的主机名或 IP 地址。
• cert <Object> 代表对等方证书的证书对象。
• 返回：<Error> | <undefined>

验证证书 cert 是否颁发给了 hostname。

失败时返回一个 <Error> 对象，并在其中填充 reason、host 和 cert。成功时返回 <undefined>。

此函数旨在与可以传递给 tls.connect() 的 checkServerIdentity 选项结合使用，因此它操作的是一个证书对象。对于其他目的，请考虑使用 x509.checkHost()。

可以通过提供一个替代函数作为传递给 tls.connect() 的 options.checkServerIdentity 选项来覆盖此函数。当然，覆盖函数可以调用 tls.checkServerIdentity()，以通过额外的验证来增强已有的检查。

只有当证书通过所有其他检查时，例如由受信任的 CA 颁发（options.ca），才会调用此函数。

早期版本的 Node.js 错误地接受了给定 hostname 的证书，只要存在匹配的 uniformResourceIdentifier 主体备用名称（参见 CVE-2021-44531）。希望接受 uniformResourceIdentifier 主体备用名称的应用程序可以使用一个实现了所需行为的自定义 options.checkServerIdentity 函数。

tls.connect(options[, callback])#

• options <Object>
  • enableTrace：参见 tls.createServer()
  • host <string> 客户端应连接的主机。默认值： 'localhost'。
  • port <number> 客户端应连接的端口。
  • path <string> 创建到指定路径的 Unix 套接字连接。如果指定此选项，则忽略 host 和 port。
  • socket <stream.Duplex> 在给定的套接字上建立安全连接，而不是创建新的套接字。通常，这是 net.Socket 的实例，但允许任何 Duplex 流。如果指定了此选项，则除了证书验证外，path、host 和 port 都会被忽略。通常，传递给 tls.connect() 的套接字已经连接，但也可以稍后连接。socket 的连接/断开/销毁由用户负责；调用 tls.connect() 不会导致调用 net.connect()。
  • allowHalfOpen <boolean> 如果设置为 false，则当可读端结束时，套接字将自动结束可写端。如果设置了 socket 选项，则此选项无效。有关详细信息，请参阅 net.Socket 的 allowHalfOpen 选项。默认值： false。
  • rejectUnauthorized <boolean> 如果不为 false，则根据提供的 CA 列表验证服务器证书。如果验证失败，则会触发 'error' 事件；err.code 包含 OpenSSL 错误代码。默认值： true。
  • pskCallback <Function> 用于 TLS-PSK 协商，请参阅预共享密钥。
  • ALPNProtocols <string[]> | <Buffer[]> | <TypedArray[]> | <DataView[]> | <Buffer> | <TypedArray> | <DataView> 包含支持的 ALPN 协议的字符串、Buffer、TypedArray 或 DataView 的数组，或单个 Buffer、TypedArray 或 DataView。Buffer 应采用 [len][name][len][name]... 的格式，例如 '\x08http/1.1\x08http/1.0'，其中 len 字节是下一个协议名称的长度。传递数组通常更简单，例如 ['http/1.1', 'http/1.0']。列表中较早的协议比后面的协议有更高的优先级。
  • servername <string> 用于 SNI (服务器名称指示) TLS 扩展的服务器名称。它是要连接的主机的名称，必须是主机名，而不是 IP 地址。多宿主服务器可以使用它来选择正确的证书呈现给客户端，请参阅 tls.createServer() 的 SNICallback 选项。
  • checkServerIdentity(servername, cert) <Function> 在检查服务器的主机名（或显式设置 servername 时的值）与证书时使用的回调函数（而不是内置的 tls.checkServerIdentity() 函数）。如果验证失败，它应该返回一个 <Error>。如果 servername 和 cert 验证通过，该方法应返回 undefined。
  • session <Buffer> 一个包含 TLS 会话的 Buffer 实例。
  • minDHSize <number> 接受 TLS 连接的 DH 参数的最小大小（以位为单位）。当服务器提供的 DH 参数大小小于 minDHSize 时，TLS 连接将被销毁并抛出错误。默认值： 1024。
  • highWaterMark <number> 与可读流的 highWaterMark 参数一致。默认值： 16 * 1024。
  • secureContext：使用 tls.createSecureContext() 创建的 TLS 上下文对象。如果未提供 secureContext，将通过将整个 options 对象传递给 tls.createSecureContext() 来创建一个。
  • onread <Object> 如果缺少 socket 选项，传入的数据将存储在单个 buffer 中，并在数据到达套接字时传递给提供的 callback，否则该选项将被忽略。有关详细信息，请参阅 net.Socket 的 onread 选项。
  • ...: 如果缺少 secureContext 选项，则使用 tls.createSecureContext() 的选项，否则它们将被忽略。
  • ...: 任何未列出的 socket.connect() 选项。
• callback <Function>
• 返回：<tls.TLSSocket>

如果指定了 callback 函数，它将被添加为 'secureConnect' 事件的监听器。

tls.connect() 返回一个 tls.TLSSocket 对象。

与 https API 不同，tls.connect() 默认不启用 SNI (服务器名称指示) 扩展，这可能导致一些服务器返回不正确的证书或完全拒绝连接。要启用 SNI，除了 host 之外，还要设置 servername 选项。

下面演示了 tls.createServer() 回显服务器示例的客户端

// Assumes an echo server that is listening on port 8000.
import { connect } from 'node:tls';
import { readFileSync } from 'node:fs';
import { stdin } from 'node:process';

const options = {
  // Necessary only if the server requires client certificate authentication.
  key: readFileSync('client-key.pem'),
  cert: readFileSync('client-cert.pem'),

  // Necessary only if the server uses a self-signed certificate.
  ca: [ readFileSync('server-cert.pem') ],

  // Necessary only if the server's cert isn't for "localhost".
  checkServerIdentity: () => { return null; },
};

const socket = connect(8000, options, () => {
  console.log('client connected',
              socket.authorized ? 'authorized' : 'unauthorized');
  stdin.pipe(socket);
  stdin.resume();
});
socket.setEncoding('utf8');
socket.on('data', (data) => {
  console.log(data);
});
socket.on('end', () => {
  console.log('server ends connection');
});// Assumes an echo server that is listening on port 8000.
const { connect } = require('node:tls');
const { readFileSync } = require('node:fs');

const options = {
  // Necessary only if the server requires client certificate authentication.
  key: readFileSync('client-key.pem'),
  cert: readFileSync('client-cert.pem'),

  // Necessary only if the server uses a self-signed certificate.
  ca: [ readFileSync('server-cert.pem') ],

  // Necessary only if the server's cert isn't for "localhost".
  checkServerIdentity: () => { return null; },
};

const socket = connect(8000, options, () => {
  console.log('client connected',
              socket.authorized ? 'authorized' : 'unauthorized');
  process.stdin.pipe(socket);
  process.stdin.resume();
});
socket.setEncoding('utf8');
socket.on('data', (data) => {
  console.log(data);
});
socket.on('end', () => {
  console.log('server ends connection');
});copy

要为此示例生成证书和密钥，请运行：

openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \
  -keyout client-key.pem -out client-cert.pem copy

然后，要为此示例生成 server-cert.pem 证书，请运行

openssl pkcs12 -certpbe AES-256-CBC -export -out server-cert.pem \
  -inkey client-key.pem -in client-cert.pem copy

tls.connect(path[, options][, callback])#

• path <string> options.path 的默认值。
• options <Object> 参见 tls.connect()。
• callback <Function> 参见 tls.connect()。
• 返回：<tls.TLSSocket>

与 tls.connect() 相同，只是 path 可以作为参数而不是选项提供。

如果指定了路径选项，它将优先于路径参数。

tls.connect(port[, host][, options][, callback])#

• port <number> options.port 的默认值。
• host <string> options.host 的默认值。
• options <Object> 参见 tls.connect()。
• callback <Function> 参见 tls.connect()。
• 返回：<tls.TLSSocket>

与 tls.connect() 相同，只是 port 和 host 可以作为参数而不是选项提供。

如果指定了端口或主机选项，它将优先于任何端口或主机参数。

tls.createSecureContext([options])#

• options <Object>
  • allowPartialTrustChain <boolean> 将信任 CA 证书列表中的中间（非自签名）证书视为受信任。
  • ca <string> | <string[]> | <Buffer> | <Buffer[]> 可选地覆盖受信任的 CA 证书。如果未指定，默认受信任的 CA 证书与使用 default 类型调用 tls.getCACertificates() 返回的证书相同。如果指定了，默认列表将被 ca 选项中的证书完全替换（而不是拼接）。如果用户希望添加额外的证书而不是完全覆盖默认值，则需要手动拼接。该值可以是字符串或 Buffer，或者是字符串和/或 Buffer 的 Array。任何字符串或 Buffer 都可以包含多个连接在一起的 PEM CA。对等方的证书必须能链接到服务器信任的 CA，连接才能被验证。当使用无法链接到众所周知的 CA 的证书时，必须明确将证书的 CA 指定为受信任的，否则连接将无法验证。如果对等方使用的证书与默认 CA 之一不匹配或无法链接，请使用 ca 选项提供一个对等方证书可以匹配或链接到的 CA 证书。对于自签名证书，证书本身就是其 CA，必须提供。对于 PEM 编码的证书，支持的类型是 "TRUSTED CERTIFICATE"、"X509 CERTIFICATE" 和 "CERTIFICATE"。
  • cert <string> | <string[]> | <Buffer> | <Buffer[]> PEM 格式的证书链。每个私钥应提供一个证书链。每个证书链应由为提供的私钥 key 的 PEM 格式证书、紧随其后的 PEM 格式的中间证书（如果有）按顺序组成，且不包括根 CA（根 CA 必须是对方预先知道的，参见 ca）。当提供多个证书链时，它们不必与 key 中的私钥顺序相同。如果未提供中间证书，对方将无法验证证书，握手将失败。
  • sigalgs <string> 以冒号分隔的支持的签名算法列表。该列表可以包含摘要算法（SHA256、MD5 等）、公钥算法（RSA-PSS、ECDSA 等）、两者的组合（例如 'RSA+SHA384'）或 TLS v1.3 方案名称（例如 rsa_pss_pss_sha512）。更多信息请参阅 OpenSSL man pages。
  • ciphers <string> 密码套件规范，替换默认值。更多信息，请参阅修改默认的 TLS 密码套件。允许的密码可以通过 tls.getCiphers() 获取。密码名称必须大写，以便 OpenSSL 接受它们。
  • clientCertEngine <string> 可以提供客户端证书的 OpenSSL 引擎的名称。已弃用。
  • crl <string> | <string[]> | <Buffer> | <Buffer[]> PEM 格式的 CRL（证书吊销列表）。
  • dhparam <string> | <Buffer> 'auto' 或自定义 Diffie-Hellman 参数，对于非 ECDHE 完全前向保密是必需的。如果省略或无效，参数将被静默丢弃，DHE 密码将不可用。基于 ECDHE 的完全前向保密仍然可用。
  • ecdhCurve <string> 一个描述命名曲线的字符串，或一个以冒号分隔的曲线 NID 或名称列表，例如 P-521:P-384:P-256，用于 ECDH 密钥协商。设置为 auto 以自动选择曲线。使用 crypto.getCurves() 获取可用曲线名称的列表。在最近的版本中，openssl ecparam -list_curves 也将显示每个可用椭圆曲线的名称和描述。默认值： tls.DEFAULT_ECDH_CURVE。
  • honorCipherOrder <boolean> 尝试使用服务器的密码套件偏好，而不是客户端的。当为 true 时，会导致在 secureOptions 中设置 SSL_OP_CIPHER_SERVER_PREFERENCE，更多信息请参阅 OpenSSL 选项。
  • key <string> | <string[]> | <Buffer> | <Buffer[]> | <Object[]> PEM 格式的私钥。PEM 允许私钥被加密。加密的密钥将使用 options.passphrase 解密。可以使用不同算法的多个密钥，可以是一个未加密的密钥字符串或缓冲区的数组，或者是一个形式为 {pem: <string|buffer>[, passphrase: <string>]} 的对象数组。对象形式只能出现在数组中。object.passphrase 是可选的。加密的密钥如果提供了 object.passphrase，将用它解密，否则用 options.passphrase 解密。
  • privateKeyEngine <string> 从中获取私钥的 OpenSSL 引擎的名称。应与 privateKeyIdentifier 一起使用。已弃用。
  • privateKeyIdentifier <string> 由 OpenSSL 引擎管理的私钥的标识符。应与 privateKeyEngine 一起使用。不应与 key 一起设置，因为这两个选项以不同的方式定义私钥。已弃用。
  • maxVersion <string> 可选地设置允许的最高 TLS 版本。可以是 'TLSv1.3'、'TLSv1.2'、'TLSv1.1' 或 'TLSv1' 之一。不能与 secureProtocol 选项一起指定；请使用其中之一。默认值： tls.DEFAULT_MAX_VERSION。
  • minVersion <string> 可选地设置允许的最低 TLS 版本。可以是 'TLSv1.3'、'TLSv1.2'、'TLSv1.1' 或 'TLSv1' 之一。不能与 secureProtocol 选项一起指定；请使用其中之一。避免设置为低于 TLSv1.2，但为了互操作性可能需要这样做。TLSv1.2 之前的版本可能需要降低 OpenSSL 安全级别。默认值： tls.DEFAULT_MIN_VERSION。
  • passphrase <string> 用于单个私钥和/或 PFX 的共享密码短语。
  • pfx <string> | <string[]> | <Buffer> | <Buffer[]> | <Object[]> PFX 或 PKCS12 编码的私钥和证书链。pfx 是单独提供 key 和 cert 的替代方案。PFX 通常是加密的，如果是，将使用 passphrase 来解密它。可以提供多个 PFX，可以是一个未加密的 PFX 缓冲区的数组，或者是一个形式为 {buf: <string|buffer>[, passphrase: <string>]} 的对象数组。对象形式只能出现在数组中。object.passphrase 是可选的。加密的 PFX 如果提供了 object.passphrase，将用它解密，否则用 options.passphrase 解密。
  • secureOptions <number> 可选地影响 OpenSSL 协议行为，这通常不是必需的。如果使用，应该非常小心！值是来自 OpenSSL 选项 的 SSL_OP_* 选项的数字位掩码。
  • secureProtocol <string> 用于选择要使用的 TLS 协议版本的传统机制，它不支持独立控制最小和最大版本，也不支持将协议限制为 TLSv1.3。请改用 minVersion 和 maxVersion。可能的值列在 SSL_METHODS 中，请使用函数名作为字符串。例如，使用 'TLSv1_1_method' 强制使用 TLS 版本 1.1，或使用 'TLS_method' 允许任何最高到 TLSv1.3 的 TLS 协议版本。不建议使用低于 1.2 的 TLS 版本，但为了互操作性可能需要这样做。默认值： 无，参见 minVersion。
  • sessionIdContext <string> 服务器使用的不透明标识符，以确保会话状态不在应用程序之间共享。客户端不使用。
  • ticketKeys <Buffer> 48 字节的加密强度伪随机数据。更多信息请参阅会话恢复。
  • sessionTimeout <number> 服务器创建的 TLS 会话在此秒数后将不再可恢复。更多信息请参阅会话恢复。默认值： 300。

tls.createServer() 将 honorCipherOrder 选项的默认值设置为 true，其他创建安全上下文的 API 则不设置它。

tls.createServer() 使用从 process.argv 生成的 128 位截断 SHA1 哈希值作为 sessionIdContext 选项的默认值，其他创建安全上下文的 API 没有默认值。

tls.createSecureContext() 方法创建一个 SecureContext 对象。它可以作为多个 tls API（例如 server.addContext()）的参数使用，但没有公共方法。tls.Server 构造函数和 tls.createServer() 方法不支持 secureContext 选项。

对于使用证书的密码，密钥是*必需的*。可以使用 key 或 pfx 来提供它。

如果没有给出 ca 选项，那么 Node.js 将默认使用Mozilla 的公共信任 CA 列表。

不鼓励使用自定义 DHE 参数，而推荐使用新的 dhparam: 'auto' 选项。当设置为 'auto' 时，将自动选择具有足够强度的知名 DHE 参数。否则，如有必要，可以使用 openssl dhparam 创建自定义参数。密钥长度必须大于或等于 1024 位，否则将抛出错误。虽然 1024 位是允许的，但为了更强的安全性，请使用 2048 位或更大。

tls.createServer([options][, secureConnectionListener])#

• options <Object>
  • ALPNProtocols <string[]> | <Buffer[]> | <TypedArray[]> | <DataView[]> | <Buffer> | <TypedArray> | <DataView> 包含支持的 ALPN 协议的字符串、Buffer、TypedArray 或 DataView 的数组，或单个 Buffer、TypedArray 或 DataView。Buffer 应采用 [len][name][len][name]... 格式，例如 0x05hello0x05world，其中第一个字节是下一个协议名称的长度。传递数组通常更简单，例如 ['hello', 'world']。（协议应按其优先级排序。）
  • ALPNCallback <Function> 如果设置，当客户端使用 ALPN 扩展打开连接时，将调用此函数。一个参数将传递给回调：一个包含 servername 和 protocols 字段的对象，分别包含来自 SNI 扩展的服务器名称（如果有）和 ALPN 协议名称字符串的数组。回调必须返回 protocols 中列出的字符串之一，该字符串将作为选定的 ALPN 协议返回给客户端，或者返回 undefined，以致命警报拒绝连接。如果返回的字符串与客户端的任何 ALPN 协议都不匹配，将抛出错误。此选项不能与 ALPNProtocols 选项一起使用，同时设置这两个选项将抛出错误。
  • clientCertEngine <string> 可以提供客户端证书的 OpenSSL 引擎的名称。已弃用。
  • enableTrace <boolean> 如果为 true，将在新连接上调用 tls.TLSSocket.enableTrace()。可以在安全连接建立后启用跟踪，但必须使用此选项来跟踪安全连接的建立过程。默认值： false。
  • handshakeTimeout <number> 如果 SSL/TLS 握手在指定的毫秒数内未完成，则中止连接。每当握手超时时，tls.Server 对象上会发出一个 'tlsClientError' 事件。默认值： 120000（120 秒）。
  • rejectUnauthorized <boolean> 如果不为 false，服务器将拒绝任何未经提供的 CA 列表授权的连接。此选项仅在 requestCert 为 true 时有效。默认值： true。
  • requestCert <boolean> 如果为 true，服务器将向连接的客户端请求证书并尝试验证该证书。默认值： false。
  • sessionTimeout <number> 服务器创建的 TLS 会话在此秒数后将不再可恢复。更多信息请参阅会话恢复。默认值： 300。
  • SNICallback(servername, callback) <Function> 如果客户端支持 SNI TLS 扩展，将调用此函数。调用时会传递两个参数：servername 和 callback。callback 是一个错误优先的回调函数，它接受两个可选参数：error 和 ctx。如果提供了 ctx，它是一个 SecureContext 实例。tls.createSecureContext() 可用于获取一个合适的 SecureContext。如果使用一个假值的 ctx 参数调用 callback，将使用服务器的默认安全上下文。如果未提供 SNICallback，将使用具有高级 API 的默认回调（见下文）。
  • ticketKeys <Buffer> 48 字节的加密强度伪随机数据。更多信息请参阅会话恢复。
  • pskCallback <Function> 用于 TLS-PSK 协商，请参阅预共享密钥。
  • pskIdentityHint <string> 发送给客户端的可选提示，以帮助在 TLS-PSK 协商期间选择身份。在 TLS 1.3 中将被忽略。设置 pskIdentityHint 失败时，将发出带有 'ERR_TLS_PSK_SET_IDENTITY_HINT_FAILED' 代码的 'tlsClientError' 事件。
  • ...: 可以提供任何 tls.createSecureContext() 选项。对于服务器，通常需要身份选项（pfx、key/cert 或 pskCallback）。
  • ...: 可以提供任何 net.createServer() 选项。
• secureConnectionListener <Function>
• 返回: <tls.Server>

创建一个新的 tls.Server。如果提供了 secureConnectionListener，它会自动被设置为 'secureConnection' 事件的监听器。

ticketKeys 选项在 node:cluster 模块的工作进程之间自动共享。

下面演示了一个简单的回显服务器

import { createServer } from 'node:tls';
import { readFileSync } from 'node:fs';

const options = {
  key: readFileSync('server-key.pem'),
  cert: readFileSync('server-cert.pem'),

  // This is necessary only if using client certificate authentication.
  requestCert: true,

  // This is necessary only if the client uses a self-signed certificate.
  ca: [ readFileSync('client-cert.pem') ],
};

const server = createServer(options, (socket) => {
  console.log('server connected',
              socket.authorized ? 'authorized' : 'unauthorized');
  socket.write('welcome!\n');
  socket.setEncoding('utf8');
  socket.pipe(socket);
});
server.listen(8000, () => {
  console.log('server bound');
});const { createServer } = require('node:tls');
const { readFileSync } = require('node:fs');

const options = {
  key: readFileSync('server-key.pem'),
  cert: readFileSync('server-cert.pem'),

  // This is necessary only if using client certificate authentication.
  requestCert: true,

  // This is necessary only if the client uses a self-signed certificate.
  ca: [ readFileSync('client-cert.pem') ],
};

const server = createServer(options, (socket) => {
  console.log('server connected',
              socket.authorized ? 'authorized' : 'unauthorized');
  socket.write('welcome!\n');
  socket.setEncoding('utf8');
  socket.pipe(socket);
});
server.listen(8000, () => {
  console.log('server bound');
});copy

要为此示例生成证书和密钥，请运行：

openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \
  -keyout server-key.pem -out server-cert.pem copy

然后，要为此示例生成 client-cert.pem 证书，请运行

openssl pkcs12 -certpbe AES-256-CBC -export -out client-cert.pem \
  -inkey server-key.pem -in server-cert.pem copy

可以通过使用 tls.connect() 中的示例客户端连接到该服务器来对其进行测试。

tls.setDefaultCACertificates(certs)#

• certs <string[]> | <ArrayBufferView[]> 一个 PEM 格式的 CA 证书数组。

设置 Node.js TLS 客户端使用的默认 CA 证书。如果提供的证书解析成功，它们将成为 tls.getCACertificates() 返回的默认 CA 证书列表，并被后续未指定自己 CA 证书的 TLS 连接使用。在设置为默认值之前，证书将被去重。

此函数仅影响当前的 Node.js 线程。由 HTTPS 代理缓存的先前会话不会受此更改的影响，因此应在进行任何不希望被缓存的 TLS 连接之前调用此方法。

要使用系统 CA 证书作为默认值

const tls = require('node:tls');
tls.setDefaultCACertificates(tls.getCACertificates('system'));import tls from 'node:tls';
tls.setDefaultCACertificates(tls.getCACertificates('system'));copy

此函数完全替换默认的 CA 证书列表。要向现有的默认值中添加其他证书，请获取当前证书并追加到它们后面

const tls = require('node:tls');
const currentCerts = tls.getCACertificates('default');
const additionalCerts = ['-----BEGIN CERTIFICATE-----\n...'];
tls.setDefaultCACertificates([...currentCerts, ...additionalCerts]);import tls from 'node:tls';
const currentCerts = tls.getCACertificates('default');
const additionalCerts = ['-----BEGIN CERTIFICATE-----\n...'];
tls.setDefaultCACertificates([...currentCerts, ...additionalCerts]);copy

tls.getCACertificates([type])#

• type <string> | <undefined> 将返回的 CA 证书的类型。有效值为 "default"、"system"、"bundled" 和 "extra"。默认值： "default"。
• 返回：<string[]> 一个 PEM 编码的证书数组。如果同一个证书在多个来源中重复存储，数组可能包含重复项。

根据 type 返回一个包含来自不同来源的 CA 证书的数组

• "default"：返回 Node.js TLS 客户端默认使用的 CA 证书。
  • 当启用 --use-bundled-ca（默认）时，或者未启用 --use-openssl-ca 时，这将包括来自捆绑的 Mozilla CA 存储的 CA 证书。
  • 当启用 --use-system-ca 时，这也将包括来自系统信任存储的证书。
  • 当使用 NODE_EXTRA_CA_CERTS 时，这也将包括从指定文件加载的证书。
• "system"：根据 --use-system-ca 设置的规则，返回从系统信任存储加载的 CA 证书。当未启用 --use-system-ca 时，可以使用此选项获取系统证书。
• "bundled"：返回捆绑的 Mozilla CA 存储中的 CA 证书。这将与 tls.rootCertificates 相同。
• "extra"：返回从 NODE_EXTRA_CA_CERTS 加载的 CA 证书。如果未设置 NODE_EXTRA_CA_CERTS，则为空数组。

tls.getCiphers()#

• 返回：<string[]>

返回一个包含支持的 TLS 密码名称的数组。由于历史原因，名称为小写，但必须大写才能在 tls.createSecureContext() 的 ciphers 选项中使用。

并非所有支持的密码都默认启用。请参阅修改默认的 TLS 密码套件。

以 'tls_' 开头的密码名称用于 TLSv1.3，所有其他的都用于 TLSv1.2 及以下版本。

console.log(tls.getCiphers()); // ['aes128-gcm-sha256', 'aes128-sha', ...] copy

tls.rootCertificates#

• 类型：<string[]>

一个不可变的字符串数组，代表当前 Node.js 版本提供的捆绑 Mozilla CA 存储中的根证书（PEM 格式）。

由 Node.js 提供的捆绑 CA 存储是 Mozilla CA 存储在发布时的快照。它在所有支持的平台上都是相同的。

要获取当前 Node.js 实例使用的实际 CA 证书，其中可能包括从系统存储加载的证书（如果使用 --use-system-ca）或从 NODE_EXTRA_CA_CERTS 指定的文件加载的证书，请使用 tls.getCACertificates()。

tls.DEFAULT_ECDH_CURVE#

在 tls 服务器中用于 ECDH 密钥协商的默认曲线名称。默认值为 'auto'。更多信息请参阅 tls.createSecureContext()。

tls.DEFAULT_MAX_VERSION#

• 类型：<string> tls.createSecureContext() 的 maxVersion 选项的默认值。可以赋值为任何支持的 TLS 协议版本：'TLSv1.3'、'TLSv1.2'、'TLSv1.1' 或 'TLSv1'。默认值： 'TLSv1.3'，除非使用 CLI 选项更改。使用 --tls-max-v1.2 将默认值设置为 'TLSv1.2'。使用 --tls-max-v1.3 将默认值设置为 'TLSv1.3'。如果提供了多个选项，则使用最高的最大值。

tls.DEFAULT_MIN_VERSION#

• 类型：<string> tls.createSecureContext() 的 minVersion 选项的默认值。可以赋值为任何支持的 TLS 协议版本：'TLSv1.3'、'TLSv1.2'、'TLSv1.1' 或 'TLSv1'。TLSv1.2 之前的版本可能需要降低 OpenSSL 安全级别。默认值： 'TLSv1.2'，除非使用 CLI 选项更改。使用 --tls-min-v1.0 将默认值设置为 'TLSv1'。使用 --tls-min-v1.1 将默认值设置为 'TLSv1.1'。使用 --tls-min-v1.3 将默认值设置为 'TLSv1.3'。如果提供了多个选项，则使用最低的最小值。

tls.DEFAULT_CIPHERS#

• 类型：<string> tls.createSecureContext() 的 ciphers 选项的默认值。可以赋值为任何支持的 OpenSSL 密码。默认为 crypto.constants.defaultCoreCipherList 的内容，除非使用 CLI 选项 --tls-default-ciphers 更改。