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

Copy
1<?php
2
3/**
4 * PHP Sodium拡張機能のジェネリックハッシュ生成例。
5 * sodium_crypto_generichash_final 関数は、
6 * generichash処理の最終段階でハッシュ値を計算して返します。
7 *
8 * PHP Sodium拡張機能は、暗号化処理を安全かつ効率的に行うためのライブラリです。
9 * generichashは、任意のデータから固定長のハッシュ値を生成するために使用されます。
10 *
11 * @param string $data ハッシュ化する元のデータ
12 * @param int $length 生成するハッシュのバイト長 (デフォルトは最大値)
13 * @return string 生成されたハッシュ値のバイナリ文字列
14 */
15function generateGenericHash(string $data, int $length = SODIUM_CRYPTO_GENERICHASH_BYTES_MAX): string
16{
17    // PHP Sodium拡張機能がロードされているか確認します。
18    // ロードされていない場合、関連関数は利用できません。
19    if (!extension_loaded('sodium')) {
20        die('エラー: PHP Sodium 拡張機能がロードされていません。php.iniで有効にする必要があります。');
21    }
22
23    // generichashのハッシュステートを初期化します。
24    // このステートオブジェクトがハッシュ処理の進行状況を保持します。
25    // キーはオプションですが、ここでは汎用的なハッシュとしてキーなしで初期化します。
26    $state = sodium_crypto_generichash_init();
27
28    // ハッシュ処理対象のデータをステートに追加します。
29    // データを複数回に分けて追加することも可能です。
30    sodium_crypto_generichash_update($state, $data);
31
32    // 最終的なハッシュ値を生成します。
33    // $length 引数でハッシュのバイト長を指定できます。
34    // デフォルトはSODIUM_CRYPTO_GENERICHASH_BYTES_MAX (64バイト) です。
35    $hash = sodium_crypto_generichash_final($state, $length);
36
37    return $hash;
38}
39
40// --- 使用例 ---
41$message = "システムエンジニアを目指す初心者のためのPHP Sodiumハッシュ生成例です。";
42
43// デフォルトの最大長でハッシュを生成
44$hashResultMax = generateGenericHash($message);
45
46echo "元のメッセージ: " . $message . PHP_EOL;
47echo "生成されたGeneric Hash (デフォルト最大長, hex): " . bin2hex($hashResultMax) . PHP_EOL;
48echo "ハッシュのバイト長 (デフォルト最大長): " . strlen($hashResultMax) . " バイト" . PHP_EOL . PHP_EOL;
49
50// 最小長でハッシュを生成する例
51$hashResultMin = generateGenericHash($message, SODIUM_CRYPTO_GENERICHASH_BYTES_MIN);
52
53echo "生成されたGeneric Hash (最小長, hex): " . bin2hex($hashResultMin) . PHP_EOL;
54echo "ハッシュのバイト長 (最小長): " . strlen($hashResultMin) . " バイト" . PHP_EOL . PHP_EOL;
55
56// 特定のバイト長でハッシュを生成する例 (例: 32バイト)
57$customLength = 32; // 最小値と最大値の間の任意の長さ
58$hashResultCustom = generateGenericHash($message, $customLength);
59
60echo "生成されたGeneric Hash (" . $customLength . "バイト長, hex): " . bin2hex($hashResultCustom) . PHP_EOL;
61echo "ハッシュのバイト長 (" . $customLength . "バイト長): " . strlen($hashResultCustom) . " バイト" . PHP_EOL;
62
63?>

PHPのSodium拡張機能は、データを安全に扱うための暗号化処理を効率的に実行するライブラリです。このサンプルコードでは、この拡張機能を用いて任意のデータから「ジェネリックハッシュ」を生成する手順を説明しています。ジェネリックハッシュとは、元のデータがわずかでも変更されると全く異なる値になる、固定長の短い値のことで、データの同一性や完全性を確認する目的で利用されます。

まず、PHP環境でSodium拡張機能が利用できるかをextension_loaded('sodium')で確認します。その後、sodium_crypto_generichash_init()関数でハッシュ計算のための内部的な「ステート」（処理状況を保持する状態）を初期化します。次に、ハッシュ化したい実際のデータをsodium_crypto_generichash_update()関数を使って、このステートに追加していきます。

そして、sodium_crypto_generichash_final()関数が、これまで処理してきたステート情報から最終的なハッシュ値を計算して返します。この関数は、引数$stateにこれまでのハッシュ計算の状況、$lengthには生成するハッシュ値のバイト長を指定します。$lengthを省略した場合は、最も長いバイト長であるSODIUM_CRYPTO_GENERICHASH_BYTES_MAXが適用されます。この関数の戻り値は、計算によって生成されたハッシュ値のバイナリ文字列です。サンプルコードの使用例では、デフォルトの最大長、最小長、そして特定のバイト長でハッシュを生成し、その結果を表示しています。

Copy
1<?php
2
3// Sodium拡張がロードされているか確認します。
4// システムエンジニアを目指す初心者向けに、拡張機能の有効化の重要性を示唆します。
5if (!extension_loaded('sodium')) {
6    die('PHP Sodium 拡張機能がロードされていません。php.ini で有効にしてください。' . PHP_EOL);
7}
8
9/**
10 * Libsodiumのgenerichash_finalとcrypto_box関数の使用例を示します。
11 *
12 * この関数では、長いメッセージのハッシュをストリーミングで計算し、
13 * そのハッシュ値をsodium_crypto_box関数を使って安全に暗号化および復号化する方法を示します。
14 * キーワードである'sodium_crypto_box'と、リファレンス情報である'sodium_crypto_generichash_final'
15 * の両方を関連付けて利用します。
16 */
17function demonstrateSodiumGenerichashAndCryptoBox(): void
18{
19    echo "--- Sodium Crypto Generichash Final & Crypto Box デモンストレーション ---\n\n";
20
21    // 1. sodium_crypto_box 用の鍵ペアを生成します。
22    // Alice（送信者）とBob（受信者）の公開鍵と秘密鍵のペアを作成します。
23    $aliceKeypair = sodium_crypto_box_keypair();
24    $alicePublicKey = sodium_crypto_box_publickey($aliceKeypair);
25    $aliceSecretKey = sodium_crypto_box_secretkey($aliceKeypair);
26
27    $bobKeypair = sodium_crypto_box_keypair();
28    $bobPublicKey = sodium_crypto_box_publickey($bobKeypair);
29    $bobSecretKey = sodium_crypto_box_secretkey($bobKeypair);
30
31    echo "AliceとBobの鍵ペアを生成しました。\n\n";
32
33    // 2. ハッシュ化する元の「長い」メッセージを準備します。
34    // 実際のアプリケーションでは、これは大きなファイルの内容などになります。
35    $originalMessage = str_repeat('これはハッシュ化するための非常に長いメッセージの一部です。 ', 1000);
36    echo "元のメッセージの長さ: " . strlen($originalMessage) . " バイト\n\n";
37
38    // 3. sodium_crypto_generichash を使って、メッセージのハッシュをストリーミングで計算します。
39    // sodium_crypto_generichash_init() でハッシュ状態を初期化します。
40    // これは、長いデータを一度にメモリにロードすることなくハッシュ化するための第一歩です。
41    $hashState = sodium_crypto_generichash_init();
42
43    // メッセージを小さなチャンク（塊）に分けて、ハッシュ状態を順次更新します。
44    // これが「ストリーミング」処理のシミュレーションです。
45    $chunkSize = 256; // チャンクのサイズ
46    for ($i = 0; $i < strlen($originalMessage); $i += $chunkSize) {
47        $chunk = substr($originalMessage, $i, $chunkSize);
48        sodium_crypto_generichash_update($hashState, $chunk);
49    }
50
51    // sodium_crypto_generichash_final() でハッシュ処理を終了し、最終的なハッシュ値を取得します。
52    // 第二引数でハッシュの長さを指定できます。SODIUM_CRYPTO_GENERICHASH_BYTES は標準的な32バイトです。
53    $generatedHash = sodium_crypto_generichash_final($hashState, SODIUM_CRYPTO_GENERICHASH_BYTES);
54    echo "計算された元のメッセージのハッシュ (長さ " . strlen($generatedHash) . " バイト):\n";
55    echo bin2hex($generatedHash) . "\n\n";
56
57    // 4. 計算したハッシュ値を sodium_crypto_box で暗号化して送信します (Alice -> Bob)。
58    // ノンス（nonce: Number used once）を生成します。各暗号化操作でユニークである必要があります。
59    // ノンスは暗号文と共に送信されます。
60    $nonce = random_bytes(SODIUM_CRYPTO_BOX_NONCEBYTES);
61
62    // AliceがBobの公開鍵と自身の秘密鍵を使用してハッシュを暗号化します。
63    $encryptedHash = sodium_crypto_box(
64        $generatedHash,   // 暗号化するデータ
65        $nonce,           // ノンス
66        $bobPublicKey,    // 受信者の公開鍵
67        $aliceSecretKey   // 送信者の秘密鍵
68    );
69    echo "sodium_crypto_box を使用してハッシュを暗号化しました。\n\n";
70
71    // 5. Bobが暗号化されたハッシュ値を復号し、元のハッシュと比較します (Bob -> Alice)。
72    // BobがAliceの公開鍵と自身の秘密鍵を使用して暗号化されたハッシュを復号します。
73    $decryptedHash = sodium_crypto_box_open(
74        $encryptedHash,   // 暗号文
75        $nonce,           // ノンス (暗号化時と同じものを使用)
76        $alicePublicKey,  // 送信者の公開鍵
77        $bobSecretKey     // 受信者の秘密鍵
78    );
79
80    // 復号に失敗した場合 (例: 暗号文やノンスが改ざんされた場合など) は false が返されます。
81    if ($decryptedHash === false) {
82        echo "エラー: ハッシュの復号に失敗しました。メッセージが改ざんされた可能性があります。\n";
83        return;
84    }
85
86    echo "復号されたハッシュ (長さ " . strlen($decryptedHash) . " バイト):\n";
87    echo bin2hex($decryptedHash) . "\n\n";
88
89    // 復号されたハッシュが元のハッシュと一致するかどうかを確認します。
90    // hash_equals() はタイミング攻撃を防ぐために文字列比較に推奨される関数です。
91    if (hash_equals($generatedHash, $decryptedHash)) {
92        echo "成功: 生成されたハッシュと復号されたハッシュが一致しました。ハッシュは安全に送信されました。\n";
93    } else {
94        echo "失敗: ハッシュが一致しません。送信または復号中に何らかの問題が発生しました。\n";
95    }
96}
97
98// デモンストレーション関数を実行します。
99demonstrateSodiumGenerichashAndCryptoBox();

PHPのsodium_crypto_generichash_final関数は、LibreSSLやOpenSSLのジェネリックハッシュ（BLAKE2b）アルゴリズムをPHPで利用するための機能の一部です。この関数は、sodium_crypto_generichash_initで初期化され、sodium_crypto_generichash_updateで順次データが追加されたハッシュ計算の途中の状態（$state）を受け取り、その計算を終了させて最終的なハッシュ値を生成します。引数$lengthは出力するハッシュ値のバイト長を指定し、戻り値として計算されたハッシュ値の文字列を返します。

サンプルコードでは、sodium_crypto_generichash_finalで生成されたハッシュ値が、sodium_crypto_box関数によって安全に暗号化・復号化される過程を示しています。sodium_crypto_boxは、送信者と受信者の公開鍵・秘密鍵のペア、および一意のノンス（nonce）を使用してデータを暗号化し、そのデータの機密性と認証性を保証します。これにより、生成されたハッシュ値が通信中に改ざんされることなく、安全に相手に届けられ、その正当性が確認できる仕組みが実現されます。これらの関数は、データの完全性検証と安全な通信をPHPで実現するための重要なツールとして利用されます。