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

Copy
1<?php declare(strict_types=1);
2
3// PHP Sodium拡張機能がロードされているか確認します。
4// この拡張機能は、暗号化操作を行うために必要です。
5if (!extension_loaded('sodium')) {
6    echo "PHP Sodium extension is not loaded. Please enable it in your php.ini.\n";
7    exit(1);
8}
9
10/**
11 * PHP Sodium拡張機能の `sodium_crypto_secretstream_xchacha20poly1305_keygen` を使用した、
12 * ストリーム暗号化・復号化の基本的な流れを示す関数です。
13 *
14 * `sodium_crypto_secretstream_xchacha20poly1305_keygen` は、ストリーム暗号化のための
15 * 秘密鍵を生成します。この鍵は、連続したデータを安全に暗号化および復号化するために使用され、
16 * 短いメッセージの暗号化に用いられる `sodium_crypto_secretbox` とは異なる用途を持ちます。
17 *
18 * @param string $originalMessage 暗号化する元のメッセージ
19 * @return void
20 */
21function demonstrateSodiumSecretStream(string $originalMessage): void
22{
23    echo "--- Sodium Secret Stream Demonstration ---\n\n";
24
25    // 1. ストリーム暗号化用の秘密鍵を生成します。
26    // この鍵はバイナリ文字列で、暗号化と復号化の両方に使用されるため、
27    // 安全に保管し、共有されるべきです。
28    $key = sodium_crypto_secretstream_xchacha20poly1305_keygen();
29    echo "Generated Stream Key (binary). For security reasons, the key content itself is not displayed.\n";
30
31    // 2. プッシュ操作（暗号化）のための状態を初期化します。
32    // `sodium_crypto_secretstream_xchacha20poly1305_init_push` は、
33    // ストリームの初期化に必要なヘッダーと、以降の暗号化に使用する状態ハンドルを返します。
34    // ヘッダーは復号化に必須であり、暗号文と一緒に受信者に送信される必要があります。
35    // 戻り値は `[状態ハンドル (resource), ヘッダー (string)]` の配列です。
36    [$streamPushState, $header] = sodium_crypto_secretstream_xchacha20poly1305_init_push($key);
37    echo "Stream Push State Initialized. Header generated (size: " . strlen($header) . " bytes).\n";
38
39    // 3. 元のメッセージをチャンク（断片）に分割し、ストリームで暗号化します。
40    // `sodium_crypto_secretstream_xchacha20poly1305_push` は、指定されたチャンクデータを暗号化し、
41    // 内部の状態を更新します。
42    // 最後のチャンクには `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL` タグを付け、
43    // 受信者にストリームの終了を伝えます。
44    $chunkSize = 30; // デモンストレーションのためにチャンクサイズを設定
45    $encryptedChunks = [];
46    $messageLength = strlen($originalMessage);
47
48    echo "Original Message: '" . $originalMessage . "' (Length: " . $messageLength . " bytes)\n";
49    echo "Encrypting message in chunks (chunk size: " . $chunkSize . ")...\n";
50
51    for ($i = 0; $i < $messageLength; $i += $chunkSize) {
52        $chunk = substr($originalMessage, $i, $chunkSize);
53        $isLastChunk = ($i + $chunkSize >= $messageLength);
54        // 通常のメッセージチャンクには SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE を使用
55        $tag = $isLastChunk ? SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL : SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE;
56
57        // `additional_data` (追加認証データ) は、この例では空文字列として指定します。
58        // これは、暗号文とは別に認証されるデータ（例: タイムスタンプなど）に使用できます。
59        $encryptedChunk = sodium_crypto_secretstream_xchacha20poly1305_push($streamPushState, $chunk, '', $tag);
60        $encryptedChunks[] = $encryptedChunk;
61        echo " - Original Chunk: '" . $chunk . "'\n";
62        echo " - Encrypted Chunk (tag: " . $tag . ", hex): " . bin2hex($encryptedChunk) . "\n";
63    }
64
65    // 4. 暗号化されたチャンクとヘッダーを連結して、完全な暗号文を形成します。
66    // この `$fullCiphertext` は、ネットワークなどを介して受信者に安全に転送されるべきデータです。
67    $fullCiphertext = $header . implode('', $encryptedChunks);
68    echo "\nFull Ciphertext (length: " . strlen($fullCiphertext) . " bytes).\n";
69
70    echo "\n--- Decryption Process ---\n";
71
72    // 5. プル操作（復号化）のための状態を初期化します。
73    // `sodium_crypto_secretstream_xchacha20poly1305_init_pull` は、
74    // 受信したヘッダーと暗号化に使用された秘密鍵を使って、復号化のための状態ハンドルを返します。
75    // 戻り値は状態ハンドル (resource) です。
76    $streamPullState = sodium_crypto_secretstream_xchacha20poly1305_init_pull($header, $key);
77    echo "Stream Pull State Initialized using header and key.\n";
78
79    // 6. 暗号化されたチャンクをストリームで復号化します。
80    // `sodium_crypto_secretstream_xchacha20poly1305_pull` は、暗号化されたチャンクと状態ハンドルを受け取り、
81    // 復号化されたデータと対応するタグを返します。
82    $decryptedMessage = '';
83    echo "Decrypting message in chunks...\n";
84
85    foreach ($encryptedChunks as $chunkIndex => $encryptedChunk) {
86        // 戻り値は `[復号化されたデータ (string), 受信タグ (int)]` の配列です。
87        [$decryptedChunk, $receivedTag] = sodium_crypto_secretstream_xchacha20poly1305_pull($streamPullState, $encryptedChunk);
88        $decryptedMessage .= $decryptedChunk;
89        echo " - Encrypted Chunk (from stream, hex): " . bin2hex($encryptedChunk) . "\n";
90        echo " - Decrypted Chunk: '" . $decryptedChunk . "' (received tag: " . $receivedTag . ")\n";
91
92        if ($receivedTag === SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL) {
93            echo " - Final chunk detected and processed.\n";
94        }
95    }
96
97    echo "\nDecrypted Message: '" . $decryptedMessage . "' (Length: " . strlen($decryptedMessage) . " bytes)\n";
98
99    // 7. 元のメッセージと復号化されたメッセージが一致するか検証します。
100    if ($originalMessage === $decryptedMessage) {
101        echo "\nSUCCESS: Original message matches decrypted message.\n";
102    } else {
103        echo "\nFAILURE: Original message DOES NOT match decrypted message.\n";
104    }
105    echo "\n------------------------------------------\n";
106}
107
108// --- サンプル実行 ---
109
110// 比較的長いメッセージでのデモンストレーション
111$testMessage1 = "This is a secret message that needs to be streamed securely. It contains some sensitive information, potentially longer than a single chunk and requires multiple encryption operations to demonstrate the stream functionality.";
112demonstrateSodiumSecretStream($testMessage1);
113
114echo "\n";
115
116// 短いメッセージでのデモンストレーション
117// チャンクサイズがメッセージ長を超える場合でも正しく動作することを確認します。
118$testMessage2 = "Short secret!";
119demonstrateSodiumSecretStream($testMessage2);

sodium_crypto_secretstream_xchacha20poly1305_keygenは、PHPのSodium拡張機能が提供する、ストリーム暗号化のための秘密鍵を生成する関数です。この関数は引数を取らずに呼び出され、暗号化と復号化の両方に使用されるランダムなバイナリ文字列の秘密鍵を返します。生成された鍵は機密情報であり、その安全な保管と適切な管理が非常に重要です。

この関数で生成される鍵は、動画ストリームや大容量ファイルなど、連続したデータを安全に暗号化および復号化するストリーム暗号化に適しています。これは、短いメッセージの暗号化に用いられるsodium_crypto_secretboxとは異なる用途を持ちます。

鍵が生成されると、これを用いてsodium_crypto_secretstream_xchacha20poly1305_init_push関数で暗号化を開始するための状態と、復号化に必須となるヘッダーを初期化します。受信側では、この鍵と送信されたヘッダーを使ってsodium_crypto_secretstream_xchacha20poly1305_init_pull関数で復号化状態を初期化し、暗号文を安全に復元します。これにより、データが断片化されていても、効率的かつ安全なストリーム処理を実現します。

Copy
1<?php
2
3/**
4 * sodium_crypto_secretstream_xchacha20poly1305_keygen() を使用して
5 * ストリーム暗号化と復号化の基本的な流れを示します。
6 *
7 * この関数は、ストリーム暗号化のための共通鍵を生成します。
8 * キーワード "sodium_crypto_box" は公開鍵暗号の機能ですが、
9 * このサンプルでは、Sodium 拡張が提供する「暗号化機能」という広い文脈での関連性を示し、
10 * 与えられたリファレンス情報 (sodium_crypto_secretstream_xchacha20poly1305_keygen) を中心に、
11 * データのセキュアなストリーミング方法を初心者向けに解説します。
12 *
13 * @param string $plaintext 暗号化・復号化する元の平文データ
14 * @return void
15 */
16function encryptAndDecryptDataStream(string $plaintext): void
17{
18    echo "--- ストリーム暗号化・復号化の開始 ---\n\n";
19
20    // 1. ストリーム暗号用の共通鍵を生成します。
21    // この鍵は秘密にしておく必要があり、string型で返されます。
22    $key = sodium_crypto_secretstream_xchacha20poly1305_keygen();
23    echo "【ステップ1】共通鍵を生成しました。\n";
24    echo "鍵の長さ: " . strlen($key) . "バイト\n\n";
25
26    // 2. 暗号化処理の準備: ストリームの初期化
27    // sodium_crypto_secretstream_xchacha20poly1305_init_push は、
28    // ストリームの「プッシュ状態」と、受信側で復号化に必要な「ヘッダー」を返します。
29    [$streamPushState, $header] = sodium_crypto_secretstream_xchacha20poly1305_init_push($key);
30    echo "【ステップ2】暗号化ストリームを初期化しました。\n";
31    echo "ヘッダーの長さ: " . strlen($header) . "バイト\n";
32    echo "このヘッダーは暗号文と共に送信され、復号化時に使用されます。\n\n";
33
34    // 3. データをチャンク（断片）に分けて暗号化します。
35    // ストリーム暗号は、大きなデータをメモリにすべて読み込まずに、
36    // 少しずつ処理するのに適しています。
37    $ciphertextChunks = [];
38    $offset = 0;
39    $chunkSize = 8192; // 8KBずつデータを処理する例
40    $totalPlaintextLength = strlen($plaintext);
41
42    echo "【ステップ3】平文をチャンクに分割し、暗号化しています...\n";
43    while ($offset < $totalPlaintextLength) {
44        $currentChunk = substr($plaintext, $offset, $chunkSize);
45        // 最後のチャンクには特別なタグ `TAG_FINAL` を付けます。
46        $tag = ($offset + $chunkSize >= $totalPlaintextLength) ?
47            SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL :
48            SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE;
49
50        // チャンクを暗号化します。
51        $encryptedChunk = sodium_crypto_secretstream_xchacha20poly1305_push($streamPushState, $currentChunk, '', $tag);
52        $ciphertextChunks[] = $encryptedChunk;
53
54        echo "  - チャンク " . count($ciphertextChunks) . " 暗号化済 (元の長さ: " . strlen($currentChunk) . "バイト)\n";
55        $offset += $chunkSize;
56    }
57    echo "すべてのチャンクの暗号化が完了しました。\n\n";
58
59    // 4. 復号化処理の準備: ストリームの初期化
60    // 受信側では、共通鍵と受け取ったヘッダーを使ってストリームを初期化します。
61    [$streamPullState, $pulledHeader] = sodium_crypto_secretstream_xchacha20poly1305_init_pull($key, $header);
62
63    // ヘッダーが正しく読み込まれたことを確認
64    if ($pulledHeader !== $header) {
65        echo "エラー: 復号化ヘッダーが一致しません。通信が不正な可能性があります。\n";
66        return;
67    }
68    echo "【ステップ4】復号化ストリームを初期化しました。\n";
69    echo "受信したヘッダーが正しく検証されました。\n\n";
70
71    // 5. 暗号化されたチャンクを一つずつ復号化します。
72    $decryptedText = '';
73    echo "【ステップ5】暗号化されたチャンクを復号化しています...\n";
74    foreach ($ciphertextChunks as $index => $encryptedChunk) {
75        // チャンクを復号化し、そのタグも取得します。
76        // タグが `TAG_FINAL` の場合、ストリームの終わりを示します。
77        [$decryptedChunk, $tag] = sodium_crypto_secretstream_xchacha20poly1305_pull($streamPullState, $encryptedChunk);
78        
79        // 復号されたデータを結合します。
80        $decryptedText .= $decryptedChunk;
81        
82        echo "  - チャンク " . ($index + 1) . " 復号化済 (タグ: " . $tag . ")\n";
83    }
84    echo "すべてのチャンクの復号化が完了しました。\n\n";
85
86    // 6. 結果の検証
87    echo "【ステップ6】復号化結果を検証しています...\n";
88    if ($plaintext === $decryptedText) {
89        echo "✅ 成功: 元の平文と復号化されたテキストが完全に一致します。\n";
90        echo "  元の平文の冒頭: '" . substr($plaintext, 0, 100) . "...'\n";
91        echo "  復号化されたテキストの冒頭: '" . substr($decryptedText, 0, 100) . "...'\n";
92    } else {
93        echo "❌ 失敗: 元の平文と復号化されたテキストが一致しません。\n";
94        echo "  データが破損したか、不正な操作が行われた可能性があります。\n";
95    }
96    echo "\n--- ストリーム暗号化・復号化の終了 ---\n";
97}
98
99// サンプルデータとして、比較的長い文字列を生成します。
100$sampleText = str_repeat("これは Libsodium のストリーム暗号化機能のテストデータです。", 500) . // 約2.5KB * 500 = 1.25MB
101              "これでストリームが終了します。";
102
103// 関数を呼び出して、ストリーム暗号化と復号化の処理を実行します。
104encryptAndDecryptDataStream($sampleText);

PHP 8のsodium_crypto_secretstream_xchacha20poly1305_keygen関数は、LibSodium拡張が提供するセキュリティ機能の一つで、ストリーム暗号化のための共通鍵を生成します。この関数は引数を取らず、安全なランダムなバイト列である共通鍵をstring型で返します。この共通鍵は、データの送受信者間で秘密に共有される必要があり、暗号化と復号化の両方に使用されます。

サンプルコードでは、この生成された共通鍵を用いて、大きなデータを効率的に暗号化・復号化するストリーム暗号の基本的な流れを示しています。まず、共通鍵で暗号化ストリームを初期化すると、受信側で復号化に必要な「ヘッダー」が生成されます。次に、元のデータを小さな断片（チャンク）に分け、それぞれをヘッダーと共に送信側で生成されたストリーム状態を使って暗号化します。これにより、全てのデータを一度にメモリに読み込むことなく処理できます。

復号化の際には、同じ共通鍵と受け取ったヘッダーを使って復号化ストリームを初期化し、暗号化された各チャンクを順に復号します。最終的に、元のデータと復号されたデータが一致するかどうか検証することで、データの完全性と機密性が保たれていることを確認しています。この一連の流れは、特にファイル転送やネットワーク通信など、継続的なデータ処理が必要な場面で有効です。