Node.js TLSサーバー証明書検証の要点：tls.checkServerIdentity()

2025-06-01

より詳しく見ていきましょう。

役割と目的

セキュリティ強化
この検証を行うことで、クライアントは偽のサーバーに誤って接続してしまうリスクを減らし、通信の安全性を高めることができます。
ホスト名検証
サーバー証明書には、その証明書が有効なドメイン名（またはワイルドカード）が記載されています。tls.checkServerIdentity() は、この証明書に記載された名前と、クライアントが接続しようとしているホスト名を比較します。
サーバー認証
TLS/SSL 通信の初期段階で、クライアントは接続先のサーバーが本当に意図したサーバーであるかを確認する必要があります。中間者攻撃（Man-in-the-Middle attack）を防ぐために不可欠なプロセスです。

動作の仕組み

TLS ハンドシェイク
クライアントが TLS でサーバーに接続を試みると、サーバーは自身のデジタル証明書をクライアントに送信します。
証明書の解析
クライアント側の TLS 実装（Node.js の tls モジュール）は、受け取った証明書を解析し、Subject Alternative Name (SAN) 拡張や Common Name (CN) フィールドに含まれるホスト名情報を抽出します。
tls.checkServerIdentity() の実行
Node.js は内部的に、またはユーザーが明示的に指定した場合、tls.checkServerIdentity() 関数を使用して、抽出されたホスト名情報と接続しようとしているホスト名を比較します。
検証結果
- 一致する場合
  証明書に記載されたホスト名が、接続先のホスト名と一致する場合、サーバーの識別は成功し、安全な通信が確立されます。
- 一致しない場合
  ホスト名が一致しない場合、サーバーの識別は失敗となり、通常は接続が中断され、エラーが発生します。これは、接続しようとしているサーバーが、提示した証明書の正当な所有者ではない可能性があることを示唆します。

カスタマイズ

Node.js では、tls.connect() や https.request() などのオプションで、独自の checkServerIdentity 関数を提供することができます。これにより、デフォルトのホスト名検証ロジックをカスタマイズしたり、追加の検証を行ったりすることが可能です。ただし、カスタムの検証ロジックを実装する際には、セキュリティ上のリスクを十分に理解し、慎重に行う必要があります。

例

例えば、あなたが https://example.com に接続しようとした場合、サーバー example.com は自身の証明書を送信します。tls.checkServerIdentity() は、その証明書に example.com が含まれているかどうかを確認します。もし証明書が malicious-site.com 用のものであれば、検証は失敗し、接続は拒否されます。

一般的なエラー

- 原因
  サーバー証明書に記載されているホスト名（または Subject Alternative Name (SAN)）が、接続しようとしているホスト名と一致しない場合に発生します。
- トラブルシューティング
  - 接続先のホスト名の確認
    コード内で指定している接続先のホスト名が正しいか確認してください。タイプミスや不要な空白が含まれていないか注意しましょう。
  - 証明書の確認
    サーバーの証明書の内容を確認し、接続したいホスト名が含まれているか確認してください。SANs (Subject Alternative Names) が正しく設定されているかどうかも重要です。
  - ワイルドカード証明書の確認
    ワイルドカード証明書 (*.example.com) を使用している場合、サブドメインが正しく一致しているか確認してください。例えば、*.example.com は test.example.com には有効ですが、another.sub.example.com や example.net には有効ではありません。
  - リダイレクトの確認
    HTTP から HTTPS へのリダイレクトが発生している場合、リダイレクト後のホスト名に対して証明書が有効である必要があります。
Error: unable to verify the first certificate (または類似の証明書検証エラー)
- 原因
  クライアントがサーバー証明書の発行元（CA: Certificate Authority）を信頼できない場合に発生します。これは、自己署名証明書を使用している場合や、信頼されていない CA によって署名された証明書を使用している場合に起こりやすいです。
- トラブルシューティング
  - 信頼された CA の設定
    tls.connect() や https.request() などのオプションで、ca (Certificate Authorities) を指定して、信頼する CA 証明書のリストを提供する必要があります。既知の CA の証明書は通常、Node.js に含まれていますが、カスタム CA や自己署名証明書の場合は明示的に指定する必要があります。
  - rejectUnauthorized: false (非推奨)
    セキュリティリスクを伴いますが、一時的な回避策として rejectUnauthorized: false オプションを設定することで、証明書の検証をスキップできます。本番環境では絶対に避けるべきです。
  - 中間証明書の確認
    サーバーが中間証明書を使用している場合、サーバー側で中間証明書が正しく設定・送信されているか確認してください。クライアント側も中間証明書を含めた CA 証明書チェーン全体を信頼できる必要があります。
カスタム checkServerIdentity 関数の実装ミス
- 原因
  tls.connect() などのオプションで独自の checkServerIdentity 関数を提供している場合、その実装に誤りがあると、意図しない検証結果になることがあります。
- トラブルシューティング
  - ロジックの再確認
    カスタム関数のロジックを慎重に再確認し、ホスト名の比較や追加の検証が正しく行われているか確認してください。
  - エラーハンドリング
    カスタム関数内で発生する可能性のあるエラーを適切に処理し、予期しない例外が発生しないように注意してください。
  - テスト
    様々なシナリオでカスタム関数を十分にテストし、意図した通りに動作するか確認してください。
ネットワークの問題
- 原因
  DNS の解決に失敗したり、ファイアウォールが通信をブロックしたりすると、そもそも正しいホスト名で接続を試みることができず、結果的に tls.checkServerIdentity() でエラーが発生することがあります。
- トラブルシューティング
  - DNS の確認
    ping コマンドなどで接続先のホスト名が正しく解決できるか確認してください。
  - ファイアウォールの確認
    クライアントとサーバー間の通信がファイアウォールによってブロックされていないか確認してください。

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

Wireshark などのネットワーク解析ツール
ネットワークのパケットをキャプチャして分析することで、TLS ハンドシェイクの過程や証明書のやり取りを詳細に確認できます。
OpenSSL などのツールを活用
openssl s_client -connect <ホスト名>:<ポート番号> などのコマンドラインツールを使用して、サーバーの証明書情報を直接確認したり、TLS ハンドシェイクをテストしたりすることができます。
詳細なログの出力
Node.js の TLS モジュールは、環境変数 NODE_DEBUG=tls を設定することで、詳細なログを出力できます。これにより、ハンドシェイクの過程や証明書の検証の詳細を確認できます。
エラーメッセージをよく読む
エラーメッセージには、問題の原因を特定するための重要な情報が含まれています。

デフォルトの checkServerIdentity() の使用
https モジュールなどを利用する際に、特に何も指定しなければ、Node.js 内部のデフォルトの checkServerIdentity() が自動的に使用されます。
カスタム checkServerIdentity() 関数の実装
tls.connect() のオプションとして独自の関数を提供し、ホスト名の検証ロジックをカスタマイズする方法を示します。

デフォルトの checkServerIdentity() の使用例

この例では、https モジュールを使用して安全なウェブサイトにリクエストを送信します。https モジュールはデフォルトで、サーバー証明書のホスト名を検証するために内部の checkServerIdentity() を使用します。

const https = require('https');

const options = {
  hostname: 'example.com', // 接続先のホスト名
  port: 443,
  path: '/',
  method: 'GET'
};

const req = https.request(options, (res) => {
  console.log('ステータスコード:', res.statusCode);
  res.on('data', (d) => {
    // データ処理
    // process.stdout.write(d);
  });
});

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

req.end();

このコードでは、特に checkServerIdentity オプションを指定していませんが、https.request はデフォルトでサーバー証明書の検証を行い、ホスト名が一致しない場合はエラーを発生させます。

カスタム checkServerIdentity() 関数の実装例

この例では、tls.connect() を使用して TLS ソケットを直接作成し、checkServerIdentity オプションに独自の関数を提供します。このカスタム関数内で、証明書の検証ロジックを自由に実装できます。

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

// サーバーの証明書 (例)
const serverCert = fs.readFileSync('server.crt');

const options = {
  host: 'localhost', // 接続先のホスト名
  port: 8000,
  // CA 証明書 (自己署名証明書の場合はサーバー証明書自身を指定)
  ca: [fs.readFileSync('ca.crt')],
  // カスタムの checkServerIdentity 関数
  checkServerIdentity: (host, cert) => {
    console.log('検証対象ホスト名:', host);
    console.log('サーバー証明書:', cert);

    // ここで独自の検証ロジックを実装します

    // 例: 証明書の Subject CN (Common Name) がホスト名と一致するか確認
    const subject = cert.subject;
    if (subject && subject.CN === host) {
      return undefined; // 検証成功 (エラーなし)
    } else {
      return new Error(`証明書の CN '${subject ? subject.CN : ''}' はホスト名 '${host}' と一致しません`);
    }

    // より複雑な検証 (SANs の確認など) を行うことも可能です
    // const subjectaltname = cert.subjectaltname;
    // ...
  }
};

const client = tls.connect(options, () => {
  console.log('TLS 接続が確立されました');
  client.write('Hello from client!\r\n');
});

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

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

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

解説

証明書オブジェクト (cert)
このオブジェクトには、サーバー証明書の様々な情報が含まれています。よく使用されるプロパティとしては、subject (証明書の主体情報、Common Name (CN) などを含む) や subjectaltname (Subject Alternative Names) などがあります。
カスタム関数の戻り値
- undefined: 検証が成功した場合に返します。
- Error オブジェクト: 検証が失敗した場合に、エラーオブジェクトを返します。このエラーオブジェクトのエラーメッセージが、接続エラーとして報告されます。
options.checkServerIdentity
カスタムのサーバー識別検証関数を指定します。この関数は、接続先のホスト名 (host) とサーバーの証明書オブジェクト (cert) を引数として受け取ります。
options.ca
信頼する CA 証明書の配列を指定します。自己署名証明書の場合は、サーバー証明書自身を指定することがあります。
options.port
接続先のポート番号を指定します。
options.host
接続先のホスト名を指定します。
tls.connect(options, callback)
TLS ソケットを確立するための関数です。options オブジェクトで様々な設定を行います。

自己署名証明書を使用する場合は、クライアント側でその証明書を信頼するように明示的に設定する必要があります (ca オプションなど)。
上記の例では、簡単な CN の比較のみを行っていますが、実際には SANs (Subject Alternative Names) の検証や、より厳密な証明書の検証を行うことが推奨されます。
カスタムの checkServerIdentity 関数を実装する際には、セキュリティ上のリスクを十分に理解し、慎重に行う必要があります。誤った実装は、中間者攻撃などのセキュリティ脆弱性を生み出す可能性があります。

rejectUnauthorized オプションの利用 (セキュリティ上の注意が必要)

tls.connect() や https.request() などのオプションで rejectUnauthorized: false を設定すると、サーバー証明書の検証を完全にスキップすることができます。これは tls.checkServerIdentity() 自体の処理を迂回する方法と言えます。

const https = require('https');

const options = {
  hostname: 'self-signed.example.com', // 自己署名証明書のサーバー
  port: 443,
  path: '/',
  method: 'GET',
  rejectUnauthorized: false // 証明書の検証をスキップ
};

const req = https.request(options, (res) => {
  console.log('ステータスコード:', res.statusCode);
  res.on('data', (d) => {
    process.stdout.write(d);
  });
});

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

req.end();

注意点
rejectUnauthorized: false は、中間者攻撃のリスクを高めるため、本番環境での使用は絶対に避けるべきです。このオプションは、自己署名証明書を使用する開発環境や、証明書の検証を意図的に行わない特別な場合にのみ限定的に使用するべきです。

servername オプションの明示的な設定

SNI (Server Name Indication) をサポートするサーバーに接続する場合、tls.connect() や https.request() の servername オプションを明示的に設定することが重要です。これは、サーバーが複数の仮想ホストで異なる証明書を提供している場合に、クライアントが正しい証明書を要求するために必要です。

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

const options = {
  host: 'example.com', // IP アドレスまたは解決可能なホスト名
  port: 443,
  servername: 'example.com', // SNI ヘッダーで送信するサーバー名
  ca: [fs.readFileSync('ca.crt')] // 信頼する CA 証明書
};

const socket = tls.connect(options, () => {
  console.log('TLS 接続が確立されました (SNI)');
  socket.write('GET / HTTP/1.1\r\nHost: example.com\r\n\r\n');
});

socket.on('data', (data) => {
  console.log('サーバーからのデータ:', data.toString());
  socket.end();
});

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

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

servername を正しく設定することで、サーバーは接続先のホスト名に対応した証明書をクライアントに提示し、デフォルトの checkServerIdentity() がその証明書を検証する際に正しい情報に基づいて判断できるようになります。

カスタムの証明書検証ロジックへの部分的な統合

完全にデフォルトの checkServerIdentity() を置き換えるのではなく、その結果に追加の検証ロジックを組み込むことも考えられます。例えば、デフォルトの検証が成功した後に追加のカスタムチェックを行うなどです。ただし、Node.js の標準 API では、デフォルトの checkServerIdentity() の結果を直接フックするような仕組みは提供されていません。カスタム関数内でデフォルトの検証ロジックを再現し、その結果に基づいて追加の処理を行う必要があります。これは複雑になるため、通常はデフォルトの動作で十分な場合が多いです。

特定の CA 証明書の信頼

ca オプションを使用して、信頼する CA 証明書のリストを明示的に指定することで、デフォルトの信頼された CA のリストを限定したり、追加したりすることができます。これにより、特定の組織が発行した証明書のみを信頼するように設定できます。

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

const options = {
  hostname: 'internal.example.com',
  port: 443,
  path: '/',
  method: 'GET',
  ca: [fs.readFileSync('internal-ca.crt')] // 内部 CA の証明書のみを信頼
};

const req = https.request(options, (res) => {
  // ...
});

// ...

証明書ピンニング (高度なテクニック)

証明書ピンニングは、クライアント側で特定のサーバーの証明書（またはその一部、例えば公開鍵のハッシュ値）をハードコードまたは設定ファイルに保存しておき、接続時にサーバーから提示された証明書と照合する手法です。これにより、たとえ信頼された CA によって発行された証明書であっても、ピンニングされた証明書と一致しない場合は接続を拒否することができます。Node.js の標準 API に直接的な証明書ピンニングの機能はありませんが、カスタムの checkServerIdentity 関数内でこのロジックを実装することは可能です。ただし、証明書のローテーションに対応する必要があるなど、運用上の複雑さが増します。

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