PHP password_hash() e password_verify(): guardar senhas

Guarde senhas com password_hash($password, PASSWORD_DEFAULT) e verifique um login com password_verify($password, $hash), que retorna true ou false. Nunca guarde a senha em si, e nunca use md5() ou sha1() para isso.

<?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));

Rode duas vezes: o hash é diferente a cada vez, e as duas versões são verificadas. O mesmo vale para todos os hashes desta página, então a sua saída não vai bater com a de mais ninguém.

Fazer login com password_verify

Um login compara a senha enviada com o hash salvo quando a conta foi criada. Este bloco "cadastra" um usuário e depois mostra um formulário de login; teste a senha certa (hunter2) e depois uma errada.

<?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>

A mensagem de erro é a mesma para um e-mail desconhecido e uma senha errada. Dizer qual dos dois está errado conta a um atacante quais e-mails têm conta. Depois de um login bem-sucedido, um site real guarda o id do usuário na sessão, como mostra a página sobre sessões.

O que há dentro do hash

Um hash bcrypt é uma string que guarda tudo de que o password_verify() precisa: o algoritmo, o custo e o salt, seguidos do hash em si. O password_get_info() lê as primeiras partes de volta.

<?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));

Como o salt fica guardado no hash, você precisa de uma única coluna no banco de dados, e dois usuários com a mesma senha ainda recebem hashes diferentes. Faça essa coluna VARCHAR(255): o bcrypt tem 60 caracteres, mas o PASSWORD_DEFAULT pode mudar para um algoritmo com saída mais longa.

Escolher o custo

O custo é o quanto cada hash é lento de propósito, e cada passo acima dobra o trabalho. O PHP 8.3 usa custo 10 para bcrypt (o PHP 8.4 aumentou o padrão para 12). Um login deve levar uns 100 a 300 ms de hashing; meça no seu próprio servidor:

<?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);
}

Os números dependem da máquina, mas cada linha deve ser umas duas vezes a anterior. Mais alto é mais seguro contra quebra e mais lento para cada login, então escolha o custo mais alto que a sua página de login aguenta.

Atualizar hashes antigos com password_needs_rehash

Quando você aumenta o custo ou o PHP muda o PASSWORD_DEFAULT, os hashes existentes continuam funcionando, e o password_needs_rehash() diz quais estão desatualizados. O único momento em que você tem a senha em texto puro é no login, então é ali que você atualiza:

<?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));

O prefixo $2y$10$ vira $2y$12$, e no próximo login o password_needs_rehash() retorna false.

Nunca use md5 ou sha1 para senhas

md5() e sha1() são hashes gerais rápidos e sem salt. Rápido é exatamente o errado para senhas: um atacante com uma tabela vazada consegue testar bilhões de palpites por segundo numa GPU, e um hash sem salt de uma senha comum já está em tabelas públicas de consulta. Compare a velocidade:

<?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);

No tempo em que o password_hash() faz um hash, o md5 faz centenas de milhares, então cada palpite de quem tenta quebrar a senha fica esse tanto de vezes mais barato. Pesquise 5f4dcc3b5aa765d61d8327deb882cf99 e você encontra a palavra "password" na hora.

Se você herdar uma tabela de hashes md5, não dá para convertê-los diretamente. Envolva-os: guarde password_hash($oldMd5) e verifique com password_verify(md5($input), $stored), depois troque cada um por um hash normal quando aquele usuário fizer login de novo.

Argon2id e o limite de 72 bytes

O PASSWORD_ARGON2ID usa mais memória por hash, o que torna a quebra por GPU muito mais cara. Ele está disponível quando o PHP é compilado com a libargon2 (a maioria dos pacotes Linux é); verifique com 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)));

A última linha imprime bool(true): duas senhas diferentes batem porque o bcrypt ignora tudo depois do byte 72. Senhas reais raramente chegam a isso, mas frases-senha em japonês ou em outras escritas multibyte chegam a 72 bytes com uns 24 caracteres. Se você permite senhas muito longas, use Argon2id, que não tem esse limite. O password_verify() funciona com os dois algoritmos, então você pode trocar com o password_needs_rehash() como acima.