【PHP8.x】Random\Engine\Secure::generate()メソッドの使い方

Copy
1<?php
2
3/**
4 * 指定されたバイト数の暗号論的にセキュアなランダムバイト列を生成し、
5 * それを16進数文字列に変換して返します。
6 *
7 * この関数は、PHP 8で導入された Random\Engine\Secure クラスの
8 * generate メソッドを利用しています。
9 * generate メソッドが返すのはバイナリデータのため、表示に適した
10 * ランダム文字列として利用するために bin2hex 関数で16進数に変換しています。
11 *
12 * @param int $byteLength 生成するランダムなバイト列の長さ（バイト数）。
13 *                        例: 16を指定すると、32文字の16進数文字列が生成されます。
14 * @return string 生成されたランダムな16進数文字列。
15 */
16function generateSecureRandomString(int $byteLength = 16): string
17{
18    // Random\Engine\Secure クラスは、予測不可能な、セキュリティ用途に適した
19    // 暗号論的にセキュアな乱数（ランダムデータ）を生成するためのエンジンを提供します。
20    $engine = new Random\Engine\Secure();
21
22    // generate メソッドを呼び出し、指定されたバイト数($byteLength)の
23    // 暗号論的にセキュアなランダムバイト列を生成します。
24    // この結果はバイナリデータ（生のバイト列）です。
25    $randomBytes = $engine->generate($byteLength);
26
27    // バイナリデータは、そのまま表示すると文字化けする可能性があります。
28    // 人間が読みやすく、ウェブページやファイル名などに利用できる
29    // ランダムな「文字列」として使うため、
30    // bin2hex() 関数を使って、バイナリデータを16進数表現の文字列に変換します。
31    // 例えば、16バイトのバイナリデータは、32文字の16進数文字列になります。
32    return bin2hex($randomBytes);
33}
34
35// ---------- サンプルコードの実行例 ----------
36
37// 32バイトのランダムなバイト列を基に、64文字の16進数文字列を生成して表示します。
38$randomString = generateSecureRandomString(32);
39echo "生成されたセキュアなランダム文字列 (32バイトの元データ): " . $randomString . PHP_EOL;
40
41// 別の長さで試す例：8バイトのランダムなバイト列を基に、16文字の16進数文字列を生成
42$shortRandomString = generateSecureRandomString(8);
43echo "短いセキュアなランダム文字列 (8バイトの元データ): " . $shortRandomString . PHP_EOL;
44

このPHPサンプルコードは、PHP 8で導入されたRandom\Engine\Secureクラスのgenerateメソッドを利用して、暗号論的にセキュアなランダムな16進数文字列を生成するものです。Random\Engine\Secureクラスは、予測困難でセキュリティ用途に適した、高品質なランダムデータを提供するエンジンを提供します。

generateSecureRandomString関数は、引数として受け取る$byteLengthで、生成したいランダムなバイト列の長さを指定します。例えば、$byteLengthに16を指定すると、16バイトのランダムなバイナリデータが生成されます。Random\Engine\Secure::generateメソッドの戻り値はバイナリデータ（生のバイト列）であるため、そのままでは表示に適さず、文字化けする可能性があります。

このため、コードではbin2hex関数を用いて、生成されたバイナリデータを人間が読みやすく、ウェブページやファイル名などに利用できる16進数表現の文字列に変換しています。これにより、元のバイト数の2倍の長さの16進数文字列が得られます。この関数の戻り値は、最終的に生成されたこのランダムな16進数文字列です。セッションIDやトークン、パスワードソルトなど、予測不可能性が求められるセキュリティ関連の用途で安全なランダム文字列が必要な場合に非常に役立ちます。

Copy
1<?php
2
3/**
4 * 暗号学的に安全なランダムバイト列を使用して、RFC 4122 バージョン4に準拠したUUIDを生成します。
5 *
6 * この関数は、PHP 8.2以降で利用可能な Random\Engine\Secure クラスの generate メソッドを使用します。
7 * generate メソッドは、指定されたバイト数の暗号学的に安全なランダムなバイト列を生成します。
8 *
9 * @return string RFC 4122 バージョン4形式のUUID文字列 (例: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx)
10 */
11function generateUuidV4(): string
12{
13    // Random\Engine\Secure クラスのインスタンスを作成します。
14    // これは、オペレーティングシステムが提供する高品質なエントロピー源（乱数の種）を利用して
15    // 暗号学的に安全な乱数を生成するためのエンジンです。
16    $engine = new Random\Engine\Secure();
17
18    // UUIDは16バイト（128ビット）のデータで構成されます。
19    // generate メソッドを呼び出して、16バイトの暗号学的に安全なランダムなバイト列を取得します。
20    $bytes = $engine->generate(16);
21
22    // 取得したバイナリデータを16進数表現の文字列に変換します。
23    // bin2hex 関数は、バイナリ文字列を対応する2文字の16進数文字列に変換します。
24    // 例: 16バイトのデータは32文字の16進数文字列になります。
25    $hex = bin2hex($bytes);
26
27    // UUIDバージョン4の特定の要件を満たすために、いくつかのビットを修正します。
28    // UUIDの標準フォーマットは "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx" です。
29    // ここで '4' はUUIDのバージョンを示し、'y' は予約ビットのパターンを示します。
30
31    // 6バイト目（16進数文字列の12番目の文字）を '4' に設定し、UUIDのバージョンが4であることを示します。
32    // この変更により、UUIDがランダムまたは擬似ランダムなUUIDであることが保証されます。
33    $hex[12] = '4';
34
35    // 8バイト目（16進数文字列の16番目の文字）の最上位2ビットを '10' (バイナリ) に設定します。
36    // これは16進数では '8', '9', 'a', 'b' のいずれかに対応します。
37    // 元の16進数文字を数値に変換し、ビットマスク (0x3) とOR演算 (0x8) を使用して修正後、
38    // 再び16進数文字に戻します。これにより、UUIDのバリアントが正しく設定されます。
39    $hex[16] = dechex((hexdec($hex[16]) & 0x3) | 0x8);
40
41    // 最後に、生成された16進数文字列をUUIDの標準フォーマットに整形します。
42    // ハイフンで区切られた5つのセクション（8-4-4-4-12文字）を持つ形式にします。
43    return sprintf(
44        '%s-%s-%s-%s-%s',
45        substr($hex, 0, 8),    // 最初の8文字
46        substr($hex, 8, 4),    // 次の4文字
47        substr($hex, 12, 4),   // 次の4文字 (バージョン'4'を含む)
48        substr($hex, 16, 4),   // 次の4文字 (予約ビットを含む)
49        substr($hex, 20, 12)   // 最後の12文字
50    );
51}
52
53// この関数が正しく動作することを確認するための簡単な実行例です。
54// 実際のアプリケーションでは、この関数を呼び出してUUIDを取得し、必要に応じて使用します。
55// 例:
56// echo generateUuidV4() . PHP_EOL;

このPHPコードは、RFC 4122 バージョン4に準拠したUniversally Unique Identifier（UUID）を生成するgenerateUuidV4関数です。UUIDは、ネットワーク上のあらゆる場所で一意性が保証される識別子として広く利用されます。

UUID生成の核となるのは、PHP 8.2以降で利用可能なRandom\Engine\Secureクラスです。このクラスは、オペレーティングシステムが提供する高品質なエントロピー源を利用し、暗号学的に安全な乱数を生成するためのエンジンです。

サンプルコードではまず、Random\Engine\Secureのインスタンスを作成します。次に、そのインスタンスのgenerateメソッドを呼び出し、引数に16を指定して16バイトの暗号学的に安全なランダムなバイト列を取得します。このgenerateメソッドは、引数int $bytesで指定されたバイト数のランダムなバイナリデータをstring型で返します。

取得したバイナリデータは、bin2hex関数によって16進数表現の文字列に変換されます。その後、RFC 4122 バージョン4の規定に基づき、UUIDのバージョンを示すために特定の文字を'4'に、またバリアントを示すために別の特定の文字のビットを修正します。最後に、sprintf関数とsubstr関数を使って、16進数文字列を「xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx」という標準的なUUID形式に整形して返します。

この関数を使用することで、システムエンジニアは、データベースの主キー、セッションID、分散システムにおけるトランザクションIDなど、高い一意性と安全性が求められる識別子を容易に生成できます。