php-doc-en/reference/strings/functions/crypt.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" xml:id="function.crypt">
 <refnamediv>
  <refname>crypt</refname>
  <refpurpose>One-way string hashing</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>
   <function>crypt</function> will return a hashed string using the
   standard Unix <abbrev>DES</abbrev>-based algorithm or
   alternative algorithms that may be available on the system.
  </para>
  <para>
   The <parameter>salt</parameter> parameter is optional. However, <function>crypt</function> creates a weak password without the <parameter>salt</parameter>. PHP 5.6 or later raise an E_NOTICE error without it. Make sure to specify a strong enough salt for better security. 
  </para>
  <para>
   <function>password_hash</function> uses a strong hash, generates a strong salt, and applies proper rounds automatically. <function>password_hash</function> is a simple <function>crypt</function> wrapper and compatible with existing password hashes. Use of <function>password_hash</function> is encouraged.
  </para>
  <para>
   Some operating systems support more than one type of hash.  In
   fact, sometimes the standard DES-based algorithm is replaced by an
   MD5-based algorithm.  The hash type is triggered by the salt argument.
   Prior to 5.3, PHP would determine the available algorithms at install-time
   based on the system's crypt(). If no salt is provided, PHP will
   auto-generate either a standard two character (DES) salt, or a twelve
   character (MD5), depending on the availability of MD5 crypt().  PHP sets a
   constant named <constant>CRYPT_SALT_LENGTH</constant> which indicates the
   longest valid salt allowed by the available hashes.
  </para>
  <para>
   The standard DES-based <function>crypt</function> returns the
   salt as the first two characters of the output. It also only uses the
   first eight characters of <parameter>str</parameter>, so longer strings
   that start with the same eight characters will generate the same result
   (when the same salt is used).
  </para>
  <simpara>
   On systems where the crypt() function supports multiple
   hash types, the following constants are set to 0 or 1
   depending on whether the given type is available:
  </simpara>
  <itemizedlist>
   <listitem>
    <simpara>
     <constant>CRYPT_STD_DES</constant> - Standard DES-based hash with a two character salt
       from the alphabet "./0-9A-Za-z". Using invalid characters in the salt will cause
       crypt() to fail.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <constant>CRYPT_EXT_DES</constant> - Extended DES-based hash. The "salt" is a
     9-character string consisting of an underscore followed by 4 bytes of iteration count and
     4 bytes of salt. These are encoded as printable characters, 6 bits per character, least
     significant character first. The values 0 to 63 are encoded as "./0-9A-Za-z". Using invalid
     characters in the salt will cause crypt() to fail.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <constant>CRYPT_MD5</constant> - MD5 hashing with a twelve character salt starting with
     $1$
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <constant>CRYPT_BLOWFISH</constant> - Blowfish hashing with a salt as
     follows: "$2a$", "$2x$" or "$2y$", a two digit cost parameter, "$", and
     22 characters from the alphabet "./0-9A-Za-z". Using characters outside of
     this range in the salt will cause crypt() to return a zero-length string.
     The two digit cost parameter is the base-2 logarithm of the iteration
     count for the underlying Blowfish-based hashing algorithmeter and must be
     in range 04-31, values outside this range will cause crypt() to fail.
     Versions of PHP before 5.3.7 only support "$2a$" as the salt prefix: PHP
     5.3.7 introduced the new prefixes to fix a security weakness in the
     Blowfish implementation.  Please refer to
     <link xlink:href="&url.crypt.blowfish;">this document</link> for full
     details of the security fix, but to summarise, developers targeting only
     PHP 5.3.7 and later should use "$2y$" in preference to "$2a$".
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <constant>CRYPT_SHA256</constant> - SHA-256 hash with a sixteen character salt
     prefixed with $5$. If the salt string starts with 'rounds=&lt;N&gt;$', the numeric value of N
     is used to indicate how many times the hashing loop should be executed, much like the cost
     parameter on Blowfish. The default number of rounds is 5000, there is a minimum of
     1000 and a maximum of 999,999,999. Any selection of N outside this range will be truncated to
     the nearest limit.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <constant>CRYPT_SHA512</constant> - SHA-512 hash with a sixteen character salt
     prefixed with $6$. If the salt string starts with 'rounds=&lt;N&gt;$', the numeric value of N
     is used to indicate how many times the hashing loop should be executed, much like the cost
     parameter on Blowfish. The default number of rounds is 5000, there is a minimum of
     1000 and a maximum of 999,999,999. Any selection of N outside this range will be truncated to
     the nearest limit.
    </simpara>
   </listitem>
  </itemizedlist>
  <note>
   <para>
    As of PHP 5.3.0, PHP contains its own implementation and will use that
    if the system lacks of support for one or more of the algorithms.
   </para>
  </note>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>str</parameter></term>
     <listitem>
      <para>
       The string to be hashed.
      </para>
      <caution>
       <para>
        Using the <constant>CRYPT_BLOWFISH</constant> algorithm, will result
        in the <parameter>str</parameter> parameter being truncated to a
        maximum length of 72 characters.
       </para>
      </caution>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>salt</parameter></term>
     <listitem>
      <para>
       An optional salt string to base the hashing on. If not provided, the
       behaviour is defined by the algorithm implementation and can lead to
       unexpected results.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns the hashed string or a string that is shorter than 13 characters
   and is guaranteed to differ from the salt on failure.
  </para>
  <warning>
   <simpara>
    When validating passwords, a string comparison function that isn't
    vulnerable to timing attacks should be used to compare the output of
    <function>crypt</function> to the previously known hash. PHP 5.6 onwards
    provides <function>hash_equals</function> for this purpose.
   </simpara>
  </warning>
 </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.6.5</entry>
       <entry>
        When the failure string "*0" is given as the
        <parameter>salt</parameter>, "*1" will now be returned for consistency
        with other crypt implementations. Prior to this version, PHP 5.6 would
        incorrectly return a DES hash.
       </entry>
      </row>
      <row>
       <entry>5.6.0</entry>
       <entry>
        Raise E_NOTICE security warning if <parameter>salt</parameter> is omitted.
       </entry>
      </row>
      <row>
       <entry>5.5.21</entry>
       <entry>
        When the failure string "*0" is given as the
        <parameter>salt</parameter>, "*1" will now be returned for consistency
        with other crypt implementations. Prior to this version, PHP 5.5 (and
        earlier branches) would incorrectly return a DES hash.
       </entry>
      </row>
      <row>
       <entry>5.3.7</entry>
       <entry>
        Added <literal>$2x$</literal> and <literal>$2y$</literal> Blowfish
        modes to deal with potential high-bit attacks.
       </entry>
      </row>
      <row>
       <entry>5.3.2</entry>
       <entry>
        Added SHA-256 and SHA-512 crypt based on Ulrich Drepper's 
        <link xlink:href="&url.crypt.sha;">implementation</link>.
       </entry>
      </row>
      <row>
       <entry>5.3.2</entry>
       <entry>
        Fixed Blowfish behaviour on invalid rounds to return "failure" 
        string ("*0" or "*1"), instead of falling back to DES.
       </entry>
      </row>
      <row>
       <entry>5.3.0</entry>
       <entry>
        PHP now contains its own implementation for the MD5 crypt, Standard DES,
        Extended DES and the Blowfish algorithms and will use that if the system
        lacks of support for one or more of the algorithms.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>crypt</function> examples</title>
    <programlisting role="php">
<![CDATA[
<?php
$hashed_password = crypt('mypassword'); // let the salt be automatically generated

/* You should pass the entire results of crypt() as the salt for comparing a
   password, to avoid problems when different hashing algorithms are used. (As
   it says above, standard DES-based password hashing uses a 2-character salt,
   but MD5-based hashing uses 12.) */
if (hash_equals($hashed_password, crypt($user_input, $hashed_password))) {
   echo "Password verified!";
}
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Using <function>crypt</function> with htpasswd</title>
    <programlisting role="php">
<![CDATA[
<?php
// Set the password
$password = 'mypassword';

// Get the hash, letting the salt be automatically generated
$hash = crypt($password);
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Using <function>crypt</function> with different hash types</title>
    <programlisting role="php">
<![CDATA[
<?php
/* These salts are examples only, and should not be used verbatim in your code.
   You should generate a distinct, correctly-formatted salt for each password.
*/
if (CRYPT_STD_DES == 1) {
    echo 'Standard DES: ' . crypt('rasmuslerdorf', 'rl') . "\n";
}

if (CRYPT_EXT_DES == 1) {
    echo 'Extended DES: ' . 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[
Standard DES: rl.3StKT.4T8M
Extended DES: _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>
    There is no decrypt function, since <function>crypt</function> uses a
    one-way algorithm.
   </simpara>
  </note>
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>hash_equals</function></member>
    <member><function>password_hash</function></member>
    <member><function>md5</function></member>
    <member>The <link linkend="ref.mcrypt">Mcrypt</link> extension</member>
    <member>The Unix man page for your crypt function for more information</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
-->