【PHP8.x】hash_hkdf関数の使い方

hash_hkdf関数の使い方について、初心者にもわかりやすく解説します。

作成日: 2025年09月11日更新日: 2025年09月29日

基本的な使い方

hash_hkdf関数は、HKDF (HMAC-based Extract-and-Expand Key Derivation Function) と呼ばれる、弱いキーから暗号学的に安全なキーを導出するためのアルゴリズムを実行し、強力な鍵を導出する関数です。

この関数は、情報量の少ない初期キーや秘密情報から、暗号化や認証などのセキュリティ用途に適した、予測困難で安全な鍵を生成するために利用されます。具体的には、algo引数で指定されたハッシュアルゴリズム（例: 'sha256'）を使用し、key引数で与えられた入力キー、オプションのsalt引数で与えられるソルト値、そしてinfo引数で与えられるキーの用途を区別するための追加情報に基づいて、length引数で指定されたバイト長の導出キーを生成します。

生成された導出キーはバイナリ文字列として返されます。主に、共通鍵暗号化の鍵生成やメッセージ認証コード（MAC）の鍵派生など、セキュリティが非常に重要なアプリケーションで安全な鍵を構築する際に役立ちます。

利用する際は、適切なハッシュアルゴリズムの選択と、ランダムでユニークなソルトの使用が推奨されます。ただし、この関数はパスワードを直接ハッシュ化して保存する目的には推奨されません。パスワードストレージには、password_hash()関数のような専用の機能を使用するべきです。

この関数はPHP 8.4で追加された機能です。

構文(syntax)


1<?php
2
3$derivedKey = hash_hkdf(
4    'sha256',              // 使用するハッシュアルゴリズム
5    'input key material',  // 入力鍵マテリアル (IKM)
6    32,                    // 生成する鍵の長さ (バイト単位)。0の場合、アルゴリズムのハッシュ出力長になる
7    'info for encryption', // 鍵の用途やコンテキスト情報
8    'salt value'           // ソルト値
9);
10
11?>

引数(parameters)

string $algo, string $key, int $length = 0, string $info = '', string $salt = ''

string $algo: 鍵導出関数で使用するハッシュアルゴリズム名 (例: 'sha256')
string $key: 導出する鍵の元となる秘密鍵
int $length = 0: 導出する鍵の長さ。0を指定するとアルゴリズムのデフォルト長が使用される
string $info = '': 派生鍵のコンテキストや用途を指定する情報文字列
string $salt = '': 鍵導出プロセスで使用するソルト。指定しない場合はランダムなソルトが生成される

戻り値(return)

string

指定されたキーとアルゴリズムに基づいて生成された、キー拡張値（鍵拡張値）を文字列として返します。

サンプルコード

PHP hash_hkdfで鍵を導出する


1<?php
2
3declare(strict_types=1);
4
5/**
6 * hash_hkdf を使用して鍵を導出するサンプル
7 *
8 * hash_hkdf は、HMAC (Hash-based Message Authentication Code) を利用した
9 * 鍵導出関数 (HKDF) です。HMAC の計算には内部的に hash_hmac() と同様の
10 * メカニズムが使われています。
11 *
12 * この関数は、一つのマスターキーから、暗号化キーや認証キーなど、
13 * 用途に応じた複数の安全なキーを生成するのに役立ちます。
14 *
15 * @return void
16 */
17function generateDerivedKey(): void
18{
19    // --- パラメータ設定 ---
20
21    // hash_hmac で使用されるハッシュアルゴリズム
22    $algorithm = 'sha256';
23
24    // 元となるキー (Input Keying Material)
25    // 実際には、より安全な方法で生成・管理されたキーを使用します。
26    $inputKey = random_bytes(32);
27
28    // 生成したい派生キーの長さ (バイト単位)
29    // 例: AES-256-GCM で使用する 32 バイト (256 ビット) のキーを生成
30    $outputLength = 32;
31
32    // 派生キーの用途を区別するための情報 (省略可能)
33    // これを変えることで、同じ入力キーから異なるキーを安全に生成できます。
34    $info = 'authentication-key';
35
36    // キーの強度を高めるためのソルト (省略可能ですが強く推奨)
37    $salt = random_bytes(16);
38
39    // --- 鍵の導出 ---
40
41    // hash_hkdf関数を呼び出して、新しいキーを生成します。
42    $derivedKey = hash_hkdf($algorithm, $inputKey, $outputLength, $info, $salt);
43
44    // --- 結果の表示 ---
45
46    echo "■ 元のキーとパラメータ" . PHP_EOL;
47    echo "アルゴリズム: " . $algorithm . PHP_EOL;
48    echo "入力キー (hex):   " . bin2hex($inputKey) . PHP_EOL;
49    echo "情報 (info):      " . $info . PHP_EOL;
50    echo "ソルト (hex):     " . bin2hex($salt) . PHP_EOL;
51    echo PHP_EOL;
52
53    echo "■ 導出されたキー" . PHP_EOL;
54    echo "長さ:             " . strlen($derivedKey) . " バイト" . PHP_EOL;
55    echo "派生キー (hex):   " . bin2hex($derivedKey) . PHP_EOL;
56}
57
58// サンプル関数を実行します
59generateDerivedKey();

PHPのhash_hkdf関数は、HMAC（Hash-based Message Authentication Code）の技術を応用した鍵導出関数（HKDF）です。この関数は、一つのマスターキーから、暗号化用や認証用など、用途に応じた複数の安全な新しいキー（派生キー）を生成するために使用されます。内部的には、キーワードにもあるhash_hmac関数と同様の仕組みが利用されています。

第1引数$algoには、'sha256'のようなハッシュアルゴリズムを指定します。第2引数$keyには、派生キーの元となるマスターキーを渡します。第3引数$lengthで、生成したいキーの長さをバイト単位で指定します。0を指定すると、使用するハッシュアルゴリズムの出力サイズと同じ長さになります。第4引数$infoは、キーの用途を区別するための情報です。これを変えることで、同じマスターキーからでも異なるキーを安全に生成できます。第5引数$saltは、キーの強度を高めるためのランダムな値で、セキュリティ向上のために使用することが強く推奨されます。

これらの引数に基づいて、関数は指定された長さの新しい派生キーを計算し、その結果を文字列として返します。このサンプルコードは、ランダムに生成したキーとソルトを使い、安全な派生キーを生成する一連の流れを示しています。

hash_hkdfはマスターキーから複数の安全な鍵を生成するための関数です。サンプルの$inputKeyはランダムなマスターキーを想定していますが、パスワードなどから鍵を導出する場合は、事前にArgon2やPBKDF2のようなパスワードハッシュ関数で十分なストレッチングを行うことが重要です。$saltは省略可能とありますが、セキュリティ強化のために必ず使用し、毎回異なるランダムな値を使ってください。また、$info引数には鍵の用途を明確にする文字列を指定することで、同じ入力キーから異なる用途の鍵を安全に導出できます。導出された鍵は機密情報ですので、サンプルコードのように表示せず、厳重に管理してください。