Node.js v21.7.2 ドキュメント

暗号化サポートが利用できないかの判定#

Node.js は、node:crypto モジュールのサポートを含めずにビルドされる可能性があります。このような場合、tls からインポートしようとすると、または 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）証明書を1つのファイルに連結したものです。例：cat ca1-cert.pem ca2-cert.pem > ca-cert.pem

完全順方向秘匿性#

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

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

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

• ECDHE：楕円曲線ディフィー・ヘルマン鍵合意プロトコルの一時的なバージョン。
• DHE：ディフィー・ヘルマン鍵合意プロトコルの一時的なバージョン。

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

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

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

ALPN と SNI#

ALPN（アプリケーションレイヤープロトコルネゴシエーション拡張）と SNI（サーバー名表示）は、TLS ハンドシェイク拡張です。

• ALPN：複数のプロトコル（HTTP、HTTP/2）で 1 つの TLS サーバーを使用できます。
• 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 で取得できます。

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

基盤となるOpenSSL APIの制限により、現在の実装では非同期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()を呼び出してチケットキーを取得し、それを配布することはできますが、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オプションを使用します。

openssl s_client -connect localhost:443 -reconnect copy

デバッグ出力を読み取ります。最初の接続には「New」と表示されます。

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

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

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の作成時にも使用できます。

暗号リストには、'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でサポートされていますが、セキュリティが低いため、デフォルトでは有効になっていません。

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

クラス: tls.CryptoStream#

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

cryptoStream.bytesWritten#

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

クラス: tls.SecurePair#

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

イベント: 'secure'#

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

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

クラス: tls.Server#

• 拡張: <net.Server>

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

イベント: 'connection'#

• socket <stream.Duplex>

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

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

イベント: 'keylog'#

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

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

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

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

イベント: 'newSession'#

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

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

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

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

イベント: 'OCSPRequest'#

クライアントが証明書ステータス要求を送信すると、'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 要求の典型的な流れは次のとおりです。

1. クライアントがサーバーに接続し、'OCSPRequest' を送信します（ClientHello のステータス情報拡張機能を介して）。
2. サーバーが要求を受信し、'OCSPRequest' イベントを発行して、登録されている場合にリスナーを呼び出します。
3. サーバーは、certificate または issuer のいずれかから OCSP URL を抽出し、CA に OCSP 要求 を実行します。
4. サーバーは CA から 'OCSPResponse' を受信し、callback 引数を介してクライアントに送り返します。
5. クライアントは応答を検証し、ソケットを破棄するか、ハンドシェイクを実行します。

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

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

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

イベント: 'resumeSession'#

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

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

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

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

TLS セッションの再開方法を以下に示します。

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

イベント: 'secureConnection'#

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

• tlsSocket <tls.TLSSocket> 確立された TLS ソケット。

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

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

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

イベント: 'tlsClientError'#

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

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

server.addContext(hostname, context)#

• hostname <string> SNI ホスト名またはワイルドカード（例：'*'）
• context <Object> | <tls.SecureContext> tls.createSecureContext() の options 引数から可能なプロパティ（例：key、cert、ca など）を含むオブジェクト、または tls.createSecureContext() 自体で作成された TLS コンテキストオブジェクト。

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

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

server.address()#

• 戻り値: <Object>

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

server.close([callback])#

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

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

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

server.getTicketKeys()#

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

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

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

server.listen()#

暗号化された接続をリッスンするサーバーを開始します。このメソッドは、net.Server の server.listen() と同じです。

server.setSecureContext(options)#

• options <Object> tls.createSecureContext() の `options` 引数から可能なプロパティ（例：`key`、`cert`、`ca`など）を含むオブジェクト。

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

server.setTicketKeys(keys)#

• keys <Buffer> | <TypedArray> | <DataView> セッションチケットキーを含む48バイトのバッファー。

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

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

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

クラス: tls.TLSSocket#

• 拡張: <net.Socket>

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

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

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

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

• 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が提供されない場合、optionsオブジェクト全体をtls.createSecureContext()に渡して作成されます。
  • …: secureContext オプションがない場合に使用される tls.createSecureContext() オプション。それ以外の場合は無視されます。

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

イベント: 'keylog'#

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

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

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

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

イベント: 'OCSPResponse'#

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

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

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

イベント: 'secureConnect'#

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

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

イベント: 'session'#

• session <Buffer>

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

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

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

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

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

tlsSocket.address()#

• 戻り値: <Object>

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

tlsSocket.authorizationError#

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

tlsSocket.authorized#

• <boolean>

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

tlsSocket.disableRenegotiation()#

このTLSSocketインスタンスのTLS再ネゴシエーションを無効にします。呼び出されると、再ネゴシエートしようとすると、TLSSocketで'error'イベントが発生します。

tlsSocket.enableTrace()#

有効にすると、TLSパケットトレース情報はstderrに書き込まれます。これは、TLS接続の問題をデバッグするために使用できます。

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

tlsSocket.encrypted#

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

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

• length <number> キーイングマテリアルから取得するバイト数

• label <string> アプリケーション固有のラベル。通常、IANAエクスポーターラベルレジストリの値を使用します。

• context <Buffer> （オプション）コンテキストを指定します。

• 戻り値: <Buffer> 要求されたバイト数のキーイングマテリアル

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

例

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

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

tlsSocket.getCertificate()#

• 戻り値: <Object>

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

tls.TLSSocket.getPeerCertificate()に、証明書の構造の例を示します。

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

tlsSocket.getCipher()#

• 戻り値: <Object>
  • name <string> 暗号スイートのOpenSSL名。
  • standardName <string> 暗号スイートのIETF名。
  • version <string> この暗号スイートでサポートされている最小TLSプロトコルバージョン。実際にネゴシエートされたプロトコルについては、tls.TLSSocket.getProtocol()を参照してください。

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

例：AES256-SHA暗号を使用したTLSv1.2プロトコル

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

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

tlsSocket.getEphemeralKeyInfo()#

• 戻り値: <Object>

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

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

tlsSocket.getFinished()#

• 戻り値: <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])#

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

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

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

証明書オブジェクト#

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

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

証明書の例

{ 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

tlsSocket.getPeerFinished()#

• 戻り値: <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()#

• 戻り値: <X509Certificate>

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

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

tlsSocket.getProtocol()#

• 戻り値: <string> | <null>

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

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

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

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

tlsSocket.getSession()#

• <Buffer>

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

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

注：getSession()はTLSv1.2以前でのみ機能します。TLSv1.3については、アプリケーションは'session'イベントを使用する必要があります（TLSv1.2以前でも機能します）。

tlsSocket.getSharedSigalgs()#

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

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

tlsSocket.getTLSTicket()#

• <Buffer>

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

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

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

tlsSocket.getX509Certificate()#

• 戻り値: <X509Certificate>

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

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

tlsSocket.isSessionReused()#

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

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

tlsSocket.localAddress#

• <string>

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

tlsSocket.localPort#

• <integer>

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

tlsSocket.remoteAddress#

• <string>

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

tlsSocket.remoteFamily#

• <string>

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

tlsSocket.remotePort#

• <integer>

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

tlsSocket.renegotiate(options, callback)#

• options <Object>

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

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

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

tlsSocket.renegotiate()メソッドはTLS再交渉プロセスを開始します。完了すると、コールバック関数には、エラー（要求が失敗した場合）またはnullのいずれかの単一の引数が渡されます。

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

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

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

tlsSocket.setMaxSendFragment(size)#

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

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

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

tls.checkServerIdentity(hostname, cert)#

• hostname <string> 証明書を検証するホスト名またはIPアドレス。
• cert <Object> ピアの証明書を表す証明書オブジェクト。
• 戻り値: <Error> | <undefined>

証明書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])#

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

    • hint: <string> サーバーから送信され、ネゴシエーション中に使用するIDをクライアントが決定するのに役立つオプションのメッセージ。TLS 1.3を使用する場合は常にnullです。
    • 戻り値: <Object> { psk: <Buffer|TypedArray|DataView>, identity: <string> } 形式のオブジェクト、またはネゴシエーションプロセスを停止するためのnull。pskは、選択された暗号のダイジェストと互換性がある必要があります。identityはUTF-8エンコーディングを使用する必要があります。

    TLS-PSK（事前共有キー）のネゴシエーション時に、この関数は、サーバーから提供されるオプションのidentity hint（hintが削除されたTLS 1.3の場合はnull）を使用して呼び出されます。デフォルトの関数はサーバーのホスト名/IPアドレスを証明書と照合しようとしますが、PSKでは証明書が存在しないため適用されません。そのため、接続にはカスタムtls.checkServerIdentity()を提供する必要があります。RFC 4279に詳細情報があります。

  • 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が提供されない場合、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（Server Name Indication）拡張を有効にしません。これにより、一部のサーバーが誤った証明書を返すか、接続を完全に拒否する可能性があります。SNIを有効にするには、hostに加えてservernameオプションを設定します。

tls.createServer()のechoサーバーの例に対するクライアントを示します。

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

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

• path <string> options.pathのデフォルト値。
• options <Object> tls.connect()を参照。
• callback <Function> tls.connect()を参照。
• 戻り値: <tls.TLSSocket>

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

指定されている場合、pathオプションは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を提供できます。

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

tls.createSecureContext([options])#

• options <Object>
  • ca <string> | <string[]> | <Buffer> | <Buffer[]> 信頼できるCA証明書をオプションでオーバーライドします。デフォルトでは、Mozillaが管理する既知のCAを信頼します。CAがこのオプションを使用して明示的に指定されると、MozillaのCAは完全に置き換えられます。値は、文字列またはBuffer、または文字列とBufferの配列です。文字列または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形式の証明書、それに続く中間証明書（存在する場合）、順序どおりに、ルート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未満に設定することは避けてください。ただし、相互運用性のために必要になる場合があります。デフォルト：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プロトコルバージョンを許可します。TLSバージョン1.2未満を使用することは推奨されませんが、相互運用性のために必要になる場合があります。デフォルト：なし、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])#

• context <Object> tls.createSecureContext()によって返されるセキュアコンテキストオブジェクト。
• isServer <boolean> このTLS接続をサーバーとして開く必要がある場合はtrue。
• requestCert <boolean> サーバーが接続クライアントから証明書を要求する必要があるかどうかを指定する場合はtrue。isServerがtrueの場合にのみ適用されます。
• rejectUnauthorized <boolean> falseでない場合、サーバーは無効な証明書を持つクライアントを自動的に拒否します。isServerがtrueの場合にのみ適用されます。
• options
  • enableTrace: tls.createServer() を参照してください。
  • secureContext: tls.createSecureContext()からのTLSコンテキストオブジェクト。
  • isServer: trueの場合、TLSソケットはサーバーモードでインスタンス化されます。デフォルト：false。
  • server <net.Server> net.Serverインスタンス。
  • requestCert: tls.createServer()を参照してください。
  • rejectUnauthorized: tls.createServer() を参照してください。
  • ALPNProtocols: tls.createServer() を参照してください。
  • SNICallback: tls.createServer() を参照してください。
  • session <Buffer> TLSセッションを含むBuffer インスタンス。
  • requestOCSP <boolean> trueの場合、OCSPステータス要求拡張がクライアントhelloに追加され、セキュアな通信を確立する前にソケットで'OCSPResponse'イベントが発生することを指定します。

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

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

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

tls.createSecurePair()メソッドは、現在tls.TLSSocket()に置き換えられています。たとえば、次のコード

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

は、次のように置き換えることができます。

secureSocket = tls.TLSSocket(socket, options); copy

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

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拡張機能を使用して接続を開くと、これが呼び出されます。コールバックには、それぞれSNI拡張機能からのサーバー名（存在する場合）とALPNプロトコル名文字列の配列を含むservernameフィールドとprotocolsフィールドを持つオブジェクトが1つ渡されます。コールバックは、クライアントに選択された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>

    • socket: <tls.TLSSocket> この接続のサーバーtls.TLSSocketインスタンス。
    • identity: <string> クライアントから送信されたidentityパラメーター。
    • 戻り値: <Buffer> | <TypedArray> | <DataView> バッファーまたはネゴシエーションプロセスを停止するnullのいずれかでなければならない事前共有キー。返されたPSKは、選択された暗号のダイジェストと互換性がある必要があります。

    TLS-PSK（事前共有キー）をネゴシエートする場合、この関数はクライアントによって提供されたidentityを使用して呼び出されます。戻り値がnullの場合、ネゴシエーションプロセスは停止し、「unknown_psk_identity」アラートメッセージが相手側に送信されます。サーバーがPSKアイデンティティが不明であったという事実を隠したい場合、コールバックはネゴシエーションが完了する前に「decrypt_error」で接続が失敗するように、pskとしてランダムなデータを提供する必要があります。PSK暗号はデフォルトで無効になっており、TLS-PSKを使用するには、ciphersオプションで暗号スイートを明示的に指定する必要があります。詳細については、RFC 4279を参照してください。

  • pskIdentityHint <string> TLS-PSKネゴシエーション中にアイデンティティの選択を支援するためにクライアントに送信するオプションのヒント。TLS 1.3では無視されます。pskIdentityHintの設定に失敗すると、コード'ERR_TLS_PSK_SET_IDENTIY_HINT_FAILED'で'tlsClientError'が発行されます。

  • …：任意のtls.createSecureContext()オプションを指定できます。サーバーの場合、アイデンティティオプション（pfx、key/cert、またはpskCallback）は通常必要です。

  • …：任意のnet.createServer()オプションを指定できます。

• secureConnectionListener <Function>
• 戻り値: <tls.Server>

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

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

以下は、単純なエコーサーバーを示しています。

const tls = require('node:tls');
const fs = require('node:fs');

const options = {
  key: fs.readFileSync('server-key.pem'),
  cert: fs.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: [ fs.readFileSync('client-cert.pem') ],
};

const server = tls.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

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

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ストアのスナップショットです。サポートされているすべてのプラットフォームで同一です。

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'を割り当てることができます。デフォルト：CLIオプションを使用して変更されていない限り、'TLSv1.3'です。--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'を割り当てることができます。デフォルト：CLIオプションを使用して変更されていない限り、'TLSv1.2'です。--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暗号のいずれかを割り当てることができます。--tls-default-ciphersを使用してCLIオプションで変更されていない限り、crypto.constants.defaultCoreCipherListの内容をデフォルトとします。