Node.js v25.0.0 文件

確定加密支援是否不可用#

Node.js 可以在構建時不支援 node:crypto 模組。在這種情況下，嘗試從 tls import 或呼叫 require('node:tls') 將會導致丟擲錯誤。

使用 CommonJS 時，丟擲的錯誤可以使用 try/catch 捕獲。

let tls;
try {
  tls = require('node:tls');
} catch (err) {
  console.error('tls support is disabled!');
} copy

當使用詞法 ESM import 關鍵字時，只有在嘗試載入模組*之前*註冊了 process.on('uncaughtException') 的處理程式（例如，使用預載入模組），才能捕獲該錯誤。

使用 ESM 時，如果程式碼有可能在未啟用加密支援的 Node.js 版本上執行，請考慮使用 import() 函式，而不是詞法 import 關鍵字。

let tls;
try {
  tls = await import('node:tls');
} catch (err) {
  console.error('tls support is disabled!');
} copy

TLS/SSL 概念#

TLS/SSL 是一組協議，依賴於公鑰基礎設施 (PKI) 來實現客戶端和伺服器之間的安全通訊。對於大多數常見情況，每個伺服器都必須有一個私鑰。

私鑰可以透過多種方式生成。以下示例演示瞭如何使用 OpenSSL 命令列介面生成一個 2048 位的 RSA 私鑰：

openssl genrsa -out ryans-key.pem 2048 copy

使用 TLS/SSL 時，所有伺服器（以及某些客戶端）都必須有一個證書。證書是與私鑰對應的公鑰，並由證書頒發機構或私鑰所有者進行數字簽名（此類證書稱為“自簽名”證書）。獲取證書的第一步是建立一個證書籤名請求 (CSR) 檔案。

OpenSSL 命令列介面可用於為私鑰生成 CSR：

openssl req -new -sha256 -key ryans-key.pem -out ryans-csr.pem copy

CSR 檔案生成後，可以將其傳送給證書頒發機構進行簽名，或用於生成自簽名證書。

以下示例演示瞭如何使用 OpenSSL 命令列介面建立自簽名證書：

openssl x509 -req -in ryans-csr.pem -signkey ryans-key.pem -out ryans-cert.pem copy

證書生成後，可用於生成 .pfx 或 .p12 檔案：

openssl pkcs12 -export -in ryans-cert.pem -inkey ryans-key.pem \
      -certfile ca-cert.pem -out ryans.pfx copy

其中：

• in：是已簽名的證書
• inkey：是關聯的私鑰
• certfile：是所有證書頒發機構 (CA) 證書拼接成的一個檔案，例如 cat ca1-cert.pem ca2-cert.pem > ca-cert.pem

openssl s_client -connect localhost:443 -reconnect copy

New, TLSv1.2, Cipher is ECDHE-RSA-AES128-GCM-SHA256 copy

Reused, TLSv1.2, Cipher is ECDHE-RSA-AES128-GCM-SHA256 copy

修改預設的 TLS 密碼套件#

Node.js 內建了預設的已啟用和已停用的 TLS 密碼套件。這個預設密碼列表可以在構建 Node.js 時進行配置，以允許發行版提供自己的預設列表。

以下命令可用於顯示預設的密碼套件：

node -p crypto.constants.defaultCoreCipherList | tr ':' '\n'
TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256
TLS_AES_128_GCM_SHA256
ECDHE-RSA-AES128-GCM-SHA256
ECDHE-ECDSA-AES128-GCM-SHA256
ECDHE-RSA-AES256-GCM-SHA384
ECDHE-ECDSA-AES256-GCM-SHA384
DHE-RSA-AES128-GCM-SHA256
ECDHE-RSA-AES128-SHA256
DHE-RSA-AES128-SHA256
ECDHE-RSA-AES256-SHA384
DHE-RSA-AES256-SHA384
ECDHE-RSA-AES256-SHA256
DHE-RSA-AES256-SHA256
HIGH
!aNULL
!eNULL
!EXPORT
!DES
!RC4
!MD5
!PSK
!SRP
!CAMELLIA copy

可以使用 --tls-cipher-list 命令列開關（直接使用，或透過 NODE_OPTIONS 環境變數）完全替換此預設值。例如，以下命令使 ECDHE-RSA-AES128-GCM-SHA256:!RC4 成為預設的 TLS 密碼套件：

node --tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4' server.js

export NODE_OPTIONS=--tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4'
node server.js copy

要進行驗證，請使用以下命令顯示設定的密碼列表，注意 defaultCoreCipherList 和 defaultCipherList 之間的區別：

node --tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4' -p crypto.constants.defaultCipherList | tr ':' '\n'
ECDHE-RSA-AES128-GCM-SHA256
!RC4 copy

即，defaultCoreCipherList 列表在編譯時設定，而 defaultCipherList 在執行時設定。

要從執行時內部修改預設密碼套件，請修改 tls.DEFAULT_CIPHERS 變數，這必須在監聽任何套接字之前執行，它不會影響已經開啟的套接字。例如：

// Remove Obsolete CBC Ciphers and RSA Key Exchange based Ciphers as they don't provide Forward Secrecy
tls.DEFAULT_CIPHERS +=
  ':!ECDHE-RSA-AES128-SHA:!ECDHE-RSA-AES128-SHA256:!ECDHE-RSA-AES256-SHA:!ECDHE-RSA-AES256-SHA384' +
  ':!ECDHE-ECDSA-AES128-SHA:!ECDHE-ECDSA-AES128-SHA256:!ECDHE-ECDSA-AES256-SHA:!ECDHE-ECDSA-AES256-SHA384' +
  ':!kRSA'; copy

預設值也可以在每個客戶端或伺服器的基礎上使用 tls.createSecureContext() 的 ciphers 選項來替換，該選項也存在於 tls.createServer()、tls.connect() 以及建立新的 tls.TLSSocket 時。

密碼列表可以包含 TLSv1.3 密碼套件名稱（以 'TLS_' 開頭）和 TLSv1.2 及以下密碼套件規範的混合。TLSv1.2 密碼支援傳統的規範格式，詳情請參閱 OpenSSL 密碼列表格式 文件，但這些規範不適用於 TLSv1.3 密碼。TLSv1.3 套件只能透過在密碼列表中包含其全名來啟用。例如，不能使用傳統的 TLSv1.2 'EECDH' 或 '!EECDH' 規範來啟用或停用它們。

儘管 TLSv1.3 和 TLSv1.2 密碼套件的相對順序如何，TLSv1.3 協議比 TLSv1.2 安全得多，並且如果握手錶明支援它，並且有任何 TLSv1.3 密碼套件被啟用，則總是會優先選擇 TLSv1.3 而非 TLSv1.2。

Node.js 中包含的預設密碼套件經過精心挑選，以反映當前的安全最佳實踐和風險緩解。更改預設密碼套件可能會對應用程式的安全性產生重大影響。只有在絕對必要時才應使用 --tls-cipher-list 開關和 ciphers 選項。

預設密碼套件為 Chrome 的“現代加密”設定首選 GCM 密碼，併為完全正向保密首選 ECDHE 和 DHE 密碼，同時提供一些向後相容性。

依賴於不安全且已棄用的 RC4 或基於 DES 的密碼的舊客戶端（如 Internet Explorer 6）無法使用預設配置完成握手過程。如果必須支援這些客戶端，TLS 建議可能會提供一個相容的密碼套件。有關格式的更多詳細資訊，請參閱 OpenSSL 密碼列表格式 文件。

只有五個 TLSv1.3 密碼套件：

• 'TLS_AES_256_GCM_SHA384'
• 'TLS_CHACHA20_POLY1305_SHA256'
• 'TLS_AES_128_GCM_SHA256'
• 'TLS_AES_128_CCM_SHA256'
• 'TLS_AES_128_CCM_8_SHA256'

前三個預設啟用。兩個基於 CCM 的套件受 TLSv1.3 支援，因為它們在受限系統上可能效能更高，但預設情況下未啟用，因為它們提供的安全性較低。

OpenSSL 安全級別#

OpenSSL 庫強制執行安全級別，以控制加密操作的最低可接受安全級別。OpenSSL 的安全級別從 0 到 5，每個級別都強制執行更嚴格的安全要求。預設安全級別為 2，通常適用於大多數現代應用程式。然而，一些舊版功能和協議，如 TLSv1，需要較低的安全級別（SECLEVEL=0）才能正常工作。有關更詳細的資訊，請參閱 OpenSSL 關於安全級別的文件。

import { createServer, connect } from 'node:tls';
const port = 443;

createServer({ ciphers: 'DEFAULT@SECLEVEL=0', minVersion: 'TLSv1' }, function(socket) {
  console.log('Client connected with protocol:', socket.getProtocol());
  socket.end();
  this.close();
})
.listen(port, () => {
  connect(port, { ciphers: 'DEFAULT@SECLEVEL=0', maxVersion: 'TLSv1' });
});const { createServer, connect } = require('node:tls');
const port = 443;

createServer({ ciphers: 'DEFAULT@SECLEVEL=0', minVersion: 'TLSv1' }, function(socket) {
  console.log('Client connected with protocol:', socket.getProtocol());
  socket.end();
  this.close();
})
.listen(port, () => {
  connect(port, { ciphers: 'DEFAULT@SECLEVEL=0', maxVersion: 'TLSv1' });
});copy

X509 證書錯誤程式碼#

多個函式可能會因為 OpenSSL 報告的證書錯誤而失敗。在這種情況下，該函式透過其回撥提供一個 <Error>，該錯誤具有一個 code 屬性，該屬性可以取以下值之一：

• 'UNABLE_TO_GET_ISSUER_CERT'：無法獲取頒發者證書。
• 'UNABLE_TO_GET_CRL'：無法獲取證書 CRL。
• 'UNABLE_TO_DECRYPT_CERT_SIGNATURE'：無法解密證書籤名。
• 'UNABLE_TO_DECRYPT_CRL_SIGNATURE'：無法解密 CRL 的簽名。
• 'UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY'：無法解碼頒發者公鑰。
• 'CERT_SIGNATURE_FAILURE'：證書籤名失敗。
• 'CRL_SIGNATURE_FAILURE'：CRL 簽名失敗。
• 'CERT_NOT_YET_VALID'：證書尚未生效。
• 'CERT_HAS_EXPIRED'：證書已過期。
• 'CRL_NOT_YET_VALID'：CRL 尚未生效。
• 'CRL_HAS_EXPIRED'：CRL 已過期。
• 'ERROR_IN_CERT_NOT_BEFORE_FIELD'：證書的 notBefore 欄位格式錯誤。
• 'ERROR_IN_CERT_NOT_AFTER_FIELD'：證書的 notAfter 欄位格式錯誤。
• 'ERROR_IN_CRL_LAST_UPDATE_FIELD'：CRL 的 lastUpdate 欄位格式錯誤。
• 'ERROR_IN_CRL_NEXT_UPDATE_FIELD'：CRL 的 nextUpdate 欄位格式錯誤。
• 'OUT_OF_MEM'：記憶體不足。
• 'DEPTH_ZERO_SELF_SIGNED_CERT'：自簽名證書。
• 'SELF_SIGNED_CERT_IN_CHAIN'：證書鏈中的自簽名證書。
• 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY'：無法在本地獲取頒發者證書。
• 'UNABLE_TO_VERIFY_LEAF_SIGNATURE'：無法驗證第一個證書。
• 'CERT_CHAIN_TOO_LONG'：證書鏈太長。
• 'CERT_REVOKED'：證書已吊銷。
• 'INVALID_CA'：無效的 CA 證書。
• 'PATH_LENGTH_EXCEEDED'：路徑長度約束超出。
• 'INVALID_PURPOSE'：不支援的證書用途。
• 'CERT_UNTRUSTED'：證書不受信任。
• 'CERT_REJECTED'：證書被拒絕。
• 'HOSTNAME_MISMATCH'：主機名不匹配。

當發生像 UNABLE_TO_VERIFY_LEAF_SIGNATURE、DEPTH_ZERO_SELF_SIGNED_CERT 或 UNABLE_TO_GET_ISSUER_CERT 這樣的證書錯誤時，Node.js 會附加一個提示，建議如果根 CA 已在本地安裝，則嘗試使用 --use-system-ca 標誌執行，以引導開發者走向安全的解決方案，防止不安全的變通方法。

類：tls.Server#

• 繼承自：<net.Server>

接受使用 TLS 或 SSL 的加密連線。

const logFile = fs.createWriteStream('/tmp/ssl-keys.log', { flags: 'a' });
// ...
server.on('keylog', (line, tlsSocket) => {
  if (tlsSocket.remoteAddress !== '...')
    return; // Only log keys for a particular IP
  logFile.write(line);
}); copy

const tlsSessionStore = {};
server.on('newSession', (id, data, cb) => {
  tlsSessionStore[id.toString('hex')] = data;
  cb();
});
server.on('resumeSession', (id, cb) => {
  cb(null, tlsSessionStore[id.toString('hex')] || null);
}); copy

類：tls.TLSSocket#

• 繼承自: <net.Socket>

對寫入的資料進行透明加密並執行所有必需的 TLS 協商。

tls.TLSSocket 的例項實現了雙工 Stream 介面。

返回 TLS 連線元資料的方法（例如 tls.TLSSocket.getPeerCertificate()）只會在連線開啟時返回資料。

const logFile = fs.createWriteStream('/tmp/ssl-keys.log', { flags: 'a' });
// ...
tlsSocket.on('keylog', (line) => logFile.write(line)); copy

tlsSocket.once('session', (session) => {
  // The session can be used immediately or later.
  tls.connect({
    session: session,
    // Other connect options...
  });
}); copy

const keyingMaterial = tlsSocket.exportKeyingMaterial(
  128,
  'client finished');

/*
 Example return value of keyingMaterial:
 <Buffer 76 26 af 99 c5 56 8e 42 09 91 ef 9f 93 cb ad 6c 7b 65 f8 53 f1 d8 d9
    12 5a 33 b8 b5 25 df 7b 37 9f e0 e2 4f b8 67 83 a3 2f cd 5d 41 42 4c 91
    74 ef 2c ... 78 more bytes>
*/ copy

{
    "name": "AES256-SHA",
    "standardName": "TLS_RSA_WITH_AES_256_CBC_SHA",
    "version": "SSLv3"
} copy

{ subject:
   { OU: [ 'Domain Control Validated', 'PositiveSSL Wildcard' ],
     CN: '*.nodejs.org' },
  issuer:
   { C: 'GB',
     ST: 'Greater Manchester',
     L: 'Salford',
     O: 'COMODO CA Limited',
     CN: 'COMODO RSA Domain Validation Secure Server CA' },
  subjectaltname: 'DNS:*.nodejs.org, DNS:nodejs.org',
  infoAccess:
   { 'CA Issuers - URI':
      [ 'http://crt.comodoca.com/COMODORSADomainValidationSecureServerCA.crt' ],
     'OCSP - URI': [ 'http://ocsp.comodoca.com' ] },
  modulus: 'B56CE45CB740B09A13F64AC543B712FF9EE8E4C284B542A1708A27E82A8D151CA178153E12E6DDA15BF70FFD96CB8A88618641BDFCCA03527E665B70D779C8A349A6F88FD4EF6557180BD4C98192872BCFE3AF56E863C09DDD8BC1EC58DF9D94F914F0369102B2870BECFA1348A0838C9C49BD1C20124B442477572347047506B1FCD658A80D0C44BCC16BC5C5496CFE6E4A8428EF654CD3D8972BF6E5BFAD59C93006830B5EB1056BBB38B53D1464FA6E02BFDF2FF66CD949486F0775EC43034EC2602AEFBF1703AD221DAA2A88353C3B6A688EFE8387811F645CEED7B3FE46E1F8B9F59FAD028F349B9BC14211D5830994D055EEA3D547911E07A0ADDEB8A82B9188E58720D95CD478EEC9AF1F17BE8141BE80906F1A339445A7EB5B285F68039B0F294598A7D1C0005FC22B5271B0752F58CCDEF8C8FD856FB7AE21C80B8A2CE983AE94046E53EDE4CB89F42502D31B5360771C01C80155918637490550E3F555E2EE75CC8C636DDE3633CFEDD62E91BF0F7688273694EEEBA20C2FC9F14A2A435517BC1D7373922463409AB603295CEB0BB53787A334C9CA3CA8B30005C5A62FC0715083462E00719A8FA3ED0A9828C3871360A73F8B04A4FC1E71302844E9BB9940B77E745C9D91F226D71AFCAD4B113AAF68D92B24DDB4A2136B55A1CD1ADF39605B63CB639038ED0F4C987689866743A68769CC55847E4A06D6E2E3F1',
  exponent: '0x10001',
  pubkey: <Buffer ... >,
  valid_from: 'Aug 14 00:00:00 2017 GMT',
  valid_to: 'Nov 20 23:59:59 2019 GMT',
  fingerprint: '01:02:59:D9:C3:D2:0D:08:F7:82:4E:44:A4:B4:53:C5:E2:3A:87:4D',
  fingerprint256: '69:AE:1A:6A:D4:3D:C6:C1:1B:EA:C6:23:DE:BA:2A:14:62:62:93:5C:7A:EA:06:41:9B:0B:BC:87:CE:48:4E:02',
  fingerprint512: '19:2B:3E:C3:B3:5B:32:E8:AE:BB:78:97:27:E4:BA:6C:39:C9:92:79:4F:31:46:39:E2:70:E5:5F:89:42:17:C9:E8:64:CA:FF:BB:72:56:73:6E:28:8A:92:7E:A3:2A:15:8B:C2:E0:45:CA:C3:BC:EA:40:52:EC:CA:A2:68:CB:32',
  ext_key_usage: [ '1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2' ],
  serialNumber: '66593D57F20CBC573E433381B5FEC280',
  raw: <Buffer ... > } copy

tls.checkServerIdentity(hostname, cert)#

• hostname <string> 用於驗證證書的主機名或 IP 地址。
• cert <Object> 代表對等方證書的證書物件。
• 返回：<Error> | <undefined>

驗證證書 cert 是否頒發給了 hostname。

失敗時返回一個 <Error> 物件，並在其中填充 reason、host 和 cert。成功時返回 <undefined>。

此函式旨在與可以傳遞給 tls.connect() 的 checkServerIdentity 選項結合使用，因此它操作的是一個證書物件。對於其他目的，請考慮使用 x509.checkHost()。

可以透過提供一個替代函式作為傳遞給 tls.connect() 的 options.checkServerIdentity 選項來覆蓋此函式。當然，覆蓋函式可以呼叫 tls.checkServerIdentity()，以透過額外的驗證來增強已有的檢查。

只有當證書透過所有其他檢查時，例如由受信任的 CA 頒發（options.ca），才會呼叫此函式。

早期版本的 Node.js 錯誤地接受了給定 hostname 的證書，只要存在匹配的 uniformResourceIdentifier 主體備用名稱（參見 CVE-2021-44531）。希望接受 uniformResourceIdentifier 主體備用名稱的應用程式可以使用一個實現了所需行為的自定義 options.checkServerIdentity 函式。

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> 用於 TLS-PSK 協商，請參閱預共享金鑰。
  • ALPNProtocols <string[]> | <Buffer[]> | <TypedArray[]> | <DataView[]> | <Buffer> | <TypedArray> | <DataView> 包含支援的 ALPN 協議的字串、Buffer、TypedArray 或 DataView 的陣列，或單個 Buffer、TypedArray 或 DataView。Buffer 應採用 [len][name][len][name]... 的格式，例如 '\x08http/1.1\x08http/1.0'，其中 len 位元組是下一個協議名稱的長度。傳遞陣列通常更簡單，例如 ['http/1.1', 'http/1.0']。列表中較早的協議比後面的協議有更高的優先順序。
  • servername <string> 用於 SNI (伺服器名稱指示) TLS 擴充套件的伺服器名稱。它是要連線的主機的名稱，必須是主機名，而不是 IP 地址。多宿主伺服器可以使用它來選擇正確的證書呈現給客戶端，請參閱 tls.createServer() 的 SNICallback 選項。
  • 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' 事件的監聽器。

tls.connect() 返回一個 tls.TLSSocket 物件。

與 https API 不同，tls.connect() 預設不啟用 SNI (伺服器名稱指示) 擴充套件，這可能導致一些伺服器返回不正確的證書或完全拒絕連線。要啟用 SNI，除了 host 之外，還要設定 servername 選項。

下面演示了 tls.createServer() 回顯伺服器示例的客戶端

// Assumes an echo server that is listening on port 8000.
import { connect } from 'node:tls';
import { readFileSync } from 'node:fs';
import { stdin } from 'node:process';

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

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

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

const socket = connect(8000, options, () => {
  console.log('client connected',
              socket.authorized ? 'authorized' : 'unauthorized');
  stdin.pipe(socket);
  stdin.resume();
});
socket.setEncoding('utf8');
socket.on('data', (data) => {
  console.log(data);
});
socket.on('end', () => {
  console.log('server ends connection');
});// Assumes an echo server that is listening on port 8000.
const { connect } = require('node:tls');
const { readFileSync } = require('node:fs');

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

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

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

const socket = 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');
});copy

要為此示例生成證書和金鑰，請執行：

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

然後，要為此示例生成 server-cert.pem 證書，請執行

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

tls.connect(path[, options][, callback])#

• path <string> options.path 的預設值。
• options <Object> 參見 tls.connect()。
• callback <Function> 參見 tls.connect()。
• 返回：<tls.TLSSocket>

與 tls.connect() 相同，只是 path 可以作為引數而不是選項提供。

如果指定了路徑選項，它將優先於路徑引數。

tls.connect(port[, host][, options][, callback])#

• port <number> options.port 的預設值。
• host <string> options.host 的預設值。
• options <Object> 參見 tls.connect()。
• callback <Function> 參見 tls.connect()。
• 返回：<tls.TLSSocket>

與 tls.connect() 相同，只是 port 和 host 可以作為引數而不是選項提供。

如果指定了埠或主機選項，它將優先於任何埠或主機引數。

tls.createSecureContext([options])#

• options <Object>
  • allowPartialTrustChain <boolean> 將信任 CA 證書列表中的中間（非自簽名）證書視為受信任。
  • ca <string> | <string[]> | <Buffer> | <Buffer[]> 可選地覆蓋受信任的 CA 證書。如果未指定，預設受信任的 CA 證書與使用 default 型別呼叫 tls.getCACertificates() 返回的證書相同。如果指定了，預設列表將被 ca 選項中的證書完全替換（而不是拼接）。如果使用者希望新增額外的證書而不是完全覆蓋預設值，則需要手動拼接。該值可以是字串或 Buffer，或者是字串和/或 Buffer 的 Array。任何字串或 Buffer 都可以包含多個連線在一起的 PEM CA。對等方的證書必須能連結到伺服器信任的 CA，連線才能被驗證。當使用無法連結到眾所周知的 CA 的證書時，必須明確將證書的 CA 指定為受信任的，否則連線將無法驗證。如果對等方使用的證書與預設 CA 之一不匹配或無法連結，請使用 ca 選項提供一個對等方證書可以匹配或連結到的 CA 證書。對於自簽名證書，證書本身就是其 CA，必須提供。對於 PEM 編碼的證書，支援的型別是 "TRUSTED CERTIFICATE"、"X509 CERTIFICATE" 和 "CERTIFICATE"。
  • cert <string> | <string[]> | <Buffer> | <Buffer[]> PEM 格式的證書鏈。每個私鑰應提供一個證書鏈。每個證書鏈應由為提供的私鑰 key 的 PEM 格式證書、緊隨其後的 PEM 格式的中間證書（如果有）按順序組成，且不包括根 CA（根 CA 必須是對方預先知道的，參見 ca）。當提供多個證書鏈時，它們不必與 key 中的私鑰順序相同。如果未提供中間證書，對方將無法驗證證書，握手將失敗。
  • sigalgs <string> 以冒號分隔的支援的簽名演算法列表。該列表可以包含摘要演算法（SHA256、MD5 等）、公鑰演算法（RSA-PSS、ECDSA 等）、兩者的組合（例如 'RSA+SHA384'）或 TLS v1.3 方案名稱（例如 rsa_pss_pss_sha512）。更多資訊請參閱 OpenSSL man pages。
  • ciphers <string> 密碼套件規範，替換預設值。更多資訊，請參閱修改預設的 TLS 密碼套件。允許的密碼可以透過 tls.getCiphers() 獲取。密碼名稱必須大寫，以便 OpenSSL 接受它們。
  • clientCertEngine <string> 可以提供客戶端證書的 OpenSSL 引擎的名稱。已棄用。
  • crl <string> | <string[]> | <Buffer> | <Buffer[]> PEM 格式的 CRL（證書吊銷列表）。
  • dhparam <string> | <Buffer> 'auto' 或自定義 Diffie-Hellman 引數，對於非 ECDHE 完全前向保密是必需的。如果省略或無效，引數將被靜默丟棄，DHE 密碼將不可用。基於 ECDHE 的完全前向保密仍然可用。
  • ecdhCurve <string> 一個描述命名曲線的字串，或一個以冒號分隔的曲線 NID 或名稱列表，例如 P-521:P-384:P-256，用於 ECDH 金鑰協商。設定為 auto 以自動選擇曲線。使用 crypto.getCurves() 獲取可用曲線名稱的列表。在最近的版本中，openssl ecparam -list_curves 也將顯示每個可用橢圓曲線的名稱和描述。預設值： tls.DEFAULT_ECDH_CURVE。
  • honorCipherOrder <boolean> 嘗試使用伺服器的密碼套件偏好，而不是客戶端的。當為 true 時，會導致在 secureOptions 中設定 SSL_OP_CIPHER_SERVER_PREFERENCE，更多資訊請參閱 OpenSSL 選項。
  • key <string> | <string[]> | <Buffer> | <Buffer[]> | <Object[]> PEM 格式的私鑰。PEM 允許私鑰被加密。加密的金鑰將使用 options.passphrase 解密。可以使用不同演算法的多個金鑰，可以是一個未加密的金鑰字串或緩衝區的陣列，或者是一個形式為 {pem: <string|buffer>[, passphrase: <string>]} 的物件陣列。物件形式只能出現在陣列中。object.passphrase 是可選的。加密的金鑰如果提供了 object.passphrase，將用它解密，否則用 options.passphrase 解密。
  • privateKeyEngine <string> 從中獲取私鑰的 OpenSSL 引擎的名稱。應與 privateKeyIdentifier 一起使用。已棄用。
  • privateKeyIdentifier <string> 由 OpenSSL 引擎管理的私鑰的識別符號。應與 privateKeyEngine 一起使用。不應與 key 一起設定，因為這兩個選項以不同的方式定義私鑰。已棄用。
  • maxVersion <string> 可選地設定允許的最高 TLS 版本。可以是 'TLSv1.3'、'TLSv1.2'、'TLSv1.1' 或 'TLSv1' 之一。不能與 secureProtocol 選項一起指定；請使用其中之一。預設值： tls.DEFAULT_MAX_VERSION。
  • minVersion <string> 可選地設定允許的最低 TLS 版本。可以是 'TLSv1.3'、'TLSv1.2'、'TLSv1.1' 或 'TLSv1' 之一。不能與 secureProtocol 選項一起指定；請使用其中之一。避免設定為低於 TLSv1.2，但為了互操作性可能需要這樣做。TLSv1.2 之前的版本可能需要降低 OpenSSL 安全級別。預設值： tls.DEFAULT_MIN_VERSION。
  • passphrase <string> 用於單個私鑰和/或 PFX 的共享密碼短語。
  • pfx <string> | <string[]> | <Buffer> | <Buffer[]> | <Object[]> PFX 或 PKCS12 編碼的私鑰和證書鏈。pfx 是單獨提供 key 和 cert 的替代方案。PFX 通常是加密的，如果是，將使用 passphrase 來解密它。可以提供多個 PFX，可以是一個未加密的 PFX 緩衝區的陣列，或者是一個形式為 {buf: <string|buffer>[, passphrase: <string>]} 的物件陣列。物件形式只能出現在陣列中。object.passphrase 是可選的。加密的 PFX 如果提供了 object.passphrase，將用它解密，否則用 options.passphrase 解密。
  • secureOptions <number> 可選地影響 OpenSSL 協議行為，這通常不是必需的。如果使用，應該非常小心！值是來自 OpenSSL 選項 的 SSL_OP_* 選項的數字位掩碼。
  • secureProtocol <string> 用於選擇要使用的 TLS 協議版本的傳統機制，它不支援獨立控制最小和最大版本，也不支援將協議限制為 TLSv1.3。請改用 minVersion 和 maxVersion。可能的值列在 SSL_METHODS 中，請使用函式名作為字串。例如，使用 'TLSv1_1_method' 強制使用 TLS 版本 1.1，或使用 'TLS_method' 允許任何最高到 TLSv1.3 的 TLS 協議版本。不建議使用低於 1.2 的 TLS 版本，但為了互操作性可能需要這樣做。預設值： 無，參見 minVersion。
  • sessionIdContext <string> 伺服器使用的不透明識別符號，以確保會話狀態不在應用程式之間共享。客戶端不使用。
  • ticketKeys <Buffer> 48 位元組的加密強度偽隨機資料。更多資訊請參閱會話恢復。
  • sessionTimeout <number> 伺服器建立的 TLS 會話在此秒數後將不再可恢復。更多資訊請參閱會話恢復。預設值： 300。

tls.createServer() 將 honorCipherOrder 選項的預設值設定為 true，其他建立安全上下文的 API 則不設定它。

tls.createServer() 使用從 process.argv 生成的 128 位截斷 SHA1 雜湊值作為 sessionIdContext 選項的預設值，其他建立安全上下文的 API 沒有預設值。

tls.createSecureContext() 方法建立一個 SecureContext 物件。它可以作為多個 tls API（例如 server.addContext()）的引數使用，但沒有公共方法。tls.Server 建構函式和 tls.createServer() 方法不支援 secureContext 選項。

對於使用證書的密碼，金鑰是*必需的*。可以使用 key 或 pfx 來提供它。

如果沒有給出 ca 選項，那麼 Node.js 將預設使用Mozilla 的公共信任 CA 列表。

不鼓勵使用自定義 DHE 引數，而推薦使用新的 dhparam: 'auto' 選項。當設定為 'auto' 時，將自動選擇具有足夠強度的知名 DHE 引數。否則，如有必要，可以使用 openssl dhparam 建立自定義引數。金鑰長度必須大於或等於 1024 位，否則將丟擲錯誤。雖然 1024 位是允許的，但為了更強的安全性，請使用 2048 位或更大。

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

• options <Object>
  • ALPNProtocols <string[]> | <Buffer[]> | <TypedArray[]> | <DataView[]> | <Buffer> | <TypedArray> | <DataView> 包含支援的 ALPN 協議的字串、Buffer、TypedArray 或 DataView 的陣列，或單個 Buffer、TypedArray 或 DataView。Buffer 應採用 [len][name][len][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。如果使用一個假值的 ctx 引數呼叫 callback，將使用伺服器的預設安全上下文。如果未提供 SNICallback，將使用具有高階 API 的預設回撥（見下文）。
  • ticketKeys <Buffer> 48 位元組的加密強度偽隨機資料。更多資訊請參閱會話恢復。
  • pskCallback <Function> 用於 TLS-PSK 協商，請參閱預共享金鑰。
  • pskIdentityHint <string> 傳送給客戶端的可選提示，以幫助在 TLS-PSK 協商期間選擇身份。在 TLS 1.3 中將被忽略。設定 pskIdentityHint 失敗時，將發出帶有 'ERR_TLS_PSK_SET_IDENTITY_HINT_FAILED' 程式碼的 'tlsClientError' 事件。
  • ...: 可以提供任何 tls.createSecureContext() 選項。對於伺服器，通常需要身份選項（pfx、key/cert 或 pskCallback）。
  • ...: 可以提供任何 net.createServer() 選項。
• secureConnectionListener <Function>
• 返回: <tls.Server>

建立一個新的 tls.Server。如果提供了 secureConnectionListener，它會自動被設定為 'secureConnection' 事件的監聽器。

ticketKeys 選項在 node:cluster 模組的工作程序之間自動共享。

下面演示了一個簡單的回顯伺服器

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

要為此示例生成證書和金鑰，請執行：

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

然後，要為此示例生成 client-cert.pem 證書，請執行

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

可以透過使用 tls.connect() 中的示例客戶端連線到該伺服器來對其進行測試。

tls.setDefaultCACertificates(certs)#

• certs <string[]> | <ArrayBufferView[]> 一個 PEM 格式的 CA 證書陣列。

設定 Node.js TLS 客戶端使用的預設 CA 證書。如果提供的證書解析成功，它們將成為 tls.getCACertificates() 返回的預設 CA 證書列表，並被後續未指定自己 CA 證書的 TLS 連線使用。在設定為預設值之前，證書將被去重。

此函式僅影響當前的 Node.js 執行緒。由 HTTPS 代理快取的先前會話不會受此更改的影響，因此應在進行任何不希望被快取的 TLS 連線之前呼叫此方法。

要使用系統 CA 證書作為預設值

const tls = require('node:tls');
tls.setDefaultCACertificates(tls.getCACertificates('system'));import tls from 'node:tls';
tls.setDefaultCACertificates(tls.getCACertificates('system'));copy

此函式完全替換預設的 CA 證書列表。要向現有的預設值中新增其他證書，請獲取當前證書並追加到它們後面

const tls = require('node:tls');
const currentCerts = tls.getCACertificates('default');
const additionalCerts = ['-----BEGIN CERTIFICATE-----\n...'];
tls.setDefaultCACertificates([...currentCerts, ...additionalCerts]);import tls from 'node:tls';
const currentCerts = tls.getCACertificates('default');
const additionalCerts = ['-----BEGIN CERTIFICATE-----\n...'];
tls.setDefaultCACertificates([...currentCerts, ...additionalCerts]);copy

tls.getCACertificates([type])#

• type <string> | <undefined> 將返回的 CA 證書的型別。有效值為 "default"、"system"、"bundled" 和 "extra"。預設值： "default"。
• 返回：<string[]> 一個 PEM 編碼的證書陣列。如果同一個證書在多個來源中重複儲存，陣列可能包含重複項。

根據 type 返回一個包含來自不同來源的 CA 證書的陣列

• "default"：返回 Node.js TLS 客戶端預設使用的 CA 證書。
  • 當啟用 --use-bundled-ca（預設）時，或者未啟用 --use-openssl-ca 時，這將包括來自捆綁的 Mozilla CA 儲存的 CA 證書。
  • 當啟用 --use-system-ca 時，這也將包括來自系統信任儲存的證書。
  • 當使用 NODE_EXTRA_CA_CERTS 時，這也將包括從指定檔案載入的證書。
• "system"：根據 --use-system-ca 設定的規則，返回從系統信任儲存載入的 CA 證書。當未啟用 --use-system-ca 時，可以使用此選項獲取系統證書。
• "bundled"：返回捆綁的 Mozilla CA 儲存中的 CA 證書。這將與 tls.rootCertificates 相同。
• "extra"：返回從 NODE_EXTRA_CA_CERTS 載入的 CA 證書。如果未設定 NODE_EXTRA_CA_CERTS，則為空陣列。

tls.getCiphers()#

• 返回：<string[]>

返回一個包含支援的 TLS 密碼名稱的陣列。由於歷史原因，名稱為小寫，但必須大寫才能在 tls.createSecureContext() 的 ciphers 選項中使用。

並非所有支援的密碼都預設啟用。請參閱修改預設的 TLS 密碼套件。

以 'tls_' 開頭的密碼名稱用於 TLSv1.3，所有其他的都用於 TLSv1.2 及以下版本。

console.log(tls.getCiphers()); // ['aes128-gcm-sha256', 'aes128-sha', ...] copy

tls.rootCertificates#

• 型別：<string[]>

一個不可變的字串陣列，代表當前 Node.js 版本提供的捆綁 Mozilla CA 儲存中的根證書（PEM 格式）。

由 Node.js 提供的捆綁 CA 儲存是 Mozilla CA 儲存在釋出時的快照。它在所有支援的平臺上都是相同的。

要獲取當前 Node.js 例項使用的實際 CA 證書，其中可能包括從系統儲存載入的證書（如果使用 --use-system-ca）或從 NODE_EXTRA_CA_CERTS 指定的檔案載入的證書，請使用 tls.getCACertificates()。

tls.DEFAULT_ECDH_CURVE#

在 tls 伺服器中用於 ECDH 金鑰協商的預設曲線名稱。預設值為 'auto'。更多資訊請參閱 tls.createSecureContext()。

tls.DEFAULT_MAX_VERSION#

• 型別：<string> tls.createSecureContext() 的 maxVersion 選項的預設值。可以賦值為任何支援的 TLS 協議版本：'TLSv1.3'、'TLSv1.2'、'TLSv1.1' 或 'TLSv1'。預設值： 'TLSv1.3'，除非使用 CLI 選項更改。使用 --tls-max-v1.2 將預設值設定為 'TLSv1.2'。使用 --tls-max-v1.3 將預設值設定為 'TLSv1.3'。如果提供了多個選項，則使用最高的最大值。

tls.DEFAULT_MIN_VERSION#

• 型別：<string> tls.createSecureContext() 的 minVersion 選項的預設值。可以賦值為任何支援的 TLS 協議版本：'TLSv1.3'、'TLSv1.2'、'TLSv1.1' 或 'TLSv1'。TLSv1.2 之前的版本可能需要降低 OpenSSL 安全級別。預設值： 'TLSv1.2'，除非使用 CLI 選項更改。使用 --tls-min-v1.0 將預設值設定為 'TLSv1'。使用 --tls-min-v1.1 將預設值設定為 'TLSv1.1'。使用 --tls-min-v1.3 將預設值設定為 'TLSv1.3'。如果提供了多個選項，則使用最低的最小值。

tls.DEFAULT_CIPHERS#

• 型別：<string> tls.createSecureContext() 的 ciphers 選項的預設值。可以賦值為任何支援的 OpenSSL 密碼。預設為 crypto.constants.defaultCoreCipherList 的內容，除非使用 CLI 選項 --tls-default-ciphers 更改。