PBKDF2 を使ってパスワードからキーを生成する

説明

hash_pbkdf2(
    string $algo,
    #[\SensitiveParameter] string $password,
    string $salt,
    int $iterations,
    int $length = 0,
    bool $binary = false,
    array $options = []
): string

パラメータ

algo

ハッシュアルゴリズムの名前 (例: "sha256")。サポートされるアルゴリズムの一覧は hash_hmac_algos() をご参照ください。

注意:
暗号に適さないハッシュ関数は許可されません。

password

導出に使うパスワード

salt

導出に使うソルト。ランダムに生成した値でなければいけません。

iterations

導出の実行の際の内部の反復回数

length

出力する文字列の長さ。binary が true の場合、これは導出鍵のバイト長になります。 binary が false の場合、これは導出鍵のバイト長の二倍になります (キーの全バイトが十六進二桁で返されるからです)。

0が渡された場合、与えられたアルゴリズムの出力全体が使われます。

binary

true にセットされている場合、生のバイナリデータが出力されます。false の場合、小文字の16進数が出力されます。

options

様々なハッシュアルゴリズム向けの、オプションの配列。現状は、MurmurHash バリアントが "seed" だけをサポートしています。

戻り値

小文字の16進数を含む文字列が返されます。binary が true の場合、導出鍵の生のバイナリ表現が返されます。

エラー / 例外

アルゴリズムが未知である場合、 iterations パラメータが 0 以下である場合、 length が 0 よりも小さい場合、 salt が長すぎる場合 (INT_MAX - 4 よりも大きい) に、 ValueError がスローされます。

変更履歴

バージョン	説明
8.0.0	エラーが発生した場合に、 ValueError をスローするようになりました。これより前のバージョンでは、 `false` を返し、 `E_WARNING` が発生していました。
7.2.0	暗号の使用に適さないハッシュ関数 (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) は使えなくなりました。

例

例1 hash_pbkdf2() の基本的な使い方の例

<?php
$password = "password";
$iterations = 600000;

// Generate a cryptographically secure random salt using random_bytes()
$salt = random_bytes(16);

$hash = hash_pbkdf2("sha256", $password, $salt, $iterations, 20);
var_dump($hash);

// for raw binary, the $length needs to be halved for equivalent results
$hash = hash_pbkdf2("sha256", $password, $salt, $iterations, 10, true);
var_dump(bin2hex($hash));?>

上の例の出力は、たとえば以下のようになります。

string(20) "120fb6cffcf8b32c43e7"
string(20) "120fb6cffcf8b32c43e7"

注意

警告

PBKDF2 による方法はパスワードのハッシュを保存するために使うことができます。しかし、password_hash() や crypt() で CRYPT_BLOWFISH を使うのほうが、パスワードの保存に適しています。

参考

password_hash() - パスワードハッシュを作る
hash_hkdf() - 与えられたキーから導出されるHKDFキーを生成する
sodium_crypto_pwhash() - Argon2 アルゴリズムを使い、パスワードからキーを導出する