<?xml version="1.0" encoding="utf-8"?>

<!-- EN-Revision: 5003a6ea92eb50ac92121782eedfc5ad3fe9d061 Maintainer: yannick Status: ready -->

<!-- Reviewed: no -->

<refentry xml:id="function.password-hash" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">

<refnamediv>

<refname>password_hash</refname>

<refpurpose>Crée une clé de hachage pour un mot de passe</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type>string</type><methodname>password_hash</methodname>

<methodparam><modifier role="attribute">#[\SensitiveParameter]</modifier><type>string</type><parameter>password</parameter></methodparam>

<methodparam><type class="union"><type>string</type><type>int</type><type>null</type></type><parameter>algo</parameter></methodparam>

<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>

</methodsynopsis>

<para>

La fonction <function>password_hash</function> crée un nouveau

hachage en utilisant un algorithme de hachage fort et irréversible.

</para>

<simpara>

Les algorithmes suivants sont actuellement supportés :

</simpara>

<para>

<itemizedlist>

<listitem>

<simpara>

<constant>PASSWORD_DEFAULT</constant> - 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).

</simpara>

</listitem>

<listitem>

<simpara>

<constant>PASSWORD_BCRYPT</constant> - Utilisation de l'algorithme bcrypt

pour créer la clé de hachage. Ceci va créer une clé de hachage standard <function>crypt</function>

utilisant l'identifiant <literal>$2y$</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

<constant>PASSWORD_ARGON2I</constant> - 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

</simpara>

</listitem>

<listitem>

<simpara>

<constant>PASSWORD_ARGON2ID</constant> - 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

</simpara>

</listitem>

</itemizedlist>

</para>

<simpara>

Options supportées pour <constant>PASSWORD_BCRYPT</constant>:

</simpara>

<para>

<itemizedlist>

<listitem>

<para>

<literal>salt</literal> - 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.

</para>

<para>

Si omis, un salt aléatoire sera généré par la fonction <function>password_hash</function>

pour chaque mot de passe haché. C'est le mode de fonctionnement prévu.

</para>

<warning>

<para>

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é.

</para>

</warning>

</listitem>

<listitem>

<para>

<literal>cost</literal> - 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 <function>crypt</function>.

</para>

<para>

Si omis, la valeur par défaut <literal>12</literal> sera utilisée. C'est un bon compromis,

mais cela doit être ajusté en fonction du matériel utilisé.

</para>

</listitem>

</itemizedlist>

</para>

<simpara>

Options supportées pour <constant>PASSWORD_ARGON2I</constant> et <constant>PASSWORD_ARGON2ID</constant> :

</simpara>

<para>

<itemizedlist>

<listitem>

<para>

<literal>memory_cost</literal> (<type>int</type>) - Mémoire maximale

(en kibioctets) pouvant être utilisée pour calculer le hachage Argon2. Par

défaut à <constant>PASSWORD_ARGON2_DEFAULT_MEMORY_COST</constant>.

</para>

</listitem>

<listitem>

<para>

<literal>time_cost</literal> (<type>int</type>) - Durée maximale de

temps qu'il peut prendre pour calculer le hachage Argon2. Par

défaut à <constant>PASSWORD_ARGON2_DEFAULT_TIME_COST</constant>.

</para>

</listitem>

<listitem>

<para>

<literal>threads</literal> (<type>int</type>) - Nombre de threads à

utiliser pour calculer le hachage Argon2. Par défaut à <constant>PASSWORD_ARGON2_DEFAULT_THREADS</constant>.

</para>

<warning>

<para>

Uniquement disponible quand PHP utilise libargon2,

et non l'implémentation libsodium.

</para>

</warning>

</listitem>

</itemizedlist>

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<variablelist>

<varlistentry>

<term><parameter>password</parameter></term>

<listitem>

<para>

&password.parameter.password;

</para>

<caution>

<para>

L'utilisation de la constante <constant>PASSWORD_BCRYPT</constant>

pour l'algorithme fera que le paramètre

<parameter>password</parameter> sera tronqué à une longueur maximale de

72 octets.

</para>

</caution>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>algo</parameter></term>

<listitem>

<para>

&password.parameter.algo;

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>options</parameter></term>

<listitem>

<para>

&password.parameter.options;

</para>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Retourne le mot de passe haché.

</para>

<para>

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 <function>password_verify</function> de vérifier le

hachage sans avoir besoin de stocker séparément ces informations.

</para>

</refsect1>

<refsect1 role="changelog">

&reftitle.changelog;

<para>

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

<row>

<entry>8.4.0</entry>

<entry>

La valeur par défaut de l'option <literal>cost</literal> de

l'algorithme <constant>PASSWORD_BCRYPT</constant> a été augmentée de

<literal>10</literal> à <literal>12</literal>.

</entry>

</row>

<row>

<entry>8.3.0</entry>

<entry>

<function>password_hash</function> associe désormais l'exception

<exceptionname>Random\RandomException</exceptionname> sous-jacente à

<property>Exception::$previous</property> lorsqu'une

<exceptionname>ValueError</exceptionname> est levée en raison d'un échec

de la génération du sel.

</entry>

</row>

<row>

<entry>8.0.0</entry>

<entry>

<function>password_hash</function> ne retourne plus &false; en cas d'échec, une

<classname>ValueError</classname> sera levée si l'algorithme de hachage

de mot de passe n'est pas valide, ou une <classname>Error</classname> si le hachage

de mot de passe a échoué pour une raison inconnue.

</entry>

</row>

<row>

<entry>8.0.0</entry>

<entry>

<parameter>algo</parameter> est désormais nullable.

</entry>

</row>

<row>

<entry>7.4.0</entry>

<entry>

Le paramètre <parameter>algo</parameter> attend désormais une &string;, mais

continue d'accepter un &integer; afin de conserver une compatibilité antérieure.

</entry>

</row>

<row>

<entry>7.4.0</entry>

<entry>

L'extension sodium fournit une implémentation alternative pour les

mots de passe Argon2.

</entry>

</row>

<row>

<entry>7.3.0</entry>

<entry>

Ajout de la prise en charge des mots de passe Argon2id à l'aide de <constant>PASSWORD_ARGON2ID</constant>.

</entry>

</row>

<row>

<entry>7.2.0</entry>

<entry>

Ajout de la prise en charge des mots de passe Argon2i à l'aide de <constant>PASSWORD_ARGON2I</constant>.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>Exemple avec <function>password_hash</function></title>

<programlisting role="php">

<![CDATA[

<?php

echo password_hash("rasmuslerdorf", PASSWORD_DEFAULT);

?>

]]>

</programlisting>

&example.outputs.similar;

<screen>

<![CDATA[

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

]]>

</screen>

</example>

</para>

<para>

<example>

<title>Exemple avec <function>password_hash</function> en définissant manuellement l'option cost</title>

<programlisting role="php">

<![CDATA[

<?php

$options = [

// Augmente le coût de bcrypt de 12 à 13.

'cost' => 13,

];

echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options);

?>

]]>

</programlisting>

&example.outputs.similar;

<screen>

<![CDATA[

$2y$13$xeDfQumlmdm0Sco.4qmH1OGfUUmOcuRmfae0dPJhjX1Bq0yYhqbNi

]]>

</screen>

</example>

</para>

<para>

<example>

<title>Exemple avec <function>password_hash</function> pour trouver un bon coût</title>

<simpara>

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.

</simpara>

<programlisting role="php">

<![CDATA[

<?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;

?>

]]>

</programlisting>

&example.outputs.similar;

<screen>

<![CDATA[

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

]]>

</screen>

</example>

</para>

<para>

<example>

<title>Exemple avec <function>password_hash</function> et Argon2i</title>

<programlisting role="php">

<![CDATA[

<?php

echo 'Argon2i hash: ' . password_hash('rasmuslerdorf', PASSWORD_ARGON2I);

?>

]]>

</programlisting>

&example.outputs.similar;

<screen>

<![CDATA[

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

]]>

</screen>

</example>

</para>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

<caution>

<para>

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é.

</para>

<para>

Comme mentionné ci-dessus, l'utilisation de l'option <literal>salt</literal> à 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.

</para>

</caution>

<note>

<para>

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.

</para>

</note>

<note>

<simpara>

La mise à jour des algorithmes supportés par cette fonction (ou le changement à celui par

défaut) doit suivre les règles suivantes :

</simpara>

<para>

<itemizedlist>

<listitem>

<simpara>

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.

</simpara>

</listitem>

<listitem>

<simpara>

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.

</simpara>

</listitem>

</itemizedlist>

</para>

</note>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><function>password_verify</function></member>

<member><function>password_needs_rehash</function></member>

<member><function>crypt</function></member>

<member><function>sodium_crypto_pwhash_str</function></member>

</simplelist>

</para>

</refsect1>

</refentry>

<!-- Keep this comment at the end of the file

Local variables:

mode: sgml

sgml-omittag:t

sgml-shorttag:t

sgml-minimize-attributes:nil

sgml-always-quote-attributes:t

sgml-indent-step:1

sgml-indent-data:t

indent-tabs-mode:nil

sgml-parent-document:nil

sgml-default-dtd-file:"~/.phpdoc/manual.ced"

sgml-exposed-tags:nil

sgml-local-catalogs:nil

sgml-local-ecat-files:nil

End:

vim600: syn=xml fen fdm=syntax fdl=2 si

vim: et tw=78 syn=sgml

vi: ts=1 sw=1

-->