crypt.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: d76a7fe17dd2488e47d664a8ab38e161b13ac843 Maintainer: hirokawa Status: ready -->
<!-- CREDITS: shimooka,mumumu -->
<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>
   パラメータは必須ではありませんでした。ただ、これを省略すると
   <function>crypt</function>
   が作るハッシュが弱いものになってしまっていました。
   このパラメータを省略した場合には、E_NOTICE が発生していました。
   十分に強い salt を指定して、セキュリティを確保しましょう。
  </para>
  <para>
   <function>password_hash</function> は、強力なハッシュを使い、強力なソルトを生成して、それを複数回自動的に適用します。
   <function>password_hash</function> は <function>crypt</function> のシンプルなラッパーであり、既存のパスワードハッシュと互換性があります。
   <function>password_hash</function> を使うことを推奨します。
  </para>
  <para>
   ハッシュ方式は、salt 引数によって決まります。
   salt を省略した場合は、標準の 2 文字 (DES) の salt を自動生成します。
   あるいは、MD5 crypt() が使えれば 12 文字 (MD5) の salt を自動生成します。
   PHP の定数 <constant>CRYPT_SALT_LENGTH</constant> には、
   ハッシュで使用できる salt の最大長が格納されています。
  </para>
  <para>
   標準の DES ベースの場合、<function>crypt</function>
   は出力の最初の 2 文字を salt として使用します。また、
   <parameter>string</parameter> の最初の 8 文字しか使用しません。
   つまり、最初の 8 文字が同じである長い文字列は、
   同じ salt を使う限り同じ結果となります。
  </para>
  <simpara>
   以下のハッシュ形式がサポートされています:
  </simpara>
  <itemizedlist>
   <listitem>
    <simpara>
     <constant>CRYPT_STD_DES</constant> - 標準の DES ベースのハッシュで、
       アルファベット "./0-9A-Za-z" からなる 2 文字の salt を使用するもの。
       salt として無効な文字を使うと crypt() は失敗します。
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <constant>CRYPT_EXT_DES</constant> - 拡張した DES ベースのハッシュ。
     "salt" は 9 文字で、
     アンダースコアの後に 4 文字の反復回数と 4 文字の salt が続きます。
     これらの4文字それぞれが、24ビットにエンコードされ、
     下位の文字から順に並びます。
     <literal>0</literal> から <literal>63</literal> までの値は
     <literal>./0-9A-Za-z</literal> の範囲内の文字でエンコードされます。
     salt に無効な文字を使うと crypt() は失敗します。
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <constant>CRYPT_MD5</constant> - $1$ ではじまる 12 文字の salt を使用する MD5 ハッシュ。
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <constant>CRYPT_BLOWFISH</constant> - Blowfish ハッシュ。salt の形式は、
     "$2a$" か "$2x$" あるいは "$2y$"、2 桁のコストパラメータ、"$"、そして文字 "./0-9A-Za-z"
     からなる 22 文字となります。
     この範囲外の文字を salt に使うと、crypt() は長さゼロの文字列を返します。
     2 桁のコストパラメータは反復回数の 2 を底とする対数で、
     これは Blowfish ベースのハッシュアルゴリズムで使います。
     この値は 04 から 31 までの範囲でなければならず、
     それ以外の値の場合は crypt() は失敗します。
     "$2x$" ハッシュは潜在的に弱いハッシュです。
     "$2a$" ハッシュはこれと互換性があり、この弱点を軽減します。
     新しくハッシュを生成する場合は、"$2y$" を使うべきです。
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <constant>CRYPT_SHA256</constant> - SHA-256 ハッシュに
     $5$ で始まる 16 文字の salt を組み合わせたもの。salt 文字列が
     'rounds=&lt;N&gt;$' で始まる場合は、数値 N がハッシュループの実行回数を表します。
     これは Blowfish のコストパラメータのようなものです。
     rounds のデフォルトは 5000 で、1000 から 999,999,999 までの値を指定できます。
     この範囲外の N を指定すると、近い方の境界値に切り詰められます。
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <constant>CRYPT_SHA512</constant> - SHA-512 ハッシュに
     $6$ で始まる 16 文字の salt を組み合わせたもの。salt 文字列が
     'rounds=&lt;N&gt;$' で始まる場合は、数値 N がハッシュループの実行回数を表します。
     これは Blowfish のコストパラメータのようなものです。
     rounds のデフォルトは 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>
       ハッシュのもととなる salt 文字列。省略した場合の挙動は
       アルゴリズムの実装によって決まるので、予期せぬ結果となることがあり得ます。
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   ハッシュした文字列を返します。
   失敗した場合は、salt とは異なることが保証されている 13 文字未満の文字列を返します。
  </para>
  <warning>
   <simpara>
    パスワードを検証するときの文字列比較関数は、
    タイミング攻撃に対して脆弱ではないものでなければいけません。
    これをもちいて、<function>crypt</function> の出力と既知のハッシュとを比較します。
    この比較を行うために、<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/';

// PHP 以外のソフトウェアと互換性がある方法で、既存の crypt() ハッシュを検証します
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> が使用しているのは単方向アルゴリズムだからです。
   </simpara>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>hash_equals</function></member>
    <member><function>password_hash</function></member>
    <member>暗号化関数についての 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
-->