crypt.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 60b29fbe11384d5233398d70fdc74e9078fe32ad Maintainer: shein 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>Необратимое хеширование строки</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  &note.not-bin-safe;
 </refsynopsisdiv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>crypt</methodname>
   <methodparam><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> был необязательным.
   Однако функция <function>crypt</function> создаёт слабый хеш без параметра <parameter>salt</parameter>,
   а без него выдаёт ошибку уровня <constant>E_NOTICE</constant>.
   Убедитесь, что используете достаточно сложную соль для лучшей безопасности.
  </para>
  <para>
   Функция <function>password_hash</function> использует сложный хеш, генерирует сложную соль и применяет
   правильно количество раундов хеширования автоматически.
   <function>password_hash</function> является простой обёрткой над  <function>crypt</function>
   и совместима с существующими хешами паролей. Поэтому приветствуется использование <function>password_hash</function>.
  </para>
  <para>
   Вид хеширования определяется переданным аргументом salt (соль).
   Если соль не указана,
   будет автоматически сгенерирована стандартная случайная
   двухсимвольная (DES) или двенадцатисимвольная (MD5) соль, в
   зависимости от доступности алгоритма MD5 в crypt().
   Предопределённая константа <constant>CRYPT_SALT_LENGTH</constant>
   позволяет определить максимально доступную длину соли в
   соответствии с используемыми алгоритмами.
  </para>
  <para>
   Стандартная функция <function>crypt</function> на основе DES
   возвращает соль в качестве первых двух символов возвращаемой
   строки. Кроме того, она использует только первые восемь символов
   строки <parameter>string</parameter>, поэтому более длинные строки,
   начинающиеся с тех же восьми символов, сгенерируют один и тот же
   результат (при использовании одинаковой соли).
  </para>
  <simpara>
   Поддерживаются следующие типы хешей:
  </simpara>
  <itemizedlist>
   <listitem>
    <simpara>
     <constant>CRYPT_STD_DES</constant> - Стандартное DES-шифрование
     с двухсимвольной солью из алфавита "./0-9A-Za-z""./0-9A-Za-z". Использование
     других символов в соли повлечёт за собой отказ работы crypt().
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <constant>CRYPT_EXT_DES</constant> - Расширенное DES-шифрование.
     "Соль" является 9-символьной строкой, состоящая из символа подчёркивания,
     за которым следуют 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-шифрование с 12-символьной
     солью, начинающейся с $1$
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <constant>CRYPT_BLOWFISH</constant> - Blowfish-шифрование со
     следующей солью: "$2a$", "$2x$" или "$2y$", весовой параметр из двух цифр, "$" и
     22 цифры из алфавита "./0-9A-Za-z". Использование других
     символов в соли повлечёт за собой возврат пустой строки.
     Весовой параметр из двух цифр является двоичным логарифмом
     счётчика итераций нижележащего хеширующего алгоритма, основанного
     на Blowfish, и должен быть в диапазоне 04-31, значения вне
     данного диапазона вызовут отказ crypt().
     Хеши "$2x$" потенциально слабые; Хэши "$2a$" совместимы и
     смягчают эту слабость. Для новых хэшей следует использовать "$2y$".
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <constant>CRYPT_SHA256</constant> - хеш SHA-256 с шестнадцатисимвольной
     солью, начинающейся с $5$. Если строка с солью начинается с
     'rounds=&lt;N&gt;$', число N будет использовано для обозначения
     количества раундов хеширования, по аналогии с весовым параметром
     в Blowfish. По умолчанию используемое количество раундов равно 5000,
     минимально доступно 1000 и максимально 999,999,999. Любое значение
     вне этого диапазона будет усечено до ближайшего лимита.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <constant>CRYPT_SHA512</constant> - хеш SHA-512 с шестнадцатисимвольной
     солью, начинающейся с $6$. Если строка с солью начинается с
     'rounds=&lt;N&gt;$', число N будет использовано для обозначения
     количества раундов хеширования, по аналогии с весовым параметром
     в Blowfish. По умолчанию используемое количество раундов равно 5000,
     минимально доступно 1000 и максимально 999,999,999. Любое значение
     вне этого диапазона будет усечено до ближайшего лимита.
    </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 "Пароль верен!";
}
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Использование <function>crypt</function> с различными видами хешей</title>
    <programlisting role="php">
<![CDATA[
<?php
/* Приведённая соль является только примером. Не используйте эту же соль в вашем коде.
   Вы должны сгенерировать уникальную и правильную соль для каждого пароля.
*/
echo 'Стандартный DES: ',
    crypt('rasmuslerdorf', 'rl'),
    "\n";
echo 'Расширенный DES: ',
    crypt('rasmuslerdorf', '_J9..rasm'),
    "\n";
echo 'MD5:          ',
    crypt('rasmuslerdorf', '$1$rasmusle$'),
    "\n";
echo 'Blowfish:     ',
    crypt('rasmuslerdorf', '$2a$07$usesomesillystringforsalt$'),
    "\n";
echo 'SHA-256:      ',
    crypt('rasmuslerdorf', '$5$rounds=5000$usesomesillystringforsalt$'),
    "\n";
echo 'SHA-512:      ',
    crypt('rasmuslerdorf', '$6$rounds=5000$usesomesillystringforsalt$'),
    "\n";
?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
Стандартный DES: rl.3StKT.4T8M
Расширенный DES: _J9..rasmBYk8r9AiWNc
MD5:          $1$rasmusle$rISCgZzpwk3UhDidwXvin0
Blowfish:     $2y$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>
    Функция расшифровки отсутствует, так как <function>crypt</function>
    использует необратимый алгоритм хеширования.
   </simpara>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>hash_equals</function></member>
    <member><function>password_hash</function></member>
    <member>Страница руководства Unix по вашей функции crypt</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
-->