Node.js getFinished() 完全解説: ハンドシェイク監視とトラブルシューティング

2025-06-01

具体的には、以下の意味を持ちます。

false を返す場合
TLS/SSL ハンドシェイクがまだ完了していないか、または失敗したことを意味します。ハンドシェイクが完了するまでは、ソケットは安全な通信の準備ができていません。
true を返す場合
TLS/SSL ハンドシェイクが正常に完了し、安全な接続が確立されたことを意味します。この状態になって初めて、暗号化されたデータの送受信が可能になります。

どのような場面で tlsSocket.getFinished() が役立つか？

主に、TLS/SSL ハンドシェイクが完了した後に特定の処理を行いたい場合に利用されます。例えば、

ハンドシェイクの完了を監視し、タイムアウトなどのエラー処理を行いたい場合。
クライアント証明書などの接続情報が利用可能になった後に処理を行いたい場合。
安全な接続が確立されてからデータを送信したい場合。

簡単なコード例

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, (tlsSocket) => {
  console.log('クライアントが接続しました。');

  tlsSocket.on('secureConnect', () => {
    console.log('TLS/SSL ハンドシェイクが完了しました。getFinished():', tlsSocket.getFinished());
    tlsSocket.write('安全な接続が確立されました！\r\n');
  });

  tlsSocket.on('data', (data) => {
    console.log('受信データ:', data.toString());
  });

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

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

この例では、secureConnect イベントリスナーの中で tlsSocket.getFinished() を呼び出し、ハンドシェイクが完了したことを確認しています。secureConnect イベント自体がハンドシェイクの完了後に発火するため、この時点では通常 true が返ります。

以下に、tlsSocket.getFinished() が false を返す一般的な状況と、その原因およびトラブルシューティングの方法を説明します。

ハンドシェイクが完了していない

トラブルシューティング
- secureConnect イベントリスナーが発火しているか確認する。secureConnect イベントはハンドシェイクが正常に完了した後に発生する。
- ネットワーク接続が安定しているか確認する。ping コマンドなどで疎通を確認する。
- サーバーとクライアントの TLS/SSL 設定（プロトコルバージョン、暗号スイート、証明書など）が互いに互換性があるか確認する。
- サーバー側のログやエラーメッセージを確認し、ハンドシェイク失敗の原因を探る。
- クライアント側で error イベントリスナーを登録し、TLS/SSL 関連のエラーが発生していないか確認する。
原因
- 接続が確立されてから、ハンドシェイクに必要なネゴシエーションがまだ完了していない。
- ネットワークの遅延や不安定さにより、ハンドシェイクに必要なメッセージが途中で失われている。
- サーバーまたはクライアント側の設定ミスにより、互いに合意できる暗号スイートやプロトコルが見つからない。

証明書関連の問題

トラブルシューティング
- サーバー証明書の有効期限、発行者、ドメイン名などを確認する。
- 自己署名証明書を使用している場合は、クライアント側で明示的に信頼する必要がある。
- クライアント証明書が必要な場合は、クライアントが正しい証明書を設定し、送信しているか確認する。
- サーバー側で中間証明書が正しく設定されているか確認する。設定されていない場合は、サーバーの証明書と合わせて設定する必要がある。
- Node.js の tls モジュールのオプション (rejectUnauthorized) を一時的に false に設定し、証明書検証のエラーが発生しているか確認する（本番環境ではセキュリティ上のリスクがあるため推奨されません）。
原因
- サーバー証明書が無効である（期限切れ、自己署名証明書で信頼されていないなど）。
- クライアント証明書が必要な設定になっているが、クライアントが適切な証明書を提供していない。
- 中間証明書が正しく設定されていないため、証明書チェーンの検証に失敗している。

暗号スイートとプロトコルの不一致

トラブルシューティング
- サーバーとクライアントの TLS/SSL 設定を確認し、共通でサポートされている暗号スイートとプロトコルバージョンがあるか確認する。
- Node.js の tls.createServer() や tls.connect() のオプションで、ciphers や minVersion、maxVersion を適切に設定する。
原因
- サーバーとクライアントが、共通でサポートしている暗号スイートや TLS/SSL プロトコルバージョンがない。
- サーバーまたはクライアントの設定で、特定の暗号スイートやプロトコルバージョンのみを許可している。

ネットワークの問題

トラブルシューティング
- ファイアウォールの設定を確認し、TLS/SSL で使用されるポートが許可されているか確認する。
- プロキシサーバーを使用している場合は、プロキシサーバーの設定やログを確認する。
- ネットワーク接続の安定性を確認する。
原因
- ファイアウォールが TLS/SSL で使用されるポート（通常は 443）をブロックしている。
- プロキシサーバーが TLS/SSL 接続を適切に処理していない。
- ネットワークの不安定さにより、ハンドシェイクに必要なパケットが損失している。

タイムアウト

トラブルシューティング
- ネットワークの遅延を調査する。
- サーバーの負荷状況を監視する。
- Node.js の tlsSocket にタイムアウトを設定している場合は、適切な値に調整する。
原因
- ハンドシェイクが完了するまでに時間がかかりすぎ、タイムアウトが発生している。
- ネットワークの遅延が大きい場合や、サーバーの負荷が高い場合に発生しやすい。

tlsSocket.getFinished() が false の場合の一般的な流れ

connect イベント
ソケット接続が開始される。
ハンドシェイク開始
TLS/SSL ハンドシェイクが自動的に開始される。この時点では getFinished() は false を返す可能性が高い。
エラー発生 (もしあれば)
ハンドシェイク中にエラーが発生すると、error イベントが発行される。このエラーの原因を特定し、解決する必要がある。この場合、secureConnect イベントは発行されない。
secureConnect イベント
ハンドシェイクが正常に完了すると、secureConnect イベントが発行される。この時点で getFinished() は true を返す。
データ送受信
安全な接続上でデータの送受信が可能になる。
end または close イベント
接続が終了する。

tlsSocket.getFinished() が false のままで secureConnect イベントも発生しない場合は、上記のような原因を一つずつ確認していくことがトラブルシューティングの基本的なアプローチとなります。

例1: サーバー側でのハンドシェイク完了後の処理

この例では、TLS サーバーがクライアントからの接続を受け付け、ハンドシェイクが完了した後にメッセージを送信します。secureConnect イベントリスナー内で getFinished() を確認しています。

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, (tlsSocket) => {
  console.log('クライアントが接続しました。');

  tlsSocket.on('secureConnect', () => {
    console.log('TLS/SSL ハンドシェイク完了 (secureConnect): getFinished() =', tlsSocket.getFinished());
    if (tlsSocket.getFinished()) {
      tlsSocket.write('ようこそ、安全な接続が確立されました！\r\n');
    } else {
      console.log('エラー: ハンドシェイクは完了していません。');
    }
  });

  tlsSocket.on('data', (data) => {
    console.log('受信データ:', data.toString());
  });

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

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

このコードでは、secureConnect イベントが発生した時点で tlsSocket.getFinished() を呼び出し、true であれば安全な接続が確立されたと判断してメッセージを送信しています。通常、secureConnect イベントはハンドシェイク完了後に発生するため、この時点では true が返ります。しかし、念のため確認することで、より堅牢な処理が記述できます。

例2: クライアント側でのハンドシェイク完了の確認

この例では、TLS クライアントがサーバーに接続し、ハンドシェイクが完了した後にデータを送信します。

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

const options = {
  host: 'localhost',
  port: 8000,
  ca: [fs.readFileSync('./server-cert.pem')], // サーバー証明書を信頼するための設定 (自己署名証明書の場合など)
};

const client = tls.connect(options, () => {
  console.log('サーバーに接続しました。');
  console.log('TLS/SSL ハンドシェイク完了 (connect callback): getFinished() =', client.getFinished());
  if (client.getFinished()) {
    client.write('これは安全なデータです！\r\n');
  } else {
    console.log('エラー: ハンドシェイクは完了していません。');
  }
});

client.on('data', (data) => {
  console.log('受信データ:', data.toString());
  client.end();
});

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

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

クライアント側の tls.connect() のコールバック関数内でも client.getFinished() を呼び出すことで、ハンドシェイクが完了したかを確認できます。

例3: ハンドシェイク完了前に getFinished() を呼び出す

この例では、意図的にハンドシェイクが完了する前に getFinished() を呼び出し、その時点での状態を確認します。これは通常の使用方法ではありませんが、理解を深めるために役立ちます。

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

const options = {
  host: 'localhost',
  port: 8000,
  ca: [fs.readFileSync('./server-cert.pem')],
};

const client = tls.connect(options, () => {
  console.log('サーバーに接続しました (connect callback)。');
  // この時点ではまだハンドシェイクが完了していない可能性がある
  console.log('ハンドシェイク完了前 (connect callback): getFinished() =', client.getFinished());
});

client.on('secureConnect', () => {
  console.log('TLS/SSL ハンドシェイク完了 (secureConnect): getFinished() =', client.getFinished());
  client.write('安全なメッセージ\r\n');
  client.end();
});

client.on('data', (data) => {
  console.log('受信データ:', data.toString());
});

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

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

connect イベントのコールバック関数は、ソケットが接続された直後に実行されるため、まだ TLS/SSL ハンドシェイクが完了していない可能性があります。したがって、この時点で getFinished() を呼び出すと false が返ることがあります。一方、secureConnect イベントリスナー内では、ハンドシェイクが完了しているため true が返ります。

例4: エラー処理と getFinished() の組み合わせ

ハンドシェイクが失敗した場合、secureConnect イベントは発行されません。エラーイベントを監視し、その際に getFinished() の状態を確認することで、エラー発生時のハンドシェイクの状態を把握できます。

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

const options = {
  host: 'invalid-host', // 存在しないホストを指定してエラーを発生させる
  port: 8000,
  // ca: [fs.readFileSync('./server-cert.pem')],
};

const client = tls.connect(options, () => {
  console.log('サーバーに接続しました (connect callback)。');
  console.log('connect callback 内の getFinished():', client.getFinished());
});

client.on('secureConnect', () => {
  console.log('TLS/SSL ハンドシェイク完了 (secureConnect): getFinished() =', client.getFinished());
  client.write('安全なメッセージ\r\n');
  client.end();
});

client.on('data', (data) => {
  console.log('受信データ:', data.toString());
});

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

client.on('error', (err) => {
  console.error('エラーが発生しました:', err);
  console.log('エラー発生時の getFinished():', client.getFinished());
});

この例では、存在しないホストに接続しようとしているため、通常は error イベントが発生します。error イベントリスナー内で getFinished() を呼び出すと、ハンドシェイクが完了していないため false が返る可能性が高いです。

secureConnect イベントの利用 (最も一般的)

最も一般的で推奨される方法は、TLSSocket オブジェクトから発行される 'secureConnect' イベントをリッスンすることです。このイベントは、TLS/SSL ハンドシェイクが正常に完了した後に一度だけ発行されます。したがって、'secureConnect' イベントリスナー内のコードは、安全な接続が確立されたことを前提として実行できます。

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

const options = {
  host: 'localhost',
  port: 8000,
  ca: [fs.readFileSync('./server-cert.pem')],
};

const client = tls.connect(options, () => {
  console.log('TCP 接続が確立しました。');
});

client.on('secureConnect', () => {
  console.log('TLS/SSL ハンドシェイクが完了しました！');
  // ここで安全な通信を開始できます
  client.write('安全なデータを送信します。\r\n');
});

client.on('data', (data) => {
  console.log('受信データ:', data.toString());
  client.end();
});

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

この方法の利点は、イベント駆動型であり、ポーリングのように定期的に状態を確認する必要がないことです。ハンドシェイクが完了したときに自然に処理が実行されます。

tlsSocket.authorized プロパティの利用

TLSSocket オブジェクトには authorized という読み取り専用のプロパティがあります。これは、リモートピアの証明書が検証に成功したかどうかを示すブール値を保持します。ハンドシェイクが正常に完了し、証明書の検証も成功した場合、authorized は true になります。

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

const options = {
  host: 'localhost',
  port: 8000,
  ca: [fs.readFileSync('./server-cert.pem')],
  rejectUnauthorized: true, // 証明書の検証を必須にする
};

const client = tls.connect(options, () => {
  console.log('TCP 接続が確立しました。');
});

client.on('secureConnect', () => {
  console.log('TLS/SSL ハンドシェイク完了。認証結果:', client.authorized);
  if (client.authorized) {
    client.write('認証成功、安全なデータを送信します。\r\n');
  } else {
    console.error('認証失敗:', client.authorizationError);
  }
});

client.on('data', (data) => {
  console.log('受信データ:', data.toString());
  client.end();
});

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

authorized プロパティは、単にハンドシェイクが完了しただけでなく、証明書の検証が成功したかどうかも示してくれるため、よりセキュリティに配慮したプログラミングに役立ちます。rejectUnauthorized: true オプションを設定している場合、authorized が true であれば、ハンドシェイクと証明書検証の両方が成功したことが保証されます。

tlsSocket.handshakeTimeout の監視 (間接的な方法)

tlsSocket.handshakeTimeout プロパティを設定することで、ハンドシェイクが指定された時間内に完了しない場合にタイムアウトエラーを発生させることができます。これは直接的に完了状態を知る方法ではありませんが、タイムアウトが発生しなかった場合は、通常ハンドシェイクが完了していると推測できます。

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

const options = {
  host: 'localhost',
  port: 8000,
  ca: [fs.readFileSync('./server-cert.pem')],
  handshakeTimeout: 5000, // 5秒でタイムアウト
};

const client = tls.connect(options, () => {
  console.log('TCP 接続が確立しました。');
});

client.on('secureConnect', () => {
  console.log('TLS/SSL ハンドシェイクが完了しました！');
  client.write('安全なデータを送信します。\r\n');
});

client.on('data', (data) => {
  console.log('受信データ:', data.toString());
  client.end();
});

client.on('timeout', () => {
  console.error('TLS/SSL ハンドシェイクがタイムアウトしました。');
  client.destroy();
});

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

この方法は、ハンドシェイクが正常に完了しなかった場合の処理を実装するのに役立ちますが、完了したことを直接的に知るための代替手段としてはやや間接的です。

Promise ベースのラッパーの利用 (非標準)

Node.js の tls モジュールはデフォルトではコールバックベースのAPIを提供していますが、util.promisify を利用したり、サードパーティのライブラリを使用したりすることで、Promise ベースのAPIにラップすることができます。これにより、async/await を使ってハンドシェイクの完了をより簡潔に待つことができます。

const tls = require('tls');
const fs = require('fs');
const { promisify } = require('util');

async function connectTLS(options) {
  return new Promise((resolve, reject) => {
    const socket = tls.connect(options, () => {
      resolve(socket);
    });
    socket.on('error', reject);
  });
}

async function main() {
  const options = {
    host: 'localhost',
    port: 8000,
    ca: [fs.readFileSync('./server-cert.pem')],
  };

  try {
    const client = await connectTLS(options);
    console.log('TLS/SSL ハンドシェイクが完了しました (Promise)。');
    client.write('安全なデータを送信します。\r\n');
    client.on('data', (data) => {
      console.log('受信データ:', data.toString());
      client.end();
    });
    client.on('end', () => {
      console.log('接続を閉じました。');
    });
  } catch (err) {
    console.error('エラー:', err);
  }
}

main();

この例では、tls.connect を Promise でラップした connectTLS 関数を作成し、async/await を使用してハンドシェイクの完了を待っています。Promise が解決されれば、ハンドシェイクが成功したとみなすことができます。

tlsSocket.getFinished() はハンドシェイクの完了状態を直接的に確認する手段ですが、より一般的で推奨される方法は、'secureConnect' イベントをリッスンすることです。また、tlsSocket.authorized プロパティを利用することで、ハンドシェイクの完了と証明書の検証の成功を同時に確認できます。タイムアウト設定や Promise ベースのラッパーも、間接的またはよりモダンな方法として利用できます。

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