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