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

Copy
1<?php
2
3/**
4 * PHP Sodium拡張機能を使用してパスワードをハッシュ化し、検証する一連の流れを実演します。
5 * 主に SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13 定数の使用を示します。
6 * システムエンジニアを目指す初心者向けに、各ステップを簡潔に解説します。
7 */
8function demonstrateSodiumPasswordHashing(): void
9{
10    // 安全に扱うべきパスワードの例
11    $password = 'mySuperSecretPassword123!';
12
13    echo "元のパスワード: " . $password . "\n\n";
14
15    // ----------------------------------------------------
16    // ステップ1: パスワードのハッシュ化 (データベース保存のため)
17    // ----------------------------------------------------
18
19    // `sodium_crypto_pwhash_str()` 関数を使ってパスワードを安全なハッシュ形式に変換します。
20    // このハッシュは、データベースなどに保存するのに適しています。
21    //
22    // 引数:
23    // 1. $password: ハッシュ化したい元のパスワード。
24    // 2. SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE: 演算回数を指定する定数。セキュリティとパフォーマンスのバランスを取ります。
25    // 3. SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE: 使用メモリ量を指定する定数。こちらもセキュリティとパフォーマンスのバランスを取ります。
26    // 4. SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13: 使用するハッシュアルゴリズムを指定する定数。
27    //    これは、NIST (米国国立標準技術研究所) が推奨する最新かつ強力なパスワードハッシュアルゴリズムの一つである
28    //    Argon2id バージョン1.3 を選択します。これにより、ブルートフォース攻撃などに対する耐性が向上します。
29    $hashedPassword = sodium_crypto_pwhash_str(
30        $password,
31        SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE, // 時間コスト (演算回数)
32        SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE, // メモリコスト (使用メモリ量)
33        SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13     // アルゴリズム: Argon2id 1.3
34    );
35
36    // ハッシュ化に失敗した場合
37    if ($hashedPassword === false) {
38        echo "エラー: パスワードのハッシュ化に失敗しました。PHP Sodium拡張が正しく設定されているか確認してください。\n";
39        return;
40    }
41
42    echo "生成されたハッシュ: " . $hashedPassword . "\n\n";
43
44    // ----------------------------------------------------
45    // ステップ2: ハッシュ化されたパスワードの検証 (ログイン時など)
46    // ----------------------------------------------------
47
48    // `sodium_crypto_pwhash_str_verify()` 関数を使って、
49    // 入力されたパスワードが以前にハッシュ化されたものと一致するかを確認します。
50    //
51    // 引数:
52    // 1. $hashedPassword: データベースなどに保存されているハッシュ済みのパスワード。
53    // 2. $password: ユーザーが入力した（検証したい）元のパスワード。
54    $isValid = sodium_crypto_pwhash_str_verify($hashedPassword, $password);
55
56    if ($isValid) {
57        echo "検証結果: パスワードが一致しました。ログイン成功！\n";
58    } else {
59        echo "検証結果: パスワードが一致しませんでした。ログイン失敗。\n";
60    }
61
62    // 誤ったパスワードでの検証例
63    $wrongPassword = 'thisIsWrongPassword';
64    echo "\n誤ったパスワード ('" . $wrongPassword . "') で検証します。\n";
65    $isInvalid = sodium_crypto_pwhash_str_verify($hashedPassword, $wrongPassword);
66
67    if (!$isInvalid) { // 期待される結果は false (一致しない)
68        echo "検証結果: パスワードが一致しませんでした。正しい動作です。\n";
69    } else {
70        echo "検証結果: エラー - 誤ったパスワードで一致してしまいました。\n";
71    }
72}
73
74// 関数を実行して、一連の処理を確認します。
75demonstrateSodiumPasswordHashing();

このサンプルコードは、PHPのSodium拡張機能を利用してパスワードを安全にハッシュ化し、そのハッシュを検証する一連の流れを実演しています。特に、パスワードハッシュアルゴリズムとして推奨されるArgon2idバージョン1.3を選択するための定数、SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13の使用方法に焦点を当てています。

まず、sodium_crypto_pwhash_str()関数を使って元のパスワードをハッシュ化します。この関数は、元のパスワードの他に、演算回数や使用メモリ量といったセキュリティパラメータ、そしてSODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13定数で指定されるハッシュアルゴリズム（Argon2idバージョン1.3）を引数として受け取ります。これにより、ブルートフォース攻撃などに対して非常に強い耐性を持つ、安全なハッシュ値（文字列）が生成され、これをデータベースなどに保存します。処理が失敗した場合はfalseを戻り値として返します。

次に、sodium_crypto_pwhash_str_verify()関数を用いて、ユーザーが入力したパスワードが、保存されているハッシュ値と一致するかを検証します。この関数は、保存済みのハッシュ値とユーザー入力のパスワードの二つを引数として受け取り、両者が一致すればtrueを、一致しなければfalseを戻り値として返します。これにより、実際のパスワードを公開することなく、安全にログイン認証などの処理を行うことができます。この一連のプロセスを通じて、セキュリティを考慮したパスワード管理の基本を学ぶことができます。

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * libsodium拡張機能を使用し、AEAD (認証付き暗号化) の基本的な流れを示します。
7 * 特に、AES256-GCMスキームのノンセ（nonce）サイズ取得関数
8 * `sodium_crypto_aead_aes256gcm_npubbytes` の使用例に焦点を当てています。
9 * また、関連する定数 `SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13` の情報も示します。
10 *
11 * @param string $plainText 暗号化する元のテキストデータ。
12 * @return void
13 */
14function demonstrateAeadEncryption(string $plainText): void
15{
16    echo "--- libsodium AEAD 暗号化デモンストレーション ---\n\n";
17
18    // ----------------------------------------------------
19    // リファレンス情報で指定された定数: SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13
20    // この定数は、パスワードハッシュアルゴリズムArgon2id v1.3を指定する際に使用されます。
21    // 今回の主要なキーワードとは直接関連しませんが、同じlibsodium拡張機能の一部です。
22    // ----------------------------------------------------
23    echo "1. パスワードハッシュアルゴリズム定数の確認:\n";
24    echo "   SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13 の値: " . SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13 . "\n";
25    echo "   (この定数は、`sodium_crypto_pwhash` 関数でArgon2idアルゴリズムを指定する際に使われます。)\n\n";
26
27    // ----------------------------------------------------
28    // キーワードに最も関連性の高いコード: sodium_crypto_aead_aes256gcm_npubbytes の使用
29    // AES256-GCMのノンセ（Nonce, Number Used Once）に必要なバイト数を取得します。
30    // ノンセは、同じ鍵で同じ平文を暗号化しても常に異なる暗号文を生成するために不可欠な、一度だけ使用されるランダムな値です。
31    // ----------------------------------------------------
32    echo "2. AES256-GCM 認証付き暗号化と復号化:\n";
33
34    // 1. 暗号化に必要な鍵を生成します (256ビット = 32バイト)。
35    // 実際のアプリケーションでは、この鍵を安全に管理・保存する必要があります。
36    $key = random_bytes(SODIUM_CRYPTO_AEAD_AES256GCM_KEYBYTES);
37    echo "   - 生成された暗号化キー (HEX, 最初の16バイト): " . bin2hex(substr($key, 0, 16)) . "...\n";
38
39    // 2. `sodium_crypto_aead_aes256gcm_npubbytes` を使って、ノンセの推奨バイト数を取得します。
40    $nonceSize = sodium_crypto_aead_aes256gcm_npubbytes();
41    echo "   - AES256-GCM ノンセの推奨バイト数: " . $nonceSize . " バイト\n";
42
43    // 3. 推奨されたバイト数で安全なランダムなノンセを生成します。
44    // ノンセは、暗号化ごとに新しいものを生成し、絶対に再利用してはいけません。
45    // 暗号文と一緒に保存し、復号時に使用します。
46    $nonce = random_bytes($nonceSize);
47    echo "   - 生成されたノンセ (HEX, 最初の8バイト): " . bin2hex(substr($nonce, 0, 8)) . "...\n";
48
49    // 4. オプションの追加認証データ (AAD)。
50    // 暗号化されませんが、暗号文と関連付けられ、復号時に改ざんされていないことを検証します。
51    $additionalData = 'example-metadata-for-document';
52    echo "   - 追加認証データ (AAD): '" . $additionalData . "'\n\n";
53
54    echo "   --- 暗号化処理 ---\n";
55    echo "   - 元の平文データ: '" . $plainText . "'\n";
56
57    // 5. データを暗号化します。戻り値は暗号文と認証タグが結合されたものです。
58    try {
59        $cipherTextWithTag = sodium_crypto_aead_aes256gcm_encrypt(
60            $plainText,
61            $additionalData,
62            $nonce,
63            $key
64        );
65        echo "   - 暗号文 (HEX, 最初の16バイト): " . bin2hex(substr($cipherTextWithTag, 0, 16)) . "...\n";
66        echo "   - 暗号文の全長: " . strlen($cipherTextWithTag) . " バイト\n\n";
67    } catch (SodiumException $e) {
68        echo "   - 暗号化エラー: " . $e->getMessage() . "\n";
69        return; // エラーが発生した場合はここで処理を中断
70    }
71
72
73    echo "   --- 復号化処理 ---\n";
74
75    // 6. データを復号化します。
76    // 鍵、ノンセ、AAD、または暗号文のいずれかが変更されている場合、復号は失敗し false を返します。
77    try {
78        $decryptedText = sodium_crypto_aead_aes256gcm_decrypt(
79            $cipherTextWithTag,
80            $additionalData,
81            $nonce,
82            $key
83        );
84
85        if ($decryptedText === false) {
86            echo "   - 復号化に失敗しました。データが改ざんされたか、鍵/ノンセ/AADが誤っている可能性があります。\n";
87        } else {
88            echo "   - 復号化された平文データ: '" . $decryptedText . "'\n";
89            if ($decryptedText === $plainText) {
90                echo "   - 復号化されたデータは元の平文と完全に一致しました。\n";
91            } else {
92                echo "   - 警告: 復号化されたデータが元の平文と一致しませんでした。\n";
93            }
94        }
95    } catch (SodiumException $e) {
96        echo "   - 復号化エラー: " . $e->getMessage() . "\n";
97    }
98
99    echo "\n--- デモンストレーション終了 ---\n";
100}
101
102// PHP 7.2 以降で `sodium` 拡張機能が有効になっていることを確認してください。
103if (extension_loaded('sodium')) {
104    // サンプルコードの実行
105    demonstrateAeadEncryption("これは機密情報です。AES256-GCMで安全に暗号化しましょう！");
106} else {
107    echo "エラー: 'sodium' 拡張機能がロードされていません。php.ini で有効にしてください。\n";
108}

このサンプルコードは、PHPのsodium拡張機能を用いて、認証付き暗号化（AEAD）の基本的な利用方法を示しています。特に、AES256-GCM方式におけるノンセ（nonce）の推奨サイズを取得するsodium_crypto_aead_aes256gcm_npubbytes関数の使用に焦点を当てています。

SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13は、パスワードハッシュアルゴリズムArgon2idのバージョン1.3を指定するための定数です。この定数はint型の値を持ち、sodium_crypto_pwhash関数と組み合わせて、パスワードを安全にハッシュ化する際に利用されます。

主要なキーワードであるsodium_crypto_aead_aes256gcm_npubbytes関数は、AES256-GCM暗号化スキームで必要なノンセの推奨バイト数を取得します。ノンセとは、同じ鍵でデータを暗号化する際にも、毎回異なる暗号文を生成するために一度だけ使用されるランダムな値です。この関数は引数を取らず、推奨バイト数をint型で返します。セキュリティ確保のため、ノンセは暗号化ごとに新しく生成し、絶対に再利用してはいけません。

サンプルでは、まずこの関数でノンセサイズを取得し、そのサイズでノンセを生成します。その後、生成した鍵、ノンセ、そしてオプションの追加認証データ（AAD）を用いて平文を暗号化し、最後に同じ情報で復号化を行っています。これにより、データの機密性だけでなく、改ざん防止による完全性も同時に保証されます。これらの機能を利用するには、PHPのsodium拡張機能が有効になっている必要があります。