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

Copy
1<?php
2
3/**
4 * 指定されたパスワードをLibsodiumのpwhash関数でハッシュ化します。
5 *
6 * この関数は、SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE 定数を使用して、
7 * パスワードハッシュのメモリ使用量を「適度な」レベルに設定します。
8 * これは一般的なアプリケーションに適したセキュリティとパフォーマンスのバランスを提供します。
9 *
10 * @param string $password ハッシュ化する元のパスワード。
11 * @return string|false ハッシュ化されBase64エンコードされたパスワード文字列、または失敗した場合は false。
12 */
13function generatePasswordHashWithModerateLimits(string $password): string|false
14{
15    // Libsodium拡張機能がロードされているか確認
16    if (!extension_loaded('sodium')) {
17        error_log("Error: The 'sodium' PHP extension is not loaded.");
18        return false;
19    }
20
21    // パスワードハッシュの出力バイト数を定義。
22    // SODIUM_CRYPTO_PWHASH_SALTBYTES はソルトの最小バイト数を定義しており、
23    // 通常、出力ハッシュはこの値よりも大きく設定されます。
24    // ここでは、デフォルトのハッシュ長を約64バイトとしています。
25    $outputLength = SODIUM_CRYPTO_PWHASH_SALTBYTES * 2; // 例えば32バイトのソルトに対し64バイトのハッシュ出力
26
27    // パスワードハッシュに利用する、暗号学的に安全なランダムなソルトを生成します。
28    // ソルトの長さは SODIUM_CRYPTO_PWHASH_SALTBYTES で定義されています。
29    $salt = random_bytes(SODIUM_CRYPTO_PWHASH_SALTBYTES);
30
31    // sodium_crypto_pwhash 関数を使用してパスワードをハッシュ化します。
32    //
33    // SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE:
34    //   計算に要するCPU時間に関する操作制限です。
35    //   「適度な」セキュリティとパフォーマンスのバランスを提供します。
36    //
37    // SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE:
38    //   計算に要するメモリ使用量に関するメモリ制限です。
39    //   参照されている定数で、「適度な」リソース消費を設定します。
40    //   SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE は、Webログインのような
41    //   高速なレスポンスが求められるインタラクティブな用途で使用される
42    //   より低いメモリ制限です。MODERATE は INTERACTIVE よりも高いセキュリティを提供します。
43    //
44    // SODIUM_CRYPTO_PWHASH_ALG_DEFAULT:
45    //   使用するパスワードハッシュアルゴリズムを指定します。
46    //   PHP 8以降ではArgon2idがデフォルトとして推奨されています。
47    $hashedPasswordBinary = sodium_crypto_pwhash(
48        $outputLength,                              // 出力されるハッシュのバイト数
49        $password,                                  // ハッシュ化するパスワード
50        $salt,                                      // ランダムに生成されたソルト
51        SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE,     // CPU操作の制限 (OpLimit)
52        SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE,     // メモリ使用量の制限 (MemLimit)
53        SODIUM_CRYPTO_PWHASH_ALG_DEFAULT            // 使用するハッシュアルゴリズム
54    );
55
56    // ハッシュ化されたパスワード (バイナリデータ) とソルトを結合してBase64エンコードし、
57    // データベースなどに安全に保存できる文字列形式で返します。
58    // 検証時にはこの文字列からソルトとハッシュを抽出し、再度pwhash関数で比較します。
59    if ($hashedPasswordBinary !== false) {
60        // ソルトとハッシュを結合して保存することで、検証時に同じソルトを使用できます。
61        return base64_encode($salt . $hashedPasswordBinary);
62    } else {
63        error_log("Error: Failed to generate password hash.");
64        return false;
65    }
66}
67
68// --- サンプルコードの使用例 ---
69
70// このブロックは `generatePasswordHashWithModerateLimits` 関数の動作を示すものです。
71// 実際のアプリケーションでは、エラーハンドリングを強化し、ハッシュ検証のロジックも必要になります。
72
73// テスト用のパスワード
74$testPassword = 'mySuperSecretPassword123!';
75
76echo "元のパスワード: " . $testPassword . PHP_EOL;
77
78// パスワードをハッシュ化
79$hashedResult = generatePasswordHashWithModerateLimits($testPassword);
80
81if ($hashedResult !== false) {
82    echo "ハッシュ化されたパスワード (MODERATE 設定): " . $hashedResult . PHP_EOL;
83
84    // ここではハッシュの生成のみを示していますが、
85    // 実際のアプリケーションでは、保存されたハッシュと入力パスワードを比較する
86    // `sodium_crypto_pwhash_str_verify` や同様の検証ロジックが必要です。
87} else {
88    echo "パスワードのハッシュ化に失敗しました。PHPの 'sodium' 拡張機能が有効か確認してください。" . PHP_EOL;
89}

このサンプルコードは、PHPのLibsodium拡張機能を利用してパスワードを安全にハッシュ化する方法を示すgeneratePasswordHashWithModerateLimits関数を定義しています。この関数は、引数として受け取った元のパスワード（$password）を、セキュリティを考慮した設定でハッシュ化し、その結果を文字列として返します。

特に、SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE定数の使用がこのコードのポイントです。この定数は、パスワードハッシュの計算時に使用されるメモリ使用量の上限を「適度な」レベルに設定します。これは、一般的なWebアプリケーションにおいて、サーバーへの負荷とパスワードのセキュリティ強度のバランスを最適化するために推奨される設定です。より高速な処理が求められるインタラクティブな用途にはSODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVEという定数もありますが、MODERATEはそれよりも高いセキュリティを提供します。

generatePasswordHashWithModerateLimits関数内では、まずLibsodium拡張機能がロードされているかを確認します。次に、暗号学的に安全なランダムなソルトを生成し、sodium_crypto_pwhash関数に渡します。この関数には、出力されるハッシュの長さ、元のパスワード、生成したソルト、CPU操作の制限（SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE）、そして今回注目するメモリ使用量の制限としてSODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE、さらにデフォルトのハッシュアルゴリズムを引数として指定しています。

ハッシュ化が成功した場合、関数は生成されたバイナリ形式のハッシュとソルトを結合し、Base64エンコードした文字列を戻り値として返します。この文字列はデータベースなどに安全に保存され、後続のパスワード認証プロセスで入力されたパスワードとの比較に利用されます。ハッシュ化処理が失敗した場合は、エラーメッセージをログに出力し、falseを返します。

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * Demonstrates secure password hashing and authenticated encryption using the Sodium extension.
7 *
8 * This function illustrates how to:
9 * 1. Hash a user password using the `SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE` constant for memory cost.
10 * 2. Encrypt and decrypt sensitive data using AES256-GCM, utilizing
11 *    `sodium_crypto_aead_aes256gcm_npubbytes()` to determine the required nonce size.
12 *
13 * @param string $password      The plain-text password to be hashed.
14 * @param string $sensitiveData The sensitive data string to be encrypted.
15 * @return array An associative array containing the hashed password,
16 *               encrypted data (base64-encoded), nonce (base64-encoded),
17 *               and the decrypted data (if successful).
18 */
19function handleSecureOperations(string $password, string $sensitiveData): array
20{
21    // --- Password Hashing ---
22    // SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE is a predefined constant
23    // representing a moderate memory limit for the Argon2id password hashing algorithm.
24    // It's crucial for configuring the computational cost of the hash.
25    $hashedPassword = sodium_crypto_pwhash_str(
26        $password,
27        SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE,  // CPU cost (operations limit)
28        SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE   // Memory cost (memory limit)
29    );
30
31    echo "Original Password: " . $password . PHP_EOL;
32    echo "Hashed Password: " . $hashedPassword . PHP_EOL;
33
34    // Verify the password (e.g., during a login attempt).
35    if (sodium_crypto_pwhash_str_verify($hashedPassword, $password)) {
36        echo "Password verification successful." . PHP_EOL;
37    } else {
38        echo "Password verification failed." . PHP_EOL;
39    }
40
41    echo PHP_EOL;
42
43    // --- Authenticated Encryption (AEAD) ---
44    // Generate a random, cryptographically secure key for AES256-GCM encryption.
45    // This key must be kept secret and managed securely.
46    $encryptionKey = sodium_crypto_aead_aes256gcm_keygen();
47
48    // The `sodium_crypto_aead_aes256gcm_npubbytes()` function returns the required
49    // size (in bytes) for the nonce (number used once) for AES256-GCM.
50    // A nonce must be unique for each encryption with the same key.
51    $nonceBytes = sodium_crypto_aead_aes256gcm_npubbytes();
52    echo "Nonce size required for AES256-GCM: " . $nonceBytes . " bytes." . PHP_EOL;
53
54    // Generate a cryptographically secure random nonce of the required size.
55    $nonce = random_bytes($nonceBytes);
56
57    echo "Original Sensitive Data: " . $sensitiveData . PHP_EOL;
58
59    // Encrypt the sensitive data using AES256-GCM.
60    // The `encrypt` function returns the ciphertext combined with an authentication tag.
61    $encryptedData = sodium_crypto_aead_aes256gcm_encrypt(
62        $sensitiveData,  // Message to encrypt
63        '',              // Optional: Additional authenticated data (AAD)
64        $nonce,          // Unique nonce
65        $encryptionKey   // Encryption key
66    );
67
68    echo "Encrypted Data (base64-encoded for display): " . base64_encode($encryptedData) . PHP_EOL;
69
70    // Decrypt the data. The same key and nonce used for encryption must be provided.
71    // If the data has been tampered with or the key/nonce are incorrect,
72    // decryption will fail and return `false`.
73    $decryptedData = sodium_crypto_aead_aes256gcm_decrypt(
74        $encryptedData,
75        '',
76        $nonce,
77        $encryptionKey
78    );
79
80    if ($decryptedData === false) {
81        echo "Decryption failed or data was tampered with!" . PHP_EOL;
82        $decryptedData = null; // Indicate decryption failure
83    } else {
84        echo "Decrypted Data: " . $decryptedData . PHP_EOL;
85        if ($decryptedData === $sensitiveData) {
86            echo "Decryption successful and data integrity verified." . PHP_EOL;
87        } else {
88            echo "Decryption successful but data mismatch (unexpected)." . PHP_EOL;
89        }
90    }
91
92    return [
93        'hashed_password' => $hashedPassword,
94        'encrypted_data' => base64_encode($encryptedData), // Store base64 for persistent storage
95        'encryption_nonce' => base64_encode($nonce),       // Store base64 for persistent storage
96        'decrypted_data' => $decryptedData,
97    ];
98}
99
100// --- Example Usage ---
101// Ensure the Sodium extension is loaded before attempting cryptographic operations.
102if (extension_loaded('sodium')) {
103    $userPassword = 'MySuperSecretPassword123!';
104    $privateUserData = '{"name": "Jane Doe", "email": "jane.doe@example.com", "credit_card_last4": "1234"}';
105
106    $results = handleSecureOperations($userPassword, $privateUserData);
107
108    echo PHP_EOL . "--- Operation Results ---" . PHP_EOL;
109    echo "Stored Hashed Password (example): " . $results['hashed_password'] . PHP_EOL;
110    echo "Stored Encrypted Data (example): " . $results['encrypted_data'] . PHP_EOL;
111    echo "Stored Encryption Nonce (example): " . $results['encryption_nonce'] . PHP_EOL;
112    echo "Retrieved Decrypted Data (example): " . ($results['decrypted_data'] ?? 'Decryption Failed') . PHP_EOL;
113
114    // In a real application, the encryption key would be securely managed and not returned or stored directly like this.
115    // The nonce would be stored alongside the encrypted data.
116} else {
117    echo "Error: The PHP 'sodium' extension is not loaded. Please enable it to run this example." . PHP_EOL;
118}

このPHPコードは、Sodium拡張機能を用いたパスワードの安全なハッシュ化と、データの認証付き暗号化の例を示します。

SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE定数は、パスワードハッシュアルゴリズムArgon2idのメモリ使用量を「中程度」に設定する整数値です。これはsodium_crypto_pwhash_str関数で使用され、パスワードハッシュの計算コストを決定し、セキュリティ強度に影響を与えます。ハッシュ化されたパスワードはsodium_crypto_pwhash_str_verify関数で元のパスワードと比較して検証されます。

データの認証付き暗号化では、sodium_crypto_aead_aes256gcm_npubbytes()関数が重要な役割を果たします。この関数は、AES256-GCM暗号化に必要なNonce（ナンス：Number used once）のバイト数を返します。Nonceは同じ鍵で複数回暗号化する際に毎回異なる値を使用する必要があり、データごとの一意性を保証します。取得したNonceサイズに基づいてランダムなNonceを生成し、sodium_crypto_aead_aes256gcm_encrypt関数でデータを暗号化します。暗号化されたデータはsodium_crypto_aead_aes256gcm_decrypt関数で復号化され、データが改ざんされていないかも検証されます。復号化に失敗した場合、この関数はfalseを返します。

handleSecureOperations関数は、平文のパスワードと機密データを引数として受け取り、ハッシュ済みパスワード、暗号化データ、Nonce、そして復号化されたデータを格納した連想配列を戻り値として返します。これにより、パスワード管理と機密データ保護の基本的な流れを理解できます。