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>

    • 提示：<string> 可选消息，由服务器发送以帮助客户端在协商期间决定使用哪种身份。如果使用 TLS 1.3，则始终为 null。
    • 返回：<Object> 以 { psk: <Buffer|TypedArray|DataView>, identity: <string> } 或 null 的形式停止协商过程。psk 必须与所选加密算法的摘要兼容。identity 必须使用 UTF-8 编码。

    在协商 TLS-PSK（预共享密钥）时，将调用此函数，并由服务器提供可选身份 hint，或者在 TLS 1.3 的情况下提供 null，因为 hint 已被移除。需要为连接提供自定义 tls.checkServerIdentity()，因为默认设置会尝试将服务器的主机名/IP 与证书进行核对，但对于 PSK 并不适用，因为不会有证书存在。更多信息可以在 RFC 4279 中找到。

  • ALPNProtocols：<string[]> | <Buffer[]> | <TypedArray[]> | <DataView[]> | <Buffer> | <TypedArray> | <DataView> 一组字符串，可以是 Buffer、TypedArray 或 DataView，或者单个 Buffer、TypedArray 或 DataView，包含支持的 ALPN 协议。Buffer 应该采用 [len][name][len][name]... 格式，例如 '\x08http/1.1\x08http/1.0'，其中 len 字节表示下一个协议名称的长度。通常传递数组会更简单，例如 ['http/1.1', 'http/1.0']。列表中较前的协议优先级高于后面的协议。

  • servername：<string> SNI（服务器名称指示）TLS 扩展的服务器名称。它是正在连接的主机的名称，必须是主机名，而不是 IP 地址。多宿主服务器可以使用它来选择向客户端呈现的正确证书，请参阅 SNICallback 选项到 tls.createServer()。

  • 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' 事件的监听器。

🌐 The callback function, if specified, will be added as a listener for the 'secureConnect' event.

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

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

🌐 Unlike the https API, tls.connect() does not enable the SNI (Server Name Indication) extension by default, which may cause some servers to return an incorrect certificate or reject the connection altogether. To enable SNI, set the servername option in addition to host.

以下展示了来自 tls.createServer() 的回声服务器示例客户端：

🌐 The following illustrates a client for the echo server example from tls.createServer():

// Assumes an echo server that is listening on port 8000.
const tls = require('node:tls');
const fs = require('node:fs');

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

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

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

const socket = tls.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');
}); 拷贝