iDoc.dev

日本語

English
简体中文
Español
Français
Português
Deutsch
Italiano
한국어
Русский
العربية

日本語

English
简体中文
Español
Français
Português
Deutsch
Italiano
한국어
Русский
العربية

テーマ

TLS (SSL) ​

[Stable: 2 - Stable]

Stable: 2 Stability: 2 - Stable

ソースコード: lib/tls.js

node:tls モジュールは、OpenSSL を基盤とした Transport Layer Security (TLS)と Secure Socket Layer (SSL)プロトコルの実装を提供します。このモジュールは以下のようにアクセスできます。

js
import tls from 'node:tls'
js
const tls = require('node:tls')

crypto サポートの有無の判定 ​

node:cryptoモジュールのサポートを含めずに Node.js をビルドすることが可能です。そのような場合、tlsからimportを試行したり、require('node:tls')を呼び出したりすると、エラーが発生します。

CommonJS を使用する場合、try/catch を使用してスローされたエラーをキャッチできます。

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

字句的 ESM importキーワードを使用する場合、エラーは、モジュールの読み込みを試みる前にprocess.on('uncaughtException')のハンドラを登録した場合（例えば、プリロードモジュールを使用した場合）にのみキャッチできます。

ESM を使用する場合、crypto サポートが有効になっていない Node.js のビルドでコードが実行される可能性がある場合は、字句的importキーワードの代わりにimport()関数を使用することを検討してください。

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

TLS/SSL の概念 ​

TLS/SSL は、公開鍵インフラストラクチャ（PKI）に依存して、クライアントとサーバー間の安全な通信を可能にするプロトコルのセットです。一般的なほとんどの場合、各サーバーは秘密鍵を持っている必要があります。

秘密鍵は複数の方法で生成できます。以下の例は、OpenSSL コマンドラインインターフェースを使用して 2048 ビット RSA 秘密鍵を生成する方法を示しています。

bash
openssl genrsa -out ryans-key.pem 2048

TLS/SSL では、すべてのサーバー（および一部のクライアント）は証明書を持っている必要があります。証明書は秘密鍵に対応する公開鍵であり、認証局または秘密鍵の所有者によってデジタル署名されています（そのような証明書は「自己署名」と呼ばれます）。証明書を取得する最初のステップは、証明書署名要求（CSR）ファイルを作成することです。

OpenSSL コマンドラインインターフェースを使用して、秘密鍵の CSR を生成できます。

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

CSR ファイルが生成されたら、署名のために認証局に送信するか、自己署名証明書を生成するために使用できます。

OpenSSL コマンドラインインターフェースを使用した自己署名証明書の生成を以下の例に示します。

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

証明書が生成されたら、.pfxまたは.p12ファイルを作成するために使用できます。

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

ここで：

  • in: 署名された証明書です。
  • inkey: 関連付けられた秘密鍵です。
  • certfile: すべての認証局（CA）証明書を単一ファイルに連結したものです。例：cat ca1-cert.pem ca2-cert.pem > ca-cert.pem

完全順方向秘匿性 ​

順方向秘匿性 あるいは 完全順方向秘匿性 という用語は、鍵合意（つまり、鍵交換）方式の特徴を表します。つまり、サーバとクライアントの鍵を使用して、現在の通信セッションのみに使用される新しい一時的な鍵をネゴシエートします。実際には、これは、サーバの秘密鍵が侵害された場合でも、攻撃者がセッション用に生成された鍵ペアを取得した場合にのみ、傍受者が通信を復号化できることを意味します。

完全順方向秘匿性は、すべての TLS/SSL ハンドシェイクで鍵合意のための鍵ペアをランダムに生成することによって実現されます（すべてのセッションで同じ鍵を使用することとは対照的です）。この手法を実装する方法は「一時的な」と呼ばれます。

現在、完全順方向秘匿性を達成するために一般的に使用されている方法は 2 つあります（従来の略語に文字「E」が付加されていることに注意してください）。

  • ECDHE: 楕円曲線 Diffie-Hellman 鍵合意プロトコルの、一時的なバージョン。
  • DHE: Diffie-Hellman 鍵合意プロトコルの、一時的なバージョン。

ECDHE を使用した完全順方向秘匿性は、デフォルトで有効になっています。ecdhCurve オプションは、TLS サーバを作成する際に、使用するサポートされている ECDH 曲線のリストをカスタマイズするために使用できます。詳細はtls.createServer()を参照してください。

DHE はデフォルトで無効になっていますが、dhparamオプションを'auto'に設定することで、ECDHE と共に有効にすることができます。カスタム DHE パラメータもサポートされていますが、自動的に選択された、よく知られたパラメータを優先して使用することをお勧めします。

完全順方向秘匿性は、TLSv1.2 まではオプションでした。TLSv1.3 以降は、（PSK のみの接続を除いて）(EC)DHE が常に使用されます。

ALPN と SNI ​

ALPN（Application-Layer Protocol Negotiation Extension）と SNI（Server Name Indication）は、TLS ハンドシェイク拡張です。

  • ALPN: 1 つの TLS サーバで複数のプロトコル（HTTP、HTTP/2）を使用できるようにします。
  • SNI: 1 つの TLS サーバで、異なる証明書を持つ複数のホスト名を使用できるようにします。

事前共有鍵 ​

通常の証明書ベースの認証の代替として、TLS-PSK サポートが利用可能です。これは、TLS 接続を認証するために証明書の代わりに事前共有鍵を使用し、相互認証を提供します。TLS-PSK と公開鍵インフラストラクチャは相互に排他的ではありません。クライアントとサーバーは両方に対応でき、通常の暗号ネゴシエーションステップでどちらかを選択できます。

TLS-PSK は、すべての接続マシンと安全に鍵を共有する手段が存在する場合にのみ適切な選択肢であるため、ほとんどの TLS 用途における公開鍵インフラストラクチャ（PKI）に取って代わるものではありません。OpenSSL の TLS-PSK 実装では、近年多くのセキュリティ上の欠陥が見つかっており、これは主に少数のアプケーションでのみ使用されているためです。PSK 暗号に切り替える前に、すべての代替ソリューションを検討してください。PSK を生成する際には、RFC 4086で説明されているように、十分なエントロピーを使用することが非常に重要です。パスワードやその他の低エントロピーソースから共有秘密を導出することは安全ではありません。

PSK 暗号はデフォルトで無効になっており、TLS-PSK を使用するには、ciphersオプションで暗号スイートを明示的に指定する必要があります。利用可能な暗号のリストは、openssl ciphers -v 'PSK'で取得できます。すべての TLS 1.3 暗号は PSK を使用でき、openssl ciphers -v -s -tls1_3 -pskで取得できます。クライアント接続では、証明書がない場合、デフォルトのものが失敗するため、カスタムcheckServerIdentityを渡す必要があります。

RFC 4279によると、最大 128 バイトの長さの PSK ID と最大 64 バイトの長さの PSK をサポートする必要があります。OpenSSL 1.1.0 以降、最大 ID サイズは 128 バイト、最大 PSK 長は 256 バイトです。

現在の実装では、基盤となる OpenSSL API の制限のため、非同期 PSK コールバックをサポートしていません。

TLS-PSK を使用するには、クライアントとサーバーでpskCallbackオプションを指定する必要があります。これは、使用する PSK（選択した暗号のダイジェストと互換性がある必要があります）を返す関数です。

これは最初にクライアントで呼び出されます。

  • ヒント: ネゴシエーション中にクライアントが使用する ID を決定するのに役立つ、サーバーから送信される<string>のオプションメッセージ。TLS 1.3 を使用する場合は常にnullです。
  • 戻り値: { psk: <Buffer|TypedArray|DataView>, identity: <string> }またはnullの形式の<Object>。

次にサーバーで：

nullの戻り値はネゴシエーションプロセスを停止し、unknown_psk_identityアラートメッセージを相手側に送信します。サーバーが PSK ID が不明であったという事実を隠したい場合、コールバックはネゴシエーションが完了する前にdecrypt_errorで接続が失敗するように、pskとして何らかのランダムデータを提供する必要があります。

クライアント開始再交渉攻撃の軽減 ​

TLS プロトコルは、クライアントが TLS セッションの特定の側面を再交渉することを許可しています。残念ながら、セッションの再交渉には、サーバー側のリソースが不釣り合いなほど必要となるため、サービス拒否攻撃の可能性のあるベクトルとなります。

リスクを軽減するために、再交渉は 10 分ごとに 3 回に制限されています。この閾値を超えると、tls.TLSSocketインスタンスで'error'イベントが発行されます。制限は設定可能です。

  • tls.CLIENT_RENEG_LIMIT <number> 再交渉要求の数を指定します。デフォルト: 3。
  • tls.CLIENT_RENEG_WINDOW <number> 再交渉ウィンドウの時間を秒単位で指定します。デフォルト: 600 (10 分)。

影響とリスクを完全に理解せずに、デフォルトの再交渉制限を変更しないでください。

TLSv1.3 は再交渉をサポートしていません。

セッション再開 ​

TLS セッションの確立は比較的遅くなる可能性があります。セッションの状態を保存して後で再利用することで、このプロセスを高速化できます。これを行うためのいくつかのメカニズムがあり、ここでは古いものから新しいもの（そして推奨されるもの）の順に説明します。

セッション識別子 ​

サーバーは新しい接続に対して一意の ID を生成し、クライアントに送信します。クライアントとサーバーはセッションの状態を保存します。再接続時に、クライアントは保存されたセッション状態の ID を送信し、サーバーにもその ID の状態がある場合、それを利用することに同意できます。そうでない場合、サーバーは新しいセッションを作成します。詳細については、RFC 2246の 23 ページと 30 ページを参照してください。

セッション識別子を使用した再開は、HTTPS リクエストを行う際のほとんどの Web ブラウザでサポートされています。

Node.js の場合、クライアントは'session'イベントを待ってセッションデータを取得し、後続のtls.connect()のsessionオプションにそのデータを提供してセッションを再利用します。サーバーは、セッション ID をルックアップキーとして使用してセッションを再利用するために、'newSession'イベントと'resumeSession'イベントのハンドラーを実装する必要があります。ロードバランサーまたはクラスタワーカー間でセッションを再利用するには、サーバーはセッションハンドラーで共有セッションキャッシュ（Redis など）を使用する必要があります。

セッションチケット ​

サーバはセッション状態全体を暗号化し、「チケット」としてクライアントに送信します。再接続時には、初期接続時に状態がサーバに送信されます。このメカニズムにより、サーバ側のセッションキャッシュが不要になります。サーバが何らかの理由（復号化失敗、期限切れなど）でチケットを使用しない場合、新しいセッションを作成し、新しいチケットを送信します。詳細はRFC 5077を参照してください。

セッションチケットを使用した再開は、HTTPS リクエストを行う多くの Web ブラウザで一般的にサポートされるようになっています。

Node.js では、クライアントはセッション識別子を使用した再開とセッションチケットを使用した再開に対して同じ API を使用します。デバッグのために、tls.TLSSocket.getTLSTicket()が値を返す場合、セッションデータにはチケットが含まれ、それ以外の場合はクライアント側のセッション状態が含まれます。

TLSv1.3 では、サーバから複数のチケットが送信され、複数の'session'イベントが発生することに注意してください。詳細は'session'を参照してください。

単一プロセスのサーバは、セッションチケットを使用するために特別な実装は必要ありません。サーバの再起動やロードバランサにまたがってセッションチケットを使用するには、すべてのサーバが同じチケットキーを持っている必要があります。内部的には 3 つの 16 バイトキーがありますが、tls API は便宜上それらを単一の 48 バイトバッファとして公開しています。

server.getTicketKeys()を 1 つのサーバインスタンスで呼び出してチケットキーを取得し、それらを配布することは可能ですが、48 バイトの安全なランダムデータ安全に生成して、tls.createServer()のticketKeysオプションで設定する方が合理的です。キーは定期的に再生成する必要があり、サーバのキーはserver.setTicketKeys()でリセットできます。

セッションチケットキーは暗号キーであり、安全に保管する必要があります。TLS 1.2 以前では、それらが侵害されると、それらを使用して暗号化されたすべてのセッションを復号化できます。ディスクに保存するべきではなく、定期的に再生成する必要があります。

クライアントがチケットのサポートをアドバタイズした場合、サーバはそれらを送信します。サーバは、secureOptionsにrequire('node:constants').SSL_OP_NO_TICKETを指定することでチケットを無効にできます。

セッション識別子とセッションチケットの両方にタイムアウトがあり、サーバは新しいセッションを作成します。タイムアウトは、tls.createServer()のsessionTimeoutオプションで設定できます。

すべてのメカニズムにおいて、再開に失敗した場合、サーバは新しいセッションを作成します。セッションの再開に失敗しても TLS/HTTPS 接続エラーが発生しないため、不必要に悪い TLS パフォーマンスに気付かない場合があります。OpenSSL CLI を使用して、サーバがセッションを再開していることを確認できます。openssl s_clientに-reconnectオプションを使用します。例：

bash
openssl s_client -connect localhost:443 -reconnect

デバッグ出力を確認してください。最初の接続は「New」と表示されます。例：

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

後続の接続は「Reused」と表示されます。例：

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

デフォルトの TLS 暗号スイートの変更 ​

Node.js は、有効化および無効化された TLS 暗号のデフォルトスイートを組み込んで構築されています。このデフォルトの暗号リストは、Node.js をビルドする際に設定でき、ディストリビューションが独自のデフォルトリストを提供できるようにします。

次のコマンドを使用して、デフォルトの暗号スイートを表示できます。

bash
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

このデフォルトは、--tls-cipher-listコマンドラインスイッチ（直接、またはNODE_OPTIONS環境変数経由）を使用して完全に置き換えることができます。たとえば、次のコマンドはECDHE-RSA-AES128-GCM-SHA256:!RC4をデフォルトの TLS 暗号スイートにします。

bash
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

確認するには、次のコマンドを使用して設定された暗号リストを表示します。defaultCoreCipherListとdefaultCipherListの違いに注意してください。

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

つまり、defaultCoreCipherListリストはコンパイル時に設定され、defaultCipherListリストは実行時に設定されます。

ランタイム内からデフォルトの暗号スイートを変更するには、tls.DEFAULT_CIPHERS変数を変更します。これは、ソケットをリッスンする前に実行する必要があり、既に開いているソケットには影響しません。例：

js
// 廃止されたCBC暗号とRSA鍵交換ベースの暗号を削除します。これらはフォワードシークレシーを提供しません。
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'

デフォルトは、tls.createSecureContext()のciphersオプションを使用して、クライアントまたはサーバーごとに置き換えることもできます。これはtls.createServer()、tls.connect()でも使用でき、新しいtls.TLSSocketを作成する場合にも使用できます。

暗号リストには、'TLS_'で始まる TLSv1.3 暗号スイート名と、TLSv1.2 以下の暗号スイートの仕様を混在させることができます。TLSv1.2 暗号はレガシー仕様形式をサポートしています。詳細については、OpenSSL の暗号リスト形式ドキュメントを参照してください。ただし、これらの仕様は TLSv1.3 暗号には適用されません。TLSv1.3 スイートは、暗号リストに完全な名前を含めることによってのみ有効化できます。たとえば、レガシー TLSv1.2 の'EECDH'または'!EECDH'仕様を使用して有効化または無効化することはできません。

TLSv1.3 と TLSv1.2 の暗号スイートの相対的な順序に関わらず、TLSv1.3 プロトコルは TLSv1.2 よりもはるかに安全であり、ハンドシェイクでサポートされていることが示され、TLSv1.3 暗号スイートが有効になっている場合は、常に TLSv1.2 よりも優先されます。

Node.js に含まれるデフォルトの暗号スイートは、現在のセキュリティベストプラクティスとリスク軽減を反映するように慎重に選択されています。デフォルトの暗号スイートを変更すると、アプリケーションのセキュリティに大きな影響を与える可能性があります。--tls-cipher-listスイッチとciphersオプションは、絶対に必要な場合にのみ使用する必要があります。

デフォルトの暗号スイートは、Chrome の「最新の暗号化」設定のために GCM 暗号を優先し、完全なフォワードシークレシーのために ECDHE および DHE 暗号を優先する一方、ある程度の下位互換性を提供します。

安全でない廃止された RC4 または DES ベースの暗号（Internet Explorer 6 など）に依存する古いクライアントは、デフォルトの設定ではハンドシェイクプロセスを完了できません。これらのクライアントを必ずサポートする必要がある場合は、TLS の推奨事項で互換性のある暗号スイートを提供できます。形式の詳細については、OpenSSL の暗号リスト形式ドキュメントを参照してください。

TLSv1.3 暗号スイートは 5 つだけです。

  • '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'

最初の 3 つはデフォルトで有効になっています。2 つのCCMベースのスイートは、制約のあるシステムでパフォーマンスが向上する可能性があるため、TLSv1.3 でサポートされていますが、セキュリティが低いため、デフォルトでは有効になっていません。

OpenSSL セキュリティレベル ​

OpenSSL ライブラリは、暗号化操作の許容最低セキュリティレベルを制御するために、セキュリティレベルを適用します。OpenSSL のセキュリティレベルは 0 から 5 まであり、レベルが上がるごとにセキュリティ要件が厳しくなります。デフォルトのセキュリティレベルは 1 で、ほとんどの最新のアプリケーションに適しています。ただし、TLSv1 などの一部のレガシー機能とプロトコルは、正常に機能するためにより低いセキュリティレベル(SECLEVEL=0)を必要とします。詳細については、OpenSSL のセキュリティレベルに関するドキュメントを参照してください。

セキュリティレベルの設定 ​

Node.js アプリケーションでセキュリティレベルを調整するには、@SECLEVEL=Xを暗号文字列に含めることができます。ここでXは目的のセキュリティレベルです。たとえば、デフォルトの OpenSSL 暗号リストを使用しながらセキュリティレベルを 0 に設定するには、次のように使用できます。

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

この方法はセキュリティレベルを 0 に設定し、レガシー機能の使用を許可しながら、デフォルトの OpenSSL 暗号を引き続き活用できます。

使用方法 ​

デフォルトの TLS 暗号スイートの変更で説明されているように、--tls-cipher-list=DEFAULT@SECLEVEL=Xを使用して、コマンドラインからセキュリティレベルと暗号を設定することもできます。ただし、コマンドラインオプションを使用して暗号を設定することは一般的に推奨されず、アプリケーションコード内で個々のコンテキストの暗号を構成することをお勧めします。この方法により、より細かい制御が可能になり、グローバルにセキュリティレベルを低下させるリスクを軽減できます。

X509 証明書エラーコード ​

OpenSSL によって報告される証明書エラーにより、複数の関数が失敗することがあります。そのような場合、関数はコールバックを介してcodeプロパティを持つ<Error>を提供し、次のいずれかの値を取ることができます。

  • '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': ホスト名と一致しません。

クラス: tls.CryptoStream ​

追加日時: v0.3.4

非推奨日時: v0.11.3

[安定性: 0 - 非推奨]

安定性: 0 安定性: 0 - 非推奨: tls.TLSSocket を代わりに使用してください。

tls.CryptoStreamクラスは、暗号化されたデータのストリームを表します。このクラスは非推奨であり、もはや使用すべきではありません。

cryptoStream.bytesWritten ​

追加日時: v0.3.4

非推奨日時: v0.11.3

cryptoStream.bytesWrittenプロパティは、基となるソケットに書き込まれたバイトの総数を返します。これには、TLS プロトコルの実装に必要なバイト数も含まれます。

クラス: tls.SecurePair ​

追加日時: v0.3.2

非推奨日時: v0.11.3

[安定性: 0 - 非推奨]

安定性: 0 安定性: 0 - 非推奨: tls.TLSSocket を代わりに使用してください。

tls.createSecurePair()によって返されます。

イベント: 'secure' ​

追加日時: v0.3.2

非推奨日時: v0.11.3

'secure'イベントは、安全な接続が確立されると、SecurePairオブジェクトによって発行されます。

サーバーの'secureConnection'イベントの確認と同様に、使用された証明書が適切に承認されているかどうかを確認するために、pair.cleartext.authorizedを検査する必要があります。

クラス: tls.Server ​

追加日時: v0.3.2

TLS または SSL を使用して暗号化された接続を受け入れます。

イベント: 'connection' ​

追加日時: v0.3.2

このイベントは、新しい TCP ストリームが確立されると、TLS ハンドシェイクが始まる前に発行されます。socketは通常net.Socketタイプのオブジェクトですが、net.Server'connection'イベントから作成されたソケットとは異なり、イベントを受信しません。通常、ユーザーはこのイベントにアクセスする必要はありません。

このイベントは、ユーザーが TLS サーバーに接続を挿入するために明示的に発行することもできます。その場合、任意のDuplexストリームを渡すことができます。

イベント: 'keylog' ​

追加されたバージョン: v12.3.0, v10.20.0

  • line <Buffer> NSS SSLKEYLOGFILE形式の ASCII テキストの行。
  • tlsSocket <tls.TLSSocket> それが生成されたtls.TLSSocketインスタンス。

keylogイベントは、このサーバーへの接続によって鍵素材が生成または受信されたときに発生します（通常はハンドシェイクが完了する前ですが、必ずしもそうとは限りません）。この鍵素材は、キャプチャされた TLS トラフィックの復号を可能にするため、デバッグのために保存できます。ソケットごとに複数回発生することがあります。

一般的なユースケースは、受信した行を共通のテキストファイルに追加し、後でソフトウェア（Wireshark など）を使用してトラフィックを復号することです。

js
const logFile = fs.createWriteStream('/tmp/ssl-keys.log', { flags: 'a' })
// ...
server.on('keylog', (line, tlsSocket) => {
  if (tlsSocket.remoteAddress !== '...') return // 特定のIPの鍵のみログに記録する
  logFile.write(line)
})

イベント: 'newSession' ​

[履歴]

バージョン変更
v0.11.12callback引数がサポートされるようになりました。
v0.9.2追加されたバージョン: v0.9.2

'newSession'イベントは、新しい TLS セッションの作成時に発生します。これは、外部ストレージにセッションを保存するために使用できます。データは、'resumeSession'コールバックに提供する必要があります。

リスナーコールバックは、呼び出されるときに 3 つの引数を渡されます。

  • sessionId <Buffer> TLS セッション識別子
  • sessionData <Buffer> TLS セッションデータ
  • callback <Function> 引数を取らないコールバック関数。安全な接続を介してデータを送受信するには、これを呼び出す必要があります。

このイベントをリッスンしても、イベントリスナーの追加後に確立された接続にのみ影響します。

イベント: 'OCSPRequest' ​

追加されたバージョン: v0.11.13

'OCSPRequest'イベントは、クライアントが証明書ステータス要求を送信したときに発生します。リスナーコールバックは、呼び出されるときに 3 つの引数を渡されます。

  • certificate <Buffer> サーバー証明書
  • issuer <Buffer> 発行者の証明書
  • callback <Function> OCSP 要求の結果を提供するために呼び出す必要があるコールバック関数。

サーバーの現在の証明書を解析して OCSP URL と証明書 ID を取得できます。OCSP 応答を取得した後、callback(null, resp)が呼び出されます。ここで、respは OCSP 応答を含むBufferインスタンスです。certificateとissuerはどちらも、プライマリと発行者の証明書のBuffer DER 表現です。これらを使用して、OCSP 証明書 ID と OCSP エンドポイント URL を取得できます。

または、callback(null, null)を呼び出して、OCSP 応答がないことを示すことができます。

callback(err)を呼び出すと、socket.destroy(err)呼び出しが行われます。

OCSP 要求の典型的な流れは以下のとおりです。

証明書が自己署名されているか、発行者がルート証明書リストにない場合、issuerはnullになる可能性があります。（TLS 接続を確立するときに、caオプションを介して発行者を指定できます。）

このイベントをリッスンしても、イベントリスナーの追加後に確立された接続にのみ影響します。

asn1.jsのような npm モジュールを使用して、証明書を解析できます。

イベント: 'resumeSession' ​

追加バージョン: v0.9.2

'resumeSession' イベントは、クライアントが以前の TLS セッションの再開を要求したときに発生します。リスナーコールバックは呼び出されるときに 2 つの引数を渡されます。

  • sessionId <Buffer> TLS セッション識別子
  • callback <Function> 以前のセッションが復元されたときに呼び出されるコールバック関数: callback([err[, sessionData]])

このイベントリスナーは、指定された sessionId を使用して、'newSession' イベントハンドラーによって保存された sessionData を外部ストレージで検索する必要があります。見つかった場合は、セッションを再開するために callback(null, sessionData) を呼び出します。見つからない場合、セッションは再開できません。ハンドシェイクを継続し、新しいセッションを作成できるように、sessionData を指定せずに callback() を呼び出す必要があります。callback(err) を呼び出して、着信接続を終了し、ソケットを破棄することも可能です。

このイベントをリッスンすると、イベントリスナーの追加後に確立された接続にのみ影響します。

以下の例は、TLS セッションの再開を示しています。

js
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)
})

イベント: 'secureConnection' ​

追加バージョン: v0.3.2

'secureConnection' イベントは、新しい接続のハンドシェイキングプロセスが正常に完了した後に発生します。リスナーコールバックは呼び出されるときに 1 つの引数を渡されます。

tlsSocket.authorized プロパティは、クライアントがサーバーの提供された認証局のいずれかによって検証されたかどうかを示す boolean 値です。tlsSocket.authorized が false の場合、socket.authorizationError に認証失敗の理由が設定されます。TLS サーバーの設定によっては、承認されていない接続が受け入れられる可能性があります。

tlsSocket.alpnProtocol プロパティは、選択された ALPN プロトコルを含む文字列です。クライアントまたはサーバーが ALPN 拡張機能を送信しなかったため、ALPN に選択されたプロトコルがない場合、tlsSocket.alpnProtocol は false となります。

tlsSocket.servername プロパティは、SNI を介して要求されたサーバー名を含む文字列です。

イベント: 'tlsClientError' ​

追加バージョン: v6.0.0

'tlsClientError' イベントは、セキュアな接続確立前にエラーが発生した場合に発行されます。リスナーコールバックは呼び出されるときに 2 つの引数を渡されます。

  • exception <Error> エラーを記述する Error オブジェクト
  • tlsSocket <tls.TLSSocket> エラーが発生した元の tls.TLSSocket インスタンス。

server.addContext(hostname, context) ​

追加バージョン: v0.5.3

server.addContext() メソッドは、クライアントリクエストの SNI 名が指定された hostname（またはワイルドカード）と一致する場合に使用されるセキュアコンテキストを追加します。

複数のコンテキストが一致する場合、最後に追加されたものが使用されます。

server.address() ​

追加バージョン: v0.6.0

オペレーティングシステムによって報告された、バインドされたアドレス、アドレスファミリ名、およびサーバーのポートを返します。詳細は net.Server.address() を参照してください。

server.close([callback]) ​

追加バージョン: v0.3.2

  • callback <Function> サーバーインスタンスの 'close' イベントをリッスンするために登録されるリスナーコールバック。
  • 戻り値: <tls.Server>

server.close() メソッドは、サーバーが新しい接続を受け入れるのを停止します。

この関数は非同期的に動作します。サーバーに開いている接続がなくなると 'close' イベントが発行されます。

server.getTicketKeys() ​

追加バージョン: v3.0.0

  • 戻り値: <Buffer> セッションチケットキーを含む 48 バイトのバッファ。

セッションチケットキーを返します。

詳細は、セッション再開を参照してください。

server.listen() ​

暗号化された接続を待ち受けるサーバーを開始します。このメソッドは、net.Serverからのserver.listen()と同一です。

server.setSecureContext(options) ​

追加バージョン: v11.0.0

server.setSecureContext()メソッドは、既存のサーバーのセキュアコンテキストを置き換えます。サーバーへの既存の接続は中断されません。

server.setTicketKeys(keys) ​

追加バージョン: v3.0.0

セッションチケットキーを設定します。

チケットキーの変更は、将来のサーバー接続にのみ有効です。既存の、または現在保留中のサーバー接続は、以前のキーを使用します。

詳細は、セッション再開を参照してください。

クラス: tls.TLSSocket ​

追加バージョン: v0.11.4

書き込まれたデータの透過的な暗号化と、必要なすべての TLS ネゴシエーションを実行します。

tls.TLSSocketのインスタンスは、デュプレックスStreamインターフェースを実装します。

TLS 接続のメタデータ（例：tls.TLSSocket.getPeerCertificate()）を返すメソッドは、接続が開いている間のみデータ を返します。

new tls.TLSSocket(socket[, options]) ​

[履歴]

バージョン変更
v12.2.0enableTrace オプションがサポートされました。
v5.0.0ALPN オプションがサポートされました。
v0.11.4追加されました: v0.11.4
  • socket <net.Socket> | <stream.Duplex> サーバー側では、任意の Duplex ストリーム。クライアント側では、net.Socket の任意のインスタンス（クライアント側の汎用的な Duplex ストリームサポートには、tls.connect() を使用する必要があります）。
  • options <Object>
    • enableTrace: tls.createServer() を参照してください。
    • isServer: SSL/TLS プロトコルは非対称であるため、TLSSocket はサーバーとして動作するのかクライアントとして動作するのかを知る必要があります。true の場合、TLS ソケットはサーバーとしてインスタンス化されます。デフォルト: false。
    • server <net.Server> net.Server インスタンス。
    • requestCert: 証明書を要求することによってリモートピアを認証するかどうか。クライアントは常にサーバー証明書を要求します。サーバー（isServer が true）は、クライアント証明書を要求するために requestCert を true に設定できます。
    • rejectUnauthorized: tls.createServer() を参照してください。
    • ALPNProtocols: tls.createServer() を参照してください。
    • SNICallback: tls.createServer() を参照してください。
    • session <Buffer> TLS セッションを含む Buffer インスタンス。
    • requestOCSP <boolean> true の場合、OCSP ステータス要求拡張がクライアント hello に追加され、安全な通信を確立する前にソケットで 'OCSPResponse' イベントが発生することを指定します。
    • secureContext: tls.createSecureContext() で作成された TLS コンテキストオブジェクト。secureContext が提供されない場合、tls.createSecureContext() に options オブジェクト全体を渡すことで作成されます。
    • ...: secureContext オプションがない場合に使用される tls.createSecureContext() オプション。それ以外の場合は無視されます。

既存の TCP ソケットから新しい tls.TLSSocket オブジェクトを構築します。

イベント: 'keylog' ​

追加バージョン: v12.3.0, v10.20.0

  • line <Buffer> NSS SSLKEYLOGFILE形式の ASCII テキストの行。

keylogイベントは、ソケットで鍵素材が生成または受信されたときにtls.TLSSocketで発生します。この鍵素材は、キャプチャされた TLS トラフィックの復号を可能にするため、デバッグ用に保存できます。ハンドシェイクが完了する前または後に、複数回発生することがあります。

一般的なユースケースは、受信した行を共通のテキストファイルに追加し、後でソフトウェア（Wireshark など）を使用してトラフィックを復号することです。

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

イベント: 'OCSPResponse' ​

追加バージョン: v0.11.13

'OCSPResponse'イベントは、tls.TLSSocketの作成時にrequestOCSPオプションが設定されていて、OCSP 応答が受信された場合に発生します。リスナーコールバックは呼び出されるときに単一の引数を渡されます。

  • response <Buffer> サーバーの OCSP 応答

通常、responseは、サーバーの証明書の失効状態に関する情報を含む、サーバーの CA からのデジタル署名付きオブジェクトです。

イベント: 'secureConnect' ​

追加バージョン: v0.11.4

'secureConnect'イベントは、新しい接続のハンドシェイクプロセスが正常に完了した後に発生します。リスナーコールバックは、サーバーの証明書が承認されたかどうかに関係なく呼び出されます。サーバー証明書が指定された CA のいずれかによって署名されたかどうかを確認するのはクライアントの責任です。tlsSocket.authorized === falseの場合、エラーはtlsSocket.authorizationErrorプロパティを調べると見つけることができます。ALPN が使用された場合、tlsSocket.alpnProtocolプロパティをチェックして、ネゴシエートされたプロトコルを確認できます。

'secureConnect'イベントは、new tls.TLSSocket()コンストラクタを使用して <tls.TLSSocket>が作成されたときには発生しません。

イベント: 'session' ​

追加バージョン: v11.10.0

'session'イベントは、新しいセッションまたは TLS チケットが利用可能になったときに、クライアントのtls.TLSSocketで発生します。これは、ネゴシエートされた TLS プロトコルバージョンによっては、ハンドシェイクが完了する前になる場合と、ならない場合があります。このイベントは、サーバー上では発生しません。また、新しいセッションが作成されなかった場合（たとえば、接続が再開された場合）にも発生しません。一部の TLS プロトコルバージョンでは、このイベントが複数回発生することがあり、その場合、すべてのセッションを再開に使用できます。

クライアントでは、接続を再開するために、sessionをtls.connect()のsessionオプションに提供できます。

詳細はセッション再開を参照してください。

TLSv1.2 以下では、ハンドシェイクが完了したらtls.TLSSocket.getSession()を呼び出すことができます。TLSv1.3 では、プロトコルによってチケットベースの再開のみが許可され、複数のチケットが送信され、チケットはハンドシェイクが完了するまで送信されません。そのため、再開可能なセッションを取得するには、'session'イベントを待機する必要があります。すべての TLS バージョンで動作するようにするには、アプリケーションはgetSession()の代わりに'session'イベントを使用する必要があります。1 つのセッションのみを取得または使用する予定のアプリケーションは、このイベントを 1 回だけリッスンする必要があります。

js
tlsSocket.once('session', session => {
  // セッションはすぐに、または後で利用できます。
  tls.connect({
    session: session,
    // その他の接続オプション...
  })
})

tlsSocket.address() ​

[履歴]

バージョン変更
v18.4.0familyプロパティは数値ではなく文字列を返すようになりました。
v18.0.0familyプロパティは文字列ではなく数値を返すようになりました。
v0.11.4追加バージョン: v0.11.4

オペレーティングシステムによって報告された基になるソケットのバインドされたaddress、アドレスfamily名、およびportを返します: { port: 12346, family: 'IPv4', address: '127.0.0.1' }。

tlsSocket.authorizationError ​

追加: v0.11.4

ピアの証明書が検証されなかった理由を返します。このプロパティは、tlsSocket.authorized === false の場合のみ設定されます。

tlsSocket.authorized ​

追加: v0.11.4

このプロパティは、ピア証明書がtls.TLSSocketインスタンスの作成時に指定された CA のいずれかによって署名された場合にtrue、それ以外の場合はfalseになります。

tlsSocket.disableRenegotiation() ​

追加: v8.4.0

このTLSSocketインスタンスの TLS 再ネゴシエーションを無効にします。呼び出されると、再ネゴシエーションの試行はTLSSocketで'error'イベントをトリガーします。

tlsSocket.enableTrace() ​

追加: v12.2.0

有効にすると、TLS パケットトレース情報がstderrに出力されます。これは、TLS 接続の問題のデバッグに使用できます。

出力形式は、openssl s_client -traceまたはopenssl s_server -traceの出力と同じです。OpenSSL のSSL_trace()関数によって生成されますが、形式は文書化されておらず、予告なく変更される可能性があり、依存すべきではありません。

tlsSocket.encrypted ​

追加: v0.11.4

常にtrueを返します。これは、TLS ソケットと通常のnet.Socketインスタンスを区別するために使用できます。

tlsSocket.exportKeyingMaterial(length, label[, context]) ​

追加: v13.10.0, v12.17.0

  • length <number> キーイングマテリアルから取得するバイト数
  • label <string> アプリケーション固有のラベル。通常、これはIANA Exporter Label Registryからの値になります。
  • context <Buffer> 任意でコンテキストを提供します。
  • 戻り値: <Buffer> 要求されたキーイングマテリアルのバイト

キーイングマテリアルは、ネットワークプロトコル（たとえば、IEEE 802.1X の仕様など）におけるさまざまな種類の攻撃を防ぐための検証に使用されます。

例

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

/*
 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>
*/

詳細については、OpenSSL のSSL_export_keying_materialドキュメントを参照してください。

tlsSocket.getCertificate() ​

追加日時: v11.2.0

ローカル証明書を表すオブジェクトを返します。返されたオブジェクトには、証明書のフィールドに対応するいくつかのプロパティがあります。

証明書の構造の例については、tls.TLSSocket.getPeerCertificate()を参照してください。

ローカル証明書がない場合は、空のオブジェクトが返されます。ソケットが破棄されている場合は、nullが返されます。

tlsSocket.getCipher() ​

[履歴]

バージョン変更点
v13.4.0, v12.16.0IETF 暗号名をstandardNameとして返すように変更。
v12.0.0固定文字列('TLSv1/SSLv3')の代わりに、最小暗号バージョンを返すように変更。
v0.11.4追加日時: v0.11.4
  • 戻り値: <Object>
    • name <string> 暗号スイートの OpenSSL 名。
    • standardName <string> 暗号スイートの IETF 名。
    • version <string> この暗号スイートでサポートされている最小 TLS プロトコルバージョン。実際のネゴシエートされたプロトコルについては、tls.TLSSocket.getProtocol()を参照してください。

ネゴシエートされた暗号スイートに関する情報を格納したオブジェクトを返します。

たとえば、AES256-SHA 暗号を使用した TLSv1.2 プロトコルの場合：

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

詳細については、SSL_CIPHER_get_nameを参照してください。

tlsSocket.getEphemeralKeyInfo() ​

追加日時: v5.0.0

クライアント接続における完全順方向秘匿性での一時的な鍵交換のパラメータのタイプ、名前、サイズを表すオブジェクトを返します。鍵交換が一時的なものでない場合は、空のオブジェクトを返します。これはクライアントソケットでのみサポートされているため、サーバーソケットで呼び出された場合はnullが返されます。サポートされているタイプは'DH'と'ECDH'です。nameプロパティは、タイプが'ECDH'の場合のみ使用できます。

例： { type: 'ECDH', name: 'prime256v1', size: 256 }

tlsSocket.getFinished() ​

追加日時: v9.9.0

  • 戻り値: <Buffer> | <undefined> SSL/TLS ハンドシェイクの一部としてソケットに送信された最新のFinishedメッセージ、またはFinishedメッセージがまだ送信されていない場合はundefined。

Finishedメッセージは、完全なハンドシェイクのメッセージダイジェスト（TLS 1.0 では合計 192 ビット、SSL 3.0 ではそれ以上）であるため、SSL/TLS によって提供される認証が望ましくない場合や不十分な場合に、外部認証手順に使用できます。

OpenSSL のSSL_get_finishedルーチンに対応し、RFC 5929からのtls-uniqueチャネルバインディングを実装するために使用できます。

tlsSocket.getPeerCertificate([detailed]) ​

追加日時: v0.11.4

  • detailed <boolean> trueの場合、完全な証明書チェーンを含めます。それ以外の場合は、ピアの証明書のみを含めます。
  • 戻り値: <Object> 証明書オブジェクト。

ピアの証明書を表すオブジェクトを返します。ピアが証明書を提供しない場合、空のオブジェクトが返されます。ソケットが破棄されている場合、nullが返されます。

完全な証明書チェーンが要求された場合、各証明書には、発行者の証明書を表すオブジェクトを含むissuerCertificateプロパティが含まれます。

証明書オブジェクト ​

[履歴]

バージョン変更点
v19.1.0, v18.13.0"ca"プロパティを追加
v17.2.0, v16.14.0fingerprint512 を追加
v11.4.0楕円曲線公開鍵情報のサポート

証明書オブジェクトには、証明書のフィールドに対応するプロパティがあります。

  • ca <boolean> 認証機関（CA）の場合はtrue、それ以外の場合はfalse。
  • raw <Buffer> DER エンコードされた X.509 証明書データ。
  • subject <Object> 国（C）、州または州名（ST）、市区町村（L）、組織（O）、組織単位（OU）、および共通名（CN）という用語で記述された証明書の件名。共通名は通常、TLS 証明書では DNS 名です。例: {C: 'UK', ST: 'BC', L: 'Metro', O: 'Node Fans', OU: 'Docs', CN: 'example.com'}。
  • issuer <Object> subjectと同じ用語で記述された証明書の発行者。
  • valid_from <string> 証明書の有効期限開始日時。
  • valid_to <string> 証明書の有効期限終了日時。
  • serialNumber <string> 16 進文字列としての証明書のシリアル番号。例: 'B9B0D332A1AA5635'。
  • fingerprint <string> DER エンコードされた証明書の SHA-1 ダイジェスト。:区切りの 16 進文字列として返されます。例: '2A:7A:C2:DD:...'。
  • fingerprint256 <string> DER エンコードされた証明書の SHA-256 ダイジェスト。:区切りの 16 進文字列として返されます。例: '2A:7A:C2:DD:...'。
  • fingerprint512 <string> DER エンコードされた証明書の SHA-512 ダイジェスト。:区切りの 16 進文字列として返されます。例: '2A:7A:C2:DD:...'。
  • ext_key_usage <Array> （オプション）拡張キーの使用状況、OID のセット。
  • subjectaltname <string> （オプション）件名の連結された名前を含む文字列。subject名の代替。
  • infoAccess <Array> （オプション）OCSP で使用される AuthorityInfoAccess を記述する配列。
  • issuerCertificate <Object> （オプション）発行者の証明書オブジェクト。自己署名証明書の場合、これは循環参照になる可能性があります。

証明書には、キーの種類に応じて、公開鍵に関する情報が含まれる場合があります。

RSA キーの場合、次のプロパティが定義されている場合があります。

  • bits <number> RSA ビットサイズ。例: 1024。
  • exponent <string> 16 進数の文字列表記の RSA 指数。例: '0x010001'。
  • modulus <string> 16 進文字列としての RSA モジュラス。例: 'B56CE45CB7...'。
  • pubkey <Buffer> 公開鍵。

EC キーの場合、次のプロパティが定義されている場合があります。

  • pubkey <Buffer> 公開鍵。
  • bits <number> ビット単位のキーサイズ。例: 256。
  • asn1Curve <string> （オプション）楕円曲線の OID の ASN.1 名。よく知られた曲線は OID で識別されます。珍しいことですが、曲線がその数学的特性によって識別される可能性があり、その場合は OID を持たない場合があります。例: 'prime256v1'。
  • nistCurve <string> （オプション）楕円曲線の NIST 名（存在する場合）。よく知られたすべての曲線が NIST によって名前が割り当てられているわけではありません。例: 'P-256'。

証明書の例:

js
{ 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 ... > }

tlsSocket.getPeerFinished() ​

追加バージョン: v9.9.0

  • 戻り値: <Buffer> | <undefined> ソケットから SSL/TLS ハンドシェイクの一部として受信した、または受信を期待している最新のFinishedメッセージ。Finishedメッセージがない場合はundefined。

Finishedメッセージは、完全なハンドシェイクのメッセージダイジェスト（TLS 1.0 では合計 192 ビット、SSL 3.0 ではそれ以上）であるため、SSL/TLS によって提供される認証が不要であるか、不十分な場合、外部認証手順に使用できます。

OpenSSL のSSL_get_peer_finishedルーチンに対応し、RFC 5929からのtls-uniqueチャネルバインディングを実装するために使用できます。

tlsSocket.getPeerX509Certificate() ​

追加バージョン: v15.9.0

ピア証明書を <X509Certificate>オブジェクトとして返します。

ピア証明書がない場合、またはソケットが破棄されている場合、undefinedが返されます。

tlsSocket.getProtocol() ​

追加バージョン: v5.7.0

現在の接続のネゴシエートされた SSL/TLS プロトコルバージョンの文字列を返します。ハンドシェイクプロセスが完了していない接続済みソケットには'unknown'が返されます。サーバソケットまたは切断されたクライアントソケットにはnullが返されます。

プロトコルバージョンは次のとおりです。

  • 'SSLv3'
  • 'TLSv1'
  • 'TLSv1.1'
  • 'TLSv1.2'
  • 'TLSv1.3'

詳細については、OpenSSL のSSL_get_versionドキュメントを参照してください。

tlsSocket.getSession() ​

追加バージョン: v0.11.4

TLS セッションデータ、またはセッションがネゴシエートされなかった場合はundefinedを返します。クライアントでは、このデータをtls.connect()のsessionオプションに提供して、接続を再開できます。サーバーでは、デバッグに役立つ場合があります。

詳細については、セッション再開を参照してください。

注: getSession()は TLSv1.2 以下でのみ動作します。TLSv1.3 の場合は、アプリケーションで'session'イベントを使用する必要があります（TLSv1.2 以下でも動作します）。

tlsSocket.getSharedSigalgs() ​

追加日時: v12.11.0

  • 戻り値: <Array> サーバーとクライアント間で共有される署名アルゴリズムのリスト（優先度の高い順）。

詳細はSSL_get_shared_sigalgsを参照してください。

tlsSocket.getTLSTicket() ​

追加日時: v0.11.4

クライアントの場合、利用可能な TLS セッションチケットがあればそれを返し、なければundefinedを返します。サーバーの場合、常にundefinedを返します。

デバッグに役立つ場合があります。

詳細はセッション再開を参照してください。

tlsSocket.getX509Certificate() ​

追加日時: v15.9.0

ローカル証明書を <X509Certificate>オブジェクトとして返します。

ローカル証明書が存在しない場合、またはソケットが破棄されている場合、undefinedを返します。

tlsSocket.isSessionReused() ​

追加日時: v0.5.6

  • 戻り値: <boolean> セッションが再利用された場合はtrue、そうでない場合はfalseを返します。

詳細はセッション再開を参照してください。

tlsSocket.localAddress ​

追加日時: v0.11.4

ローカル IP アドレスの文字列表現を返します。

tlsSocket.localPort ​

追加日時: v0.11.4

ローカルポートの数値表現を返します。

tlsSocket.remoteAddress ​

追加日時: v0.11.4

リモート IP アドレスの文字列表現を返します。例：'74.125.127.100'または'2001:4860:a005::68'。

tlsSocket.remoteFamily ​

追加日時: v0.11.4

リモート IP ファミリの文字列表現を返します。'IPv4'または'IPv6'。

tlsSocket.remotePort ​

追加日時: v0.11.4

リモートポートの数値表現を返します。例えば、443。

tlsSocket.renegotiate(options, callback) ​

[履歴]

バージョン変更点
v18.0.0callback引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACKではなくERR_INVALID_ARG_TYPEがスローされるようになりました。
v0.11.8追加日時: v0.11.8

  • options <Object>

    • rejectUnauthorized <boolean> falseでない場合、サーバー証明書は提供された CA のリストに対して検証されます。検証に失敗すると'error'イベントが発行されます。err.codeには OpenSSL のエラーコードが含まれます。デフォルト: true。
    • requestCert

  • callback <Function> renegotiate()がtrueを返した場合、コールバックは'secure'イベントに一度だけアタッチされます。renegotiate()がfalseを返した場合、tlsSocketが破棄されていない限り、callbackは次のティックでエラーとともに呼び出されます。tlsSocketが破棄されている場合は、callbackはまったく呼び出されません。

  • 戻り値: <boolean> 再交渉が開始された場合はtrue、そうでない場合はfalse。

tlsSocket.renegotiate()メソッドは TLS 再交渉プロセスを開始します。完了すると、callback関数には、リクエストが失敗した場合はError、成功した場合はnullのいずれかの単一引数が渡されます。

このメソッドは、安全な接続が確立された後にピアの証明書を要求するために使用できます。

サーバーとして実行している場合、handshakeTimeoutタイムアウト後にソケットはエラーとともに破棄されます。

TLSv1.3 の場合、再交渉は開始できません。プロトコルでサポートされていません。

tlsSocket.setKeyCert(context) ​

追加日時: v22.5.0, v20.17.0

tlsSocket.setKeyCert() メソッドは、ソケットで使用する秘密鍵と証明書を設定します。これは、TLS サーバーの ALPNCallback からサーバー証明書を選択する場合に主に役立ちます。

tlsSocket.setMaxSendFragment(size) ​

追加日時: v0.11.11

  • size <number> 最大 TLS フラグメントサイズ。最大値は 16384 です。デフォルト: 16384。
  • 戻り値: <boolean>

tlsSocket.setMaxSendFragment() メソッドは、最大 TLS フラグメントサイズを設定します。制限の設定に成功した場合は true を、そうでない場合は false を返します。

フラグメントサイズを小さくすると、クライアントのバッファリングレイテンシが減少します。大きなフラグメントは、フラグメント全体が受信され、整合性が検証されるまで TLS レイヤーによってバッファリングされます。大きなフラグメントは複数のラウンドトリップにまたがり、パケット損失や並べ替えによって処理が遅れる可能性があります。ただし、フラグメントサイズを小さくすると、余分な TLS フレームワークバイトと CPU オーバーヘッドが増加し、サーバーのスループット全体が低下する可能性があります。

tls.checkServerIdentity(hostname, cert) ​

[履歴]

バージョン変更内容
v17.3.1, v16.13.2, v14.18.3, v12.22.9CVE-2021-44531 への対応としてuniformResourceIdentifierサブジェクト代替名はサポートされなくなりました。
v0.8.4追加日時: v0.8.4

証明書 cert が hostname に発行されていることを検証します。

失敗した場合は、reason、host、cert を設定した <Error> オブジェクトを返します。成功した場合は、<undefined> を返します。

この関数は、tls.connect() に渡すことができる checkServerIdentity オプションと組み合わせて使用することを目的としており、証明書オブジェクト で動作します。その他の目的には、代わりに x509.checkHost() を使用することを検討してください。

この関数は、tls.connect() に渡される options.checkServerIdentity オプションとして代替関数を提供することで上書きできます。上書き関数は、追加の検証で実行されるチェックを拡張するために、もちろん tls.checkServerIdentity() を呼び出すことができます。

この関数は、信頼できる CA によって発行されたことなど、証明書が他のすべてのチェックに合格した場合にのみ呼び出されます (options.ca)。

以前のバージョンの Node.js は、一致する uniformResourceIdentifier サブジェクト代替名が存在する場合、特定の hostname の証明書を誤って受け入れていました ( CVE-2021-44531 を参照)。uniformResourceIdentifier サブジェクト代替名を受け入れるアプリケーションは、目的の動作を実装するカスタム options.checkServerIdentity 関数を使用できます。

tls.connect(options[, callback]) ​

[履歴]

バージョン変更点
v15.1.0, v14.18.0onread オプションを追加
v14.1.0, v13.14.0highWaterMark オプションがサポートされました
v13.6.0, v12.16.0pskCallback オプションがサポートされました
v12.9.0allowHalfOpen オプションをサポート
v12.4.0hints オプションがサポートされました
v12.2.0enableTrace オプションがサポートされました
v11.8.0, v10.16.0timeout オプションがサポートされました
v8.0.0lookup オプションがサポートされました
v8.0.0ALPNProtocols オプションに TypedArray または DataView を使用できるようになりました
v5.0.0ALPN オプションがサポートされました
v5.3.0, v4.7.0secureContext オプションがサポートされました
v0.11.3追加: v0.11.3

  • 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（Server Name Indication）TLS 拡張子のサーバー名。接続先のホストの名前であり、IP アドレスではなくホスト名でなければなりません。マルチホームサーバーで、クライアントに提示する正しい証明書を選択するために使用できます。tls.createServer()のSNICallbackオプションを参照してください。
    • checkServerIdentity(servername, cert) <Function> サーバーのホスト名（または明示的に設定されたservername）と証明書を照合する際に（組み込みのtls.checkServerIdentity()関数の代わりに）使用されるコールバック関数。検証に失敗した場合は、<Error>を返す必要があります。servernameとcertが検証された場合は、undefinedを返す必要があります。
    • session <Buffer> TLS セッションを含むBufferインスタンス。
    • minDHSize <number> TLS 接続を受け入れる DH パラメーターの最小サイズ（ビット単位）。サーバーがminDHSizeよりも小さいサイズの DH パラメーターを提供した場合、TLS 接続は切断され、エラーがスローされます。デフォルト: 1024。
    • highWaterMark: <number> 読み取り可能ストリームのhighWaterMarkパラメーターと一貫性があります。デフォルト: 16 * 1024。
    • secureContext: tls.createSecureContext()で作成された TLS コンテキストオブジェクト。secureContextが提供されない場合、tls.createSecureContext()にoptionsオブジェクト全体を渡して作成されます。
    • 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（Server Name Indication）拡張子を有効にしません。これにより、一部のサーバーが正しくない証明書を返すか、接続を完全に拒否する可能性があります。SNI を有効にするには、hostに加えてservernameオプションを設定します。

以下は、tls.createServer()からのエコーサーバーの例に対するクライアントを示しています。

js
// ポート8000でリッスンしているエコーサーバーを想定しています。
import { connect } from 'node:tls'
import { readFileSync } from 'node:fs'
import { stdin } from 'node:process'

const options = {
  // サーバーがクライアント証明書認証を要求する場合にのみ必要です。
  key: readFileSync('client-key.pem'),
  cert: readFileSync('client-cert.pem'),

  // サーバーが自己署名証明書を使用する場合にのみ必要です。
  ca: [readFileSync('server-cert.pem')],

  // サーバーの証明書が "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')
})
js
// ポート8000でリッスンしているエコーサーバーを想定しています。
const { connect } = require('node:tls')
const { readFileSync } = require('node:fs')

const options = {
  // サーバーがクライアント証明書認証を要求する場合にのみ必要です。
  key: readFileSync('client-key.pem'),
  cert: readFileSync('client-cert.pem'),

  // サーバーが自己署名証明書を使用する場合にのみ必要です。
  ca: [readFileSync('server-cert.pem')],

  // サーバーの証明書が "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')
})

この例で証明書とキーを生成するには、以下を実行します。

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

次に、この例でserver-cert.pem証明書を生成するには、以下を実行します。

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

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

追加日: v0.11.3

pathをオプションではなく引数として提供できる点を除いて、tls.connect()と同じです。

パスオプションが指定されている場合は、パス引数よりも優先されます。

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

追加日: v0.11.3

portとhostをオプションではなく引数として提供できる点を除いて、tls.connect()と同じです。

ポートまたはホストオプションが指定されている場合は、ポートまたはホスト引数よりも優先されます。

tls.createSecureContext([options]) ​

[履歴]

バージョン変更点
v22.9.0, v20.18.0allowPartialTrustChainオプションが追加されました。
v22.4.0, v20.16.0clientCertEngine、privateKeyEngine、privateKeyIdentifierオプションは、OpenSSL 3 で非推奨となった OpenSSL のカスタムエンジンサポートに依存しています。
v19.8.0, v18.16.0dhparamオプションに適切な既知のパラメータで DHE を有効にする'auto'を設定できるようになりました。
v12.12.0OpenSSL エンジンから秘密鍵を取得するためのprivateKeyIdentifierとprivateKeyEngineオプションを追加しました。
v12.11.0サポートされる署名アルゴリズムをオーバーライドするためのsigalgsオプションを追加しました。
v12.0.0TLSv1.3 サポートを追加しました。
v11.5.0ca:オプションでBEGIN TRUSTED CERTIFICATEをサポートするようになりました。
v11.4.0, v10.16.0minVersionとmaxVersionを使用して、許可される TLS プロトコルバージョンを制限できるようになりました。
v10.0.0OpenSSL の変更により、ecdhCurveをfalseに設定できなくなりました。
v9.3.0optionsパラメータにclientCertEngineを含めることができるようになりました。
v9.0.0ecdhCurveオプションに、複数の':'で区切られたカーブ名または'auto'を設定できるようになりました。
v7.3.0keyオプションが配列の場合、個々のエントリにpassphraseプロパティが不要になりました。Arrayエントリには、stringまたはBufferのみを指定できるようになりました。
v5.2.0caオプションに、複数の CA 証明書を含む単一の文字列を指定できるようになりました。
v0.11.13追加日: v0.11.13
  • options <Object>
    • allowPartialTrustChain <boolean> 信頼できる CA 証明書リスト内の中間（自己署名ではない）証明書を信頼済みとして扱います。
    • ca <string> | <string[]> | <Buffer> | <Buffer[]> 信頼できる CA 証明書をオプションでオーバーライドします。デフォルトでは、Mozilla が管理する既知の CA を信頼します。CA がこのオプションを使用して明示的に指定されると、Mozilla の CA は完全に置き換えられます。値は、文字列またはBuffer、あるいは文字列とBufferのArrayです。文字列またはBufferには、複数の PEM CA を連結して含めることができます。接続を認証するには、ピアの証明書をサーバーによって信頼される CA にチェーンできる必要があります。既知の CA にチェーンできない証明書を使用する場合は、証明書の CA を明示的に信頼済みとして指定する必要があります。そうでないと、接続の認証に失敗します。ピアがデフォルトの CA のいずれにも一致しないか、チェーンしない証明書を使用する場合は、caオプションを使用して、ピアの証明書が一致するか、チェーンできる CA 証明書を提供します。自己署名証明書の場合、証明書自体が CA であり、提供する必要があります。PEM でエンコードされた証明書の場合、サポートされるタイプは "TRUSTED CERTIFICATE"、"X509 CERTIFICATE"、および "CERTIFICATE" です。tls.rootCertificatesも参照してください。
    • cert <string> | <string[]> | <Buffer> | <Buffer[]> PEM 形式の証明書チェーン。秘密鍵ごとに 1 つの証明書チェーンを提供する必要があります。各証明書チェーンは、提供された秘密keyの PEM 形式の証明書、それに続く PEM 形式の中間証明書（存在する場合）、順序どおりに、ルート CA を含めずに構成する必要があります（ルート CA はピアに事前に知られている必要があります。caを参照）。複数の証明書チェーンを提供する場合、それらの秘密鍵のkey内での順序は同じである必要はありません。中間証明書が提供されない場合、ピアは証明書を検証できず、ハンドシェイクは失敗します。
    • sigalgs <string> サポートされる署名アルゴリズムの、コロンで区切られたリスト。このリストには、ダイジェストアルゴリズム（SHA256、MD5など）、公開鍵アルゴリズム（RSA-PSS、ECDSAなど）、両方の組み合わせ（例：'RSA+SHA384'）、または TLS v1.3 スキーム名（例：rsa_pss_pss_sha512）を含めることができます。詳細については、OpenSSL マニュアルページを参照してください。
    • ciphers <string> デフォルトを置き換える暗号スイートの仕様。詳細については、デフォルトの TLS 暗号スイートの変更を参照してください。許可される暗号は、tls.getCiphers()を使用して取得できます。OpenSSL が受け入れるには、暗号名は大文字にする必要があります。
    • clientCertEngine <string> クライアント証明書を提供できる OpenSSL エンジンの名前。非推奨。
    • crl <string> | <string[]> | <Buffer> | <Buffer[]> PEM 形式の CRL（証明書失効リスト）。
    • dhparam <string> | <Buffer> 非 ECDHE の完全順方向秘匿性に必要な'auto'またはカスタム Diffie-Hellman パラメータ。省略または無効な場合、パラメータはサイレントに破棄され、DHE 暗号は使用できなくなります。ECDHEベースの完全順方向秘匿性は引き続き使用できます。
    • ecdhCurve <string> ECDH 鍵合意に使用する、名前付きカーブまたはコロンで区切られたカーブ NID または名のリストを記述する文字列（例：P-521:P-384:P-256）。カーブを自動的に選択するには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オブジェクトを作成します。これは、server.addContext()など、いくつかのtlsAPI の引数として使用できますが、公開メソッドはありません。tls.Serverコンストラクタとtls.createServer()メソッドは、secureContextオプションをサポートしていません。

暗号で証明書を使用する場合は、鍵が必須です。keyまたはpfxを使用して提供できます。

caオプションが指定されていない場合、Node.js はデフォルトでMozilla の公開的に信頼されている CA リストを使用します。

新しいdhparam: 'auto'オプションを優先して、カスタム DHE パラメータは推奨されません。'auto'に設定すると、十分な強度を持つ既知の DHE パラメータが自動的に選択されます。それ以外の場合は、必要に応じてopenssl dhparamを使用してカスタムパラメータを作成できます。キーの長さは 1024 ビット以上である必要があります。そうでない場合、エラーがスローされます。1024 ビットは許可されていますが、より強力なセキュリティのために 2048 ビット以上を使用してください。

tls.createSecurePair([context][, isServer][, requestCert][, rejectUnauthorized][, options]) ​

[履歴]

バージョン変更点
v5.0.0ALPN オプションがサポートされました。
v0.11.3非推奨化: v0.11.3
v0.3.2追加: v0.3.2

[安定度: 0 - 非推奨]

安定度: 0 安定性: 0 - 非推奨: tls.TLSSocket を代わりに使用してください。

  • context <Object> tls.createSecureContext()によって返されるセキュアコンテキストオブジェクト
  • isServer <boolean> サーバーとして TLS 接続を開く場合true。
  • requestCert <boolean> サーバーが接続クライアントから証明書を要求するかどうかを指定する場合true。isServerがtrueの場合にのみ適用されます。
  • rejectUnauthorized <boolean> falseでない場合、サーバーは自動的に無効な証明書を持つクライアントを拒否します。isServerがtrueの場合にのみ適用されます。
  • options

暗号化されたデータを読み書きするストリームと、クリアテキストデータを読み書きするストリームの 2 つのストリームを持つ新しいセキュアペアオブジェクトを作成します。一般的に、暗号化されたストリームは着信暗号化データストリームとの間でパイプされ、クリアテキストストリームは元の暗号化ストリームの代替として使用されます。

tls.createSecurePair()は、cleartextとencryptedストリームプロパティを持つtls.SecurePairオブジェクトを返します。

cleartextの使用は、tls.TLSSocketと同じ API です。

tls.createSecurePair()メソッドは、tls.TLSSocket()に代わり非推奨となりました。例えば、以下のコード：

js
pair = tls.createSecurePair(/* ... */)
pair.encrypted.pipe(socket)
socket.pipe(pair.encrypted)

は以下のように置き換えられます：

js
secureSocket = tls.TLSSocket(socket, options)

ここでsecureSocketはpair.cleartextと同じ API を持ちます。

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

[履歴]

バージョン変更
v22.4.0, v20.16.0clientCertEngine オプションは、OpenSSL 3 で非推奨となった OpenSSL のカスタムエンジンサポートに依存しています。
v19.0.0ALPNProtocols が設定されている場合、サポートされているプロトコルがない ALPN 拡張機能を送信する着信接続は、致命的な no_application_protocol アラートで終了します。
v20.4.0, v18.19.0options パラメータに ALPNCallback を含めることができるようになりました。
v12.3.0options パラメータで net.createServer() オプションをサポートするようになりました。
v9.3.0options パラメータに clientCertEngine を含めることができるようになりました。
v8.0.0ALPNProtocols オプションに TypedArray または DataView を使用できるようになりました。
v5.0.0ALPN オプションがサポートされるようになりました。
v0.3.2追加: v0.3.2

  • 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フィールドを含むオブジェクトが 1 つ渡されます。それぞれ、SNI 拡張機能からのサーバー名（存在する場合）と ALPN プロトコル名文字列の配列が含まれています。コールバックは、クライアントに選択された ALPN プロトコルとして返されるprotocolsにリストされている文字列のいずれか、または接続を致命的なアラートで拒否するための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の 2 つの引数が渡されます。callbackは、2 つのオプションの引数（errorとctx）を取るエラーファーストコールバックです。ctxは提供されている場合、SecureContextインスタンスです。tls.createSecureContext()を使用して適切なSecureContextを取得できます。callbackが偽のctx引数で呼び出された場合、サーバーのデフォルトのセキュアコンテキストが使用されます。SNICallbackが提供されていない場合、高レベル API を使用したデフォルトのコールバックが使用されます（下記参照）。
    • ticketKeys: <Buffer> 暗号化的に強力な擬似乱数の 48 バイト。詳細については、セッション再開を参照してください。
    • pskCallback: <Function> TLS-PSK ネゴシエーションについては、事前共有キーを参照してください。
    • pskIdentityHint: <string> TLS-PSK ネゴシエーション中に ID の選択を支援するためにクライアントに送信するオプションのヒント。TLS 1.3 では無視されます。pskIdentityHintの設定に失敗すると、'ERR_TLS_PSK_SET_IDENTITY_HINT_FAILED'コードで'tlsClientError'が発行されます。
    • ...: 任意のtls.createSecureContext()オプションを提供できます。サーバーの場合、通常は ID オプション（pfx、key/cert、またはpskCallback）が必要です。
    • ...: 任意のnet.createServer()オプションを提供できます。

  • secureConnectionListener <Function>

  • 戻り値: <tls.Server>

新しいtls.Serverを作成します。secureConnectionListenerが提供されている場合、'secureConnection'イベントのリスナーとして自動的に設定されます。

ticketKeysオプションは、node:clusterモジュールのワーカー間で自動的に共有されます。

簡単なエコーサーバーの例を以下に示します。

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

この例で証明書とキーを生成するには、次のように実行します。

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

次に、この例のclient-cert.pem証明書を生成するには、次のように実行します。

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

サーバーは、tls.connect()の例のクライアントを使用して接続することでテストできます。

tls.getCiphers() ​

追加日時: v0.10.2

サポートされている TLS 暗号の名前の配列を返します。名前は歴史的な理由から小文字ですが、tls.createSecureContext()のciphersオプションで使用するには大文字にする必要があります。

サポートされているすべての暗号がデフォルトで有効になっているわけではありません。デフォルトの TLS 暗号スイートの変更を参照してください。

'tls_'で始まる暗号名は TLSv1.3 用であり、それ以外は TLSv1.2 以下用です。

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

tls.rootCertificates ​

追加日時: v12.3.0

現在の Node.js バージョンによって提供されるバンドルされた Mozilla CA ストアからのルート証明書（PEM 形式）を表す文字列の不変の配列です。

Node.js によって提供されるバンドルされた CA ストアは、リリース時に固定された Mozilla CA ストアのスナップショットです。すべてのサポートされているプラットフォームで同一です。

tls.DEFAULT_ECDH_CURVE ​

[履歴]

バージョン変更
v10.0.0デフォルト値が'auto'に変更されました。
v0.11.13追加日時: v0.11.13

tls サーバーでの ECDH キー合意に使用するデフォルトの曲線名です。デフォルト値は'auto'です。詳細はtls.createSecureContext()を参照してください。

tls.DEFAULT_MAX_VERSION ​

追加日時: v11.4.0

  • <string> tls.createSecureContext()のmaxVersionオプションのデフォルト値です。サポートされている TLS プロトコルバージョン'TLSv1.3', 'TLSv1.2', 'TLSv1.1', または'TLSv1'のいずれかを割り当てることができます。デフォルト: CLI オプションを使用して変更されない限り'TLSv1.3'です。--tls-max-v1.2を使用するとデフォルトが'TLSv1.2'に設定されます。--tls-max-v1.3を使用するとデフォルトが'TLSv1.3'に設定されます。複数のオプションが指定されている場合、最も高い最大値が使用されます。

tls.DEFAULT_MIN_VERSION ​

追加日時: v11.4.0

  • <string> tls.createSecureContext() の minVersion オプションのデフォルト値です。サポートされている TLS プロトコルバージョン'TLSv1.3'、'TLSv1.2'、'TLSv1.1'、または'TLSv1'のいずれかを割り当てることができます。TLSv1.2 より前のバージョンでは、OpenSSL セキュリティレベル のダウングレードが必要になる場合があります。デフォルト: CLI オプションで変更しない限り'TLSv1.2'です。--tls-min-v1.0を使用するとデフォルトが'TLSv1'に設定されます。--tls-min-v1.1を使用するとデフォルトが'TLSv1.1'に設定されます。--tls-min-v1.3を使用するとデフォルトが'TLSv1.3'に設定されます。複数のオプションが指定されている場合、最小の最小値が使用されます。

tls.DEFAULT_CIPHERS ​

追加日時: v19.8.0, v18.16.0

  • <string> tls.createSecureContext() の ciphers オプションのデフォルト値です。サポートされている OpenSSL 暗号のいずれかを割り当てることができます。--tls-default-ciphers を使用した CLI オプションで変更しない限り、crypto.constants.defaultCoreCipherList の内容をデフォルトとします。