Node.js tls.connect(options[, callback])用法及代码示例

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(预共享 key )时，使用服务器提供的可选标识hint 或null(在删除hint 的 TLS 1.3 的情况下)调用此函数。有必要为连接提供自定义tls.checkServerIdentity()，因为默认连接会尝试根据证书检查服务器的主机名/IP，但这不适用于 PSK，因为不会存在证书。更多信息可以在RFC 4279 中找到。

  • ALPNProtocols : <string[]> | <Buffer[]> | <TypedArray[]> | <DataView[]> | <Buffer> | <TypedArray> | <DataView> 包含支持的 ALPN 协议的字符串数组，Buffer 或 TypedArray 或 DataView 或单个 Buffer 或 TypedArray 或 DataView。 Buffer s 应该具有格式 [len][name][len][name]... 例如'\x08http/1.1\x08http/1.0' ，其中 len 字节是下一个协议名称的长度。传递数组通常要简单得多，例如['http/1.1', 'http/1.0'] 。列表中较早的协议比后面的协议具有更高的偏好。

  • servername : <string> SNI(服务器名称指示)TLS 扩展的服务器名称。它是要连接的主机的名称，并且必须是主机名，而不是 IP 地址。 multi-homed 服务器可以使用它来选择要呈现给客户端的正确证书，请参阅 tls.createServer() 的 SNICallback 选项。

  • checkServerIdentity(servername, cert) <Function> 根据证书检查服务器的主机名(或显式设置时提供的 servername)时要使用的回调函数(而不是内置的 tls.checkServerIdentity() 函数)。如果验证失败，这应该返回 <Error> 。如果验证了servername 和cert，则该方法应返回undefined。

  • session <Buffer> Buffer 实例，包含 TLS 会话。

  • minDHSize <number> DH 参数的最小大小(以位为单位)以接受 TLS 连接。当服务器提供大小小于 minDHSize 的 DH 参数时，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.
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');
});