password_needs_rehash

(PHP 5 >= 5.5.0)

password_needs_rehash — Checks if the given hash matches the given options

说明

boolean password_needs_rehash ( string $hash , integer $algo [, array $options ] )

This function checks to see if the supplied hash implements the algorithm and options provided. If not, it is assumed that the hash needs to be rehashed.

参数

hash: 一个由 password_hash() 创建的散列值。
algo: 一个用来在散列密码时指示算法的密码算法常量。
options: 一个包含有选项的关联数组。目前支持两个选项：salt，在散列密码时加的盐（干扰字符串），以及cost，用来指明算法递归的层数。这两个值的例子可在 crypt() 页面找到。

范例

Example #1 Usage of password_needs_rehash()

  <?php

$password  =  'rasmuslerdorf' ;
 $hash  =  '$2y$10$YCFsG6elYca568hBi2pZ0.3LDL5wjgxct1N8w/oLR/jfHsiQwCqTS' ;

 // The cost parameter can change over time as hardware improves
 $options  = array( 'cost'  =>  11 );

 // Verify stored hash against plain-text password
 if ( password_verify ( $password ,  $hash )) {
     // Check if a newer hashing algorithm is available
    // or the cost has changed
     if ( password_needs_rehash ( $hash ,  PASSWORD_DEFAULT ,  $options )) {
         // If so, create a new hash, and replace the old one
         $newHash  =  password_hash ( $password ,  PASSWORD_DEFAULT ,  $options );
    }

     // Log user in
 }
 ?>

返回值

Returns TRUE if the hash should be rehashed to match the given algo and options, or FALSE otherwise.

用户评论:

[#1] admin at torntech dot com [2014-09-13 14:48:03]

Some other use-cases for the password_needs_rehash function is when you have specified using the PASSWORD_DEFAULT algorithm for password_hash.
As mentioned on the Password Hashing Predefined Constants and password_hash pages, the algorithm used by PASSWORD_DEFAULT is subject to change as different versions of PHP are released.
Additionally password_needs_rehash would be used if you have changed the optional cost or static salt (DO NOT USE A STATIC SALT) requirements of your password_hash options.

Full example:

<?php $new = [ 'options' => ['cost' => 11], 'algo' => PASSWORD_DEFAULT, 'hash' => null ]; $password = 'rasmuslerdorf'; //stored hash of password $oldHash = '$2y$07$BCryptRequires22Chrcte/VlQH0piJtjXl.0t1XkA8pw9dMXTpOq'; //verify stored hash against plain-text password if (true === password_verify($password, $oldHash)) { //verify legacy password to new password_hash options if (true === password_needs_rehash($oldHash, $new['algo'], $new['options'])) { //rehash/store plain-text password using new hash $newHash = password_hash($password, $new['algo'], $new['options']); echo $newHash; } } ?>

The above example will output something similar to:
$2y$11$Wu5rN3u38.g/XWdUeA6Wj.PD.F0fLXXmZrMNFyzzg2UxkVmxlk41W

[#2] php dot net at muer dot nl [2014-05-13 21:39:04]

nick, this function cannot check if a string is a MD5 or SHA1 hash. It can only tell you if a password, hashed using the password_hash function, needs to be put through the hashing function again to keep up to date with the new defaults.

The only time you can use this function is when your user logs in and you have already checked by means of password_verify that the password entered is actually correct. At that point, if password_needs_rehash returns true, you can put the plain text password through the password_hash function.

[#3] nick at nickstallman dot net [2013-07-18 00:02:54]

ydroneaud this would be used on a login page, not at any other time.

So if you have a site with MD5 passwords for example, and wish to upgrade to SHA256 for additional security you would put this check in the login script.

This function will take a user's hash and say if it is SHA256, if it isn't then you can take the user's password which you still have as plaintext and rehash it as SHA256.

This lets you gradually update the hashes in your database without disrupting any features or resetting passwords.

[#4] ydroneaud at opteya dot com [2013-06-21 17:11:31]

According to the documentation, it's checking if the given hashed password string is compatible with the provided algorithm (and options, but not salt), eg. it's checking if the hashed password string was generated with the provided algorithm (and options, but not salt).

There's nothing to 'rehash' in its parameters ... especially not the already hashed password string, and the password "stored" in the hashed password string is not supposed to be known, it's not in clear, it's a secret.

The name of the function seems misleading, this function should have been called "password_hash_compatible()" instead.

This function could be use to check if a password database/a hashed password string (hashed by function "password_hash()") need to be upgraded to a stronger password hashing/storage scheme: if the function returns false, a new password will have to be set for the user, hashed with the new, stronger, algorithm/options.

One should carefully think before using this function to support multiple algorithms/options in one database, eg. support "legacy scheme" passwords + "new scheme" ...