Webエンジニア向けプログラミング解説動画をYouTubeで配信中!
▶ チャンネル登録はこちら

【PHP8.x】CURLE_SSL_PINNEDPUBKEYNOTMATCH定数の使い方

CURLE_SSL_PINNEDPUBKEYNOTMATCH定数の使い方について、初心者にもわかりやすく解説します。

作成日: 更新日:

基本的な使い方

CURLE_SSL_PINNEDPUBKEYNOTMATCH定数は、PHPのcURL拡張機能において、SSL/TLS通信中に発生する特定のエラーを表す定数です。この定数は、通信相手のサーバーの公開鍵(Public Key)のピンニング(Pinning)が失敗した際に返されるエラーコードの一つとなります。

公開鍵ピンニングとは、セキュアな通信を行う際に、特定のサーバーが提示する公開鍵、またはその公開鍵のハッシュ値が、あらかじめクライアント側(アプリケーション側)に設定された「正しい」とされている情報と一致するかどうかを検証するセキュリティ機能です。これにより、悪意のある第三者が正規のサーバーになりすまして通信を傍受する「中間者攻撃(Man-in-the-Middle attack)」を防ぐことができます。

CURLE_SSL_PINNEDPUBKEYNOTMATCH定数が示すのは、cURLが通信相手のサーバーから受け取った公開鍵の情報が、事前にCURLOPT_PINNEDPUBLICKEYオプションなどで設定されたピン留めされた公開鍵の情報と一致しなかった状況です。このエラーが発生した場合、通信の信頼性が確保できないため、cURLは安全のために通信を中断します。開発者は、curl_errno()関数やcurl_error()関数を使用してこのエラーコードを検出し、適切なエラーハンドリングを行うことで、アプリケーションのセキュリティを向上させることができます。この定数は、SSL/TLS通信のセキュリティ検証において非常に重要な役割を果たします。

構文(syntax)

1<?php
2echo CURLE_SSL_PINNEDPUBKEYNOTMATCH;
3?>

引数(parameters)

引数なし

引数はありません

戻り値(return)

int

この定数は、SSL証明書の公開鍵が期待されるものと一致しない場合に返される整数値です。

サンプルコード

PHP: CURLE_SSL_PINNEDPUBKEYNOTMATCH エラーを検証する

1<?php
2
3/**
4 * cURLリクエストを実行し、SSL公開鍵ピンニングエラーをチェックします。
5 *
6 * この関数は、指定されたURLに対してcURLリクエストを試み、
7 * 特に CURLE_SSL_PINNEDPUBKEYNOTMATCH エラーが発生した場合の処理を示します。
8 * 公開鍵ピンニングは、サーバーのSSL証明書が既知の公開鍵に一致するかを検証するセキュリティ機能です。
9 *
10 * @param string $url リクエストを送信するURL。HTTPSである必要があります。
11 * @param string $pinnedPublicKeySha256 (オプション) 期待される公開鍵のSHA256ハッシュ文字列。
12 *                                      "sha256//<base64_encoded_hash>" の形式で指定します。
13 *                                      不正な値を指定すると、ピンニングエラーが発生する可能性があります。
14 * @return string|false レスポンスの本文、またはエラーが発生した場合は false を返します。
15 */
16function performCurlRequestAndCheckPinningError(string $url, string $pinnedPublicKeySha256 = ''): string|false
17{
18    // cURLセッションを初期化
19    $ch = curl_init();
20
21    // リクエストURLを設定
22    curl_setopt($ch, CURLOPT_URL, $url);
23
24    // 転送内容を文字列として取得し、直接出力しないように設定
25    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
26
27    // SSL証明書の検証を有効にする(セキュリティのために推奨されます)
28    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
29    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2); // ホスト名の検証も行う
30
31    // 公開鍵ピンニングを設定する場合
32    if (!empty($pinnedPublicKeySha256)) {
33        // CURLOPT_PINNEDPUBLICKEY オプションを設定
34        // 指定されたハッシュとサーバーの公開鍵が一致しない場合、エラーが発生します。
35        // 例: "sha256//AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=" (これは不正なダミーです)
36        echo "SSL公開鍵ピンニングを有効にしてリクエストを試みます。期待ハッシュ: {$pinnedPublicKeySha256}\n";
37        curl_setopt($ch, CURLOPT_PINNEDPUBLICKEY, $pinnedPublicKeySha256);
38    } else {
39        echo "SSL公開鍵ピンニングなしでリクエストを試みます。\n";
40    }
41
42    // cURLリクエストを実行
43    $response = curl_exec($ch);
44
45    // cURLエラーが発生したかどうかを確認
46    if (curl_errno($ch)) {
47        $error_code = curl_errno($ch);
48        $error_message = curl_error($ch);
49
50        // エラーコードが CURLE_SSL_PINNEDPUBKEYNOTMATCH と一致するか確認
51        if ($error_code === CURLE_SSL_PINNEDPUBKEYNOTMATCH) {
52            echo "------------------------------------------------------------------\n";
53            echo "【検出】CURLE_SSL_PINNEDPUBKEYNOTMATCH エラーが発生しました。\n";
54            echo "コード: " . $error_code . "\n";
55            echo "メッセージ: " . $error_message . "\n";
56            echo "これは、サーバーのSSL証明書に含まれる公開鍵が、\n";
57            echo "CURLOPT_PINNEDPUBLICKEY で指定された期待されるハッシュと一致しなかったことを意味します。\n";
58            echo "これにより、中間者攻撃(Man-in-the-Middle attacks)を防ぐことができます。\n";
59            echo "------------------------------------------------------------------\n";
60        } else {
61            echo "cURLリクエスト中に別のエラーが発生しました。\n";
62            echo "コード: " . $error_code . "\n";
63            echo "メッセージ: " . $error_message . "\n";
64        }
65        curl_close($ch);
66        return false;
67    }
68
69    // cURLセッションを閉じる
70    curl_close($ch);
71
72    echo "cURLリクエストが成功しました。\n";
73    return $response;
74}
75
76// === サンプルコードの使用例 ===
77
78// 実際のウェブサイト(HTTPS)
79$targetUrl = "https://www.google.com";
80
81// 1. ピンニングなしでのリクエスト例
82echo "--- 1. SSL公開鍵ピンニングなしでのリクエスト ---\n";
83$resultNoPinning = performCurlRequestAndCheckPinningError($targetUrl);
84if ($resultNoPinning !== false) {
85    echo "レスポンスの最初の100文字: " . substr($resultNoPinning, 0, 100) . "...\n\n";
86} else {
87    echo "ピンニングなしのリクエストは失敗しました。\n\n";
88}
89
90
91// 2. 不正な公開鍵ハッシュでのリクエスト例 (エラー発生を意図)
92// 注意: このハッシュは 'www.google.com' には一致しないダミー値です。
93// 正しいハッシュは、対象サーバーの証明書から抽出する必要があります。
94// フォーマットは "sha256//<Base64エンコードされたSHA256ハッシュ>" です。
95$badPinnedPublicKey = "sha256//AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="; // 偽のハッシュ
96
97echo "--- 2. 不正なSSL公開鍵ハッシュでのリクエスト (エラー発生を意図) ---\n";
98$resultWithBadPinning = performCurlRequestAndCheckPinningError($targetUrl, $badPinnedPublicKey);
99if ($resultWithBadPinning !== false) {
100    echo "レスポンスの最初の100文字: " . substr($resultWithBadPinning, 0, 100) . "...\n\n";
101} else {
102    echo "不正なピンニングハッシュでのリクエストは失敗しました。\n\n";
103}
104
105// 3. CURLE_SSL_PINNEDPUBKEYNOTMATCH 定数の値を確認
106echo "--- 3. CURLE_SSL_PINNEDPUBKEYNOTMATCH 定数の値 ---\n";
107echo "CURLE_SSL_PINNEDPUBKEYNOTMATCH の値は: " . CURLE_SSL_PINNEDPUBKEYNOTMATCH . " (int型)\n";
108echo "この値は、cURLが公開鍵ピンニング検証に失敗した際に返すエラーコードです。\n";
109

CURLE_SSL_PINNEDPUBKEYNOTMATCHは、PHPのcURL拡張機能が提供する定数で、SSL公開鍵ピンニングの検証が失敗した際に発生するエラーコードを表します。この定数の戻り値はint型です。

サンプルコードでは、performCurlRequestAndCheckPinningError関数を用いて、指定されたURLに対してcURLリクエストを実行し、このエラーが発生する状況を確認しています。この関数は、リクエストを送信するURLと、オプションとして期待される公開鍵のSHA256ハッシュ文字列を引数に取ります。成功時にはサーバーからのレスポンス文字列を、失敗時にはfalseを返します。

関数内では、curl_init()でcURLセッションを初期化し、CURLOPT_URLでURLを設定後、CURLOPT_PINNEDPUBLICKEYオプションに期待する公開鍵のハッシュを設定することで、SSL公開鍵ピンニングを有効にしています。公開鍵ピンニングは、サーバーのSSL証明書に含まれる公開鍵が、あらかじめ指定された既知の公開鍵と一致するかを検証するセキュリティ機能です。

curl_exec()でリクエストを実行した後、curl_errno()でエラーの有無を確認します。もしエラーが発生し、そのエラーコードがCURLE_SSL_PINNEDPUBKEYNOTMATCHと一致した場合、これは指定した公開鍵ハッシュとサーバーの公開鍵が一致しなかったことを示しています。この機能により、悪意のある中間者攻撃を防ぐことが可能になります。サンプルコードの実行例では、不正なピンニングハッシュを指定した場合にこのエラーが検出される様子が示されています。

公開鍵ピンニングは、CURLOPT_PINNEDPUBLICKEYオプションで指定するハッシュ値とサーバーの公開鍵が一致するかを検証し、セキュリティを強化する機能です。このハッシュ値は対象サーバーから正確に取得し、sha256//で始まるBase64エンコードされた正しい形式で設定する必要があります。誤ったハッシュ値を使用すると、正当な通信でもCURLE_SSL_PINNEDPUBKEYNOTMATCHエラーが発生し、アクセスができなくなりますので注意してください。また、サーバーのSSL証明書が更新された場合は、ピンニング設定も忘れずに最新の状態へ更新することが重要です。このエラーはピンニング失敗を意味するため、他のcURLエラーとは区別して適切に対応してください。基本的なSSL検証であるCURLOPT_SSL_VERIFYPEERとCURLOPT_SSL_VERIFYHOSTは、セキュリティのために常に有効にすることが推奨されます。

PHP cURL SSLピンニングエラーを検出する

1<?php
2
3/**
4 * cURLを使用してSSL公開鍵ピンニングのエラーを処理する例。
5 *
6 * この関数は、指定されたURLに対してcURLリクエストを送信し、
7 * CURLOPT_PINNEDPUBLICKEYオプションで意図的に間違った公開鍵ハッシュを設定することで、
8 * CURLE_SSL_PINNEDPUBKEYNOTMATCHエラーを発生させ、その処理方法を示します。
9 *
10 * @param string $url リクエストを送信するURL。
11 * @param string $pinned_public_key ピンニングする公開鍵ハッシュ(sha256//...形式)。
12 *                                  このサンプルでは意図的に間違った値を指定し、エラーを発生させます。
13 */
14function handleCurlSslPinnedPubKeyError(string $url, string $pinned_public_key): void
15{
16    // cURLセッションを初期化
17    $ch = curl_init();
18
19    // cURLオプションを設定
20    curl_setopt($ch, CURLOPT_URL, $url); // リクエスト先のURL
21    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // 戻り値を文字列で取得
22    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true); // SSLピアの検証を有効にする (推奨)
23    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2); // ホスト名の検証を有効にする (推奨)
24
25    // SSL公開鍵ピンニングを設定
26    // ここではデモンストレーションのため、意図的に間違った公開鍵ハッシュを設定しています。
27    // 実際のアプリケーションでは、通信相手の正しい公開鍵ハッシュを設定してください。
28    curl_setopt($ch, CURLOPT_PINNEDPUBLICKEY, $pinned_public_key);
29
30    // cURLリクエストを実行
31    $response = curl_exec($ch);
32
33    // エラーが発生したかチェック
34    if (curl_errno($ch)) {
35        $errorCode = curl_errno($ch);
36        $errorMessage = curl_error($ch);
37
38        echo "cURLエラーが発生しました: {$errorMessage} (コード: {$errorCode})\n";
39
40        // エラーコードが CURLE_SSL_PINNEDPUBKEYNOTMATCH と一致するか確認
41        if ($errorCode === CURLE_SSL_PINNEDPUBKEYNOTMATCH) {
42            echo "エラー: SSL公開鍵ピンニングが失敗しました。設定された公開鍵ハッシュがサーバの鍵と一致しません。\n";
43        } else {
44            echo "その他のcURL SSL接続エラーが発生しました。\n";
45        }
46    } else {
47        // エラーがない場合
48        echo "cURLリクエストが成功しました。\n";
49        // echo "レスポンス:\n" . substr($response, 0, 200) . "...\n"; // レスポンスの一部を表示
50    }
51
52    // cURLセッションを閉じる
53    curl_close($ch);
54}
55
56// 使用例:
57// GoogleのURLを使用しますが、公開鍵ピンニングは意図的に間違ったハッシュを指定します。
58// これにより、CURLE_SSL_PINNEDPUBKEYNOTMATCHエラーが発生するはずです。
59$targetUrl = 'https://www.google.com';
60
61// 意図的に無効なSHA256ハッシュを設定
62// 実際の鍵は'sha256//<Base64エンコードされたSHA256ハッシュ>'の形式です。
63// この例では、架空の無効なハッシュを使用しています。
64$invalidPinnedPublicKey = 'sha256//AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=';
65
66// 関数を実行
67echo "SSL公開鍵ピンニングエラーのデモンストレーションを開始します。\n";
68handleCurlSslPinnedPubKeyError($targetUrl, $invalidPinnedPublicKey);
69echo "デモンストレーションが終了しました。\n";
70
71?>

このPHPサンプルコードは、cURLを用いてSSL公開鍵ピンニングを行う際に発生する可能性があるCURLE_SSL_PINNEDPUBKEYNOTMATCHエラーの検出と処理方法を、初心者にも分かりやすく示すものです。CURLE_SSL_PINNEDPUBKEYNOTMATCHは、PHP 8のcURL拡張機能が提供する定数で、接続しようとするサーバーのSSL公開鍵ハッシュが、あらかじめ指定した期待値と一致しない場合に、cURLが返すエラーコード(整数値)を示します。

コード内のhandleCurlSslPinnedPubKeyError関数は、指定されたURL($url)に対してcURLリクエストを送信します。この関数では、デモンストレーションのために意図的に間違った公開鍵ハッシュ($pinned_public_key)をCURLOPT_PINNEDPUBLICKEYオプションに設定しています。これにより、cURLがサーバーの実際の公開鍵と設定されたハッシュが一致しないことを検知し、CURLE_SSL_PINNEDPUBKEYNOTMATCHエラーを発生させます。

リクエスト実行後、curl_errno()関数で取得したエラーコードがCURLE_SSL_PINNEDPUBKEYNOTMATCH定数と一致するかを比較することで、具体的にどのエラーが発生したのかを判別しています。この関数は具体的な値を返さず(void)、処理の結果やエラーメッセージをコンソールに出力します。システム開発において、このようなセキュリティ関連のエラーを正確に識別し、適切な対応を行うことは非常に重要です。

このサンプルコードは、意図的に間違った公開鍵を設定することでエラー発生時の処理方法を示すものです。本番環境では、CURLOPT_PINNEDPUBLICKEYには通信先のサーバから取得した正しい公開鍵のハッシュをsha256//<Base64エンコードされたSHA256ハッシュ>の形式で指定してください。誤った鍵を設定すると、CURLE_SSL_PINNEDPUBKEYNOTMATCHエラーが発生し、安全な接続が確立できなくなります。また、CURLOPT_SSL_VERIFYPEERとCURLOPT_SSL_VERIFYHOSTは、常に有効にしておくことでセキュリティが強化され、中間者攻撃などのリスクを防ぎます。このエラーは設定した鍵とサーバの鍵が不一致であることを意味するため、特に正確な鍵管理が重要です。

関連コンテンツ

関連IT用語

関連プログラミング言語