doc-fr/reference/strings/functions/crypt.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: ab5351a260a7fdab22466de11eae852fbd4616f1 Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->

<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" xml:id="function.crypt">
 <refnamediv>
  <refname>crypt</refname>
  <refpurpose>Hachage à sens unique (indéchiffrable)</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>crypt</methodname>
   <methodparam><type>string</type><parameter>str</parameter></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>salt</parameter></methodparam>
  </methodsynopsis>
  <para>
   Retourne la chaîne <parameter>str</parameter> chiffrée avec l'algorithme
   standard Unix <abbrev>DES</abbrev>, ou bien un des algorithmes disponibles
   sur la machine.
  </para>
  <para>
   Certains systèmes supportent plus d'un type de hachage. En fait,
   il arrive que le chiffrement DES standard soit remplacé par un
   algorithme de chiffrement MD5. Le choix du type de hachage est
   effectué en se basant sur la valeur du <parameter>salt</parameter>.
   À l'installation, PHP détermine les possibilités de
   la fonction <function>crypt</function>, et acceptera des <parameter>salt</parameter>
   pour d'autres types de chiffrements. Si aucun <parameter>salt</parameter>
   n'est fourni, PHP va en générer deux caractères (DES), à moins que le
   système par défaut soit MD5, auquel cas un <parameter>salt</parameter>
   compatible MD5 sera généré. PHP définit une constante appelée
   <constant>CRYPT_SALT_LENGTH</constant> permettant de vous indiquer la longueur
   du <parameter>salt</parameter> disponible pour le système de hachage utilisé.
  </para>
  <para>
   <function>crypt</function>, lorsqu'elle est utilisée avec
   le chiffrement standard DES, retourne le <parameter>salt</parameter>
   dans les deux premiers caractères de la chaîne retournée. Elle
   n'utilise que les 8 premiers caractères de <parameter>str</parameter>,
   ce qui fait que toutes les chaînes plus longues, qui ont les mêmes
   premiers 8 octets retourneront le même résultat (tant que le
   <parameter>salt</parameter> est toujours le même).
  </para>
  <simpara>
   Sur les systèmes où <function>crypt</function> supporte plusieurs types de
   hachages, les constantes suivantes sont mises à 0 ou 1,
   suivant que le type correspondant est disponible :
  </simpara>
  <itemizedlist>
   <listitem>
    <simpara>
     <constant>CRYPT_STD_DES</constant> : chiffrement DES standard à 2
     caractères depuis la classe de caractères "./0-9A-Za-z". L'utilisation
     de caractères invalides dans le salt fera échouer la fonction crypt().
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <constant>CRYPT_EXT_DES</constant> : Hachage DES étendu. Le "salt" sera une
     chaîne de 9 caractères composé d'un underscore, suivi de 4 octets du compteur d'itération
     puis 4 octets du "salt". Ces caractères seront encodés en tant que caractères imprimables,
     6 octets par caractère, et dont le premier caractère au moins sera significatif. Les valeurs
     de 0 à 63 seront encodés comme "./0-9A-Za-z". L'utilisation
     de caractères invalides dans le salt fera échouer la fonction crypt().
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <constant>CRYPT_MD5</constant> : hachage MD5 à 12 caractères
     commençant par <literal>$1$</literal>
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <constant>CRYPT_BLOWFISH</constant> : hachage Blowfish dont le salt est composé
     comme ceci ;
     <literal>$2a$</literal>, un paramètre à 2 chiffres, <literal>$</literal>,
     et 22 base 64 chiffres depuis la classe de caractères "./0-9A-Za-z". L'utilisation
     de caractères en dehors de cette classe dans le salt fera que la fonction crypt()
     retournera une chaîne vide (de longueur 0). Le paramètre à 2 chiffres est le logarithme
     base-2 du compteur d'itération pour l'algorithme de hachage basé sur Blowfish sous jacent et
     doivent être dans l'intervalle 04-31. De la même façon, si vous utilisez une valeur en dehors
     de cet intervalle, la fonction crypt() échouera.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <constant>CRYPT_SHA256</constant> - Hachage SHA-256 dont le salt est composé de 16 caractères
     préfixé par <literal>$5$</literal>. Si le salt commence par <literal>'rounds=&lt;N&gt;$'</literal>,
     la valeur numérique de N sera utilisée pour indiquer le nombre de fois que la boucle de
     hachage doit être exécutée, un peu comme le paramètre dans l'algorithme Blowfish.
     La valeur par défaut de <literal>rounds</literal> est de 5000, le minimum pouvant être de
     1000 et le maximum, de 999,999,999. Tout autre sélection de N en dehors de cet intervalle
     sera tronqué à la plus proche des 2 limites.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <constant>CRYPT_SHA512</constant> - Hachage SHA-512 dont le salt est composé de 16 caractères
     préfixé par <literal>$6$</literal>. Si le salt commence par <literal>'rounds=&lt;N&gt;$'</literal>,
     la valeur numérique de N sera utilisée pour indiquer le nombre de fois que la boucle de
     hachage doit être exécutée, un peu comme le paramètre dans l'algorithme Blowfish.
     La valeur par défaut de <literal>rounds</literal> est de 5000, le minimum pouvant être de
     1000 et le maximum, de 999,999,999. Tout autre sélection de N en dehors de cet intervalle
     sera tronqué à la plus proche des 2 limites.
    </simpara>
   </listitem>
  </itemizedlist>
  <note>
   <para>
    Depuis PHP 5.3.0, PHP dispose de sa propre implémentation, et l'utilisera
    si le système ne dispose pas de fonction crypt, ou de certains algorithmes.
   </para>
  </note>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>str</parameter></term>
     <listitem>
      <para>
       La chaîne à hacher.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>salt</parameter></term>
     <listitem>
      <para>
       Si l'argument <parameter>salt</parameter> n'est pas fourni, le comportement
       est défini par l'implémentation de l'algorithme et peut provoquer des
       résultats inattendus.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Retourne la chaîne hachée ou une chaîne qui sera inférieure à 13 caractères
   et qui est garantie de différer du salt en cas d'erreur.
  </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>5.3.2</entry>
       <entry>
        Ajout de SHA-256 et de SHA-512 basés sur
        l'<link xlink:href="&url.crypt.sha;">implementation</link>
        de Ulrich Drepper.
       </entry>
      </row>
      <row>
       <entry>5.3.2</entry>
       <entry>
        Correction du comportement de Blowfish lors d'étape invalide
        où une chaîne d'échec ("*0" ou "*1") était retournée au lieu
        de retourner le DES dans ce cas.
       </entry>
      </row>
      <row>
       <entry>5.3.0</entry>
       <entry>
        PHP dispose maintenant de sa propre implémentation de crypt
        MD5, Standard DES, Extended DES et l'algorithme Blowfish. Il l'utilisera
        si le système ne fournit pas l'un ou l'autre des algorithmes. 
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Exemple avec <function>crypt</function></title>
    <programlisting role="php">
<![CDATA[
<?php
// laissons le salt initialisé par PHP
$password = crypt('mypassword');

/*
  Il vaut mieux passer le résultat complet de crypt() comme salt nécessaire
  pour le chiffrement du mot de passe, pour éviter les problèmes entre les
  algorithmes utilisés (comme nous le disons ci-dessus, le chiffrement
  standard DES utilise un salt de 2 caractères, mais un chiffrement
  MD5 utilise un salt de 12).
*/
if (crypt($user_input, $password) == $password) {
   echo "Mot de passe correct !";
}
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Utilisation de <function>crypt</function> avec htpasswd</title>
    <programlisting role="php">
<![CDATA[
<?php
// Définition du mot de passe
$password = 'mypassword';

// Récupération du hash, on laisse le salt se générer automatiquement
$hash = crypt($password);
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Utilisation de <function>crypt</function> avec différents types de chiffrement</title>
    <programlisting role="php">
<![CDATA[
<?php
if (CRYPT_STD_DES == 1) {
    echo 'DES standard : ' . crypt('rasmuslerdorf', 'rl') . "\n";
}

if (CRYPT_EXT_DES == 1) {
    echo 'DES étendu : ' . crypt('rasmuslerdorf', '_J9..rasm') . "\n";
}

if (CRYPT_MD5 == 1) {
    echo 'MD5 :          ' . crypt('rasmuslerdorf', '$1$rasmusle$') . "\n";
}

if (CRYPT_BLOWFISH == 1) {
    echo 'Blowfish :     ' . crypt('rasmuslerdorf', '$2a$07$usesomesillystringforsalt$') . "\n";
}

if (CRYPT_SHA256 == 1) {
    echo 'SHA-256 :      ' . crypt('rasmuslerdorf', '$5$rounds=5000$usesomesillystringforsalt$') . "\n";
}

if (CRYPT_SHA512 == 1) {
    echo 'SHA-512 :      ' . crypt('rasmuslerdorf', '$6$rounds=5000$usesomesillystringforsalt$') . "\n";
}
?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
DES standard : rl.3StKT.4T8M
DES étendu : _J9..rasmBYk8r9AiWNc
MD5 :          $1$rasmusle$rISCgZzpwk3UhDidwXvin0
Blowfish :     $2a$07$usesomesillystringfore2uDLvp1Ii2e./U9C8sBjqp8I90dH6hi
SHA-256 :      $5$rounds=5000$usesomesillystri$KqJWpanXZHKq2BOB43TSaYhEWsQ1Lr5QNyPCDH/Tp.6
SHA-512 :      $6$rounds=5000$usesomesillystri$D4IrlXatmP7rx3P3InaxBeoomnAihCKRVQP22JZ6EY47Wc6BkroIuUUBOov1i.S5KPgErtP/EN5mcO.ChWQW21
]]>
    </screen>
   </example>
  </para>
 </refsect1>
 
 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <simpara>
    Il n'existe pas de fonction de déchiffrement, car la fonction <function>crypt</function>
    utilise un algorithme à un seul sens (injection).
   </simpara>
  </note>
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>md5</function></member>
    <member>L'extension <link linkend="ref.mcrypt">Mcrypt</link></member>
    <member>La page de manuel Unix de la fonction crypt pour plus d'informations</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
-->