Edit Report a Bug

sodium_crypto_pwhash_str

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_str — ASCII 文字でエンコードされたハッシュ値を得る

説明

sodium_crypto_pwhash_str(string $password, int $opslimit, int $memlimit): string

ランダムに生成されたソルト値と、 CPU とメモリへの攻撃に強いハッシュアルゴリズムを使い、指定されたメモリとCPUの使用量の最大値に基づき、パスワードの保存に適した ASCII 文字でエンコードされたハッシュを生成します。

パラメータ

password: ハッシュを生成するパスワードを文字列で指定します。
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 と一致するものとペアになるべきです。

戻り値

ハッシュ化されたパスワードを返します。

同じパスワードから同じパスワードハッシュを生成するには、 opslimit と memlimit の値を同じにしなければいけません。これらは生成されたハッシュに埋め込まれているので、ハッシュを検証する際に必要な全てが含まれています。これによって、 sodium_crypto_pwhash_str_verify() 関数が、他の引数に関する情報を追加で保存せずにハッシュを検証できるのです。

例

例1 sodium_crypto_pwhash_str() の例

<?php
$password = 'password';
echo sodium_crypto_pwhash_str(
    $password,
    SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
    SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE
);

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

$argon2id$v=19$m=65536,t=2,p=1$oWIfdaXwWwhVmovOBc2NAQ$EbsZ+JnZyyavkafS0hoc4HdaOB0ILWZESAZ7kVGa+Iw

注意

注意:
ハッシュ値は Argon2ID アルゴリズムを使って計算されます。このアルゴリズムは、GPU に対する攻撃とサイドチャネル攻撃の両方に対する耐性を提供します。 password_hash() と異なり、 salt の引数は存在せず(自動生成されます)、 opslimit と memlimit の値が必須になっています。

参考

sodium_crypto_pwhash_str_verify() - パスワードが、ハッシュ値と一致するかを調べる
sodium_crypto_pwhash() - Argon2 アルゴリズムを使い、パスワードからキーを導出する
password_hash() - パスワードハッシュを作る
password_verify() - パスワードがハッシュにマッチするかどうかを調べる
» Libsodium Argon2 docs

add a note

User Contributed Notes 1 note

down

marcus at synchromedia dot co dot uk ¶

3 years ago


If you want to ensure that the hashes you generate with sodium_crypto_pwhash_str are compatible with those generated by password_hash, you need to keep an eye on that memory setting. According to the docs, the password_hash memory_cost param is given in "kibibytes", whereas sodium_crypto_pwhash_str uses bytes. I did some experiments to see what the difference is and ran into this:

echo password_hash('password',
                   PASSWORD_ARGON2ID,
                   [
                       'memory_cost' => 15000,
                       'time_cost'   => 26,
                       'threads'     => 1,
                   ];

echo sodium_crypto_pwhash_str(
        'password', 26,
        15000000);

These result in:
$argon2id$v=19$m=15000,t=26,p=1$VG5MSkhUdEdFaGwyVG5sWA$laRHogIVAnC4ggLI8RdCDWlITTdicrdq0tK6SHGf4CI
$argon2id$v=19$m=14648,t=26,p=1$ClQ37/z9u7K6V1C2bkD4QA$51m8KhQQ9gujFSF+JyQR9d5QesayJiKsFmDU4HnGBHg

Notice that the "m=" numbers are different, and also different from what we asked for. It's down to the "kibibytes" unit. If we multiply the 15000 we used for password_hash by 1,024 instead of 1,000, we get 15,360,000, and using that number gives us the expected hash params:

echo sodium_crypto_pwhash_str(
        'password', 26,
        15360000);

$argon2id$v=19$m=15000,t=26,p=1$Qz3pWktOvT6X/LvdAk0bgQ$KosSFPfHUtWg+ppyRs3Op5/zIV6F6iy2Q7Gom8wP29c

This should be compatible with password_hash.

Incidentally the numbers I'm using for the Argon2id hash params are taken from the OWASP password guide, which recommend values different from PHP's default: https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#argon2id

add a note