archived-doc-zh/reference/strings/functions/crypt.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: d76a7fe17dd2488e47d664a8ab38e161b13ac843 Maintainer: mowangjuanzi Status: ready -->
<!-- CREDITS: Luffy -->
<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" xml:id="function.crypt">
 <refnamediv>
  <refname>crypt</refname>
  <refpurpose>单向字符串散列</refpurpose>
 </refnamediv>
 
 <refsynopsisdiv>
  &note.not-bin-safe;
 </refsynopsisdiv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>crypt</methodname>
   <methodparam><modifier role="attribute">#[\SensitiveParameter]</modifier><type>string</type><parameter>string</parameter></methodparam>
   <methodparam><type>string</type><parameter>salt</parameter></methodparam>
  </methodsynopsis>
  <para>
   <function>crypt</function> 返回基于标准 UNIX <abbrev>DES</abbrev>
   算法或替代算法的散列字符串。<function>password_verify</function>
   兼容 <function>crypt</function>。因此，由 <function>crypt</function>
   创建的密码散列可以跟 <function>password_verify</function> 一起使用。
  </para>
  <para>
   在 PHP 8.0.0 之前，<parameter>salt</parameter> 参数是可选的。然而，如果没有
   <parameter>salt</parameter>，<function>crypt</function> 
   会创建弱散列。在没有它的情况下引发 <constant>E_NOTICE</constant>
   级别的错误。为了更好的安全性，请确保指定足够强度的盐值。
  </para>
  <para>
   <function>password_hash</function> 使用了强散列，产生足够强的盐值，并自动应用合适的轮次。<function>password_hash</function> 
   是<function>crypt</function> 的简单封装，并且与现有的密码散列兼容。推荐使用 <function>password_hash</function>。
  </para>
  <para>
   散列类型由盐值参数触发。如果没有提供盐值，PHP 将自动生成一个 2 个字符（DES）或者 12 个字符（MD5）的盐值 ，这取决于
   MD5 crypt() 的可用性。PHP 设置了名为 <constant>CRYPT_SALT_LENGTH</constant> 的常量，用来表示可用散列允许的最长有效盐值。
  </para>
  <para>
   基于标准 DES 算法的 <function>crypt</function> 在输出内容的开始位置返回两个字符的盐值。它也只使用
   <parameter>string</parameter> 的开始 8 个字符，所以更长的以相同 8 个字符开始的字符串也将生成相同的结果（当使用了相同的盐值时）。
  </para>
  <simpara>
   支持以下散列类型：
  </simpara>
  <itemizedlist>
   <listitem>
    <simpara>
     <constant>CRYPT_STD_DES</constant> - 基于标准 DES 算法的散列使用 "./0-9A-Za-z" 字符中的两个字符作为盐值。在盐值中使用非法的字符将导致 crypt() 失败。
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <constant>CRYPT_EXT_DES</constant> - 扩展的基于 DES 算法的散列。“sale” 为 9 个字符的字符串，由 1 个下划线后面跟着 4 字符循环次数和 4 字符盐值组成。这些 4 字符字符串都编码为 24 字节，最低有效位在前。值 <literal>0</literal> 到 <literal>63</literal> 被编码为 <literal>./0-9A-Za-z</literal>。在盐值中使用非法的字符将导致 crypt() 失败。
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <constant>CRYPT_MD5</constant> - MD5 散列使用一个以 $1$ 开始的 12 字符的字符串盐值。
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <constant>CRYPT_BLOWFISH</constant> - Blowfish 散列使用如下盐值：“$2a$”、“$2x$” 或 “$2y$”，两位 cost 参数，“$” 以及 22 位由 “./0-9A-Za-z” 中的字符组合而成的字符串。在盐值中使用此范围之外的字符将导致 crypt() 返回一个空字符串。两位 cost 参数是循环次数以 2 为底的对数，它的范围是 04-31，超出这个范围将导致 crypt() 失败。
     “$2x$” 可能很弱，“$2x$” 散列对其兼容并增强安全性。对于新的散列，应该使用“$2y$”。
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <constant>CRYPT_SHA256</constant> - SHA-256 算法使用一个以 $5$ 开头的 16 字符字符串盐值进行散列。如果盐值字符串以 “rounds=&lt;N&gt;$” 开头，N 的数字值将被用来指定散列循环的执行次数，这点很像 Blowfish 算法的 cost 参数。默认的循环次数是 5000，最小是 1000，最大是 999,999,999。超出这个范围的 N 将会被转换为最接近的值。
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <constant>CRYPT_SHA512</constant> - SHA-512 算法使用一个以 $6$ 开头的 16 字符字符串盐值进行散列。如果盐值字符串以 “rounds=&lt;N&gt;$” 开头，N 的数字值将被用来指定散列循环的执行次数，这点很像 Blowfish 算法的 cost 参数。默认的循环次数是 5000，最小是 1000，最大是 999,999,999。超出这个范围的 N 将会被转换为最接近的值。
    </simpara>
   </listitem>
  </itemizedlist>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>string</parameter></term>
     <listitem>
      <para>
       待散列的字符串。
      </para>
      <caution>
       <para>
        使用 <constant>CRYPT_BLOWFISH</constant> 算法将导致 <parameter>string</parameter> 被裁剪为一个最长72 字节的字符串。
       </para>
      </caution>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>salt</parameter></term>
     <listitem>
      <para>
       盐值字符串。如果没有提供，算法行为将由不同的算法实现决定，并可能导致不可预料的结束。
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   返回散列后的字符串或一个少于 13 字符的字符串，从而保证在失败时与盐值区分开来。
  </para>
  <warning>
   <simpara>
    当校验密码时，应该使用一个不容易被时间攻击的字符串比较函数来比较<function>crypt</function>的输出与之前已知的散列。出于这个目的，PHP 提供了<function>hash_equals</function>。
   </simpara>
  </warning>
 </refsect1>
 
 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>8.0.0</entry>
      <entry>
       <parameter>salt</parameter>不再可选。
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>crypt</function> 示例</title>
    <programlisting role="php">
<![CDATA[
<?php
$user_input = 'rasmuslerdorf';
$hashed_password = '$6$rounds=1000000$NJy4rIPjpOaU$0ACEYGg/aKCY3v8O8AfyiO7CTfZQ8/W231Qfh2tRLmfdvFD6XfHk12u6hMr9cYIA4hnpjLNSTRtUwYr9km9Ij/';

// 验证现有的 crypt() 哈希值，以便与非 PHP 软件兼容。
if (hash_equals($hashed_password, crypt($user_input, $hashed_password))) {
   echo "Password verified!";
}
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>
 
 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <simpara>
    由于 <function>crypt</function> 使用的是单向算法，因此不存在 decrypt 函数。
   </simpara>
  </note>
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>hash_equals</function></member>
    <member><function>password_hash</function></member>
    <member>更多关于 crypt 函数的信息，请阅读 Unix man 页面</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
-->