PHP password_hash() and password_verify(): Store Passwords

Store passwords with password_hash($password, PASSWORD_DEFAULT) and check a login with password_verify($password, $hash), which returns true or false. Never store the password itself, and never use md5() or sha1() for it.

<?php
$hash = password_hash('correct horse battery staple', PASSWORD_DEFAULT);
echo $hash, "\n";

var_dump(password_verify('correct horse battery staple', $hash));
var_dump(password_verify('Correct horse battery staple', $hash));

Run it twice: the hash is different every time, and both versions verify. The same goes for every hash on this page, so your output will not match anyone else's.

Log in with password_verify

A login checks the submitted password against the hash saved when the account was created. This block "registers" one user and then shows a login form; try the right password (hunter2), then a wrong one.

<?php
// The users table: one row, hashed when the account was created
$users = ['ada@example.com' => password_hash('hunter2', PASSWORD_DEFAULT)];

$email = trim((string) ($_POST['email'] ?? 'ada@example.com'));
$message = '';

if (($_SERVER['REQUEST_METHOD'] ?? 'GET') === 'POST') {
    $hash = $users[$email] ?? null;
    if ($hash !== null && password_verify((string) ($_POST['password'] ?? ''), $hash)) {
        $message = 'Welcome back, ' . htmlspecialchars($email) . '.';
    } else {
        $message = 'Wrong email or password.';
    }
}
?>
<form method="post">
  <input name="email" value="<?= htmlspecialchars($email) ?>">
  <input name="password" type="password" placeholder="Password">
  <button>Log in</button>
</form>
<p><?= $message ?></p>

The error message is the same for an unknown email and a wrong password. Saying which one was wrong tells an attacker which emails have accounts. After a successful login, a real site stores the user id in the session, as shown on the sessions page.

What is inside the hash

A bcrypt hash is one string that holds everything password_verify() needs: the algorithm, the cost and the salt, followed by the hash itself. password_get_info() reads the first parts back.

<?php
$hash = password_hash('secret', PASSWORD_DEFAULT);
echo $hash, "\n";
echo strlen($hash), " characters\n\n";

[, $algo, $cost, $rest] = explode('$', $hash);
echo "algorithm: $algo (bcrypt)\n";
echo "cost:      $cost\n";
echo 'salt:      ', substr($rest, 0, 22), "\n";
echo 'hash:      ', substr($rest, 22), "\n\n";

print_r(password_get_info($hash));

Because the salt is stored in the hash, you need only one database column, and two users with the same password still get different hashes. Make that column VARCHAR(255): bcrypt is 60 characters, but PASSWORD_DEFAULT is allowed to change to an algorithm with longer output.

Choose the cost

The cost is how slow each hash is on purpose, and each step up doubles the work. PHP 8.3 uses cost 10 for bcrypt (PHP 8.4 raised the default to 12). A login should take roughly 100 to 300 ms of hashing; time it on your own server:

<?php
foreach ([10, 11, 12] as $cost) {
    $start = hrtime(true);
    password_hash('secret', PASSWORD_BCRYPT, ['cost' => $cost]);
    printf("cost %d: %.0f ms\n", $cost, (hrtime(true) - $start) / 1e6);
}

The numbers depend on the machine, but each line should be about twice the one before it. Higher is safer against cracking and slower for every login, so pick the highest cost your login page can afford.

Upgrade old hashes with password_needs_rehash

When you raise the cost or PHP changes PASSWORD_DEFAULT, existing hashes keep working, and password_needs_rehash() tells you which ones are out of date. The only moment you have the plain password is at login, so that is where you upgrade:

<?php
$options = ['cost' => 12];

// A hash created years ago with cost 10
$stored = password_hash('hunter2', PASSWORD_DEFAULT, ['cost' => 10]);
echo 'stored: ', substr($stored, 0, 7), "...\n";

$input = 'hunter2';
if (password_verify($input, $stored)) {
    if (password_needs_rehash($stored, PASSWORD_DEFAULT, $options)) {
        $stored = password_hash($input, PASSWORD_DEFAULT, $options);
        echo "Rehashed and saved: ", substr($stored, 0, 7), "...\n";
    }
    echo "Logged in.\n";
}

var_dump(password_needs_rehash($stored, PASSWORD_DEFAULT, $options));

The $2y$10$ prefix becomes $2y$12$, and on the next login password_needs_rehash() returns false.

Never use md5 or sha1 for passwords

md5() and sha1() are fast general hashes with no salt. Fast is exactly wrong for passwords: an attacker with a leaked table can try billions of guesses per second on a GPU, and an unsalted hash of a common password is already in public lookup tables. Compare the speed:

<?php
echo md5('password'), "\n";       // the same on every server, forever

$start = hrtime(true);
for ($i = 0; $i < 100000; $i++) {
    md5("password$i");
}
printf("100,000 md5 hashes: %.0f ms\n", (hrtime(true) - $start) / 1e6);

$start = hrtime(true);
password_hash('password', PASSWORD_DEFAULT);
printf("1 password_hash:    %.0f ms\n", (hrtime(true) - $start) / 1e6);

In the time password_hash() makes one hash, md5 makes hundreds of thousands, so every guess a cracker makes is that many times cheaper. Search for 5f4dcc3b5aa765d61d8327deb882cf99 and you will find the word "password" immediately.

If you inherit a table of md5 hashes, you cannot convert them directly. Wrap them instead: store password_hash($oldMd5) and verify with password_verify(md5($input), $stored), then replace each one with a normal hash when that user next logs in.

Argon2id and the 72-byte limit

PASSWORD_ARGON2ID uses more memory per hash, which makes GPU cracking much more expensive. It is available when PHP is built with libargon2 (most Linux packages are); check with defined('PASSWORD_ARGON2ID').

<?php
if (defined('PASSWORD_ARGON2ID')) {
    $hash = password_hash('secret', PASSWORD_ARGON2ID);
    echo $hash, "\n";
    var_dump(password_verify('secret', $hash));
}

// bcrypt only looks at the first 72 bytes of the password
$a = str_repeat('a', 72) . 'X';
$b = str_repeat('a', 72) . 'Y';
var_dump(password_verify($b, password_hash($a, PASSWORD_BCRYPT)));

The last line prints bool(true): two different passwords match because bcrypt ignores everything after byte 72. Real passwords rarely reach that, but passphrases in Japanese or other multibyte scripts reach 72 bytes at about 24 characters. If you allow very long passwords, use Argon2id, which has no such limit. password_verify() works with either algorithm, so you can switch with password_needs_rehash() as above.