sodium_crypto_pwhash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash — Dérive une clé à partir d'un mot de passe, en utilisant Argon2

Description

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

Cette fonction fournit un accès de bas niveau à la fonction de dérivation de clé crypto_pwhash de libsodium. À moins d'avoir une raison spécifique d'utiliser cette fonction, il est recommandé d'utiliser les fonctions sodium_crypto_pwhash_str() ou password_hash() à la place.

Une raison courante d'utiliser cette fonction est de dériver les graines pour les clés cryptographiques à partir d'un mot de passe et d'un sel, puis d'utiliser ces graines pour générer les clés réelles nécessaires à un certain usage (par exemple sodium_crypto_sign_detached()).

Liste de paramètres

length: int; La longueur du hachage de mot de passe à générer, en octets.
password: string; Le mot de passe pour lequel générer un hachage.
salt: Un sel à ajouter au mot de passe avant le hachage. Le sel doit être imprévisible, idéalement généré à partir d'une bonne source de nombres aléatoires telle que random_bytes(), et avoir une longueur d'au moins SODIUM_CRYPTO_PWHASH_SALTBYTES octets.
opslimit: Représente une quantité maximale de calculs à effectuer. Augmenter ce nombre fera que la fonction nécessitera plus de cycles CPU pour calculer une clé. Il existe des constantes disponibles pour définir la limite d'opérations à des valeurs appropriées en fonction de l'utilisation prévue, dans l'ordre de la force : SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE et SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE.
memlimit: La quantité maximale de RAM que la fonction utilisera, en octets. Il existe des constantes pour aider à choisir une valeur appropriée, dans l'ordre de la taille : SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE et SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE. Typiquement, ces valeurs devraient être associées aux valeurs opslimit correspondantes.
algo: int Un nombre indiquant l'algorithme de hachage à utiliser. Par défaut SODIUM_CRYPTO_PWHASH_ALG_DEFAULT (l'algorithme actuellement recommandé, qui peut changer d'une version de libsodium à une autre), ou explicitement en utilisant SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13, représentant l'algorithme Argon2id version 1.3.

Valeurs de retour

Renvoie la clé dérivée. La valeur de retour est une chaîne binaire du hachage, pas une représentation encodée en ASCII, et ne contient pas d'informations supplémentaires sur les paramètres utilisés pour créer le hachage, donc il faudra conserver ces informations si l'on doit jamais vérifier le mot de passe à l'avenir. Utiliser sodium_crypto_pwhash_str() pour éviter d'avoir besoin de faire tout cela.

Exemples

Exemple #1 Exemple de sodium_crypto_pwhash()

<?php
//Requis pour conserver le sel si nous devons jamais vérifier ce mot de passe
$salt = random_bytes(SODIUM_CRYPTO_PWHASH_SALTBYTES);
//Utiliser bin2hex pour garder la sortie lisible
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
    )
);
?>

Résultat de l'exemple ci-dessus est similaire à :

a18f346ba57992eb7e4ae6abf3fd30ee