`$hash.encodePassword`¶

Description¶

Génère le hash d'un mot de passe selon la méthode Argon2.

En option, la méthode supporte le format PCH en sortie. Ce format est une chaîne de caractères qui combine le hash, le sel et les paramètres d'encodage. Toutes ces valeurs ne sont pas secrètes et peuvent être enregistrées dans un champ en clair. La valeur PCH peut ensuite être réutilisée sur la méthode hash.verifyPassword pour contrôler un mot de passe.

Syntaxe¶

$hash.encodePassword( password [ , options ] )

Paramètres¶

password any

Mot de passe à encoder

options map

Options d'encodage du mot de passe. Les options reconnues sont indiquées ci-dessous. Les valeurs par défaut indiquées suivent les recommandations minimales de l'OWASP.

type string / number

Type d'encodage. Les valeurs possibles pour cette propriétés sont "Argon2_d" (0), "Argon2_i" (1) et "Argon2_id" (2). La valeur indiquée entre parenthèses est la valeur entière correspondante (la propriété peut être passée sous forme de String ou de Number). Veuillez consulter la documentation de Argon2 ou la page Wikipedia associée pour connaître les particularités de chaque type.

La valeur par défaut est: "Argon2_id"

version string / number

Version de l'algorithme. Les valeurs possibles sont "1.0" (16) et "1.3" (19). La valeur indiquée entre parenthèses est une version hexadécimale de la valeur, utilisée en interne dans le moteur.

La valeur par défaut est: "1.3"

salt string / number

Sel à utiliser pour l'encodage. Le sel est fortement recommandé pour éviter qu'un même mot de passe appartenant à deux personnes différentes ne génèrent le même hash en sortie. Le même sel devra être fourni lors de la vérification du mot de passe (méthode hash.verifyPassword. L'OWASP recommande un sel d'au moins de 16 bytes.

La valeur peut être un nombre entier. Dans ce cas, la méthode se charge de générer un sel aléatoirement. Ce dernier sera livré dans la réponse de la méthode.

hashLength number

Longueur du hash à générer, en bytes

La valeur par défaut est: 32

parallelism number

Nombre de cores à utiliser pour le traitement. Utiliser une valeur supérieure à 1 uniquement si le serveur d'application a la capacité d'utiliser plusieurs cores.

La valeur par défaut est: 1

memory number

Quantité de mémoire imposée pour le traitement en KB

La valeur par défaut est: 16384 (ce qui correspond à la recommandation minimale de 15 MB prescrite par l'OWASP)

iterations number

Nombre d'itérations

La valeur par défaut est: 2

charset string

Charset à utiliser

La valeur par défaut est: "UTF-8"

format string

Format de sortie (BASE64, HEX). La valeur base64 est générée sans padding.

La valeur par défaut est: BASE64

pch boolean

Flag demandant à la méthode de retourner une chaîne de caractères au format PCH. Cette dernière inclut donc le hash, le salt et tous les paramètres nécessaires à la vérification du mot de passe.

Le fait d'activer l'option pch force la valeur de charset à UTF-8 et format à BASE64.

Retour¶

Si la propriété pch est false ou non définie, la méthode retourne un map contenant le hash généré ainsi que les paramètres utilisés pour la génération. Ces derniers seront utiles lorsque l'on devra vérifier un mot de passe avec $hash.verifyPassword.

Les valeurs des propriétés type et version du map de sortie sont en valeurs entières. La propriété salt est systématiquement encodée en base64.

Si la propriété pch est activée, la méthode retourne une valeur contenant sensiblement les mêmes éléments que le map, mais exprimé sous forme de string.

Exemple¶

MapPCH

Exemple d'encodage avec retour sous forme de map.

const password = "Hello World 👍 !";
const salt = $uuid.generate();

var res = $hash.encodePassword(password, { salt: salt });

var ctrl = $hash.verifyPassword("ceci n'est pas le bon mot de passe", res);
$logger.info(ctrl);

ctrl = $hash.verifyPassword(password, res);
$logger.info(ctrl);

Exemple de valeur de retour res généré par la méthode $hash.encodePassword :

{
    "charset": UTF-8,
    "hashLength": 32,
    "salt": "YTQ3ZWE0ZDMtZGRjYi00Y2EyLWIzYjItZWRkODIwNmEwZDNk",
    "memory": 16384,
    "parallelism": 1,
    "format": "BASE64",
    type": 2,
    "version": 19,
    "hash": "lXPTGyLfK6uNJHe5GzsfyDhe6GLKlHVdF4Tx67fWD4o",
    "iterations": 2
}

Exemple d'encodage et décodage avec retour sous forme de PCH.

const password = "Hello World 👍 !";
const salt = $uuid.generate();

var res = $hash.encodePassword(password, { salt: salt, pch: true });

var ctrl = $hash.verifyPassword("ceci n'est pas le bon mot de passe", res);
$logger.info(ctrl);

ctrl = $hash.verifyPassword(password, res);
$logger.info(ctrl);