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

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 2526581912be11d14da7006fba344ca525a8566a 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><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
// saltを自動的に生成させます; お勧めできません
$hashed_password = crypt('mypassword');


/* 異なったハッシュアルゴリズムが使用された際の問題を避けるために
   crypt()の結果全体をパスワード比較用のsaltとして渡す必要があります。
   (上記のように標準DESに基づくパスワードハッシュは2文字のsaltを使用します
   が、MD5に基づくハッシュは12文字のsaltを使用します) */
if (hash_equals($hashed_password, crypt($user_input, $hashed_password))) {
   echo "Password verified!";
}
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title><function>crypt</function> を htpasswd で使用する例</title>
    <programlisting role="php">
<![CDATA[
<?php
// パスワードを設定します
$password = 'mypassword';

// ハッシュを取得します。salt は自動生成させます; お勧めできません
$hash = crypt($password);
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>異なるハッシュ形式を用いた <function>crypt</function> の例</title>
    <programlisting role="php">
<![CDATA[
<?php
/* これらの salt はあくまでも一例として示したものであり、実際のコードにそのまま使ってはいけません。
   別の、適切な形式の salt を生成して各パスワードに使いましょう。
*/
echo 'Standard DES: ',
    crypt('rasmuslerdorf', 'rl'),
    "\n";
echo 'Extended 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[
Standard DES: rl.3StKT.4T8M
Extended 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><function>md5</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
-->