array ( 0 => 'index.php', 1 => 'PHP Manual', ), 'head' => array ( 0 => 'UTF-8', 1 => 'pt_BR', ), 'this' => array ( 0 => 'function.password-hash.php', 1 => 'password_hash', 2 => 'Cria um hash de senha', ), 'up' => array ( 0 => 'ref.password.php', 1 => 'Funções da extensão Password Hashing', ), 'prev' => array ( 0 => 'function.password-get-info.php', 1 => 'password_get_info', ), 'next' => array ( 0 => 'function.password-needs-rehash.php', 1 => 'password_needs_rehash', ), 'alternatives' => array ( ), 'source' => array ( 'lang' => 'pt_BR', 'path' => 'reference/password/functions/password-hash.xml', ), 'history' => array ( ), ); $setup["toc"] = $TOC; $setup["toc_deprecated"] = $TOC_DEPRECATED; $setup["parents"] = $PARENTS; manual_setup($setup); contributors($setup); ?>

password_hash

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_hash — Cria um hash de senha

Descrição

password_hash(#[\SensitiveParameter] string $password, string|int|null $algo, array $options = []): string

password_hash() cria um novo hash de senha usando um algoritmo forte de hash de mão única.

Os seguintes algoritmos são suportados atualmente:

Opções suportadas por PASSWORD_BCRYPT:

Opções suportadas por PASSWORD_ARGON2I e PASSWORD_ARGON2ID:

Parâmetros

password

A senha do usuário.

Cuidado

Usando PASSWORD_BCRYPT como algoritmo, resultará no parâmetro password sendo truncado em um comprimento máximo de 72 bytes.

algo

Uma constante de algoritmo de senha denotando o algoritmo a ser usado ao fazer o hash da senha.

options

Um array associativo contendo opções. Consulte as constantes de algoritmo de senha para obter a documentação sobre as opções suportadas por cada algoritmo.

Valor Retornado

Retorna o hash da senha.

O algoritmo, o custo e o salt utilizados são retornados como parte do hash. Dessa forma, toda informação necessária para verificar o hash é incluída nele. Isso permite que a função password_verify() verifique o hash sem precisar de um armazenamento separado para a informação do salt ou do algoritmo.

Registro de Alterações

Versão Descrição
8.4.0 O valor padrão da opção cost do algoritmo PASSWORD_BCRYPT foi aumentado de 10 para 12.
8.3.0 password_hash() agora define a exceção Random\RandomException subjacente como a Exception::$previous quando uma exceção ValueError é lançada devido a uma falha na geração do salt.
8.0.0 password_hash() não mais retorna false em caso de falha, em vez disso uma exceção ValueError será lançada se o algoritmo de hash da senha não for válido, ou uma exceção Error se o cálculo do hash falhou por motivo desconhecido.
8.0.0 O parâmetros algo agora pode ser nulo.
7.4.0 O parâmetro algo agora espera uma string, mas ainda aceita ints para compatibilidade com versões anteriores.
7.4.0 A extensão sodium fornece uma implementação alternativa para senhas Argon2.
7.3.0 Suporte para senhas Argon2id usando PASSWORD_ARGON2ID foi adicionado.
7.2.0 Suporte para senhas Argon2i usando PASSWORD_ARGON2I foi adicionado.

Exemplos

Exemplo #1 Exemplo de password_hash()

<?php
echo password_hash("rasmuslerdorf", PASSWORD_DEFAULT);
?>

O exemplo acima produzirá algo semelhante a:

$2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.

Exemplo #2 Exemplo de configuração do custo de password_hash() manualmente

<?php
$options = [
// Aumenta o custo bcrypt de 12 para 13.
'cost' => 13,
];
echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options);
?>

O exemplo acima produzirá algo semelhante a:

$2y$13$xeDfQumlmdm0Sco.4qmH1OGfUUmOcuRmfae0dPJhjX1Bq0yYhqbNi

Exemplo #3 Exemplo de busca de um bom custo para password_hash()

Este código fará um benchmark da máquina para determinar o quão alto um custo pode ser usado sem deteriorar a experiência do usuário. É recomendado definir o custo mais alto que não desacelere outras operações que a máquina precisa executar. 11 é uma boa linha de base, e mais é melhor se a máquina for rápida o suficiente. O código abaixo visa um tempo de alongamento ≤ 350 milissegundos, que é um atraso apropriado para sistemas que lidam com logins interativos.

<?php
$timeTarget = 0.350; // 350 milissegundos

$cost = 11;
do {
$cost++;
$start = microtime(true);
password_hash("test", PASSWORD_BCRYPT, ["cost" => $cost]);
$end = microtime(true);
} while (($end - $start) < $timeTarget);

echo "Custo Apropriado Encontrado: " . $cost - 1;
?>

O exemplo acima produzirá algo semelhante a:

Custo Apropriado Encontrado: 13

Exemplo #4 Exemplo de password_hash() usando Argon2i

<?php
echo 'Argon2i hash: ' . password_hash('rasmuslerdorf', PASSWORD_ARGON2I);
?>

O exemplo acima produzirá algo semelhante a:

Argon2i hash: $argon2i$v=19$m=1024,t=2,p=2$YzJBSzV4TUhkMzc3d3laeg$zqU/1IN0/AogfP4cmSJI1vc8lpXRW9/S0sYY2i2jHT0

Notas

Cuidado

É fortemente recomendado não fornecer um salt explícito para esta função. Ela criará um salt seguro automaticamente se um não for especificado.

Como apontado acima, fornecer a opção salt no PHP 7.0.0 gerará um alerta de descontinuação. O suporte para fornecer um salt explicitamente foi removido no PHP 8.0.

Nota:

É recomendado testar esta função na máquina usada, ajustando o parâmetro custo para que a execução da função leve menos do que 350 milissegundos em sistemas interativos. O script do exemplo acima ajudará a escolher um custo bcrypt apropriado para uma determinada máquina.

Nota: Atualizações dos algoritmos suportados por esta função (ou alterações no algoritmo padrão) precisam seguir as seguintes regras:

  • Qualquer novo algoritmo precisa estar no core por pelo menos 1 versão completa do PHP antes de se tornar padrão. Assim se, por exemplo, um novo algoritmo for adicionado na versão 7.5.5, ela não seria elegível para padrão até a versão 7.7 (uma vez que a 7.6 seria a primeira versão completa). Mas se um algoritmo diferente for adicionado na versão 7.6.0, ela seria elegível para padrão na 7.7.0.
  • O padrão deve mudar apenas em uma versão completa (7.3.0, 8.0.8 etc.) e não em uma versão de revisão. A única exceção seria uma emergênca caso uma falha de segurança crítica fosse encontrada no padrão atual.

Veja Também