sodium_crypto_pwhash_str

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_str — Renvoie un hachage encodé en ASCII

Description

sodium_crypto_pwhash_str(#[\SensitiveParameter] string $password, int $opslimit, int $memlimit): string

Utilise un algorithme de hachage dur en CPU et en mémoire avec un sel généré aléatoirement, et des limites de mémoire et de CPU pour générer un hachage encodé en ASCII adapté au stockage de mots de passe.

Liste de paramètres

password: string; The password to generate a hash for.
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: Le montant maximum de RAM que la fonction utilisera, en octets. Il existe des constantes pour vous 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.

Valeurs de retour

Renvoie le hachage de mot de passe.

Pour produire le même hachage de mot de passe à partir du même mot de passe, les mêmes valeurs pour opslimit et memlimit doivent être utilisées. Ces valeurs sont intégrées dans le hachage généré, donc tout ce qui est nécessaire pour vérifier le hachage est inclus. Cela permet à la fonction sodium_crypto_pwhash_str_verify() de vérifier le hachage sans avoir besoin de stockage séparé pour les autres paramètres.

Exemples

Exemple #1 Exemple de sodium_crypto_pwhash_str()

<?php
$password = 'password';
echo sodium_crypto_pwhash_str(
    $password,
    SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
    SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE
);

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

$argon2id$v=19$m=65536,t=2,p=1$oWIfdaXwWwhVmovOBc2NAQ$EbsZ+JnZyyavkafS0hoc4HdaOB0ILWZESAZ7kVGa+Iw

Notes

Note:
Les hachages sont calculés en utilisant l'algorithme Argon2ID, fournissant une résistance à la fois aux attaques GPU et aux attaques par canaux latéraux. Contrairement à la fonction password_hash(), il n'y a pas de paramètre de sel (un sel est généré automatiquement), et les paramètres opslimit et memlimit ne sont pas optionnels.

Voir aussi

sodium_crypto_pwhash_str_verify() - Vérifie qu'un mot de passe correspond à un hachage
sodium_crypto_pwhash() - Dérive une clé à partir d'un mot de passe, en utilisant Argon2
password_hash() - Crée une clé de hachage pour un mot de passe
password_verify() - Vérifie qu'un mot de passe correspond à un hachage
» Libsodium Argon2 docs

Found A Problem?

Learn How To Improve This Page • Submit a Pull Request • Report a Bug

＋add a note

User Contributed Notes 1 note

down

marcus at synchromedia dot co dot uk ¶

3 years ago

If you want to ensure that the hashes you generate with sodium_crypto_pwhash_str are compatible with those generated by password_hash, you need to keep an eye on that memory setting. According to the docs, the password_hash memory_cost param is given in "kibibytes", whereas sodium_crypto_pwhash_str uses bytes. I did some experiments to see what the difference is and ran into this:

echo password_hash('password',
                   PASSWORD_ARGON2ID,
                   [
                       'memory_cost' => 15000,
                       'time_cost'   => 26,
                       'threads'     => 1,
                   ];

echo sodium_crypto_pwhash_str(
        'password', 26,
        15000000);

These result in:
$argon2id$v=19$m=15000,t=26,p=1$VG5MSkhUdEdFaGwyVG5sWA$laRHogIVAnC4ggLI8RdCDWlITTdicrdq0tK6SHGf4CI
$argon2id$v=19$m=14648,t=26,p=1$ClQ37/z9u7K6V1C2bkD4QA$51m8KhQQ9gujFSF+JyQR9d5QesayJiKsFmDU4HnGBHg

Notice that the "m=" numbers are different, and also different from what we asked for. It's down to the "kibibytes" unit. If we multiply the 15000 we used for password_hash by 1,024 instead of 1,000, we get 15,360,000, and using that number gives us the expected hash params:

echo sodium_crypto_pwhash_str(
        'password', 26,
        15360000);

$argon2id$v=19$m=15000,t=26,p=1$Qz3pWktOvT6X/LvdAk0bgQ$KosSFPfHUtWg+ppyRs3Op5/zIV6F6iy2Q7Gom8wP29c

This should be compatible with password_hash.

Incidentally the numbers I'm using for the Argon2id hash params are taken from the OWASP password guide, which recommend values different from PHP's default: https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#argon2id

＋add a note