sodium_crypto_pwhash
Argon2 アルゴリズムを使い、パスワードからキーを導出する
説明
string sodium_crypto_pwhash(
int $length,
#[\SensitiveParameter]string $password,
string $salt,
int $opslimit,
int $memlimit,
int $algo = SODIUM_CRYPTO_PWHASH_ALG_DEFAULT
)
この関数を使う共通の理由は、
パスワードとソルトから暗号化キーのためのシードを導出し、
その値を使うことで、特定の目的
(たとえば、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