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 的数组，或单个 Buffer、TypedArray 或 DataView，包含支持的 ALPN 协议。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”上会发出“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().】