Laravel - How do you use Hash::needsRehash()?

Question

I'm wondering how to use Hash::needsRehash() as I'm struggling to see using the documentation exactly what it's for.

if (Hash::needsRehash($hashed)) {
    $hashed = Hash::make('plain-text');
}

What exactly causes Hash::needsRehash() to return true or false, does it return true if the hashed password is in another hash (such as MD5, SHA1 etc)?

In the case that your database is full of hashes in another algorithm and Hash::needsRehash() returns true, how would you rehash the users password so that it's they're up to date? You can't rely on the "login" password because it needs to be compared first to validate, right?

I guess maybe I'm overthinking things but I'm confused right now. Luckily my users passwords are using password_hash() anyway so shouldn't be a problem.

Answer 1

Hash::needsReHash() just calls php's built-in password_needs_rehash function. A helpful comment in the docs is:

// Check if a newer hashing algorithm is available
// or the cost has changed
if (password_needs_rehash($hash, PASSWORD_DEFAULT, $options)) {

So Hash::needsReHash() will return false if and only if hashing algorithm has changed (since you're not passing any options such as cost).

As for how and when to use this, you can only rehash a user's password when you have it -- e.g. when they're logging in. So during the login process, you check if their stored password's algorithm differs from your current algorithm, and if so, you replace their stored password hash with a new one.

Answer 2

This seems to be how to do it in Laravel 5.6

Put this in your LoginController:

protected function authenticated(Request $request, $user) {
    if (Hash::needsRehash($user->password)) {
        $user->password = Hash::make($request->password);
        $user->save();
    }
}

https://laravel.com/docs/5.6/hashing#basic-usage

Answer 3

The method returns true when PHP is updated and a new/better default algorithm was added or any other parameters changed. This lets you automatically take advantage of it without updating your code.

This method is used when a user is logging in as that is the only time you have access to the plain-text password. After confirming it is correct according to the old hash, you take the plain text password, rehash it, and put it back into the database for future use.

For a hypothetical example, lets say that right now the algorithm is md5() 10k times. In PHP7, it was updated to sha512() 15k times. If the hash is in the $count|$algo|$hash format, the method can tell when a hash is outdated. Since the old algorithm was not removed, you can still validate the password with old parameters before rehashing.

Note: obviously using md5()/sha512() is a bad idea. I'm just using them as examples.