Description

password_hash(#[\SensitiveParameter] string $password, string|int|null $algo, array $options = []): string

La fonction password_hash() crée un nouveau hachage en utilisant un algorithme de hachage fort et irréversible.

Les algorithmes suivants sont actuellement supportés :

PASSWORD_DEFAULT - Utilisation de l'algorithme bcrypt (par défaut depuis PHP 5.5.0). Il est à noter que cette constante est conçue pour changer dans le temps, au fur et à mesure que des algorithmes plus récents et plus forts sont ajoutés à PHP. Pour cette raison, la longueur du résultat issu de cet algorithme peut changer dans le temps, il est donc recommandé de stocker le résultat dans une colonne de la base de données qui peut contenir au moins 60 caractères (255 octets peut être un très bon choix).
PASSWORD_BCRYPT - Utilisation de l'algorithme bcrypt pour créer la clé de hachage. Ceci va créer une clé de hachage standard crypt() utilisant l'identifiant $2y$ .
PASSWORD_ARGON2I - Utilise l'algorithme de hachage Argon2i pour créer le hachage. Cet algorithme est seulement disponible si PHP a été compilé avec le support d'Argon2
PASSWORD_ARGON2ID - Utilise l'algorithme de hachage Argon2id pour créer le hachage. Cet algorithme est seulement disponible si PHP a été compilé avec le support d'Argon2

Options supportées pour PASSWORD_BCRYPT:

salt - pour fournir manuellement un salt à utiliser lors du hachage du mot de passe. Il est à noter que cette option empêchera la génération automatique.

Si omis, un salt aléatoire sera généré par la fonction password_hash() pour chaque mot de passe haché. C'est le mode de fonctionnement prévu.

Avertissement
L'option Salt est obsolète. Il est préférable d'utiliser simplement le sel qui est généré par défaut. À partir de PHP 8.0.0, un sel explicitement fourni est ignoré.
cost - détermine le coût algorithmique qui doit être utilisé. Des exemples de ces valeurs peuvent être trouvés sur la page de la documentation de la fonction crypt().

Si omis, la valeur par défaut 12 sera utilisée. C'est un bon compromis, mais cela doit être ajusté en fonction du matériel utilisé.

Options supportées pour PASSWORD_ARGON2I et PASSWORD_ARGON2ID :

memory_cost (int) - Mémoire maximale (en kibioctets) pouvant être utilisée pour calculer le hachage Argon2. Par défaut à PASSWORD_ARGON2_DEFAULT_MEMORY_COST.
time_cost (int) - Durée maximale de temps qu'il peut prendre pour calculer le hachage Argon2. Par défaut à PASSWORD_ARGON2_DEFAULT_TIME_COST.
threads (int) - Nombre de threads à utiliser pour calculer le hachage Argon2. Par défaut à PASSWORD_ARGON2_DEFAULT_THREADS.

Avertissement
Uniquement disponible quand PHP utilise libargon2, et non l'implémentation libsodium.

Liste de paramètres

password: Le mot de passe utilisateur.

Attention
L'utilisation de la constante PASSWORD_BCRYPT pour l'algorithme fera que le paramètre password sera tronqué à une longueur maximale de 72 octets.
algo: Une constantes de l'algorithme de mot de passe représentant l'algorithme à utiliser lors du hachage du mot de passe.
options: Un tableau associatif contenant les options. Voir aussi les constantes de l'algorithme de mot de passe pour une documentation sur les options supportées pour chaque algorithme.

Valeurs de retour

Retourne le mot de passe haché.

L'algorithme utilisé, le coût et le salt sont contenus dans le hachage retourné. Aussi, toutes les informations utiles pour vérifier ce dernier y sont incluses. Ceci permet à la fonction password_verify() de vérifier le hachage sans avoir besoin de stocker séparément ces informations.

Historique

Version Description

8.4.0 La valeur par défaut de l'option cost de l'algorithme PASSWORD_BCRYPT a été augmentée de 10 à 12.

8.3.0 password_hash() associe désormais l'exception Random\RandomException sous-jacente à Exception::$previous lorsqu'une ValueError est levée en raison d'un échec de la génération du sel.

8.0.0 password_hash() ne retourne plus false en cas d'échec, une ValueError sera levée si l'algorithme de hachage de mot de passe n'est pas valide, ou une Error si le hachage de mot de passe a échoué pour une raison inconnue.

8.0.0 algo est désormais nullable.

7.4.0 Le paramètre algo attend désormais une chaîne de caractères, mais continue d'accepter un entier afin de conserver une compatibilité antérieure.

7.4.0 L'extension sodium fournit une implémentation alternative pour les mots de passe Argon2.

7.3.0 Ajout de la prise en charge des mots de passe Argon2id à l'aide de PASSWORD_ARGON2ID.

7.2.0 Ajout de la prise en charge des mots de passe Argon2i à l'aide de PASSWORD_ARGON2I.

Version	Description
8.4.0	La valeur par défaut de l'option `cost` de l'algorithme `PASSWORD_BCRYPT` a été augmentée de `10` à `12`.
8.3.0	password_hash() associe désormais l'exception Random\RandomException sous-jacente à Exception::$previous lorsqu'une ValueError est levée en raison d'un échec de la génération du sel.
8.0.0	password_hash() ne retourne plus `false` en cas d'échec, une ValueError sera levée si l'algorithme de hachage de mot de passe n'est pas valide, ou une Error si le hachage de mot de passe a échoué pour une raison inconnue.
8.0.0	`algo` est désormais nullable.
7.4.0	Le paramètre `algo` attend désormais une chaîne de caractères, mais continue d'accepter un entier afin de conserver une compatibilité antérieure.
7.4.0	L'extension sodium fournit une implémentation alternative pour les mots de passe Argon2.
7.3.0	Ajout de la prise en charge des mots de passe Argon2id à l'aide de `PASSWORD_ARGON2ID`.
7.2.0	Ajout de la prise en charge des mots de passe Argon2i à l'aide de `PASSWORD_ARGON2I`.

Exemples

Exemple #1 Exemple avec password_hash()

<?php
echo password_hash("rasmuslerdorf", PASSWORD_DEFAULT);
?>

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

$2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.

Exemple #2 Exemple avec password_hash() en définissant manuellement l'option cost

<?php
$options = [
     // Augmente le coût de bcrypt de 12 à 13.
    'cost' => 13,
];
echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options);
?>

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

$2y$13$xeDfQumlmdm0Sco.4qmH1OGfUUmOcuRmfae0dPJhjX1Bq0yYhqbNi

Exemple #3 Exemple avec password_hash() pour trouver un bon coût

Ce code effectuera un benchmark de la machine afin de déterminer le coût maximal pouvant être utilisé sans dégrader l'expérience utilisateur. Il est recommandé de choisir le coût le plus élevé possible sans ralentir les autres opérations que la machine doit exécuter. 11 constitue une bonne base, et une valeur plus élevée est préférable si la machine est suffisamment rapide. Le code ci-dessous vise un temps d'étirement ≤ 350 millisecondes, ce qui représente un délai adapté aux systèmes gérant des connexions interactives.

<?php
$timeTarget = 0.350; // 350 millisecondes

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

echo "Valeur de 'cost' la plus appropriée : " . $cost - 1;
?>

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

Valeur de 'cost' la plus appropriée : 13

Exemple #4 Exemple avec password_hash() et Argon2i

<?php
echo 'Argon2i hash: ' . password_hash('rasmuslerdorf', PASSWORD_ARGON2I);
?>

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

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

Notes

Attention

Il est fortement recommandé de ne pas fournir de sel explicite pour cette fonction. Un sel sécurisé sera automatiquement généré si aucun sel n'est spécifié.

Comme mentionné ci-dessus, l'utilisation de l'option salt à partir de PHP 7.0.0 générera un avertissement de dépréciation. La prise en charge d'un sel explicite a été supprimée à partir de PHP 8.0.0.

Note:
Il est recommandé de tester cette fonction sur la machine utilisée et d'ajuster le(s) paramètre(s) de coût afin que l'exécution de la fonction prenne moins de 350 millisecondes pour les connexions interactives. Le script de l'exemple ci-dessus aidera à choisir un coût bcrypt adapté à la machine donnée.

Note: La mise à jour des algorithmes supportés par cette fonction (ou le changement à celui par défaut) doit suivre les règles suivantes :

Chaque nouvel algorithme doit faire partie du cœur de PHP pendant au moins 1 version complète avant de prétendre à devenir l'algorithme par défaut. Aussi, si, par exemple, un nouvel algorithme est ajouté en version 7.5.5, il ne sera éligible comme algorithme par défaut qu'à partir de PHP 7.7 (sachant que 7.6 sera la première version complète). Mais si un algorithme différent a été ajouté en 7.6.0, il sera aussi éligible comme algorithme par défaut à partir de la version 7.7.0.

L'algorithme par défaut ne peut être changé que lors d'une version complète (7.3.0, 8.0.0, etc.) et non pendant une version de révision. La seule exception à ce principe de base serait une urgence, par exemple, lors de la découverte d'un bogue critique au niveau de la sécurité dans l'algorithme par défaut.

Voir aussi

password_verify() - Vérifie qu'un mot de passe correspond à un hachage
password_needs_rehash() - Vérifie que le hachage fourni est conforme à l'algorithme et aux options spécifiées
crypt() - Hachage à sens unique (indéchiffrable)
sodium_crypto_pwhash_str() - Renvoie un hachage encodé en ASCII