sodium_crypto_pwhash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash — Argon2 アルゴリズムを使い、パスワードからキーを導出する

説明

sodium_crypto_pwhash(
    int $length,
    #[\SensitiveParameter] string $password,
    string $salt,
    int $opslimit,
    int $memlimit,
    int $algo = SODIUM_CRYPTO_PWHASH_ALG_DEFAULT
): string

この関数は、 libsodium の crypto_pwhash 派生関数への低レベルのアクセスを提供します。この関数を使う明確な理由がなければ、 sodium_crypto_pwhash_str() や password_hash() 関数を代わりに使うべきです。

この関数を使う共通の理由は、パスワードとソルトから暗号化キーのためのシードを導出し、その値を使うことで、特定の目的 (たとえば、sodium_crypto_sign_detached()) で使う実際の鍵を生成することです。

パラメータ

length: 生成するパスワードハッシュの長さ。バイト単位で指定します。
password: ハッシュを生成するパスワードを文字列で指定します。
salt: ハッシュ化する前に、パスワードに追加するソルト値。この値は予測されてはいけません。 random_bytes() のような良質な乱数のソースから生成されることが理想です。そして、長さが正確に SODIUM_CRYPTO_PWHASH_SALTBYTES バイトである必要があります。
opslimit: 実際に行う計算処理の最大量。この値を大きくすると、キーを計算するのに必要なCPUサイクルが増加します。意図した使い方次第で、適切な値の上限値を設定するために、いくつかの定数が存在します。弱いものから強いものへと並べると、以下のとおりです: SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE, SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE
memlimit: この関数が使用するメモリの最大値をバイト単位で指定します。適切な値を選ぶために、ヘルパとなる定数が存在します。サイズの順に、以下の通りです: SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE, SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE これらの値は、opslimit と一致するものとペアになるべきです。
algo: 使用するハッシュアルゴリズムのIDを指定します。デフォルトは、 SODIUM_CRYPTO_PWHASH_ALG_DEFAULT (現状推奨されるアルゴリズム。これは、libsodium のバージョンによって変更されるかもしれません) です。または、 Argon2id アルゴリズム version 1.3 を表す SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13 を明示的に使うこともできます。

戻り値

導出されたキーを返します。返される値は、ハッシュのバイナリ文字列であり、 ASCII でエンコードされた文字列ではありませんし、ハッシュを生成するために使われた追加のパラメータも含まれていません。よって、将来パスワードを検証するためには、それらの情報を保持しておく必要があります。そうなることを避けるために、 sodium_crypto_pwhash_str() を使って下さい。

例

例1 sodium_crypto_pwhash() の例

<?php
//Need to keep the salt if we're ever going to be able to check this password
$salt = random_bytes(SODIUM_CRYPTO_PWHASH_SALTBYTES);
//Using bin2hex to keep output readable
echo bin2hex(
    sodium_crypto_pwhash(
        16, // == 128 bits
        'password',
        $salt,
        SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
        SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE,
        SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13
    )
);
?>

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

a18f346ba57992eb7e4ae6abf3fd30ee