【非推奨】Node.js tls.SecurePairの解説とtls.TLSSocketへの移行ガイド

2025-06-01

ただし、重要な点として、Node.jsのドキュメントによると、tls.SecurePair クラスは非推奨 (deprecated) となっており、代わりに tls.TLSSocket クラスを使用することが推奨されています。

それでも、過去のコードや概念を理解するために tls.SecurePair について説明します。

tls.SecurePair クラス (非推奨)

tls.SecurePair クラスは、Node.jsの古いバージョンのTLS (Transport Layer Security) および SSL (Secure Sockets Layer) を扱うために提供されていたクラスです。その主な目的は、暗号化されたソケットのペアを作成し、管理することでした。このペアの一方のソケットから書き込まれたデータは暗号化され、もう一方のソケットで復号化されて読み取れるようになります。

主な役割

ソケットの管理
暗号化されたデータの送受信を行うための2つのソケット（クリアテキスト側と暗号化された側）を内部的に管理していました。
暗号化と復号化
確立された通信路を通じて送受信されるデータを自動的に暗号化および復号化していました。
暗号化された通信路の確立
tls.SecurePair は、TLS/SSLハンドシェイク（接続確立処理）を行い、安全な通信路を確立する役割を担っていました。

なぜ非推奨になったのか？

tls.SecurePair が非推奨になった主な理由は、より柔軟で強力な tls.TLSSocket クラスが導入されたためです。tls.TLSSocket は、より多くのオプションを提供し、より細かくTLS/SSL接続を制御できます。また、ストリームインターフェースとの統合もよりスムーズです。

tls.SecurePair の基本的な使い方 (概念として)

tls.SecurePair のインスタンスを作成し、クライアント側とサーバー側の両方で使用して、安全な接続を確立していました。

サーバー側
サーバーは、クライアントからの接続を受け付け、tls.SecurePair のインスタンスを作成してTLS/SSLハンドシェイクを開始していました。
クライアント側
クライアントは、サーバーに接続し、同様に tls.SecurePair のインスタンスを作成してハンドシェイクを開始していました。
ソケットの取得
ハンドシェイクが成功すると、SecurePair オブジェクトからクリアテキストのデータを読み書きするためのソケット (cleartext ソケット) と、暗号化されたデータをやり取りするためのソケット (encrypted ソケット) を取得できました。
データの送受信
cleartext ソケットに対して通常のソケット操作（write(), pipe(), on('data') など）を行うことで、データは自動的に暗号化されて encrypted ソケットを通じて相手に送信され、相手側では復号化されて cleartext ソケットで受信できました。

注意点

古いコードを保守する場合にのみ、tls.SecurePair の概念を理解しておくことが役立つかもしれません。
新規開発での使用は避けるべきです。 新しいNode.jsプロジェクトでは、必ず tls.TLSSocket を使用してください。

代替: tls.TLSSocket クラス

現在推奨されている tls.TLSSocket クラスは、net.Socket を拡張したもので、TLS/SSL暗号化機能を直接組み込んでいます。これを使用することで、よりシンプルかつ効率的に安全なネットワーク接続を扱うことができます。

tls.TLSSocket の使用例（簡単な概念）：

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

// サーバー側
const server = net.createServer((socket) => {
  const secureSocket = new tls.TLSSocket(socket, {
    key: /* 秘密鍵 */,
    cert: /* 証明書 */,
    isServer: true
  });
  secureSocket.on('secureConnect', () => {
    console.log('クライアントが安全に接続しました。');
    secureSocket.write('ようこそ！');
  });
  secureSocket.on('data', (data) => {
    console.log('受信データ:', data.toString());
  });
  secureSocket.on('end', () => {
    console.log('クライアントが切断しました。');
  });
});

server.listen(8000, () => {
  console.log('TLSサーバーがポート 8000 で起動しました。');
});

// クライアント側
const client = tls.connect({
  port: 8000,
  host: 'localhost',
  // CA証明書 (サーバー証明書の検証に必要)
  // rejectUnauthorized: false // 開発環境などでの自己署名証明書の場合は注意が必要
}, () => {
  console.log('サーバーに安全に接続しました。');
  client.write('こんにちは！');
});

client.on('data', (data) => {
  console.log('サーバーからの応答:', data.toString());
});

client.on('end', () => {
  console.log('サーバーとの接続を閉じました。');
});

tls.SecurePair に関連する一般的なエラーとトラブルシューティング (非推奨)

tls.SecurePair の使用時に発生しやすかったエラーと、そのトラブルシューティングのヒントを以下に示します。これらの多くは、より現代的な tls.TLSSocket でも同様の問題として発生する可能性がありますが、SecurePair 特有の側面も含まれています。

ハンドシェイク関連のエラー (Handshake Errors)

エラー
Error: No shared cipher suite (共有する暗号スイートがない)
- 原因
  クライアントとサーバーが共通でサポートしている暗号スイートが存在しない。
- トラブルシューティング
  上記の暗号スイートに関するトラブルシューティングを参照し、クライアントとサーバーの両方で利用可能な暗号スイートの設定を見直す。

証明書関連のエラー (Certificate Errors)

エラー
Error: unable to verify the first certificate (最初の証明書を検証できない)
- 原因
  サーバーが送信した証明書チェーンが完全でないか、クライアントが中間CA証明書を認識していない。
- トラブルシューティング
  サーバー側の設定で、リーフ証明書だけでなく、中間CA証明書も連結した証明書ファイル (cert オプション) を使用する。クライアント側で必要なCA証明書 (ca オプション) を設定する。
エラー
Error: self signed certificate (自己署名証明書)
- 原因
  サーバーが自己署名証明書を使用しており、クライアントがそれをデフォルトで信頼しない。
- トラブルシューティング
  - 本番環境では、信頼された認証局 (CA) から署名された証明書を使用する。
  - 開発環境などで自己署名証明書を使用する場合は、クライアント側の tls.connect() オプションで rejectUnauthorized: false を設定する (ただし、セキュリティリスクを理解した上で慎重に行う)。または、ca オプションでサーバーの証明書（または署名したCA証明書）を明示的に指定して信頼する。

ソケット関連のエラー (Socket Errors)

エラー
Error: write after end (終了後に書き込み)
- 原因
  ソケットが既に閉じられた後に書き込みを試みている。
- トラブルシューティング
  ソケットの状態を適切に管理し、'end' イベントや 'close' イベントが発生した後に書き込みを行わないようにする。
エラー
Error: Socket closed (ソケットが閉じられた)
- 原因
  TLS/SSLハンドシェイクの失敗、ネットワークの問題、またはサーバー/クライアント側の意図的な切断などが考えられる。
- トラブルシューティング
  - ハンドシェイク関連のエラーがないか確認する。
  - ネットワーク接続が安定しているか確認する。
  - サーバーまたはクライアント側のログを確認し、切断の原因を特定する。
  - タイムアウト設定などが適切か確認する。

SecurePair 特有の問題 (非推奨クラス)

イベント処理の不備
SecurePair オブジェクトから発行されるイベント ('secure' など) を適切に処理しないと、接続の状態を正しく把握できず、予期しない動作を引き起こす可能性がありました。
- トラブルシューティング
  関連するイベントリスナーを適切に設定し、接続状態の変化に対応する処理を実装する。
cleartext ソケットと encrypted ソケットの誤用
SecurePair は内部に2つのソケット (cleartext と encrypted) を持っており、誤って暗号化されていない cleartext ソケットを直接ネットワークに書き込んだり、暗号化された encrypted ソケットから直接読み取ろうとしたりするケースがありました。
- トラブルシューティング
  データの送受信は必ず cleartext ソケットを通して行うようにする。encrypted ソケットは TLS/SSL プロトコルの内部処理で使用されるものです。

一般的なトラブルシューティングのヒント

シンプルなテストケースを作成する
問題を切り分けるために、最小限のコードで再現できるテストケースを作成し、段階的に複雑化していくと原因を特定しやすくなります。
Node.js のドキュメントを参照する
tls モジュールの公式ドキュメントには、各オプションやイベントに関する詳細な説明があります。
ネットワーク監視ツールを使用する
Wireshark などのネットワーク監視ツールを使用して、実際に送受信されているパケットを分析することで、プロトコルレベルの問題を特定できる場合があります。
ログ出力を活用する
サーバーとクライアントの両方でログ出力を追加し、接続の確立からデータ送受信までの流れを追跡できるようにする。
エラーメッセージを注意深く読む
エラーメッセージには、問題の原因に関する重要な情報が含まれていることが多いです。

繰り返しますが、tls.SecurePair は非推奨であり、これらの問題の多くは tls.TLSSocket を使用することでよりシンプルに解決できる可能性があります。新規開発では tls.TLSSocket の利用を強く推奨します。

tls.SecurePair を使用した簡単なサーバーとクライアントの例 (非推奨)

この例では、tls.SecurePair を使用して、簡単なエコーサーバーとクライアントを実装します。

サーバー側のコード (server.js)

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

// サーバーの秘密鍵と証明書
const serverKey = fs.readFileSync('server-key.pem');
const serverCert = fs.readFileSync('server-cert.pem');

const server = net.createServer((socket) => {
  // SecurePair オブジェクトを作成 (非推奨)
  const securePair = tls.createSecurePair({
    key: serverKey,
    cert: serverCert,
    // サーバー側であることを明示
    isServer: true
  });

  // encrypted ソケットと cleartext ソケットを取得
  const encryptedSocket = securePair.encrypted;
  const cleartextSocket = securePair.cleartext;

  // エラー処理
  securePair.on('error', (err) => {
    console.error('SecurePair エラー:', err);
    socket.destroy();
  });

  // cleartext ソケットにデータが来た時の処理
  cleartextSocket.on('data', (data) => {
    console.log('サーバー受信:', data.toString());
    cleartextSocket.write(`エコー: ${data.toString()}`);
  });

  // ソケットが閉じられた時の処理
  cleartextSocket.on('end', () => {
    console.log('クライアントが切断しました。');
  });

  // encrypted ソケットと元のソケットをパイプで接続
  socket.pipe(encryptedSocket);
  encryptedSocket.pipe(socket);
});

server.listen(8000, () => {
  console.log('TLS サーバーがポート 8000 で起動しました。');
});

解説

socket.pipe(encryptedSocket) と encryptedSocket.pipe(socket) によって、元の TCP ソケットと暗号化されたソケットの間でデータがやり取りされるようにパイプ処理を行います。これにより、cleartextSocket に対して読み書きを行うと、自動的に暗号化・復号化が行われます。
cleartextSocket.on('data') でクライアントから送信されたデータを受信し、エコーバックします。
securePair.encrypted が暗号化されたデータをやり取りするソケット、securePair.cleartext が暗号化・復号化後のクリアテキストデータを扱うソケットです。
接続ごとに tls.createSecurePair() を呼び出し、key (秘密鍵) と cert (証明書) を指定して SecurePair オブジェクトを作成します。isServer: true を設定してサーバー側であることを示します。
net.createServer() で通常の TCP サーバーを作成します。

クライアント側のコード (client.js)

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

// サーバーの証明書 (自己署名の場合はクライアントで信頼する必要がある)
const serverCert = fs.readFileSync('server-cert.pem');

const client = net.connect(8000, 'localhost', () => {
  console.log('サーバーに接続しました。');

  // SecurePair オブジェクトを作成 (非推奨)
  const securePair = tls.createSecurePair({
    // クライアント側であることを示す (デフォルトは false)
    // ca: [serverCert] // サーバー証明書が自己署名の場合は必要
  });

  const encryptedSocket = securePair.encrypted;
  const cleartextSocket = securePair.cleartext;

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

  cleartextSocket.on('data', (data) => {
    console.log('クライアント受信:', data.toString());
    client.end(); // データを受信したら終了
  });

  cleartextSocket.on('end', () => {
    console.log('サーバーとの接続を閉じました。');
  });

  // encrypted ソケットと元のソケットをパイプで接続
  client.pipe(encryptedSocket);
  encryptedSocket.pipe(client);

  // データを送信
  cleartextSocket.write('こんにちは、サーバー！');
});

解説

cleartextSocket.on('data') でサーバーからの応答を受信します。
cleartextSocket.write() でデータをサーバーに送信します。
サーバーと同様に、encryptedSocket と cleartextSocket を取得し、パイプ処理で元のソケットと接続します。
サーバーの証明書が自己署名の場合は、ca オプションにサーバーの証明書を指定して信頼する必要があります。
接続後に tls.createSecurePair() を呼び出し、クライアント側であることを示すために isServer: false (デフォルト) とします。
net.connect() でサーバーに接続します。

実行方法

秘密鍵 (server-key.pem) と証明書 (server-cert.pem) を生成します。自己署名証明書を生成する簡単な例 (OpenSSL が必要):

openssl genrsa -out server-key.pem 2048
openssl req -new -key server-key.pem -out server-cert.csr
# プロンプトに従って情報を入力
openssl x509 -req -days 365 -in server-cert.csr -signkey server-key.pem -out server-cert.pem

server.js と client.js を作成し、上記のコードを保存します。
ターミナルを2つ開き、一方でサーバーを起動します。
```
node server.js
```
もう一方のターミナルでクライアントを起動します。
```
node client.js
```

クライアントとサーバーの間で暗号化された通信が行われる様子がコンソールに出力されます。

重要な注意点

tls.TLSSocket の利便性
tls.TLSSocket は net.Socket を拡張しており、TLS/SSL の設定をオプションとして渡すだけで、通常のソケットと同じように安全な通信を扱うことができます。
複雑性
tls.SecurePair を直接扱う場合、暗号化とクリアテキストのソケットを明示的に管理する必要があるため、コードが複雑になりがちです。
非推奨
この例は tls.SecurePair の動作を示すためのものであり、実際のアプリケーション開発では tls.TLSSocket を使用してください。

tls.TLSSocket を使用した同様の例 (推奨)

tls.TLSSocket を使用すると、上記の例はより簡潔になります。以下は、tls.TLSSocket を使用したサーバーとクライアントの基本的な例です。

サーバー (server_tls.js)

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

const serverKey = fs.readFileSync('server-key.pem');
const serverCert = fs.readFileSync('server-cert.pem');

const server = net.createServer((socket) => {
  const secureSocket = new tls.TLSSocket(socket, {
    key: serverKey,
    cert: serverCert,
    isServer: true
  });

  secureSocket.on('secureConnect', () => {
    console.log('クライアントが安全に接続しました。');
    secureSocket.write('ようこそ！');
  });

  secureSocket.on('data', (data) => {
    console.log('サーバー受信:', data.toString());
    secureSocket.write(`エコー (TLS): ${data.toString()}`);
  });

  secureSocket.on('end', () => {
    console.log('クライアントが切断しました。');
  });

  // 元のソケットを破棄し、secureSocket を直接使用
});

server.listen(8001, () => {
  console.log('TLS サーバー (tls.TLSSocket) がポート 8001 で起動しました。');
});

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

const serverCert = fs.readFileSync('server-cert.pem');

const client = tls.connect({
  port: 8001,
  host: 'localhost',
  // ca: [serverCert] // 自己署名証明書の場合は必要
}, () => {
  console.log('サーバーに安全に接続しました (tls.TLSSocket)。');
  client.write('こんにちは、サーバー (TLS)！');
});

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

client.on('end', () => {
  console.log('サーバーとの接続を閉じました (TLS)。');
});

tls.SecurePair の代替プログラミング方法: tls.TLSSocket クラス

tls.TLSSocket クラスは、net.Socket を拡張したもので、TLS (Transport Layer Security) または SSL (Secure Sockets Layer) プロトコルによる暗号化された通信を直接扱うための機能を提供します。tls.SecurePair のように暗号化されたソケットとクリアテキストのソケットを明示的に管理する必要がなく、よりシンプルで効率的な方法で安全なネットワーク通信を実装できます。

tls.TLSSocket の基本的な使い方

net.createServer() で通常の TCP サーバーを作成します。
接続リスナー内で、接続された net.Socket オブジェクトを tls.TLSSocket のインスタンスでラップします。この際に、サーバーの秘密鍵 (key)、証明書 (cert)、および isServer: true オプションを指定します。
secureConnect イベントは、TLS/SSL ハンドシェイクが成功した後に発生します。このイベントリスナー内で、安全な通信を開始できます。
data イベントや end イベントは、通常のソケットと同様に扱うことができます。

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

const serverKey = fs.readFileSync('server-key.pem');
const serverCert = fs.readFileSync('server-cert.pem');

const server = net.createServer((socket) => {
  const secureSocket = new tls.TLSSocket(socket, {
    key: serverKey,
    cert: serverCert,
    isServer: true
  });

  secureSocket.on('secureConnect', () => {
    console.log('クライアントが安全に接続しました。');
    secureSocket.write('ようこそ！');
  });

  secureSocket.on('data', (data) => {
    console.log('サーバー受信:', data.toString());
    secureSocket.write(`エコー (TLS): ${data.toString()}`);
  });

  secureSocket.on('end', () => {
    console.log('クライアントが切断しました。');
  });

  // 元の socket は使用せず、secureSocket を直接使用します
});

server.listen(8001, () => {
  console.log('TLS サーバー (tls.TLSSocket) がポート 8001 で起動しました。');
});

クライアント側

tls.connect() 関数を使用して、サーバーへの安全な接続を確立します。この関数は、接続先のポート、ホスト、および TLS/SSL 関連のオプション（例えば、信頼する CA 証明書など）を受け取ります。
connect イベントリスナー内で、サーバーとの接続が確立し、TLS/SSL ハンドシェイクが開始されます。
secureConnect イベントは、ハンドシェイクが成功した後に発生します。
data イベントや end イベントは、通常のソケットと同様に扱うことができます。

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

const serverCert = fs.readFileSync('server-cert.pem');

const client = tls.connect({
  port: 8001,
  host: 'localhost',
  // サーバー証明書が自己署名の場合は、CA 証明書を指定するか、
  // 本番環境以外では rejectUnauthorized: false を設定することも可能 (セキュリティリスクあり)
  // ca: [serverCert]
}, () => {
  console.log('サーバーに安全に接続しました (tls.TLSSocket)。');
  client.write('こんにちは、サーバー (TLS)！');
});

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

client.on('end', () => {
  console.log('サーバーとの接続を閉じました (TLS)。');
});

tls.TLSSocket の利点

推奨される方法
Node.js の公式ドキュメントで推奨されており、将来的なサポートや機能拡張も期待できます。
ストリーム API との統合
tls.TLSSocket はストリームインターフェースを実装しており、pipe() などを使用して簡単にデータの流れを制御できます。
柔軟性
TLS/SSL プロトコルバージョン、暗号スイート、証明書の検証など、より多くのオプションを細かく設定できます。
シンプルさ
暗号化とクリアテキストのソケットを別々に扱う必要がなく、通常のソケットと同様のインターフェースで安全な通信を扱えます。

サードパーティのライブラリ
より高度なセキュリティ機能や特定のプロトコル（例えば、HTTPS/2 など）を扱う場合、node-fetch (HTTPS クライアント) や express (HTTPS サーバー機能内蔵) などのサードパーティライブラリを利用することも選択肢の一つです。これらのライブラリは、TLS/SSL の複雑な部分を抽象化し、より高レベルな API を提供します。

tls.createServer()
TLS/SSL を直接サポートするサーバーを作成するための便利な関数です。内部的には net.createServer() と tls.TLSSocket の組み合わせを抽象化しています。

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

const serverKey = fs.readFileSync('server-key.pem');
const serverCert = fs.readFileSync('server-cert.pem');

const server = tls.createServer({
  key: serverKey,
  cert: serverCert
}, (secureSocket) => {
  console.log('クライアントが安全に接続しました (tls.createServer)。');
  secureSocket.write('ようこそ！');
  secureSocket.on('data', (data) => {
    console.log('サーバー受信:', data.toString());
    secureSocket.write(`エコー (TLS Server): ${data.toString()}`);
  });
  secureSocket.on('end', () => {
    console.log('クライアントが切断しました。');
  });
});

server.listen(8002, () => {
  console.log('TLS サーバー (tls.createServer) がポート 8002 で起動しました。');
});

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レスポンダと呼ばれるサーバーに問い合わせることで、特定の証明書が現在有効かどうかを即座に確認できます。