sodium_crypto_pwhash
(PHP 7 >= 7.2.0, PHP 8)
sodium_crypto_pwhash — Argon2 アルゴリズムを使い、パスワードからキーを導出する
説明
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