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

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $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 encryption (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 an encrypted string using the
   standard Unix <abbrev>DES</abbrev>-based encryption algorithm or
   alternative algorithms that may be available on the system.
  </para>
  <para>
   Some operating systems support more than one type of encryption.  In
   fact, sometimes the standard DES-based encryption is replaced by an
   MD5-based encryption algorithm.  The encryption type is triggered by the
   salt argument.  At install time, PHP determines the capabilities of the
   crypt function and will accept salts for other encryption types.  If no
   salt is provided, PHP will auto-generate a standard two character salt by
   default, unless the default encryption type on the system is MD5, in
   which case a random MD5-compatible salt is generated.  PHP sets a
   constant named <constant>CRYPT_SALT_LENGTH</constant> which tells you
   whether a regular two character salt applies to your system or the longer
   twelve character salt is applicable.
  </para>
  <para>
   The standard DES-based encryption <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
   encryption 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 encryption with a two character salt
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <constant>CRYPT_EXT_DES</constant> - Extended DES-based encryption. 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".
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <constant>CRYPT_MD5</constant> - MD5 encryption with a twelve character salt starting with
     $1$
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <constant>CRYPT_BLOWFISH</constant> - Blowfish encryption with a salt as follows:
     "$2a$", a two digit cost parameter, "$", and 22 base 64 digits 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 select DES-based encryption
     instead, with a salt of '$2'.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <constant>CRYPT_SHA256</constant> - SHA-256 encryption 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 encryption. 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 encryption 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 encryption. 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 encrypted.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>salt</parameter></term>
     <listitem>
      <para>
       An optional salt string to base the encryption on. If not provided,
       one will be randomly generated by PHP each time you call this function.
      </para>
      <para>
       If you are using the supplied salt, you should be aware that the salt
       is generated once. If you are calling this function repeatedly, this
       may impact both appearance and security.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns the encrypted string.
  </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>
	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.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
$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 (crypt($user_input, $password) == $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 encryption types</title>
    <programlisting role="php">
<![CDATA[
<?php
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', '$5$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>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
-->