password_hash

(PHP 5 >= 5.5.0, PHP 7)

password_hashパスワードハッシュを作る

説明

string password_hash ( string $password , integer $algo [, array $options ] )

password_hash() は、強力な一方向ハッシュアルゴリズムを使って 新しいパスワードハッシュを作ります。 password_hash()crypt() と互換性があるので、 crypt() が作ったパスワードハッシュは password_hash() でも使えます。

現在、これらのアルゴリズムに対応しています。

  • PASSWORD_DEFAULT - bcrypt アルゴリズムを使います (PHP 5.5.0 の時点でのデフォルトです)。 新しくてより強力なアルゴリズムが PHP に追加されれば、 この定数もそれにあわせて変わっていきます。 そのため、これを指定したときの結果の長さは、変わる可能性があります。 したがって、結果をデータベースに格納するときにはカラム幅を 60 文字以上にできるようなカラムを使うことをお勧めします (255 文字くらいが適切でしょう)。
  • PASSWORD_BCRYPT - CRYPT_BLOWFISH アルゴリズムを使ってハッシュを作ります。これは標準の crypt() 互換のハッシュで、識別子 "$2y$" を使った場合の結果を作ります。 その結果は、常に 60 文字の文字列になります。失敗した場合に FALSE を返します。

サポートするオプション

  • salt - パスワードのハッシュに使うソルトを手動で設定します。 これは、自動生成されたソルトを上書きすることに注意しましょう。

    省略した場合は、パスワードをハッシュするたびに password_hash() がランダムなソルトを自動生成します。これは意図したとおりの操作モードです。

    警告

    このソルト・オプションは、PHP 7.0.0 で非推奨になりました。 このオプションは指定せずに、デフォルトで生成されるソルトを使うことを推奨します。

  • cost - 利用するアルゴリズムのコストを表します。 値の例については crypt() のページを参照ください。

    省略した場合のデフォルトは 10 です。この値でもかまいませんが、 ハードウェアの性能が許すならもう少し高くすることもできます。

パラメータ

password

ユーザーのパスワード。

警告

PASSWORD_BCRYPT をアルゴリズムに指定すると、 password が最大 72 文字までに切り詰められます。

algo

パスワードのハッシュに使うアルゴリズムを表す パスワードアルゴリズム定数

options

オプションを含む連想配列。各アルゴリズムがサポートするオプションについては、 パスワードアルゴリズム定数 のページを参照ください。

省略した場合は、ランダムな salt を生成してデフォルトのコストを使います。

返り値

ハッシュしたパスワードを返します。失敗した場合に FALSE を返します。

使ったアルゴリズムやコスト、そしてソフトもハッシュの一部として返されます。 つまり、ハッシュを検証するために必要な情報は、すべてそこに含まれているということです。 そのため、password_verify() でハッシュを検証するときに、 ソルトやアルゴリズムの情報を別に保存する必要はありません。

例1 password_hash() の例

<?php
/**
 * デフォルトのアルゴリズムを使ってパスワードをハッシュします。
 * 現時点でのデフォルトは BCRYPT で、その結果は 60 文字になります。
 *
 * デフォルトは、今後変わる可能性があることに注意しましょう。結果が
 * 60 文字以上になっても対応できるようにしておきましょう (255 あたりが適切です)
 */
echo password_hash("rasmuslerdorf"PASSWORD_DEFAULT)."\n";
?>

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

$2y$10$.vGA1O9wmRjrwAVXD98HNOgsNpDczlqm3Jq7KnEd1rVAGv3Fykk1a

例2 password_hash() で、コストを手動で設定する例

<?php
/**
 * この例では、BCRYPT のコストをデフォルトより上げて、12 にします。
 * また、アルゴリズムを BCRYPT に変えたことにも注目しましょう。結果は常に 60 文字になります。
 */
$options = [
    
'cost' => 12,
];
echo 
password_hash("rasmuslerdorf"PASSWORD_BCRYPT$options)."\n";
?>

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

$2y$12$QjSH496pcT5CEbzjD/vtVeH03tfHKFy36d4J0Ltp3lRtee9HDxY3K

例3 password_hash() で、ソルトを手動で設定する例

<?php
/**
 * ここでは、ソルトをランダムに生成するようにしています。
 * 固定のソルトを使ったり、ランダムではない方法で作ったソルトを使ったりしてはいけません。
 *
 * 利用例の大半にあわせて、password_hash にランダムなソルトを生成させます。
 */
$options = [
    
'cost' => 11,
    
'salt' => mcrypt_create_iv(22MCRYPT_DEV_URANDOM),
];
echo 
password_hash("rasmuslerdorf"PASSWORD_BCRYPT$options)."\n";
?>

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

$2y$11$q5MkhSBtlsJcNEVsYh64a.aCluzHnGog7TQAKVmQwO9C8xb.t89F.

例4 password_hash() で、適切なコストを探す例

<?php
/**
 * このコードは、サーバーをベンチマークして、どの程度のコストに耐えられるかを判断します。
 * サーバーに負荷をかけすぎない範囲で、できるだけ高めのコストを設定したいものです。
 * 基準として 8 から 10 程度からはじめ、サーバーが十分に高速なら、できるだけ上げていきましょう。
 * 以下のコードでは、ストレッチングの時間を 50 ミリ秒以内にすることを狙っています。
 * 対話形式のログインを扱う際の許容時間としては、このあたりが妥当なところでしょう。
 */
$timeTarget 0.05// 50 ミリ秒

$cost 8;
do {
    
$cost++;
    
$start microtime(true);
    
password_hash("test"PASSWORD_BCRYPT, ["cost" => $cost]);
    
$end microtime(true);
} while ((
$end $start) < $timeTarget);

echo 
"Appropriate Cost Found: " $cost "\n";
?>

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

Appropriate Cost Found: 10

注意

警告

この関数で使うソルトを自前で設定するのはお勧めしません。 ソルトを省略すれば、安全なソルトをこの関数が自動的に作ってくれます。

先述のとおり、PHP 7.0 で salt オプションを指定すると、 非推奨の警告が発生します。ソルトを手動で設定する仕組みは、将来のリリースで廃止されるかもしれません。

注意:

実際にサーバー上でこの関数をテストして、コストパラメータの適切な設定値を調整することをお勧めします。 対話型のシステムなら、関数の実行時間が 100 ミリ秒くらいに収まるくらいが適切です。 先ほどの例のスクリプトは、自分のハードウェア上での適切なコストを判断するための助けとなるでしょう。

注意: この関数がサポートするアルゴリズムの更新 (あるいはデフォルトのアルゴリズムの変更) は、必ず次の手順にのっとって行われます。

  • 新しく追加されたアルゴリズムがデフォルトになるまでには、 少なくとも一度は PHP のフルリリースを経ること。 つまり、たとえば、新しいアルゴリズムが 7.5.5 で追加されたとすると、 そのアルゴリズムがデフォルトになるのは早くても 7.7 以降ということになります (7.6 は、最初のフルリリースだからです)。 しかし、もし別のアルゴリズムが 7.6.0 で追加されたとすると、 そのアルゴリズムも 7.7.0 の時点でデフォルトになる資格を得ます。
  • デフォルトを変更できるのはフルリリース (7.3.0 や 8.0.0 など) のときだけで、リビジョンリリースでは変更できない。 唯一の例外は、現在のデフォルトにセキュリティ上の致命的な欠陥が発覚した場合の緊急リリースです。

参考

add a note add a note

User Contributed Notes 10 notes

up
150
martinstoeckli
4 years ago
There is a compatibility pack available for PHP versions 5.3.7 and later, so you don't have to wait on version 5.5 for using this function. It comes in form of a single php file:
https://github.com/ircmaxell/password_compat
up
32
nicoSWD
4 years ago
I agree with martinstoeckli,

don't create your own salts unless you really know what you're doing.

By default, it'll use /dev/urandom to create the salt, which is based on noise from device drivers.

And on Windows, it uses CryptGenRandom().

Both have been around for many years, and are considered secure for cryptography (the former probably more than the latter, though).

Don't try to outsmart these defaults by creating something less secure. Anything that is based on rand(), mt_rand(), uniqid(), or variations of these is *not* good.
up
34
Cloxy
4 years ago
You can produce the same hash in php 5.3.7+ with crypt() function:

<?php

$salt
= mcrypt_create_iv(22, MCRYPT_DEV_URANDOM);
$salt = base64_encode($salt);
$salt = str_replace('+', '.', $salt);
$hash = crypt('rasmuslerdorf', '$2y$10$'.$salt.'$');

echo
$hash;

?>
up
9
Lyo Mi
1 year ago
Please note that password_hash will ***truncate*** the password at the first NULL-byte.

http://blog.ircmaxell.com/2015/03/security-issue-combining-bcrypt-with.html

If you use anything as an input that can generate NULL bytes (sha1 with raw as true, or if NULL bytes can naturally end up in people's passwords), you may make your application much less secure than what you might be expecting.

The password
$a = "\01234567";
is zero bytes long (an empty password) for bcrypt.

The workaround, of course, is to make sure you don't ever pass NULL-bytes to password_hash.
up
6
VladimirMozhenkov at yahoo dot com
2 years ago
Note that this function can return NULL. It does so if you provide an incorrect constant as an algorythm. I had the following:

    $password = password_hash($password1, PASSWORD_BDCRYPT, array( 'cost' => 10 ));

and i couldn't understand why i kept having NULL written in $password; it was a simple fact that the constant was PASSWORD_BCRYPT.
up
8
Mike Robinson
3 years ago
For passwords, you generally want the hash calculation time to be between 250 and 500 ms (maybe more for administrator accounts). Since calculation time is dependent on the capabilities of the server, using the same cost parameter on two different servers may result in vastly different execution times. Here's a quick little function that will help you determine what cost parameter you should be using for your server to make sure you are within this range (note, I am providing a salt to eliminate any latency caused by creating a pseudorandom salt, but this should not be done when hashing passwords):

<?php
/**
* @Param int $min_ms Minimum amount of time in milliseconds that it should take
* to calculate the hashes
*/
function getOptimalBcryptCostParameter($min_ms = 250) {
    for (
$i = 4; $i < 31; $i++) {
       
$options = [ 'cost' => $i, 'salt' => 'usesomesillystringforsalt' ];
       
$time_start = microtime(true);
       
password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options);
       
$time_end = microtime(true);
        if ((
$time_end - $time_start) * 1000 > $min_ms) {
            return
$i;
        }
    }
}
echo
getOptimalBcryptCostParameter(); // prints 12 in my case
?>
up
4
anonymous
1 year ago
Pay close attention to the maximum allowed length of the password parameter!  If you exceed the maximum length, it will be truncated without warning.

If you prepend your own salt/pepper to the password, and that salt/pepper exceeds the maximum length, then this function will truncate the actual password.  That means password_verify() will return true with ANY password using the same salt/pepper.

It might be a good idea to append any salt/pepper to the end of the password instead.
up
8
martinstoeckli
4 years ago
In most cases it is best to omit the salt parameter. Without this parameter, the function will generate a cryptographically safe salt, from the random source of the operating system.
up
4
cottton
3 years ago
if you thought
"why is the salt included in the hash and is it save when i store it as it is in my db?"

Answer i found:
The salt just has to be unique. It not meant to be a secret.

As mentioned in notes and docu before: let password_hash() take care of the salt.

With the unique salt you force the attacker to crack the hash.
The hash is unique and cannot be found at rainbow tables.
up
-22
darkflib
1 year ago
Timings:

Note: 1 and 2 for cost are invalid.

3  -  0.085115432739258ms
4  -  1.6319751739502ms
5  -  2.9170513153076ms
6  -  5.511999130249ms
7  -  10.689973831177ms
8  -  20.890951156616ms
9  -  41.686058044434ms
10  -  84.12504196167ms (default)
11  -  168.97416114807ms
12  -  334.79714393616ms
13  -  680.88603019714ms
14  -  1342.1139717102ms
15  -  2706.4559459686ms
16  -  5404.2019844055ms
17  -  10615.604162216ms

For an average site the default of 10 is probably a sane enough value.
To Top