【PHP8.x】sodium_crypto_pwhash_scryptsalsa208sha256_str()関数の使い方

Copy
1<?php
2
3/**
4 * Libsodium (PHP Sodium extension) を使用してパスワードをハッシュ化し、検証するサンプルスクリプトです。
5 * `sodium_crypto_pwhash_scryptsalsa208sha256_str` 関数は、セキュアなパスワードハッシュを生成します。
6 * この関数は内部で安全なソルトを自動的に生成し、ハッシュ文字列に埋め込みます。
7 *
8 * キーワード: password_hash, salt
9 * 関連関数: sodium_crypto_pwhash_str_verify (ハッシュの検証に使用)
10 *
11 * Libsodium 拡張が PHP にインストールされ、有効になっている必要があります。
12 * (例: `php -m | grep sodium` で確認できます)
13 */
14
15// ハッシュ化したい元のパスワード
16$originalPassword = 'MySuperSecurePassword123!';
17
18// パスワードハッシュ化の計算量とメモリ使用量の制限を設定します。
19// これらの定数は Libsodium が提供する推奨値で、セキュリティとパフォーマンスのバランスを取ります。
20// 用途に応じてより高い値（_INTERACTIVE, _SENSITIVE）を設定することも可能です。
21$opslimit = SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE; // 計算量 (CPU時間)
22$memlimit = SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE; // メモリ使用量
23
24echo "元のパスワード: " . $originalPassword . PHP_EOL;
25echo "----------------------------------------------------" . PHP_EOL;
26
27try {
28    // パスワードをハッシュ化します。
29    // この関数が、安全なソルトを生成し、ハッシュ文字列内に埋め込みます。
30    $hashedPassword = sodium_crypto_pwhash_scryptsalsa208sha256_str(
31        $originalPassword,
32        $opslimit,
33        $memlimit
34    );
35
36    echo "生成されたハッシュ: " . $hashedPassword . PHP_EOL;
37    echo "----------------------------------------------------" . PHP_EOL;
38
39    // ----- パスワードの検証 -----
40
41    // 1. 正しいパスワードで検証を試みます。
42    // sodium_crypto_pwhash_str_verify は、ハッシュと与えられたパスワードが一致するかを検証します。
43    // このとき、ハッシュに含まれるソルトとパラメータを自動的に使用します。
44    $isVerifiedCorrect = sodium_crypto_pwhash_str_verify($hashedPassword, $originalPassword);
45    echo "正しいパスワード ('" . $originalPassword . "') で検証: ";
46    echo ($isVerifiedCorrect ? "成功 ✅" : "失敗 ❌") . PHP_EOL;
47
48    // 2. 間違ったパスワードで検証を試みます。
49    $incorrectPassword = 'WrongPassword456!';
50    $isVerifiedIncorrect = sodium_crypto_pwhash_str_verify($hashedPassword, $incorrectPassword);
51    echo "間違ったパスワード ('" . $incorrectPassword . "') で検証: ";
52    echo ($isVerifiedIncorrect ? "成功 ✅" : "失敗 ❌") . PHP_EOL;
53
54} catch (SodiumException $e) {
55    // Libsodium 拡張が有効でない場合や、その他のLibsodium関連のエラーが発生した場合
56    echo "エラーが発生しました: " . $e->getMessage() . PHP_EOL;
57    echo "ヒント: PHPの Libsodium 拡張が有効になっているか確認してください。" . PHP_EOL;
58} catch (Throwable $e) {
59    // その他の予期せぬエラーが発生した場合
60    echo "予期せぬエラーが発生しました: " . $e->getMessage() . PHP_EOL;
61}
62
63?>

このPHPサンプルコードは、Libsodium拡張のsodium_crypto_pwhash_scryptsalsa208sha256_str関数を使ってパスワードを安全にハッシュ化し、そのハッシュを検証する方法を示しています。

sodium_crypto_pwhash_scryptsalsa208sha256_str関数は、元のパスワード（$password引数）を非常に強力なアルゴリズムでハッシュ化するために使用されます。この際、ハッシュ化の計算量（CPU時間）を制御する$opslimit引数と、メモリ使用量を制御する$memlimit引数を指定し、セキュリティとシステムパフォーマンスのバランスを取ります。特に重要な点として、この関数は「salt（ソルト）」と呼ばれるランダムな値を内部で自動生成し、ハッシュ文字列内に埋め込むため、開発者が別途ソルトを管理する手間が省け、セキュリティが向上します。関数は、生成された安全なハッシュ文字列を戻り値として返します。

ハッシュ化されたパスワードは、sodium_crypto_pwhash_str_verify関数を使って検証されます。この検証関数は、保存されたハッシュ文字列と、ユーザーが入力したパスワードが一致するかどうかを判定します。このとき、ハッシュ文字列に含まれているソルトやハッシュ化時のパラメータを自動的に利用して検証を行うため、非常に簡単かつ安全にパスワードの正当性を確認できます。

サンプルコードでは、まずパスワードをハッシュ化し、その後、正しいパスワードと間違ったパスワードのそれぞれで検証を試みることで、ハッシュ化と検証の一連の流れを具体的に示しています。このコードを実行するには、PHPにLibsodium拡張がインストールされ、有効になっている必要があります。

Copy
1<?php
2
3/**
4 * Libsodiumのscryptアルゴリズムを使用してパスワードをハッシュ化し、そのハッシュを検証するサンプルコード。
5 *
6 * @param string $password ハッシュ化する元のパスワード
7 * @return void
8 */
9function demonstrateScryptPasswordHashing(string $password): void
10{
11    // Libsodium拡張機能が利用可能かを確認
12    if (!extension_loaded('sodium')) {
13        echo "エラー: Libsodium拡張機能がロードされていません。php.iniで 'extension=sodium' を有効にしてください。\n";
14        return;
15    }
16
17    // scryptアルゴリズムの計算コストパラメータを設定
18    // これらの定数はLibsodiumが推奨するセキュリティレベルを提供します。
19    // INTERACTIVEは、一般的なウェブアプリケーションのログインなど、応答性が必要な用途に適しています。
20    $opslimit = SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_INTERACTIVE;
21    $memlimit = SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_INTERACTIVE;
22
23    echo "--- パスワードハッシュの生成と検証 ---\n";
24    echo "元のパスワード: " . $password . "\n\n";
25
26    // sodium_crypto_pwhash_scryptsalsa208sha256_str を使用してパスワードをハッシュ化
27    // この関数は自動的にソルトを生成し、ハッシュ文字列に含めます。
28    $hashedPassword = sodium_crypto_pwhash_scryptsalsa208sha256_str(
29        $password,
30        $opslimit,
31        $memlimit
32    );
33
34    if ($hashedPassword === false) {
35        echo "エラー: パスワードのハッシュ化に失敗しました。\n";
36        return;
37    }
38
39    echo "生成されたハッシュ: " . $hashedPassword . "\n\n";
40
41    // --- ハッシュの検証 ---
42    echo "--- ハッシュの検証 --- \n";
43
44    // 生成されたハッシュと元のパスワードで検証を試みる (成功するはず)
45    $isVerifiedCorrect = sodium_crypto_pwhash_scryptsalsa208sha256_str_verify(
46        $hashedPassword,
47        $password
48    );
49
50    if ($isVerifiedCorrect) {
51        echo "検証結果 (元のパスワード): 成功 - パスワードが一致しました。\n";
52    } else {
53        echo "検証結果 (元のパスワード): 失敗 - パスワードが一致しませんでした。\n";
54    }
55
56    // 意図的に間違ったパスワードで検証を試みる (失敗するはず)
57    $wrongPassword = "NotMySecurePassword123";
58    echo "間違ったパスワードでの試行: '" . $wrongPassword . "'\n";
59    $isVerifiedWrong = sodium_crypto_pwhash_scryptsalsa208sha256_str_verify(
60        $hashedPassword,
61        $wrongPassword
62    );
63
64    if ($isVerifiedWrong) {
65        echo "検証結果 (間違ったパスワード): 成功 (これは問題があります！)\n";
66    } else {
67        echo "検証結果 (間違ったパスワード): 失敗 - パスワードが一致しませんでした。\n";
68    }
69    echo "\n-------------------------------------\n";
70}
71
72// サンプルとして使用するパスワードを定義
73$userPassword = "SuperSecretPassword!@#123";
74
75// 関数を実行してデモンストレーション
76demonstrateScryptPasswordHashing($userPassword);
77
78?>

PHP 8のsodium_crypto_pwhash_scryptsalsa208sha256_str関数は、ユーザーパスワードを安全にハッシュ化するために用いられます。この関数は、計算コストの高いscryptアルゴリズムを採用することで、ブルートフォース攻撃などに対するセキュリティを強化します。

引数には、ハッシュ化したい元のパスワード（$password）、計算の反復回数を設定する$opslimit（CPUコスト）、使用するメモリ量を設定する$memlimit（メモリコスト）を渡します。これらのコストパラメータには、応答性とセキュリティのバランスが取れたLibsodium推奨の定数（例: SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_INTERACTIVE）を設定するのが一般的です。

関数は、自動生成したソルトやコスト情報を含む、一意のハッシュ文字列を戻り値として返します。この生成されたハッシュ文字列はデータベースなどに保存し、元のパスワードは保存しません。パスワード認証の際には、sodium_crypto_pwhash_scryptsalsa208sha256_str_verify関数を使い、保存されたハッシュとユーザーが入力したパスワードが一致するかを検証します。本機能を利用するには、PHPにLibsodium拡張機能がロードされている必要があります。