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

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: c6e10c66531fa175bca0479e779aee96a08c2629 Maintainer: hirokawa Status: ready -->
<!-- CREDITS: shimooka -->
<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>

 <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> 文字列のハッシュを返します。
   Unix 標準の <abbrev>DES</abbrev> ベースのアルゴリズムか、
   あるいはシステム上で使えるその他のアルゴリズムを使用します。
  </para>
  <para>
   複数のハッシュ方式をサポートしているオペレーティングシステムもあります。
   実際、標準の DES ベースのアルゴリズムを MD5 ベースのものに置き換えることもあります。
   ハッシュ方式は、salt 引数によって決まります。
   PHP 5.3 より前のバージョンでは、PHP のインストール時に、
   システムの crypt() 関数から使用できるアルゴリズムを判別します。
   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>str</parameter> の最初の 8 文字しか使用しません。
   つまり、最初の 8 文字が同じである長い文字列は、
   同じ salt を使う限り同じ結果となります。
  </para>
  <simpara>
   crypt() が複数のハッシュ方式をサポートしているシステムでは、
   その方式が使用可能かどうかによって次の定数群が
   0 か 1 に設定されます。
  </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 が続きます。
     これらが表示可能な文字にエンコードされます。一文字あたり 6 ビットで、
     下位の文字から順に並びます。
     0 から 63 までの値は "./0-9A-Za-z" とエンコードされます。
     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() は失敗します。
     5.3.7 までのバージョンの PHP では、salt のプレフィックスとして "$2a$"
     だけしか使えませんでした。PHP 5.3.7 で新たなプレフィックスが導入され、
     Blowfish の実装にあったセキュリティ上の弱点に対応しました。
     セキュリティ修正の対応の詳細については
     <link xlink:href="&url.crypt.blowfish;">この文書</link> を参照ください。
     簡単にまとめると、PHP 5.3.7 以降しか使わないのなら
     "$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>
  <note>
   <para>
    PHP 5.3.0 以降、PHP 自身にもそれぞれの実装が含まれるようになりました。
    システム側でそのアルゴリズムがサポートされていない場合にこの実装を使用します。
   </para>
  </note>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>str</parameter></term>
     <listitem>
      <para>
       ハッシュしたい文字列。
      </para>
     </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>
 </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.7</entry>
       <entry>
        Blowfish のモード <literal>$2x$</literal> および <literal>$2y$</literal>
        が追加され、高ビット攻撃に対応できるようになりました。
       </entry>
      </row>
      <row>
       <entry>5.3.2</entry>
       <entry>
        SHA-256 および SHA-512 による暗号化が追加されました。Ulrich Drepper の
        <link xlink:href="&url.crypt.sha;">実装</link>
        を使っています。
       </entry>
      </row>
      <row>
       <entry>5.3.2</entry>
       <entry>
        Blowfish で無効な rounds を指定したときに、DES に切り替えるのではなく
        "failure" 文字列 ("*0" あるいは "*1") を返すようになりました。
       </entry>
      </row>
      <row>
       <entry>5.3.0</entry>
       <entry>
        PHP に MD5 crypt, Standard DES, Extended DES および Blowfish
        の実装が含まれるようになりました。システム側でこれらのアルゴリズムがサポートされていない場合に、
        この実装を使用します。
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>crypt</function> の例</title>
    <programlisting role="php">
<![CDATA[
<?php
$hashed_password = crypt('mypassword'); // saltを自動的に生成させます

/* 異なったハッシュアルゴリズムが使用された際の問題を避けるために
   crypt()の結果全体をパスワード比較用のsaltとして渡す必要があります。
   (上記のように標準DESに基づくパスワードハッシュは2文字のsaltを使用します
   が、MD5に基づくハッシュは12文字のsaltを使用します) */
if (crypt($user_input, $hashed_password) == $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 を生成して各パスワードに使いましょう。
*/
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', '$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:     $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>
    復号するための関数はありません。
    <function>crypt</function> が使用しているのは単方向アルゴリズムだからです。
   </simpara>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>md5</function></member>
    <member><link linkend="ref.mcrypt">mcrypt</link> 拡張モジュール</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
-->