PHP Password Functions In 5.5

New in PHP 5.5 is a group of functions that deal with password hashing and verification. This is such a common thing for PHP applications to do that it was decided to include it into the core of PHP. They effectively solve the problem of hashing and comparing passwords that just about every PHP developer has implemented at one point or another.

There are only a few functions available but they provide all of the functionality needed to create a hash value from a password, check if the hash is valid and to check if the password hash needs to be recreated.

To create a hash value from a password use the password_hash() function. The first parameter is the password string and the second value is the hashing algorithm to use. The value PASSWORD_DEFAULT here is a PHP constant that is currently set to the bcrypt algorithm and will be changed to better algorithms when and if they are found in newer versions of PHP.

$password = 'changeme';
$password_hash = password_hash($password, PASSWORD_DEFAULT);

You can force the password_hash() function to always use the bcrypt algorithm by using the PASSWORD_BCRYPT constant.

$password = 'changeme';
$password_hash = password_hash($password, PASSWORD_BCRYPT);

The password_hash() function also takes a third parameter of an array of options. This allows you to set a default salt and cost for the encryption algorithm. The 'salt' value allows you to enter a pre-determined salt for use when hashing the password, if this is omitted then a random salt is generated by the password_hash() function.

$password_hash = password_hash($password, PASSWORD_DEFAULT, array('salt' => 'sfyaisdyfiosydfsd6f896sd68f8asdftasdiutfisduft'));

The 'cost' parameter essentially describes the number of iterations that the hashing algorithm will run through, although it really represents a logarithmic iteration value. The default value is 10, which is a good baseline. Increasing this value will allow for a more secure hash, but will adversely effect the performance of the function.

$password_hash = password_hash($password, PASSWORD_DEFAULT, array('salt' => 'sfyaisdyfiosydfsd6f896sd68f8asdftasdiutfisduft', 'cost' => 12));

Once the hash has been created you can then verify that the password matches the hash value using the password_verify() function. The two parameters that this function takes are the password and the hashed password value.

$password = 'changeme';
$password_hash = password_hash($password, PASSWORD_DEFAULT);
if (password_verify($password, $password_hash))) {
  // password is valid
}

You can also check to see if the password hash needs to be redone with the password_needs_rehash() function. This will check a hashed password and return true if the hashed value was generated by a different hashing algorithm. This allows you to update your existing password hashes when a change to the algorithm has been made. If this returns true then you would rehash the password again in order to save it under the new algorithm.

$password = 'change me';
$password_hash = ''; // existing password hash
if (password_needs_rehash($password_hash, PASSWORD_DEFAULT)) {
  $password_hash = password_hash($password, PASSWORD_DEFAULT);
}

Because passwords created by password_hash() use the C crypt scheme you can also use password_verify() to check hashes from the crypt() function in the same way as you would from the password_hash() function.

$password = 'password';
$password_hash = crypt($password);
var_dump(password_verify($password, $password_hash));

If you are running a version of PHP less than 5.5 then there is a userland implementation of the password functions available. All you need to do is download the password.php file (in the lib directory) and include it in your application to start using these functions. You can also wrap it in an 'if' statement in order to detect the correct version of PHP and only include the password file if the version is less than 5.5. The upshot of this method is that you can be sure that your code will still work when up upgrade your PHP version to 5.5, and all you have to do is remove this single reference.

if (version_compare(phpversion(), '5.5', '<')) {
  require('password.php');
}