Node.js secureConnection イベントのエラーとトラブルシューティング【日本語】

2025-06-01

「secureConnection」イベントは、Node.js の tls (Transport Layer Security) または https モジュールで使用されるイベントの一つです。このイベントは、サーバー側の tls.Server または https.Server オブジェクトが、クライアントとの間で安全な TLS/SSL 接続が確立された際に 発行（emit）されます。

より具体的に説明すると、以下のようになります。

関連する概念
- TLS/SSL (Transport Layer Security/Secure Sockets Layer)
  インターネット上で安全な通信を提供するための暗号化プロトコルです。
- ハンドシェイク (Handshake)
  TLS/SSL 接続を確立する際に行われる、サーバーとクライアント間のネゴシエーションのプロセスです。
- tls.Server
  TLS/SSL を使用するサーバーを作成するためのクラスです。
- https.Server
  HTTP over TLS/SSL (HTTPS) を提供するサーバーを作成するためのクラスで、内部的に tls.Server を使用しています。
- tls.TLSSocket
  確立された安全な TLS/SSL 接続を表すオブジェクトです。通常の net.Socket の機能に加えて、TLS/SSL 固有のメソッドやプロパティを持っています。
主な用途
「secureConnection」イベントは、安全な接続が確立された後に特定の処理を実行したい場合に利用されます。例えば、
- クライアントの証明書情報を確認する。
- 安全な接続数を記録する。
- 接続されたクライアントに対して、安全な通信を開始するための初期設定を行う。
- 特定のクライアントに対して特別な処理を行う。
イベントハンドラの引数
このイベントが発生すると、イベントハンドラ関数に一つの引数が渡されます。それは、確立された安全な接続を表す tls.TLSSocket オブジェクトです。この tls.TLSSocket オブジェクトを通じて、安全な接続に関する情報にアクセスしたり、データの送受信を行ったりすることができます。
発生するタイミング
クライアントがサーバーに対して安全な接続を要求し、TLS/SSL のハンドシェイクが正常に完了した直後に、サーバー側で「secureConnection」イベントが発生します。これは、データが暗号化されて安全に送受信できる状態になったことを意味します。

簡単なコード例（tls モジュールを使用）

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

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

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('クライアントが切断しました (通常の接続)');
  });
});

server.on('secureConnection', (tlsSocket) => {
  console.log('安全な接続が確立されました！');
  console.log('クライアント証明書:', tlsSocket.getPeerCertificate());

  tlsSocket.on('data', (data) => {
    console.log('安全な受信データ:', data.toString());
    tlsSocket.write('サーバーからの安全な応答: ' + data.toString());
  });

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

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

この例では、tls.createServer のコールバック関数は通常の TCP 接続に対して処理を行い、server.on('secureConnection', ...) の部分は安全な TLS/SSL 接続が確立された後に実行される処理を記述しています。

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

- エラー
  Error: Cannot load certificate, Error: Cannot load private key など、証明書ファイルや秘密鍵ファイルの読み込みに失敗する。
- 原因
  - ファイルパスが間違っている。
  - ファイルが存在しない。
  - ファイルの権限が正しくないため、Node.js プロセスが読み取れない。
  - ファイル形式が正しくない（PEM 形式である必要があります）。
- トラブルシューティング
  - ファイルパスを再確認する。
  - ファイルが存在することを確認する。
  - Node.js プロセスがファイルにアクセスできる権限があるか確認する (chmod などを使用)。
  - 証明書と秘密鍵が正しい PEM 形式であることを確認する。
証明書と秘密鍵の不一致
- エラー
  特に具体的なエラーメッセージが出ない場合もありますが、TLS ハンドシェイクが失敗し、secureConnection イベントが発生しないことがあります。
- 原因
  サーバーの設定で使用している証明書と秘密鍵のペアが一致していない。
- トラブルシューティング
  - 使用している証明書が、対応する秘密鍵によって署名されているかを確認する。openssl などのツールを使って確認できます。
  - 証明書と秘密鍵を再生成し、サーバー設定に正しく適用する。
中間証明書 (CA 証明書) の不足
- エラー
  クライアントによっては、「信頼されていない証明書」として接続を拒否されることがあります。
- 原因
  サーバーの証明書が、信頼された認証局 (CA) によって署名されている場合、クライアントがその CA を信頼するために中間証明書が必要となることがあります。サーバー設定で中間証明書が正しく設定されていない場合に発生します。
- トラブルシューティング
  - 認証局から提供された中間証明書を、サーバー証明書と連結して設定する。tls.createServer の ca オプションに中間証明書の配列またはファイルを指定します。
TLS/SSL バージョンと暗号スイートの不一致
- エラー
  クライアントとサーバーでサポートしている TLS/SSL のバージョンや暗号スイートが一致しない場合、ハンドシェイクが失敗し、secureConnection イベントが発生しません。
- 原因
  サーバーまたはクライアントの設定で、互いにサポートしていないバージョンや暗号スイートのみが有効になっている。
- トラブルシューティング
  - tls.createServer の minVersion, maxVersion, ciphers オプションなどを確認し、クライアントと互換性のある設定になっているか確認する。
  - より新しい TLS バージョン（TLS 1.2 以降）を使用することを推奨します。古いバージョンには脆弱性がある可能性があります。
クライアント認証の設定ミス
- エラー
  requestCert: true を設定してクライアント証明書を要求しているにもかかわらず、クライアントが証明書を提供しない、または提供された証明書が検証に失敗する。
- 原因
  - クライアントが証明書を設定していない。
  - クライアント証明書がサーバー側の CA によって署名されていないため、検証に失敗する。
  - サーバー側の CA 証明書の設定 (ca オプション) が正しくない。
- トラブルシューティング
  - クライアントが正しい証明書を設定しているか確認する。
  - サーバー側の ca オプションに、クライアント証明書を発行した CA の証明書が正しく設定されているか確認する。
  - checkServerIdentity: false を一時的に設定して、サーバー証明書のホスト名検証をスキップし、接続できるか確認する（本番環境では推奨されません）。
ファイアウォールやネットワークの問題
- エラー
  接続がタイムアウトしたり、拒否されたりする。secureConnection イベント自体が発生しない。
- 原因
  サーバーのポートがファイアウォールでブロックされている、またはネットワーク経路に問題がある。
- トラブルシューティング
  - サーバーのファイアウォール設定を確認し、HTTPS (通常は 443 番ポート) の通信が許可されているか確認する。
  - ネットワーク接続を確認する (ping, telnet などを使用)。
Node.js のバージョンによる差異
- エラー
  特定の Node.js バージョンでのみ問題が発生する。
- 原因
  Node.js のバージョンによって、TLS/SSL の実装やデフォルト設定が異なる場合があります。
- トラブルシューティング
  - Node.js のバージョンを切り替えてテストしてみる。
  - Node.js のリリースノートを確認し、TLS/SSL 関連の変更点を確認する。
SNI (Server Name Indication) の問題
- エラー
  複数の仮想ホストで HTTPS を提供している場合に、クライアントが正しいサーバー証明書を受け取れない。
- 原因
  クライアントが SNI をサポートしていない、またはサーバー側で SNI の設定が正しく行われていない。
- トラブルシューティング
  - 古いクライアントを使用している場合は、SNI をサポートしているか確認する。
  - サーバー側で SNI の設定 (tls.createServer の SNICallback オプションなど) が正しく行われているか確認する。

トラブルシューティングのヒント

シンプルな構成でテストする
まずは最小限の設定で TLS サーバーを起動し、正常に接続できるか確認します。その後、徐々に設定を追加していくことで、問題が発生した箇所を特定しやすくなります。
ネットワーク監視ツールを使用する
Wireshark などのネットワーク監視ツールを使用すると、TLS ハンドシェイクの過程を詳細に確認でき、問題の切り分けに役立ちます。
詳細なログを出力する
tls.createServer のオプションや、tlsSocket オブジェクトのイベント (error, close など) を監視し、より詳細なログを出力するように設定すると、問題の特定に役立ちます。
エラーメッセージをよく読む
Node.js が出力するエラーメッセージは、問題の原因を特定するための重要な情報を含んでいます。

例1: 基本的な secureConnection イベントの監視

この例では、TLS サーバーを作成し、「secureConnection」イベントが発生した際にコンソールにメッセージを表示します。

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

const options = {
  key: fs.readFileSync('server-key.pem'),
  cert: fs.readFileSync('server-cert.pem'),
};

const server = tls.createServer(options, (socket) => {
  console.log('通常の接続:', socket.remoteAddress, socket.remotePort);

  socket.on('data', (data) => {
    console.log('通常の受信データ:', data.toString());
    socket.write('通常の応答: ' + data.toString());
  });

  socket.on('end', () => {
    console.log('通常の接続が閉じられました。');
  });
});

server.on('secureConnection', (tlsSocket) => {
  console.log('安全な接続が確立されました！:', tlsSocket.remoteAddress, tlsSocket.remotePort);
  console.log('TLS バージョン:', tlsSocket.getProtocol());
  console.log('暗号スイート:', tlsSocket.getCipher());
  console.log('クライアント証明書:', tlsSocket.getPeerCertificate()); // クライアント証明書が存在する場合

  tlsSocket.on('data', (data) => {
    console.log('安全な受信データ:', data.toString());
    tlsSocket.write('安全な応答: ' + data.toString());
  });

  tlsSocket.on('end', () => {
    console.log('安全な接続が閉じられました。');
  });
});

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

この例のポイント

tlsSocket.getPeerCertificate(): 接続したクライアントの証明書オブジェクトを取得します。クライアント認証が設定されている場合に有用です。
tlsSocket.getCipher(): 使用されている暗号スイートの情報を取得します。
tlsSocket.getProtocol(): 使用されている TLS/SSL のプロトコルバージョン（例: 'TLSv1.2'）を取得します。
tlsSocket オブジェクトは、安全な接続を表す tls.TLSSocket のインスタンスです。これを通じて、安全なデータの送受信や、接続に関する情報の取得ができます。
server.on('secureConnection', (tlsSocket) => { ... }); は、「secureConnection」イベントのハンドラです。TLS/SSL ハンドシェイクが成功し、安全な接続が確立した後に呼び出されます。
tls.createServer(options, (socket) => { ... }); は、通常の TCP 接続を扱うためのコールバック関数です。クライアントが TLS/SSL をネゴシエートする前の初期接続で呼び出されます。

例2: クライアント認証の処理

この例では、サーバーがクライアント証明書を要求し、「secureConnection」イベント内でクライアント証明書を検証します。

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

const options = {
  key: fs.readFileSync('server-key.pem'),
  cert: fs.readFileSync('server-cert.pem'),
  ca: [fs.readFileSync('client-ca.pem')], // クライアント証明書を発行した CA の証明書
  requestCert: true, // クライアント証明書を要求する
  rejectUnauthorized: true, // 検証に失敗したクライアントを拒否する
};

const server = tls.createServer(options, (socket) => {
  // 通常の接続処理 (必要に応じて)
});

server.on('secureConnection', (tlsSocket) => {
  console.log('安全な接続:', tlsSocket.remoteAddress, tlsSocket.remotePort);
  const clientCert = tlsSocket.getPeerCertificate();

  if (clientCert && Object.keys(clientCert).length > 0) {
    console.log('クライアント証明書の Subject:', clientCert.subject);
    console.log('クライアント証明書の Issuer:', clientCert.issuer);
    // クライアント証明書の検証結果 (options.rejectUnauthorized が true の場合は既に検証済み)
    console.log('クライアント証明書の検証:', tlsSocket.authorized ? '成功' : '失敗');
    if (!tlsSocket.authorized) {
      console.log('クライアント証明書の検証エラー:', tlsSocket.authorizationError);
      tlsSocket.destroy(); // 検証に失敗した場合は接続を閉じる
      return;
    }
    tlsSocket.write('認証成功！安全な通信を開始します。\n');
  } else {
    console.log('クライアント証明書が提供されませんでした。');
    tlsSocket.end('クライアント証明書が必要です。\n');
  }

  tlsSocket.on('data', (data) => {
    console.log('安全な受信データ:', data.toString());
    tlsSocket.write('安全な応答: ' + data.toString());
  });

  tlsSocket.on('end', () => {
    console.log('安全な接続が閉じられました。');
  });
});

server.listen(8001, () => {
  console.log('クライアント認証付き TLS サーバーがポート 8001 で起動しました。');
});

この例のポイント

tlsSocket.authorizationError: クライアント証明書の検証に失敗した場合のエラーオブジェクトです。
tlsSocket.authorized: クライアント証明書が正常に検証されたかどうかを示すブール値です。
options.ca: [fs.readFileSync('client-ca.pem')]: クライアント証明書を発行した認証局 (CA) の証明書を指定します。これにより、サーバーはクライアント証明書を検証できます。
options.rejectUnauthorized: true: クライアント証明書の検証に失敗した場合、接続を拒否するように設定します。
options.requestCert: true: サーバーがクライアントに証明書を要求するように設定します。

例3: https モジュールでの secureConnection イベント

https モジュールは内部的に tls モジュールを使用しているため、https.Server オブジェクトも「secureConnection」イベントを発行します。

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

const options = {
  key: fs.readFileSync('server-key.pem'),
  cert: fs.readFileSync('server-cert.pem'),
};

const server = https.createServer(options, (req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('HTTPS サーバーからの応答\n');
});

server.on('secureConnection', (tlsSocket, req) => {
  console.log('HTTPS 安全な接続:', tlsSocket.remoteAddress, tlsSocket.remotePort);
  console.log('TLS バージョン:', tlsSocket.getProtocol());
  // req オブジェクトも利用可能 (HTTP リクエスト情報)
  console.log('HTTP メソッド:', req.method);
  console.log('HTTP URL:', req.url);

  tlsSocket.on('data', (data) => {
    console.log('安全な受信データ (HTTPS):', data.toString());
    // HTTPS の場合は通常、req と res を通じて処理します
  });

  tlsSocket.on('end', () => {
    console.log('HTTPS 安全な接続が閉じられました。');
  });
});

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

server.on('secureConnection', (tlsSocket, req) => { ... }); のイベントハンドラには、確立された tlsSocket に加えて、HTTP リクエストを表す req オブジェクトも渡されます。これにより、安全な接続と HTTP リクエストの情報を関連付けて処理できます。
https.createServer(options, (req, res) => { ... }); は、通常の HTTPS リクエストを処理するためのコールバック関数です。

代替方法の考え方

パイプ処理 (pipe())
tls.TLSSocket はストリームの一種であるため、他のストリームと pipe() メソッドを使って接続することができます。例えば、安全な接続から読み取ったデータを別のストリーム（ファイルや別のネットワーク接続など）に直接書き込むことができます。
イベントリスナー内での直接処理
「secureConnection」イベントのリスナー内で、確立した tls.TLSSocket オブジェクトに対して直接データイベント ('data', 'end', 'error', 'close') のリスナーを設定し、データの送受信やエラー処理を行います。これは、前述の例でも示している基本的な方法であり、多くの場合、最も直接的で理解しやすいアプローチです。

例1: パイプ処理 (pipe() の利用)

この例では、安全な接続から読み取ったデータをコンソールに出力する Writable ストリームにパイプ処理します。

const tls = require('tls');
const fs = require('fs');
const { Writable } = require('stream');

const options = {
  key: fs.readFileSync('server-key.pem'),
  cert: fs.readFileSync('server-cert.pem'),
};

const server = tls.createServer(options, (socket) => {
  // 通常の接続処理
});

const logStream = new Writable({
  write(chunk, encoding, callback) {
    console.log('安全な接続からのデータ (パイプ):', chunk.toString());
    callback();
  },
});

server.on('secureConnection', (tlsSocket) => {
  console.log('安全な接続が確立されました (パイプ使用)');
  tlsSocket.pipe(logStream); // tlsSocket からのデータを logStream にパイプ
  tlsSocket.write('サーバーから安全なデータを送信します。\n');

  tlsSocket.on('end', () => {
    console.log('安全な接続が閉じられました (パイプ使用)');
  });
});

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

この例のポイント

パイプ処理は、データの流れを簡潔に記述できる利点があります。
tlsSocket.pipe(logStream): tlsSocket から読み取れるデータを logStream に自動的に書き込みます。これにより、'data' イベントのリスナーを手動で設定する必要がなくなります。

例2: 高レベルな抽象化 (フレームワークやライブラリの利用)

Express.js などの Web フレームワークや、Socket.IO などのライブラリを使用する場合、TLS/SSL の設定や安全な接続の管理はフレームワークやライブラリによって抽象化されることがあります。これらの高レベルなAPIを使用すると、「secureConnection」イベントを直接扱う必要が少なくなる場合があります。

例2-1: Express.js で HTTPS サーバーを作成する場合

const express = require('express');
const https = require('https');
const fs = require('fs');

const app = express();

const options = {
  key: fs.readFileSync('server-key.pem'),
  cert: fs.readFileSync('server-cert.pem'),
};

app.get('/', (req, res) => {
  res.send('Express HTTPS サーバーからの応答');
});

const server = https.createServer(options, app);

server.on('secureConnection', (tlsSocket) => {
  console.log('Express HTTPS 安全な接続:', tlsSocket.remoteAddress, tlsSocket.remotePort);
  // Express.js のルーティングとミドルウェアの仕組みを利用するため、
  // 個々の tlsSocket に対して直接データイベントを扱うことは少ないです。
});

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

この例のポイント

フレームワークが内部で tls モジュールを管理しているため、開発者はアプリケーションのロジックに集中できます。
Express.js を使用すると、ルーティングやミドルウェアなどの高レベルな機能を利用して HTTP/HTTPS リクエストを処理するため、「secureConnection」イベントは主に接続のロギングや、TLS 接続に関する特別な処理を行う場合に利用されることがあります。

例2-2: Socket.IO でセキュアな WebSocket 接続を扱う場合

Socket.IO は WebSocket 上にリアルタイム通信の抽象化を提供し、TLS/SSL を透過的に扱うことができます。

const https = require('https');
const fs = require('fs');
const { Server } = require('socket.io');

const options = {
  key: fs.readFileSync('server-key.pem'),
  cert: fs.readFileSync('server-cert.pem'),
};

const httpServer = https.createServer(options);
const io = new Server(httpServer);

io.on('connection', (socket) => {
  console.log('Socket.IO クライアントが接続しました:', socket.id);

  socket.on('message', (data) => {
    console.log('受信メッセージ:', data);
    socket.emit('reply', 'サーバーからの応答: ' + data);
  });

  socket.on('disconnect', () => {
    console.log('Socket.IO クライアントが切断しました:', socket.id);
  });
});

httpServer.on('secureConnection', (tlsSocket) => {
  console.log('Socket.IO HTTPS 安全な接続:', tlsSocket.remoteAddress, tlsSocket.remotePort);
  // Socket.IO が WebSocket プロトコル上で通信を管理するため、
  // tlsSocket のデータイベントを直接扱うことは通常ありません。
});

httpServer.listen(8445, () => {
  console.log('Socket.IO HTTPS サーバーがポート 8445 で起動しました。');
});

この例のポイント

「secureConnection」イベントは、基盤となる TLS 接続の確立を監視するために使用できますが、データの送受信は Socket.IO の提供する高レベルな API ('connection', 'message', 'emit' など) を通じて行います。
Socket.IO は WebSocket プロトコルを抽象化し、TLS/SSL 上でのセキュアな WebSocket 通信を容易に実現します。

「secureConnection」イベントは、安全な接続の確立を検知し、その接続に関する情報を取得したり、低レベルなデータストリームを直接操作したりする場合に非常に有効です。一方、より高レベルな抽象化を提供するフレームワークやライブラリを使用する場合、TLS/SSL の管理は内部的に行われ、開発者はアプリケーションのロジックに集中できるため、「secureConnection」イベントを直接扱う頻度は少なくなることがあります。

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