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

版本历史

版本	变更
v22.4.0, v20.16.0	The `clientCertEngine` option depends on custom engine support in OpenSSL which is deprecated in OpenSSL 3.
v19.0.0	If `ALPNProtocols` is set, incoming connections that send an ALPN extension with no supported protocols are terminated with a fatal `no_application_protocol` alert.
v20.4.0, v18.19.0	The `options` parameter can now include `ALPNCallback`.
v12.3.0	The `options` parameter now supports `net.createServer()` options.
v9.3.0	The `options` parameter can now include `clientCertEngine`.
v8.0.0	The `ALPNProtocols` option can be a `TypedArray` or `DataView` now.
v5.0.0	ALPN options are supported now.
v0.3.2	新增于: v0.3.2

options <Object>
- ALPNProtocols <string[]> | <Buffer[]> | <TypedArray[]> | <DataView[]> | <Buffer> | <TypedArray> | <DataView> 一个字符串、Buffer、TypedArray 或 DataView 的数组，或一个包含支持的 ALPN 协议的单个 Buffer、TypedArray 或 DataView。Buffer 的格式应为 [长度][name][长度][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。如果 callback 被调用时 ctx 参数为假值，则使用服务器的默认安全上下文。如果未提供 SNICallback，则将使用具有高级 API 的默认回调（见下文）。
- ticketKeys <Buffer> 48字节的加密强伪随机数据。有关更多信息，请参见会话恢复。
- pskCallback <Function> 有关 TLS-PSK 协商，请参阅预共享密钥。
- pskIdentityHint <string> 可选提示，用于在 TLS-PSK 协商期间帮助客户端选择身份。在 TLS 1.3 中将被忽略。如果设置 pskIdentityHint 失败，将触发 'tlsClientError'，并伴随 'ERR_TLS_PSK_SET_IDENTITY_HINT_FAILED' 代码。
- ...: 可以提供任意 tls.createSecureContext() 选项。对于服务器，通常需要身份选项（pfx、key/cert 或 pskCallback）。
- ...：可以提供任何net.createServer()选项。
secureConnectionListener <Function>
返回值：<tls.Server>

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

🌐 Creates a new tls.Server. The secureConnectionListener, if provided, is automatically set as a listener for the 'secureConnection' event.

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

🌐 The ticketKeys options is automatically shared between node:cluster module workers.

以下说明了一个简单的回显服务器：

🌐 The following illustrates a simple echo server:

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

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

🌐 To generate the certificate and key for this example, run:

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

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

🌐 Then, to generate the client-cert.pem certificate for this example, run:

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

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

🌐 The server can be tested by connecting to it using the example client from tls.connect().