(PHP 7 >= 7.2.0, PHP 8)
sodium_crypto_pwhash — Deriva uma chave de uma senha, usando Argon2
$length
,$password
,$salt
,$opslimit
,$memlimit
,$algo
= SODIUM_CRYPTO_PWHASH_ALG_DEFAULT
Esta função fornece acesso de baixo nível à função de derivação de chaves crypto_pwhash do libsodium. A menos que haja um motivo específico para usar esta função, deve-se usar as funções sodium_crypto_pwhash_str() ou password_hash().
Um motivo comum para usar essa função específica é derivar as sementes para chaves criptográficas a partir de uma senha e um salt, e então usar essas sementes para gerar as chaves reais necessárias para algum propósito (por exemplo, sodium_crypto_sign_detached()).
length
int; O comprimento do hash da senha a ser gerado, em bytes.
password
string; A senha para a qual será gerado um hash.
salt
Um salt para adicionar à senha antes do hash. O sal deve ser imprevisível, idealmente gerado a partir de uma boa fonte de números aleatórios, como random_bytes(), e ter um comprimento de exatamente SODIUM_CRYPTO_PWHASH_SALTBYTES
bytes.
opslimit
Representa uma quantidade máxima de cálculos a serem realizados. Aumentar esse número fará com que a função exija mais ciclos de CPU para calcular uma chave. Existem algumas constantes disponíveis para definir o limite de operações para valores apropriados, dependendo do uso pretendido, em ordem de intensidade: SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE
, SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE
e SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE
.
memlimit
A quantidade máxima de RAM que a função utilizará, em bytes. Existem constantes para ajudar você a escolher um valor apropriado, em ordem de tamanho: SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE
, SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE
e SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE
. Normalmente, elas devem ser pareadas com os valores opslimit
correspondentes.
algo
int Um número que indica o algoritmo de hash a ser usado. Por padrão, SODIUM_CRYPTO_PWHASH_ALG_DEFAULT
(o algoritmo atualmente recomendado, que pode mudar de uma versão do libsodium para outra), ou explicitamente usando SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13
, representando o algoritmo Argon2id versão 1.3.
Retorna a chave derivada. O valor de retorno é uma string binária do hash, não uma representação codificada em ASCII, e não contém informações adicionais sobre os parâmetros usados para criar o hash. Portanto, você precisará manter essas informações se for verificar a senha no futuro. Use sodium_crypto_pwhash_str() para evitar a necessidade de fazer tudo isso.
Exemplo #1 Exemplo de sodium_crypto_pwhash()
<?php
// Precisamos manter o salt se quisermos verificar essa senha
$salt = random_bytes(SODIUM_CRYPTO_PWHASH_SALTBYTES);
// Usando bin2hex para manter a saída legível
echo bin2hex(
sodium_crypto_pwhash(
16, // == 128 bits
'password',
$salt,
SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE,
SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13
)
);
?>
O exemplo acima produzirá algo semelhante a:
a18f346ba57992eb7e4ae6abf3fd30ee