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

Copy
1<?php
2
3/**
4 * HMAC (Keyed-Hash Message Authentication Code) を生成および検証する機能を提供します。
5 *
6 * HMACはメッセージの完全性と認証を保証するために使用されます。
7 * データの暗号化（encrypt）や復号（decrypt）とは異なる概念であるため、
8 * 「HMACを復号する」という操作は存在せず、代わりに「HMACを検証する」ことで
9 * メッセージが改ざんされていないか、送信者が正しいかを確認します。
10 */
11final class HmacManager
12{
13    /**
14     * 指定されたデータと秘密鍵を使用してHMACを生成します。
15     *
16     * @param string $data 認証する元のデータ（メッセージなど）。
17     * @param string $key  HMACの生成と検証に使用する秘密鍵。
18     * @param string $algo 使用するハッシュアルゴリズム（例: 'sha256', 'md5'）。
19     * @return string 生成されたHMACの16進数表現文字列。
20     */
21    public static function generate(string $data, string $key, string $algo = 'sha256'): string
22    {
23        // hash_hmac関数は、データと秘密鍵からハッシュベースのメッセージ認証コードを計算します。
24        // 第4引数をfalseにすると、HMACは16進数文字列として返されます。
25        return hash_hmac($algo, $data, $key, false);
26    }
27
28    /**
29     * 提供されたHMACが、指定されたデータと秘密鍵に対して有効であるか検証します。
30     * これはデータを「復号」するのではなく、再計算したHMACと提供されたHMACを比較する操作です。
31     *
32     * @param string $data       検証対象のデータ。
33     * @param string $key        HMACの生成に使用された秘密鍵。
34     * @param string $receivedHmac 検証するHMAC（通常はデータと共に受信したもの）。
35     * @param string $algo       HMACの生成に使用されたハッシュアルゴリズム。
36     * @return bool HMACが有効な場合はtrue、そうでない場合はfalse。
37     */
38    public static function verify(string $data, string $key, string $receivedHmac, string $algo = 'sha256'): bool
39    {
40        // 受け取ったデータと秘密鍵を使って、再度HMACを計算します。
41        $calculatedHmac = self::generate($data, $key, $algo);
42
43        // 比較には hash_equals を使用します。これにより、タイミング攻撃を防ぐことができます。
44        // 提供されたHMACと再計算されたHMACが完全に一致すれば、データは改ざんされておらず、
45        // 秘密鍵も正しく、認証されたものであると判断できます。
46        return hash_equals($calculatedHmac, $receivedHmac);
47    }
48}
49
50// --- 使用例 ---
51
52// 実際のアプリケーションでは、この秘密鍵は安全な方法で管理し、十分に長く、予測困難なものにしてください。
53$secretKey = 'this_is_a_very_secret_key_for_hmac_authentication';
54$originalMessage = 'Hello, system engineers! This message needs to be authenticated.';
55$hashAlgorithm = 'sha256'; // 一般的に使用されるハッシュアルゴリズム
56
57echo "--- HMAC 生成と検証の例 ---" . PHP_EOL . PHP_EOL;
58
59// 1. メッセージに対するHMACの生成
60$generatedHmac = HmacManager::generate($originalMessage, $secretKey, $hashAlgorithm);
61echo "元のメッセージ: " . $originalMessage . PHP_EOL;
62echo "生成されたHMAC ({$hashAlgorithm}): " . $generatedHmac . PHP_EOL . PHP_EOL;
63
64// 2. HMACの検証（正常なケース）：メッセージと鍵が正しい場合
65echo "--- 正常な検証 ---" . PHP_EOL;
66if (HmacManager::verify($originalMessage, $secretKey, $generatedHmac, $hashAlgorithm)) {
67    echo "検証成功: メッセージとHMACは有効です。データは改ざんされていません。" . PHP_EOL;
68} else {
69    echo "検証失敗: エラーが発生しました。" . PHP_EOL;
70}
71echo PHP_EOL;
72
73// 3. HMACの検証（メッセージが改ざんされたケース）：メッセージが変更された場合
74echo "--- メッセージ改ざんの検証 ---" . PHP_EOL;
75$tamperedMessage = 'Hello, system engineers! This message has been *modified*.';
76if (HmacManager::verify($tamperedMessage, $secretKey, $generatedHmac, $hashAlgorithm)) {
77    echo "検証成功: (これは表示されるべきではありません。改ざんを検出できませんでした。)" . PHP_EOL;
78} else {
79    echo "検証失敗: メッセージが改ざんされています。HMACと一致しません。" . PHP_EOL;
80}
81echo PHP_EOL;
82
83// 4. HMACの検証（秘密鍵が異なるケース）：異なる鍵で検証しようとした場合
84echo "--- 異なる秘密鍵での検証 ---" . PHP_EOL;
85$wrongKey = 'an_incorrect_secret_key';
86if (HmacManager::verify($originalMessage, $wrongKey, $generatedHmac, $hashAlgorithm)) {
87    echo "検証成功: (これは表示されるべきではありません。不正な鍵を検出できませんでした。)" . PHP_EOL;
88} else {
89    echo "検証失敗: 秘密鍵が間違っているか、HMACが不正です。" . PHP_EOL;
90}
91echo PHP_EOL;
92
93// 5. HMACの検証（HMAC自体が不正なケース）：HMACの文字列自体が改ざんされた場合
94echo "--- 不正なHMAC文字列での検証 ---" . PHP_EOL;
95$invalidHmac = 'a_fake_and_invalid_hmac_string_1234567890';
96if (HmacManager::verify($originalMessage, $secretKey, $invalidHmac, $hashAlgorithm)) {
97    echo "検証成功: (これは表示されるべきではありません。不正なHMACを検出できませんでした。)" . PHP_EOL;
98} else {
99    echo "検証失敗: HMAC文字列自体が不正または改ざんされています。" . PHP_EOL;
100}
101
102?>

PHPのhash_hmac関数は、HMAC (Keyed-Hash Message Authentication Code) を生成するために使用される機能です。HMACは、メッセージが途中で改ざんされていないこと（データの完全性）と、送信者が本物であること（認証）を保証するセキュリティメカニズムです。重要な点として、HMACはデータを「暗号化（encrypt）」したり「復号（decrypt）」したりするものではなく、データの正当性を確認する目的で利用されます。

この関数は、引数として使用するハッシュアルゴリズム（例: 'sha256'）、認証したい元のデータ、そして秘密鍵を受け取ります。戻り値として、計算されたHMACを16進数形式の文字列で返します。

サンプルコードのHmacManagerクラスは、このhash_hmac関数を利用して、HMACの生成と検証のプロセスを具体的に示しています。generateメソッドは、データと秘密鍵、ハッシュアルゴリズムを使ってHMACを生成します。verifyメソッドは、受け取ったデータと秘密鍵からHMACを再計算し、提供されたHMACと比較することで、メッセージが改ざんされていないか、秘密鍵が正しいかを確認します。この比較には、セキュリティを考慮してタイミング攻撃を防ぐhash_equals関数が用いられています。

このように、hash_hmac関数とHMACの検証プロセスは、Webアプリケーションなどでデータの信頼性とセキュリティを確保するために非常に重要です。

Copy
1<?php
2
3/**
4 * HASH_HMAC 定数を使用して HMAC の生成とセキュアな比較方法を示します。
5 *
6 * HASH_HMAC は、hash_init() 関数に渡すフラグとして使用される PHP の定数です。
7 * これは、ハッシュコンテキストを HMAC (Keyed-Hash Message Authentication Code)
8 * モードで初期化することを示します。
9 *
10 * HMAC 自体には脆弱性はありませんが、HMAC の結果文字列を比較する方法によっては、
11 * タイミング攻撃の脆弱性が発生する可能性があります。
12 *
13 * 不安全な比較 (`==` または `!=`) は、比較が失敗するタイミングから、
14 * 攻撃者がハッシュのバイトごとの情報を推測する手がかりを与える可能性があります。
15 * これにより、秘密鍵の推測につながる可能性があります。
16 *
17 * hash_equals() 関数は、文字列の比較に要する時間が、文字列が異なる箇所や
18 * 最初の相違点に関わらず常に一定になるように設計されており、
19 * この種のタイミング攻撃を防ぐために推奨されます。
20 *
21 * @param string $data 検証するデータ文字列。
22 * @param string $secretKey HMAC 生成に使用する秘密鍵。
23 * @param string $providedHmac クライアントなどから提供された HMAC 文字列。
24 * @return bool HMAC が一致すれば true、そうでなければ false。
25 */
26function verifyHmacSecurely(string $data, string $secretKey, string $providedHmac): bool
27{
28    // HASH_HMAC 定数を使用し、HMAC モードでハッシュコンテキストを初期化します。
29    // 'sha256' は使用するハッシュアルゴリズムです。
30    $context = hash_init('sha256', HASH_HMAC, ['key' => $secretKey]);
31
32    // データでハッシュコンテキストを更新します。
33    hash_update($context, $data);
34
35    // 最終的な HMAC を取得します。
36    $expectedHmac = hash_final($context);
37
38    echo "検証データ: " . $data . PHP_EOL;
39    echo "秘密鍵: " . $secretKey . PHP_EOL;
40    echo "提供された HMAC: " . $providedHmac . PHP_EOL;
41    echo "期待される HMAC (生成済み): " . $expectedHmac . PHP_EOL;
42
43    // --- 不安全な比較 (本番環境での機密データには絶対に使用しないでください) ---
44    // この比較はタイミング攻撃に対して脆弱です。
45    // 異なる場所で文字列が異なる場合、比較が完了するまでの時間が異なる可能性があります。
46    if ($providedHmac === $expectedHmac) {
47        echo "不安全な比較: HMAC が一致します (認証に使用すると脆弱性があります)。" . PHP_EOL;
48    } else {
49        echo "不安全な比較: HMAC が一致しません。" . PHP_EOL;
50    }
51
52    echo "----------------------------------------------------" . PHP_EOL;
53
54    // --- hash_equals() を使用したセキュアな比較 (推奨) ---
55    // hash_equals() は定数時間で比較を実行するため、タイミング攻撃を防ぎます。
56    if (hash_equals($expectedHmac, $providedHmac)) {
57        echo "セキュアな比較: HMAC が一致します (認証に推奨)。" . PHP_EOL;
58        return true;
59    } else {
60        echo "セキュアな比較: HMAC が一致しません。" . PHP_EOL;
61        return false;
62    }
63}
64
65// --- 使用例 ---
66$secret = 'my_super_secure_application_key';
67$message = 'Sensitive message data to protect.';
68
69// クライアントから提供された有効な HMAC をシミュレート
70// 簡便のため、ここでは hash_hmac 関数を使用して生成しますが、
71// これは hash_init/update/final のシーケンスと等価です。
72$validHmac = hash_hmac('sha256', $message, $secret);
73
74echo "--- シナリオ 1: 有効な HMAC を提供 ---" . PHP_EOL;
75verifyHmacSecurely($message, $secret, $validHmac);
76echo PHP_EOL;
77
78// クライアントから提供された無効な HMAC (例: 改ざんされたもの) をシミュレート
79$invalidHmac_modified = 'f00b4r' . substr($validHmac, 6); // 先頭を改ざん
80$invalidHmac_wrong_data = hash_hmac('sha256', 'Different message.', $secret); // 異なるデータで生成
81
82echo "--- シナリオ 2: 無効な HMAC (先頭が改ざんされたもの) を提供 ---" . PHP_EOL;
83verifyHmacSecurely($message, $secret, $invalidHmac_modified);
84echo PHP_EOL;
85
86echo "--- シナリオ 3: 無効な HMAC (異なるデータで生成されたもの) を提供 ---" . PHP_EOL;
87verifyHmacSecurely($message, $secret, $invalidHmac_wrong_data);
88echo PHP_EOL;

PHPのHASH_HMAC定数は、hash_init()関数に渡すことで、ハッシュコンテキストをHMAC（Keyed-Hash Message Authentication Code）モードで初期化するために使用されます。HMACは、データの改ざん検知や認証に利用される技術です。

このサンプルコードは、HASH_HMAC定数を用いてHMACを生成し、その検証を行う際に発生しうるセキュリティ上の脆弱性であるタイミング攻撃への対策を示しています。verifyHmacSecurely関数は、$data（検証するデータ文字列）、$secretKey（HMAC生成に使用する秘密鍵）、$providedHmac（比較対象のHMAC文字列）を受け取ります。

コードでは、まず秘密鍵とデータから正しいHMACを生成します。その後、生成したHMACと提供されたHMACを比較する際、一般的な文字列比較演算子===を使用すると、比較にかかる時間が文字列の異なる箇所によって変動し、攻撃者がその時間差から秘密情報を推測する手がかりを得てしまう可能性があります。

この脆弱性を回避するため、hash_equals()関数を使用します。この関数は、比較する文字列が一致するかどうかにかかわらず、常に一定の時間で処理を完了するように設計されており、タイミング攻撃からシステムを保護できます。関数はHMACが一致すればtrueを、一致しなければfalseを返します。セキュリティを考慮する際には、hash_equals()を使用したセキュアな比較が強く推奨されます。