Node.js v24.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 选项。

默认密码套件优先使用 GCM 密码，以满足 Chrome 的“现代密码学”设置，并且还优先使用 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，每个级别都施加了更严格的安全要求。默认安全级别为 1，通常适用于大多数现代应用程序。但是，某些遗留特性和协议（例如 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)）时，才会调用此函数。

如果存在匹配的 uniformResourceIdentifier 主题备用名称，则早期版本的 Node.js 会错误地接受给定 hostname 的证书（请参阅 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> 字符串、Buffer、TypedArray 或 DataView 数组，或者包含受支持的 ALPN 协议的单个 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() 中 echo 服务器示例的客户端

// 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 选项提供对端证书可以匹配或链接到的 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 手册页。
  • 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-based 完全正向保密仍然可用。
  • ecdhCurve <string> 一个字符串，描述用于 ECDH 密钥协商的命名曲线或以冒号分隔的曲线 NID 或名称列表，例如 P-521:P-384:P-256。设置为 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> 字符串、Buffer、TypedArray 或 DataView 的数组，或包含支持的 ALPN 协议的单个 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.getCACertificates([type])#

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

返回一个包含来自各种来源的 CA 证书的数组，具体取决于 type

• "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[]>

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

由 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 更改。