Node.js tls.createSecurePair の解説と代替方法【非推奨APIからの移行】

2025-06-01

tls.createSecurePair() は、Node.js の tls (Transport Layer Security) モジュールで、非推奨となった機能です。TLS や SSL (Secure Sockets Layer) を用いた安全な通信のためのソケットペア（読み取り可能ストリームと書き込み可能ストリームのペア）を作成するためにかつて使われていました。

より具体的に説明すると、この関数は以下の役割を持っていました。

安全なストリームの作成
TLS/SSL プロトコルに基づいて暗号化された通信を行うためのストリームを内部的に生成していました。
ソケットペアの提供
作成された安全なストリームを、読み取り専用のストリーム (pair.encrypted) と書き込み専用のストリーム (pair.cleartext) のペアとして提供していました。
データの仲介
pair.encrypted に書き込まれたデータは暗号化され、内部の安全なストリームを経由して pair.cleartext から読み取れるように、またその逆も行っていました。これにより、アプリケーションは pair.cleartext を通常のストリームのように扱いつつ、裏側では暗号化された安全な通信を実現できました。

しかし、現在では tls.createSecurePair() は非推奨となり、より柔軟で強力な tls.connect() や tls.createServer() などの関数を使うことが推奨されています。これらの新しい API は、より細かな TLS/SSL の設定や制御が可能であり、現代的なセキュリティ要件にも対応しています。

非推奨の理由の主なものとしては

セキュリティ上の懸念
過去のバージョンにおいて、いくつかのセキュリティ上の問題が指摘されたこともあります。
柔軟性の欠如
より複雑な TLS/SSL のシナリオに対応するのが難しかったため、より柔軟な API が求められました。
API の複雑さ
createSecurePair() は、安全な通信のセットアップを抽象化しすぎており、細かい設定が難しかった点があります。

現在では、安全な TLS/SSL 通信を確立するためには、一般的に以下のいずれかの方法が用いられます。

サーバー側
tls.createServer() 関数を使用し、安全な接続を受け付けるサーバーを起動します。
クライアント側
tls.connect() 関数を使用し、サーバーへの安全な接続を確立します。

これらの新しい API を使用することで、証明書の管理、暗号スイートの選択、クライアント認証など、より詳細な設定を行うことができ、より安全で信頼性の高いアプリケーションを開発できます。

もし、古いコードなどで tls.createSecurePair() を見かけた場合は、可能であれば tls.connect() や tls.createServer() への移行を検討することをお勧めします。

それでも、もし古いコードを扱う際に tls.createSecurePair() に関連する問題に遭遇した場合、以下のようなものが考えられます。

一般的なエラーとトラブルシューティング

- 原因
  使用している Node.js のバージョンが比較的新しく、tls.createSecurePair() が既に削除されている場合に発生します。
- トラブルシューティング
  コードを tls.connect() (クライアント側) または tls.createServer() (サーバー側) を使用するように書き換える必要があります。これらの新しい API はより現代的で柔軟性があります。
Error: Encrypted and cleartext streams must have corresponding 'end' methods. エラー
- 原因
  内部的に作成された暗号化ストリーム (pair.encrypted) と平文ストリーム (pair.cleartext) が正しく連携していない場合に発生することがあります。これは、Node.js の古いバージョンにおける内部的な問題である可能性がありました。
- トラブルシューティング
  Node.js のバージョンを比較的新しい安定版にアップデートすることを試してください。また、可能であれば tls.connect() や tls.createServer() への移行を検討してください。
データの不整合や通信の失敗
- 原因
  pair.encrypted に書き込んだデータが pair.cleartext で正しく読み取れない、またはその逆のケースです。これは、内部のストリーム処理における問題や、誤ったデータの書き込み・読み取り処理が原因である可能性があります。
- トラブルシューティング
  - データの書き込みと読み取りの処理が正しく行われているか確認してください。バッファリングの問題やエンコーディングの問題がないかを確認します。
  - Node.js のバージョンをアップデートしてみることも有効かもしれません。
  - 根本的な解決策としては、より安定した tls.connect() や tls.createServer() を使用するようにコードを再設計することを強く推奨します。
パフォーマンスの問題
- 原因
  tls.createSecurePair() の内部処理が、新しい API と比較して非効率である可能性があります。特に高負荷な状況下では、パフォーマンスのボトルネックになることがあります。
- トラブルシューティング
  tls.connect() や tls.createServer() に移行することで、パフォーマンスが改善される可能性があります。これらの新しい API は、より効率的な TLS/SSL ハンドシェイクとデータ処理を行うように設計されています。
セキュリティ上の懸念
- 原因
  tls.createSecurePair() が非推奨になった理由の一つに、過去のバージョンにおけるセキュリティ上の潜在的な問題が挙げられます。
- トラブルシューティング
  古いバージョンの Node.js を使用している場合は、セキュリティの観点からも最新の安定版にアップデートし、tls.connect() や tls.createServer() を使用するように移行することが非常に重要です。

現在の Node.js の tls モジュールは、イベントベースのストリーム API とより密接に統合されており、より洗練された方法で安全な通信を扱えるようになっています。
tls.createSecurePair() は、カスタムの TLS/SSL ソケットペアを比較的簡単に作成できるという利点がありましたが、その抽象化の度合いが、より複雑な要件に対応する際の柔軟性を欠く原因となっていました。

もし、具体的なエラーメッセージやコードの状況を共有していただければ、より的確なトラブルシューティングのアドバイスができるかもしれません。しかし、基本的には tls.createSecurePair() の使用は避け、新しい API への移行を検討することを強くお勧めします。

この例では、クライアントから送信されたデータをそのままクライアントに返す簡単なエコーサーバーを tls.createSecurePair() を使って実装しています。

const tls = require('tls');
const net = require('net');

const server = net.createServer((socket) => {
  const securePair = tls.createSecurePair();

  // 暗号化されたソケットと平文ソケットをパイプで接続
  socket.pipe(securePair.encrypted);
  securePair.cleartext.pipe(socket);

  // 平文ソケットからデータを受信
  securePair.cleartext.on('data', (data) => {
    console.log('サーバー受信:', data.toString());
    securePair.cleartext.write(`エコー: ${data.toString()}`);
  });

  securePair.on('secure', () => {
    console.log('安全な接続が確立されました。');
  });

  securePair.on('error', (err) => {
    console.error('TLS エラー:', err);
  });
});

const port = 8000;
server.listen(port, () => {
  console.log(`非推奨の TLS エコーサーバーがポート ${port} で起動しました。`);
});

// クライアント側のコード (tls.connect() を推奨)
const client = net.connect(port, () => {
  const securePair = tls.createSecurePair();
  client.pipe(securePair.encrypted);
  securePair.cleartext.pipe(client);

  securePair.cleartext.write('こんにちは、サーバー！');

  securePair.cleartext.on('data', (data) => {
    console.log('クライアント受信:', data.toString());
    client.end();
  });

  securePair.on('secure', () => {
    console.log('クライアント: 安全な接続が確立されました。');
  });

  securePair.on('error', (err) => {
    console.error('クライアント TLS エラー:', err);
  });
});

このコードの解説 (非推奨)

クライアント側も同様に tls.createSecurePair() を使用して安全なペアを作成し、サーバーとの通信を行います。
securePair.on('secure', ...) は、TLS/SSL ハンドシェイクが成功し、安全な接続が確立されたときに発生するイベントです。
securePair.cleartext.on('data', ...) で平文データを受信し、処理を行います。
socket.pipe(securePair.encrypted) と securePair.cleartext.pipe(socket) によって、TCP ソケットと安全なペアの暗号化された部分と平文部分がそれぞれ繋がれます。これにより、securePair.cleartext を通して読み書きするデータは自動的に暗号化・復号化されます。
サーバー側では net.createServer() で通常の TCP サーバーを作成し、接続ごとに tls.createSecurePair() で安全なペアを作成します。

この例では、サーバーが自身の証明書を使用して安全な接続を確立します。

const tls = require('tls');
const fs = require('fs');
const net = require('net');

const options = {
  key: fs.readFileSync('server-key.pem'), // 秘密鍵
  cert: fs.readFileSync('server-cert.pem'), // 証明書
};

const server = net.createServer((socket) => {
  const securePair = tls.createSecurePair(options);

  socket.pipe(securePair.encrypted);
  securePair.cleartext.pipe(socket);

  securePair.cleartext.on('data', (data) => {
    console.log('サーバー受信:', data.toString());
    securePair.cleartext.write(`応答: ${data.toString()}`);
  });

  securePair.on('secure', () => {
    console.log('安全な接続 (証明書あり) が確立されました。');
  });

  securePair.on('error', (err) => {
    console.error('TLS エラー:', err);
  });
});

const port = 8001;
server.listen(port, () => {
  console.log(`非推奨の TLS サーバー (証明書あり) がポート ${port} で起動しました。`);
});

// クライアント側のコード (tls.connect() を推奨)
const client = net.connect(port, () => {
  const securePair = tls.createSecurePair();
  client.pipe(securePair.encrypted);
  securePair.cleartext.pipe(client);

  securePair.cleartext.write('証明書ありサーバーに接続しました。');

  securePair.cleartext.on('data', (data) => {
    console.log('クライアント受信:', data.toString());
    client.end();
  });

  securePair.on('secure', () => {
    console.log('クライアント: 安全な接続 (証明書あり) が確立されました。');
  });

  securePair.on('error', (err) => {
    console.error('クライアント TLS エラー:', err);
  });
});

このコードの解説 (非推奨)

クライアント側は、特に証明書に関する設定なしに接続を試みます。実際には、信頼された認証局によって署名された証明書でない場合、クライアント側で検証エラーが発生する可能性があります。
サーバー側の tls.createSecurePair() のオプションとして、秘密鍵 (key) と証明書 (cert) を指定しています。これにより、サーバーは TLS/SSL ハンドシェイク時に自身の証明書をクライアントに提示し、安全な接続を確立します。

tls.connect() と tls.createServer() の使用例については、Node.js の公式ドキュメントや多くのオンラインリソースで確認できます。
新しい Node.js アプリケーションでは、tls.connect() (クライアント) および tls.createServer() (サーバー) を使用することを強く推奨します。 これらの新しい API は、より柔軟で安全な TLS/SSL 通信をサポートしており、証明書の管理、暗号スイートの選択、クライアント認証など、より高度な設定が可能です。
これらの例は、tls.createSecurePair() がどのように機能していたかの概念を示すためのものです。

tls.connect() (クライアント側)
TLS/SSL を使用してサーバーへの安全な接続を確立するために使用します。
tls.createServer() (サーバー側)
TLS/SSL を使用する安全なネットワークサーバーを起動するために使用します。

これらの新しい API は、tls.createSecurePair() よりも柔軟で、現代的なセキュリティ要件に対応しており、より詳細な設定が可能です。

tls.connect() (クライアント側)

tls.connect() は、指定されたオプションに基づいて TLS/SSL で保護されたソケットを確立し、tls.TLSSocket オブジェクトを返します。このオブジェクトは、通常の net.Socket と同様に読み取り可能および書き込み可能なストリームとして動作します。

基本的な使用例

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

const options = {
  host: 'example.com', // 接続先のホスト名または IP アドレス
  port: 443,           // 接続先のポート番号 (通常 HTTPS は 443)
  // 信頼する CA 証明書 (自己署名証明書の場合は必要)
  // ca: [fs.readFileSync('ca.crt')],
  // クライアント証明書 (必要な場合)
  // key: fs.readFileSync('client-key.pem'),
  // cert: fs.readFileSync('client-cert.pem'),
  // TLS バージョンなどの詳細設定も可能
};

const socket = tls.connect(options, () => {
  console.log('クライアント: サーバーとの安全な接続が確立されました。');
  socket.write('こんにちは、サーバー！');
});

socket.on('data', (data) => {
  console.log('クライアント受信:', data.toString());
  socket.end();
});

socket.on('end', () => {
  console.log('クライアント: 接続が閉じられました。');
});

socket.on('error', (err) => {
  console.error('クライアント TLS エラー:', err);
});

tls.connect() の主な利点

イベント駆動型
connect, data, end, error, secure などのイベントを通じて、接続の状態やデータの流れを監視・制御できます。
SNI (Server Name Indication) のサポート
複数の仮想ホストが同じ IP アドレスで TLS を提供する場合に、接続先のサーバー名を通知できます。
豊富なオプション
ホスト名、ポート、使用する TLS バージョン、暗号スイート、証明書、CA (Certificate Authority) 証明書など、接続に関する多くのオプションを設定できます。
明確なクライアントとしての役割
接続を開始するクライアントの意図が明確になります。

tls.createServer() (サーバー側)

tls.createServer() は、TLS/SSL で保護された接続を受け付けるサーバーを作成します。接続ごとに tls.TLSSocket オブジェクトが生成され、通常のストリームとして扱うことができます。

基本的な使用例

const tls = require('tls');
const fs = require('fs');
const net = require('net');

const options = {
  key: fs.readFileSync('server-key.pem'),   // サーバーの秘密鍵
  cert: fs.readFileSync('server-cert.pem'), // サーバーの証明書
  // クライアント証明書を要求する場合
  // requestCert: true,
  // 信頼するクライアント証明書を持つ CA 証明書
  // ca: [fs.readFileSync('ca.crt')],
  // TLS バージョンなどの詳細設定も可能
};

const server = tls.createServer(options, (socket) => {
  console.log('サーバー: クライアントからの安全な接続を受け付けました。');

  socket.on('data', (data) => {
    console.log('サーバー受信:', data.toString());
    socket.write(`サーバー応答: ${data.toString()}`);
  });

  socket.on('end', () => {
    console.log('サーバー: クライアントとの接続が閉じられました。');
  });

  socket.on('error', (err) => {
    console.error('サーバー TLS エラー:', err);
  });
});

const port = 8443;
server.listen(port, () => {
  console.log(`安全な TLS サーバーがポート ${port} で起動しました。`);
});

tls.createServer() の主な利点

イベント駆動型
connection, secureConnection, clientError, error などのイベントを通じて、サーバーの状態やクライアントとの接続を監視・制御できます。
セッション管理
TLS セッションの再利用を制御することで、パフォーマンスを向上させることができます。
SNI (Server Name Indication) のサポート
複数のドメインに対して異なる証明書を提供できます。
豊富なオプション
サーバーの秘密鍵、証明書、クライアント証明書の要求設定、信頼する CA 証明書、使用する TLS バージョン、暗号スイートなど、サーバーのセキュリティに関する多くのオプションを設定できます。
明確なサーバーとしての役割
安全な接続を待機し、処理するサーバーの意図が明確になります。

net.createServer() との組み合わせ

tls.createServer() は内部的に net.createServer() を使用しており、TLS/SSL ハンドシェイクを自動的に処理します。そのため、通常の TCP サーバーを作成する場合と同様に server.listen() を使用してポートを監視できます。

移行のヒント

tls.createSecurePair() を使用していたコードを tls.connect() や tls.createServer() に移行する際には、以下の点を考慮すると良いでしょう。

ストリーム処理
tls.TLSSocket オブジェクトは通常のストリームと同様に pipe() や on('data') などのメソッドを使用してデータの読み書きを行います。
エラーハンドリング
error イベントを適切に処理し、接続の問題やセキュリティの問題に対応できるようにします。
オプションの設定
証明書、秘密鍵、CA 証明書など、必要なセキュリティ関連のオプションを適切に設定します。
クライアントとサーバーの役割の分離
クライアント側の処理は tls.connect() を使用し、サーバー側の処理は tls.createServer() を使用するように明確に分けます。

Node.js TLS/SSL newSession イベントの仕組みと活用方法

もう少し詳しく説明すると、以下のようになります。リスナーの引数イベントリスナー関数には、通常、確立された新しいセッションに関する情報を持つオブジェクトが引数として渡されます。具体的なオブジェクトの型やプロパティは、Node. js のバージョンやモジュールの詳細によって異なる場合がありますが、セッションIDなどの情報が含まれていることが多いです。

Node.js イベント駆動：OCSPRequest イベントハンドラの書き方

もう少し詳しく説明します。OCSP とはその役割OCSP は、X.509 デジタル証明書の失効ステータスをリアルタイムで確認するためのプロトコルです。従来の証明書失効リスト (CRL) と比較して、よりタイムリーで効率的な失効確認方法を提供します。

Node.js プログラミング：OCSPResponse イベントの基礎から応用、エラー対策

より具体的に説明すると、以下のようになります。OCSP (Online Certificate Status Protocol) とは？まず、OCSPは、X.509デジタル証明書の有効性をリアルタイムで確認するためのプロトコルです。通常、証明書の有効性は失効リスト (CRL: Certificate Revocation List) を参照することで確認されますが、CRLはサイズが大きくなる可能性があり、更新頻度も高くない場合があります。OCSPは、証明書の発行局 (CA: Certificate Authority) が運用するOCSPレスポンダと呼ばれるサーバーに問い合わせることで、特定の証明書が現在有効かどうかを即座に確認できます。