password_hash

(PHP 5 >= 5.5.0, PHP 7)

password_hashCria um password hash

Descrição

password_hash ( string $password , int $algo [, array $options ] ) : string

password_hash() cria um novo password hash usando um algoritmo forte de hash de via única. password_hash() é compatível com crypt(). Por isso, os password hashes criados com crypt() podem ser utilizados com password_hash().

Os seguintes algoritmos são suportados atualmente:

  • PASSWORD_DEFAULT - Usa o algoritmo bcrypt (padrão desde o PHP 5.5.0). Perceba que essa constante foi desenhada para mudar ao longo do tempo a medida que novos algoritmos mais fortes forem adicionados ao PHP. Por essa razão, o comprimento do resultado da utilização desse identificador pode mudar ao longo do tempo. Por isso, é recomendado que armazene o resultado em uma coluna do banco de dados que possa ser expandida além dos 60 caracteres (255 caracteres seria uma boa escolha).
  • PASSWORD_BCRYPT - Usa o algoritmo CRYPT_BLOWFISH para criar o hash. Produzirá um hash compatível com o padrão crypt() usando o identificador "$2y$". O resultado será sempre uma string de 60 caracteres, ou FALSE em caso de falha.
  • PASSWORD_ARGON2I - Usa o algoritmo Argon2 para criar o hash.

Opções suportadas por PASSWORD_BCRYPT:

  • salt (string) - para fornecer manualmente um salt a ser usado quando estiver sendo feito o hash do password. Perceba que isso irá sobrepor e evitar que um salt seja gerado automaticamente.

    Se omitido, um salt aleatório será gerado pela função password_hash() para cada password sofrendo hash. Esse é o modo de operação desejado.

    Aviso

    A opção salt foi descontinuada no PHP 7.0.0. Agora é preferível que simplestemente se utilize o salt que é gerado por padrão.

  • cost - indica o custo de algoritmo que deve ser usado. Exemplos desses valores podem ser encontrados na página da função crypt().

    Se omitido, um valor padrão 10 será usado. Este é um bom patamar de custo, mas pode-se considerar aumentar esse valor dependendo do hardware.

Opções suportadas por PASSWORD_ARGON2I:

  • memory_cost (integer) - Máximo de mémoria (em bytes) que pode ser utilizado para computar o hash Argon2. O valor padrão é PASSWORD_ARGON2_DEFAULT_MEMORY_COST.

  • time_cost (integer) - Quantidade máxima de tempo que pode levar para computar o hash Argon2. O valor padrão é PASSWORD_ARGON2_DEFAULT_TIME_COST.

  • threads (integer) - Número de threads para computar o hash Argon2. O valor padrão é PASSWORD_ARGON2_DEFAULT_THREADS.

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 caracteres.

algo

Uma constante de algoritmo de senha indicando qual algoritmo utilizar no hash de senha.

options

Um array associativo contendo opções. Veja as constantes de algoritmo de senha sobre detalhes das opções suportadas por cada algoritmo.

Se omitido, um salt aleatório será gerado e o custo padrão será usado.

Valor Retornado

Retorna o hash do password, ou FALSE em caso de falha.

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.

Exemplos

Exemplo #1 Exemplo de password_hash()

<?php
/**
 * We just want to hash our password using the current DEFAULT algorithm.
 * This is presently BCRYPT, and will produce a 60 character result.
 *
 * Beware that DEFAULT may change over time, so you would want to prepare
 * By allowing your storage to expand past 60 characters (255 would be good)
 */
echo password_hash("rasmuslerdorf"PASSWORD_DEFAULT);
?>

O exemplo acima irá imprimir algo similar à:

$2y$10$.vGA1O9wmRjrwAVXD98HNOgsNpDczlqm3Jq7KnEd1rVAGv3Fykk1a

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

<?php
/**
 * In this case, we want to increase the default cost for BCRYPT to 12.
 * Note that we also switched to BCRYPT, which will always be 60 characters.
 */
$options = [
    
'cost' => 12,
];
echo 
password_hash("rasmuslerdorf"PASSWORD_BCRYPT$options);
?>

O exemplo acima irá imprimir algo similar à:

$2y$12$QjSH496pcT5CEbzjD/vtVeH03tfHKFy36d4J0Ltp3lRtee9HDxY3K

Exemplo #3 Exemplo de configuração do salt de password_hash() manualmente

<?php
/**
 * Note that the salt here is randomly generated.
 * Never use a static salt or one that is not randomly generated.
 *
 * For the VAST majority of use-cases, let password_hash generate the salt randomly for you
 */
$options = [
    
'cost' => 11,
    
'salt' => mcrypt_create_iv(22MCRYPT_DEV_URANDOM),
];
echo 
password_hash("rasmuslerdorf"PASSWORD_BCRYPT$options);
?>

O exemplo acima irá imprimir algo similar à:

$2y$11$q5MkhSBtlsJcNEVsYh64a.aCluzHnGog7TQAKVmQwO9C8xb.t89F.

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

<?php
/**
 * This code will benchmark your server to determine how high of a cost you can
 * afford. You want to set the highest cost that you can without slowing down
 * you server too much. 8-10 is a good baseline, and more is good if your servers
 * are fast enough. The code below aims for ≤ 50 milliseconds stretching time,
 * which is a good baseline for systems handling interactive logins.
 */
$timeTarget 0.05// 50 milliseconds 

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

echo 
"Appropriate Cost Found: " $cost;
?>

O exemplo acima irá imprimir algo similar à:

Appropriate Cost Found: 10

Exemplo #5 Exemplo do password_hash() usando Argon2

<?php
echo 'Argon2 hash: ' password_hash('rasmuslerdorf'PASSWORD_ARGON2I);
?>

O exemplo acima irá imprimir algo similar à:

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

Notas

Cuidado

É fortemente recomendado que não seja gerado um salt próprio 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 gerará um erro deprecation warning. O suporte para fornecer um salt manualmente será removido em uma futura versão do PHP.

Nota:

É recomendado que você teste esta função sem seus servidores, e ajuste o parâmetro custo para que a execução da função leve menos do que 100 milisegundos em sistemas interativos. O script do exemplo acima ajudará a escolher um bom valor de custo para seu hardware.

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.

Changelog

Versão Descrição
7.2.0 Suporte para passwords Argon2 usando PASSWORD_ARGON2I foi adicionado.

Veja Também