mirror of
https://github.com/macintoshplus/doc-fr.git
synced 2026-03-25 09:22:07 +01:00
439 lines
14 KiB
XML
439 lines
14 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<!-- EN-Revision: f93ab9943c0246504e18493e315b7638efe81753 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><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). Notez que cette constante est concue 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 caractères peut être un très bon choix).
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<constant>PASSWORD_BCRYPT</constant> - Utilisation de l'algorithme <constant>CRYPT_BLOWFISH</constant>
|
|
pour créer la clé de hachage. Ceci va créer une clé de hachage standard <function>crypt</function>
|
|
utilisant l'identifiant "$2y$". Le résultat sera toujours une chaîne de 60 caractères, &return.falseforfailure;.
|
|
</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. Notez 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 fournit 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>10</literal> sera utilisée. C'est un bon compromis,
|
|
mais vous pourriez vouloir l'augmenter suivant votre architecture.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<simpara>
|
|
Options supporté 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 kilo octets binaire) 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'implementation 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>
|
|
<para>
|
|
Si omis, un salt aléatoire sera créé et le cost par défaut sera
|
|
utilisé.
|
|
</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.0.0</entry>
|
|
<entry>
|
|
<function>password_hash</function> ne retourne plus &false; en cas d'échec.
|
|
</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 un implémentation alternative pour les
|
|
mots de passes 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
|
|
/**
|
|
* Nous voulons juste hacher notre mot de passe en utiliant l'algorithme par défaut.
|
|
* Actuellement, il s'agit de BCRYPT, ce qui produira un résultat sous forme de chaîne de
|
|
* caractères d'une longueur de 60 caractères.
|
|
*
|
|
* Gardez à l'esprit que DEFAULT peut changer dans le temps, aussi, vous devriez vous
|
|
* y préparer en autorisant un stockage supérieur à 60 caractères (255 peut être un bon choix)
|
|
*/
|
|
|
|
echo password_hash("rasmuslerdorf", PASSWORD_DEFAULT);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs.similar;
|
|
<screen>
|
|
<![CDATA[
|
|
$2y$10$.vGA1O9wmRjrwAVXD98HNOgsNpDczlqm3Jq7KnEd1rVAGv3Fykk1a
|
|
]]>
|
|
</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
|
|
/**
|
|
* Dans ce cas, nous souhaitons augmenter le "cost" par défaut pour BCRYPT à la valeur 12.
|
|
* Notez que nous passons également à l'algorithme BCRYPT, qui produit toujours un résultat
|
|
* de 60 caractères.
|
|
*/
|
|
|
|
$options = [
|
|
'cost' => 12,
|
|
];
|
|
echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs.similar;
|
|
<screen>
|
|
<![CDATA[
|
|
$2y$12$QjSH496pcT5CEbzjD/vtVeH03tfHKFy36d4J0Ltp3lRtee9HDxY3K
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Exemple avec <function>password_hash</function> trouver un bon coût (cost)</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
/**
|
|
* Ce code va tester votre serveur pour déterminer quel serait le meilleur "cost".
|
|
* Vous souhaitez définir le "cost" le plus élevé possible sans trop ralentir votre serveur.
|
|
* 8-10 est une bonne base, mais une valeur plus élevée est aussi un bon choix à partir
|
|
* du moment où votre serveur est suffisament rapide ! Le code suivant espère un temps
|
|
* ≤ à 50 millisecondes, ce qui est une bonne base pour les systèmes gérants les identifications
|
|
* intéractivement.
|
|
*/
|
|
$timeTarget = 0.05; // 50 millisecondes
|
|
|
|
$cost = 8;
|
|
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;
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs.similar;
|
|
<screen>
|
|
<![CDATA[
|
|
Valeur de 'cost' la plus appropriée : 10
|
|
]]>
|
|
</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 vivement recommandé de ne pas générer vous-même votre propre salt pour cette fonction.
|
|
La fonction va générer un salt sécurisé automatiquement pour vous si vous n'en spécifiez pas un !
|
|
</para>
|
|
|
|
<para>
|
|
Comme indiqué ci-dessus, fournir l'option <literal>Salt</literal> en PHP 7.0
|
|
générera un avertissement de désapprobation. La prise en charge d'un sel
|
|
fourni manuellement peut être enlevée dans une future version de PHP.
|
|
</para>
|
|
</caution>
|
|
<note>
|
|
<para>
|
|
Il est recommandé de tester cette fonction sur vos serveurs, et d'ajuster le paramètre "cost"
|
|
afin que l'exécution de cette fonction prenne moins de 100 millisecondes.
|
|
Le script dans l'exemple ci-dessus vous aide à choisir une bonne valeur suivant votre
|
|
architecture matérielle.
|
|
</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 parti 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>crypt</function></member>
|
|
<member><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.password.compat;">l'implémentation en espace utilisateur</link></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
|
|
-->
|