sodium_crypto_pwhash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash — Deriva uma chave de uma senha, usando Argon2

Descrição

sodium_crypto_pwhash(
    int $length,
    #[\SensitiveParameter] string $password,
    string $salt,
    int $opslimit,
    int $memlimit,
    int $algo = SODIUM_CRYPTO_PWHASH_ALG_DEFAULT
): string

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()).

Parâmetros

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.

Valor Retornado

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.

Exemplos

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