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

Copy
1<?php
2
3/**
4 * PHPのSodium拡張機能における汎用ハッシュのストリーミングAPIの使用例を示します。
5 * sodium_crypto_generichash_init 関数を中心に、ハッシュ生成の一連の流れを説明します。
6 *
7 * @param string      $dataToHash ハッシュ化するデータ。
8 * @param string|null $key        オプション。鍵付きハッシュ（MAC）を生成する場合に指定する鍵。
9 *                                  省略した場合は鍵なしハッシュを生成します。
10 * @param int         $length     生成するハッシュのバイト長。デフォルトは最大長（64バイト）。
11 *                                  SODIUM_CRYPTO_GENERICHASH_BYTES_MAX 定数で指定されます。
12 */
13function demonstrateSodiumGenericHashStreaming(
14    string $dataToHash,
15    ?string $key = null,
16    int $length = SODIUM_CRYPTO_GENERICHASH_BYTES_MAX
17): void {
18    // Sodium拡張機能が有効であることを確認します。
19    // 本番環境ではこのチェックを必ず行うべきです。
20    if (!extension_loaded('sodium')) {
21        echo "エラー: Sodium拡張機能が有効ではありません。\n";
22        return;
23    }
24
25    echo "--- Sodium Generic Hash Streaming 例 ---\n";
26    echo "ハッシュ対象データ: \"" . $dataToHash . "\"\n";
27    echo "ハッシュ長: " . $length . " バイト\n";
28
29    if ($key !== null) {
30        echo "鍵を使用: はい (長さ " . strlen($key) . " バイト)\n";
31    } else {
32        echo "鍵を使用: いいえ\n";
33    }
34
35    // 1. ハッシュコンテキストの初期化
36    // sodium_crypto_generichash_init 関数は、ハッシュ処理を開始するためのコンテキストを初期化します。
37    // 第1引数に鍵を渡すと鍵付きハッシュ（MAC）になります。鍵なしの場合はnullを渡します。
38    // 第2引数で生成するハッシュのバイト長を指定します。
39    $hashContext = sodium_crypto_generichash_init($key, $length);
40
41    if ($hashContext === false) {
42        // 通常、このエラーは引数の不正やシステムエラーなどで発生します。
43        echo "エラー: ハッシュコンテキストの初期化に失敗しました。\n";
44        return;
45    }
46
47    // 2. データの追加
48    // sodium_crypto_generichash_update 関数で、ハッシュ化したいデータをハッシュコンテキストに追加します。
49    // この関数を複数回呼び出すことで、大きなデータを分割して処理できます（ストリーミング）。
50    sodium_crypto_generichash_update($hashContext, $dataToHash);
51    echo "データをハッシュコンテキストに追加しました。\n";
52
53    // 3. 最終的なハッシュ値の取得
54    // sodium_crypto_generichash_final 関数で、それまでに追加されたデータから最終的なハッシュ値を計算します。
55    // 戻り値はバイナリデータです。
56    $finalHash = sodium_crypto_generichash_final($hashContext);
57
58    echo "生成されたハッシュ (16進数): " . bin2hex($finalHash) . "\n";
59    echo "-------------------------------------\n\n";
60}
61
62// サンプル実行1: 鍵なしハッシュの生成
63// 一般的なハッシュ値（データの整合性チェックなど）として使用できます。
64demonstrateSodiumGenericHashStreaming("このメッセージのハッシュを生成します。", null);
65
66// サンプル実行2: 鍵付きハッシュの生成
67// 鍵を持つ者だけが同じハッシュを生成できるため、メッセージ認証コード（MAC）として使用できます。
68// 鍵は秘密に保ち、セキュアな方法で生成・管理する必要があります。
69$secretKey = random_bytes(SODIUM_CRYPTO_GENERICHASH_KEYBYTES); // 適切な鍵長をランダムに生成
70demonstrateSodiumGenericHashStreaming("このメッセージは秘密の鍵で認証されます。", $secretKey);
71
72// サンプル実行3: ハッシュ長を指定した鍵なしハッシュの生成
73// ハッシュ長は SODIUM_CRYPTO_GENERICHASH_BYTES_MIN (1バイト) から
74// SODIUM_CRYPTO_GENERICHASH_BYTES_MAX (64バイト) の間で指定可能です。
75demonstrateSodiumGenericHashStreaming("短いハッシュ長の例。", null, SODIUM_CRYPTO_GENERICHASH_BYTES_MIN + 7);

PHPのSodium拡張機能は、セキュアな暗号処理をPHPアプリケーションで利用するためのライブラリです。sodium_crypto_generichash_init関数は、この拡張機能における汎用ハッシュのストリーミングAPIを利用する際の初期化を担当します。ストリーミングAPIは、特に大きなデータを一度に処理せず、少しずつ分割してハッシュ化していく場合に役立つ仕組みです。

この関数の第一引数$keyには、ハッシュ化に用いる鍵を指定します。nullを指定すると、一般的なハッシュ（データの整合性チェックなどに利用）が生成されます。一方、string型の秘密の鍵を指定すると、メッセージ認証コード（MAC）と呼ばれる鍵付きハッシュが生成されます。MACは、鍵を持つ者だけが同じハッシュを生成できるため、データの改ざん検出やメッセージの認証に有効です。鍵は厳重に管理する必要があります。

第二引数$lengthは、生成されるハッシュ値のバイト長を整数で指定します。省略した場合、Sodiumが定める最大長（64バイト）のハッシュが生成されます。

sodium_crypto_generichash_init関数は、ハッシュ処理の現在の状態を保持する「ハッシュコンテキスト」と呼ばれる値を返します。このコンテキストは、その後のsodium_crypto_generichash_update関数でデータを追加したり、sodium_crypto_generichash_final関数で最終的なハッシュ値を取得したりするために使用されます。引数が不正であったり、内部的なエラーが発生したりして初期化に失敗した場合はfalseを返します。

Copy
1<?php
2
3/**
4 * PHP Sodium拡張を使った暗号化とハッシュ処理のデモンストレーション。
5 * sodium_crypto_box による認証付き暗号化と、
6 * sodium_crypto_generichash_init を使った鍵付きハッシュ（MAC）の生成を示します。
7 *
8 * @param string $message 処理対象のメッセージ
9 */
10function demonstrateSodiumSecurity(string $message): void
11{
12    echo "--- 1. 非対称鍵によるメッセージの暗号化と復号 (sodium_crypto_box) ---\n";
13
14    // 送信者（Alice）と受信者（Bob）の鍵ペアを生成します。
15    // sodium_crypto_box 関数群は、公開鍵と秘密鍵を使って安全な通信を実現します。
16    $aliceKeyPair = sodium_crypto_box_keypair();
17    $alicePublicKey = sodium_crypto_box_publickey_from_keypair($aliceKeyPair);
18    $aliceSecretKey = sodium_crypto_box_secretkey_from_keypair($aliceKeyPair);
19
20    $bobKeyPair = sodium_crypto_box_keypair();
21    $bobPublicKey = sodium_crypto_box_publickey_from_keypair($bobKeyPair);
22    $bobSecretKey = sodium_crypto_box_secretkey_from_keypair($bobKeyPair);
23
24    echo "元のメッセージ: " . $message . "\n";
25
26    // 暗号化ごとに一度だけ使用するランダムな値 (ナンス) を生成します。
27    // ナンスは予測不可能でユニークである必要があります。
28    $nonce = random_bytes(SODIUM_CRYPTO_BOX_NONCEBYTES);
29
30    // AliceがBob宛にメッセージを暗号化します。
31    // Aliceの秘密鍵とBobの公開鍵を使用して、暗号化と認証を行います。
32    $encryptedMessage = sodium_crypto_box(
33        $message,
34        $nonce,
35        $bobPublicKey,
36        $aliceSecretKey
37    );
38
39    if ($encryptedMessage === false) {
40        echo "エラー: 暗号化に失敗しました。\n";
41        return;
42    }
43    echo "暗号化されたメッセージ (Hex): " . bin2hex($encryptedMessage) . "\n";
44
45    // BobがAliceからのメッセージを復号します。
46    // Bobの秘密鍵とAliceの公開鍵を使用して、復号と認証検証を行います。
47    $decryptedMessage = sodium_crypto_box_open(
48        $encryptedMessage,
49        $nonce,
50        $alicePublicKey,
51        $bobSecretKey
52    );
53
54    if ($decryptedMessage === false) {
55        echo "エラー: 復号化に失敗したか、メッセージが改ざんされました。\n";
56        return;
57    }
58    echo "復号化されたメッセージ: " . $decryptedMessage . "\n";
59    echo "復号化成功: " . ($message === $decryptedMessage ? "はい" : "いいえ") . "\n\n";
60
61
62    echo "--- 2. 鍵付きハッシュ（MAC）の生成と検証 (sodium_crypto_generichash_init) ---\n";
63
64    // メッセージ認証コード (MAC) を生成するための秘密鍵です。
65    // この鍵は送信者と受信者の間で安全に共有されている必要があります。
66    // sodium_crypto_generichash は、鍵付きハッシュとしてメッセージの認証に使えます。
67    $macKey = random_bytes(SODIUM_CRYPTO_GENERICHASH_KEYBYTES);
68    echo "MAC生成用鍵 (Hex): " . bin2hex($macKey) . "\n";
69
70    // sodium_crypto_generichash_init を使用してハッシュコンテキストを初期化します。
71    // 第1引数に鍵を指定することで、鍵付きハッシュ（MAC）として機能します。
72    // 第2引数はハッシュの出力長で、ここでは SODIUM_CRYPTO_GENERICHASH_BYTES (32バイト) を指定しています。
73    $hashState = sodium_crypto_generichash_init($macKey, SODIUM_CRYPTO_GENERICHASH_BYTES);
74    if ($hashState === false) {
75        echo "エラー: ハッシュ初期化に失敗しました。\n";
76        return;
77    }
78
79    // メッセージデータをハッシュコンテキストに供給します。
80    sodium_crypto_generichash_update($hashState, $message);
81
82    // 最終的なハッシュ値（MAC）を取得します。
83    $generatedMac = sodium_crypto_generichash_final($hashState);
84    echo "生成されたMAC (Hex): " . bin2hex($generatedMac) . "\n";
85
86    // 受信側でのMAC検証のシミュレーションを行います。
87    // 受信側も同じ共有鍵とメッセージを使ってMACを再計算し、送信されたMACと突き合わせます。
88    $verifyHashState = sodium_crypto_generichash_init($macKey, SODIUM_CRYPTO_GENERICHASH_BYTES);
89    sodium_crypto_generichash_update($verifyHashState, $message);
90    $receivedMac = sodium_crypto_generichash_final($verifyHashState);
91
92    echo "検証用MAC (Hex): " . bin2hex($receivedMac) . "\n";
93    // sodium_memcmp は、タイミング攻撃を防ぐためのバイナリ安全な比較関数です。
94    echo "MAC検証成功: " . (sodium_memcmp($generatedMac, $receivedMac) === 0 ? "はい" : "いいえ") . "\n";
95}
96
97// サンプルメッセージを定義します。
98$sampleMessage = "セキュリティで保護されたメッセージです。これはAliceからBobへ送られます。";
99
100// 関数を実行してデモンストレーションを開始します。
101demonstrateSodiumSecurity($sampleMessage);

PHP 8のsodium_crypto_generichash_init関数は、セキュリティ拡張「Sodium」の一部として、鍵付きハッシュ（Message Authentication Code, MAC）の生成処理を初期化するために使用されます。MACは、メッセージが通信中に改ざんされていないことや、信頼できる送信元から送られたことを検証するために利用される重要なセキュリティ要素です。

この関数の第1引数$keyには、MAC生成のための秘密鍵（バイナリ文字列）を指定します。この鍵は、メッセージを認証する送信者と検証する受信者の間で安全に共有されている必要があります。もしnullを指定した場合は、鍵なしの一般的なハッシュ計算の初期化となります。第2引数$lengthは、最終的に生成されるハッシュ値のバイト長を指定し、デフォルト値やSODIUM_CRYPTO_GENERICHASH_BYTESのような定数で指定可能です。

関数が成功すると、その後のハッシュ処理の状況を保持する内部コンテキスト（文字列型）を返します。この戻り値は、続けてsodium_crypto_generichash_updateでメッセージデータを供給し、sodium_crypto_generichash_finalで最終的なMACを取得する際に使用されます。処理に失敗した場合はfalseを返します。

サンプルコードでは、sodium_crypto_boxを使った非対称鍵によるメッセージの暗号化と復号のデモンストレーションに続いて、このsodium_crypto_generichash_init関数がメッセージの認証性を確保するための鍵付きハッシュ生成にどのように使われるかを示しています。これにより、機密性と完全性を両立させるセキュリティ処理の基本を理解できます。