I'm not understanding the password_hash() function

Question

I've just learned that PHP has a password_hash() function, instead of manually calling a hashing algorithm on a password. http://php.net/manual/en/function.password-hash.php

But I have two questions about the documentation.

1. The first one is about the default hashing algorithm, using PASSWORD_DEFAULT as the algorithm. Since PHP 5.5 the algorithm is bcrypt, and then it says:

Note that this constant is designed to change over time as new and stronger algorithms are added to PHP. For that reason, the length of the result from using this identifier can change over time. Therefore, it is recommended to store the result in a database column that can expand beyond 60 characters (255 characters would be a good choice)

How am I supposed to still keep users being able to log in after a hashing algorithm changes, if I'm only keeping the result of a hash, and the result of the password hash will become different?

2. Under the salt option it says:

Warning The salt option has been deprecated as of PHP 7.0.0. It is now preferred to simply use the salt that is generated by default.

If the function will generate a salt, then wouldn't the resulting hash be different in two different executions for the same password? Unless the algorithm for generating salts is such that the same password would always get the same salt, but that would defeat the purpose of using salt, wouldn't it?

Answer 1

How am I supposed to still keep users being able to log in after a hashing algorithm changes, if I'm only keeping the result of a hash, and the result of the password hash will become different?

If the function will generate a salt, then wouldn't the resulting hash be different in two different executions for the same password?

The password_verify() function will detect the hash (and salt) used to hash a specific password and act accordingly.

Use that function to check whether the password input by a user is correct.

Answer 2

How am I supposed to still keep users being able to log in after a hashing algorithm changes, if I'm only keeping the result of a hash, and the result of the password hash will become different?

The password_hash documentation currently gives the following example:

echo password_hash("rasmuslerdorf", PASSWORD_DEFAULT);

This produces output that looks like

$2y$10$.vGA1O9wmRjrwAVXD98HNOgsNpDczlqm3Jq7KnEd1rVAGv3Fykk1a

When you call password_verify, you call it like

password_verify('rasmuslerdorf', '$2y$10$.vGA1O9wmRjrwAVXD98HNOgsNpDczlqm3Jq7KnEd1rVAGv3Fykk1a')

Note that this does not have parameters for the algorithm or options. Why? Because they are stored in that output.

Algorithm	2y
Cost	10
Salt	.vGA1O9wmRjrwAVXD98HNO
Actual hash	gsNpDczlqm3Jq7KnEd1rVAGv3Fykk1a

In other words, password_verify does not get the algorithm from what your program is currently using. It gets it from what is stored in the database. So even if you change the algorithm, it will still use the old algorithm to verify the hash. The actual recommended way to do password verification is something like

if (password_verify($password, $hash)) {
  if (password_needs_rehash($hash, $algo, $options)) {
    $user->set_hash(password_hash($password, $algo, $options));
  }

  return true;
}

return false;

This will update the hash at login whenever it is out of date. The $user->set_hash method would save the new hash to the database (you have to implement this; the password_ functions are part of PHP). The $password is the plain text version just entered by the user. The $hash is the hash previously stored.

You can read more about this at password_needs_rehash in the PHP documentation.

If the function will generate a salt, then wouldn't the resulting hash be different in two different executions for the same password?

It would, but you don't call password_hash to verify the password. Instead, you call password_verify. The password_verify function does not generate a salt. It uses the one from the hash.

You might then ask why use a salt? This is covered extensively in other questions' answers (e.g. here), but the short version is to prevent rainbow tables. With a salt, you would have to create one rainbow table per salt. In this example, the salt is twenty-two characters long. Even if we limited salts to just decimal digits, that would be 10,000,000,000,000,000,000,000 tables. If we allow salts to be any base 64 digit, it's much bigger. Salts don't need to be secret to prevent rainbow tables.