<?xml version="1.0" encoding="utf-8"?>

<!-- $Revision$ -->

<!-- EN-Revision: 5003a6ea92eb50ac92121782eedfc5ad3fe9d061 Maintainer: takagi Status: ready -->

<!-- Credits: mumumu -->

<refentry xml:id="function.password-hash" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">

<refnamediv>

<refname>password_hash</refname>

<refpurpose>パスワードハッシュを作る</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type>string</type><methodname>password_hash</methodname>

<methodparam><modifier role="attribute">#[\SensitiveParameter]</modifier><type>string</type><parameter>password</parameter></methodparam>

<methodparam><type class="union"><type>string</type><type>int</type><type>null</type></type><parameter>algo</parameter></methodparam>

<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>

</methodsynopsis>

<para>

<function>password_hash</function> は、

強力な一方向ハッシュアルゴリズムを使って、

新しいパスワードハッシュを作ります。

</para>

<simpara>

現在、以下のアルゴリズムに対応しています。

</simpara>

<para>

<itemizedlist>

<listitem>

<simpara>

<constant>PASSWORD_DEFAULT</constant> - bcrypt アルゴリズムを使います (PHP 5.5.0 の時点でのデフォルトです)。

新しくてより強力なアルゴリズムが PHP に追加されれば、

この定数もそれにあわせて変わっていきます。

そのため、これを指定したときの結果の長さは、変わる可能性があります。

したがって、結果をデータベースに格納するときにはカラム幅を

60 バイト以上にできるようなカラムを使うことをお勧めします

(255 バイトくらいが適切でしょう)。

</simpara>

</listitem>

<listitem>

<simpara>

<constant>PASSWORD_BCRYPT</constant> - bcrypt アルゴリズムを使ってハッシュを作ります。

これは標準の <function>crypt</function>

互換のハッシュで、識別子 <literal>$2y$</literal> を使った場合の結果を作ります。

</simpara>

</listitem>

<listitem>

<simpara>

<constant>PASSWORD_ARGON2I</constant> - Argon2i ハッシュアルゴリズムを使って

ハッシュを作ります。このアルゴリズムは、

PHP が Argon2 のサポートを有効にしてコンパイルした場合のみ利用できます。

</simpara>

</listitem>

<listitem>

<simpara>

<constant>PASSWORD_ARGON2ID</constant> - Argon2id ハッシュアルゴリズムを使って

ハッシュを作ります。このアルゴリズムは、

PHP が Argon2 のサポートを有効にしてコンパイルした場合のみ利用できます。

</simpara>

</listitem>

</itemizedlist>

</para>

<simpara>

<constant>PASSWORD_BCRYPT</constant> がサポートするオプション:

</simpara>

<para>

<itemizedlist>

<listitem>

<para>

<literal>salt</literal> (<type>string</type>) - パスワードのハッシュに使うソルトを手動で設定します。

これは、自動生成されたソルトを上書きすることに注意しましょう。

</para>

<para>

省略した場合は、パスワードをハッシュするたびに <function>password_hash</function>

がランダムなソルトを自動生成します。これは意図したとおりの操作モードです。

</para>

<warning>

<para>

このソルト・オプションは 非推奨になっています。

このオプションは指定せずに、デフォルトで生成されるソルトを使うことを推奨します。

PHP 8.0.0 以降は、この値を明示的に指定しても無視されます。

</para>

</warning>

</listitem>

<listitem>

<para>

<literal>cost</literal> (<type>int</type>) - 利用するアルゴリズムのコストを表します。

値の例については <function>crypt</function> のページを参照ください。

</para>

<para>

省略した場合のデフォルトは <literal>12</literal> です。この値でもかまいませんが、

ハードウェアの性能に応じて調整すべきです。

</para>

</listitem>

</itemizedlist>

</para>

<simpara>

<constant>PASSWORD_ARGON2I</constant> と

<constant>PASSWORD_ARGON2ID</constant> が

サポートするオプション

</simpara>

<para>

<itemizedlist>

<listitem>

<para>

<literal>memory_cost</literal> (<type>int</type>) - Argon2 ハッシュを計算するのに

使われるメモリの最大値(キロバイト単位)。

デフォルトは <constant>PASSWORD_ARGON2_DEFAULT_MEMORY_COST</constant> です。

</para>

</listitem>

<listitem>

<para>

<literal>time_cost</literal> (<type>int</type>) - Argon2 ハッシュを計算するのに

使って良い時間の最大値。

デフォルトは <constant>PASSWORD_ARGON2_DEFAULT_TIME_COST</constant> です。

</para>

</listitem>

<listitem>

<para>

<literal>threads</literal> (<type>int</type>) - Argon2 ハッシュを計算するのに使う

スレッド数。

デフォルトは <constant>PASSWORD_ARGON2_DEFAULT_THREADS</constant> です。

</para>

<warning>

<para>

PHP が libargon2 を使う場合にのみ利用可能です。

libsodium の実装では利用できません。

</para>

</warning>

</listitem>

</itemizedlist>

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<variablelist>

<varlistentry>

<term><parameter>password</parameter></term>

<listitem>

<para>

&password.parameter.password;

</para>

<caution>

<para>

<constant>PASSWORD_BCRYPT</constant> をアルゴリズムに指定すると、

<parameter>password</parameter> が最大 72 バイトまでに切り詰められます。

</para>

</caution>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>algo</parameter></term>

<listitem>

<para>

&password.parameter.algo;

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>options</parameter></term>

<listitem>

<para>

&password.parameter.options;

</para>

<para>

省略した場合は、ランダムな salt を生成してデフォルトのコストを使います。

</para>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

ハッシュしたパスワードを返します。

</para>

<para>

使ったアルゴリズムやコスト、そしてソルトもハッシュの一部として返されます。

つまり、ハッシュを検証するために必要な情報は、すべてそこに含まれているということです。

そのため、<function>password_verify</function> でハッシュを検証するときに、

ソルトやアルゴリズムの情報を別に保存する必要はありません。

</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>8.4.0</entry>

<entry>

<constant>PASSWORD_BCRYPT</constant> アルゴリズムのデフォルトの <literal>cost</literal> オプションの値が

<literal>10</literal> から <literal>12</literal> に引き上げられました。

</entry>

</row>

<row>

<entry>8.0.0</entry>

<entry>

<function>password_hash</function>

は、失敗時に &false; を返さなくなりました。

代わりに、パスワードハッシュのアルゴリズムが有効でなかった場合は

<classname>ValueError</classname> がスローされるようになりました。

また、パスワードハッシュの作成が不明なエラーで失敗した場合は、

<classname>Error</classname> がスローされるようになっています。

</entry>

</row>

<row>

<entry>8.0.0</entry>

<entry>

引数 <parameter>algo</parameter> は、 nullable になりました。

</entry>

</row>

<row>

<entry>7.4.0</entry>

<entry>

<parameter>algo</parameter> パラメータは &string; を期待するようになりました。

しかし、後方互換性のために &integer; も未だ受け入れています。

</entry>

</row>

<row>

<entry>7.4.0</entry>

<entry>

sodium 拡張モジュールが、

Argon2 パスワードの実装の代替を提供するようになりました。

</entry>

</row>

<row>

<entry>7.3.0</entry>

<entry>

<constant>PASSWORD_ARGON2ID</constant> を使った、

Argon2id パスワードのサポートが追加されました。

</entry>

</row>

<row>

<entry>7.2.0</entry>

<entry>

<constant>PASSWORD_ARGON2I</constant> を使った、

Argon2i パスワードのサポートが追加されました。

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title><function>password_hash</function> の例</title>

<programlisting role="php">

<![CDATA[

<?php

echo password_hash("rasmuslerdorf", PASSWORD_DEFAULT);

?>

]]>

</programlisting>

&example.outputs.similar;

<screen>

<![CDATA[

$2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.

]]>

</screen>

</example>

</para>

<para>

<example>

<title><function>password_hash</function> で、コストを手動で設定する例</title>

<programlisting role="php">

<![CDATA[

<?php

$options = [

// bcrypt のコストを 12 から 13 に増やします

'cost' => 13,

];

echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options);

?>

]]>

</programlisting>

&example.outputs.similar;

<screen>

<![CDATA[

$2y$13$xeDfQumlmdm0Sco.4qmH1OGfUUmOcuRmfae0dPJhjX1Bq0yYhqbNi

]]>

</screen>

</example>

</para>

<para>

<example>

<title><function>password_hash</function> で、適切なコストを探す例</title>

<simpara>

このコードは、サーバーをベンチマークして、

ユーザー体験を悪化させることなく、

どの程度のコストに耐えられるかを判断します。

サーバーに負荷をかけすぎない範囲で、

できるだけ高めのコストを設定することをお勧めします。

基準として 11 程度からはじめ、サーバーが十分に高速なら、

できるだけ上げていきましょう。

以下のコードでは、

ストレッチングの時間を 350 ミリ秒以内にすることを狙っています。

対話形式のログインを扱う際の許容時間としては、このあたりが適切でしょう。

</simpara>

<programlisting role="php">

<![CDATA[

<?php

$timeTarget = 0.350; // 350 ミリ秒

$cost = 11;

do {

$cost++;

$start = microtime(true);

password_hash("test", PASSWORD_BCRYPT, ["cost" => $cost]);

$end = microtime(true);

} while (($end - $start) < $timeTarget);

echo "Appropriate Cost Found: " . $cost - 1;

?>

]]>

</programlisting>

&example.outputs.similar;

<screen>

<![CDATA[

Appropriate Cost Found: 13

]]>

</screen>

</example>

</para>

<para>

<example>

<title>Argon2i を使った <function>password_hash</function> の例</title>

<programlisting role="php">

<![CDATA[

<?php

echo 'Argon2i hash: ' . password_hash('rasmuslerdorf', PASSWORD_ARGON2I);

?>

]]>

</programlisting>

&example.outputs.similar;

<screen>

<![CDATA[

Argon2i hash: $argon2i$v=19$m=1024,t=2,p=2$YzJBSzV4TUhkMzc3d3laeg$zqU/1IN0/AogfP4cmSJI1vc8lpXRW9/S0sYY2i2jHT0

]]>

</screen>

</example>

</para>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

<caution>

<para>

この関数で使うソルトを自前で設定するのはお勧めしません。

ソルトを省略すれば、安全なソルトをこの関数が自動的に作ってくれます。

</para>

<para>

先述のとおり、PHP 7.0 で <literal>salt</literal> オプションを指定すると、

非推奨の警告が発生します。ソルトを手動で設定する仕組みは、PHP 8.0 で削除されました。

</para>

</caution>

<note>

<para>

実際にサーバー上でこの関数をテストして、コストパラメータの適切な設定値を調整することをお勧めします。

対話型のログインを行わせる場合、関数の実行時間が 350 ミリ秒くらいに収まるくらいが適切です。

先ほどの例のスクリプトは、自分のハードウェア上での適切な bcrypt のコストを判断するための助けとなるでしょう。

</para>

</note>

<note>

<simpara>

この関数がサポートするアルゴリズムの更新 (あるいはデフォルトのアルゴリズムの変更)

は、必ず次の手順にのっとって行われます。

</simpara>

<para>

<itemizedlist>

<listitem>

<simpara>

新しく追加されたアルゴリズムがデフォルトになるまでには、

少なくとも一度は PHP のフルリリースを経ること。

つまり、たとえば、新しいアルゴリズムが 7.5.5 で追加されたとすると、

そのアルゴリズムがデフォルトになるのは早くても 7.7 以降ということになります

(7.6 は、最初のフルリリースだからです)。

しかし、もし別のアルゴリズムが 7.6.0 で追加されたとすると、

そのアルゴリズムも 7.7.0 の時点でデフォルトになる資格を得ます。

</simpara>

</listitem>

<listitem>

<simpara>

デフォルトを変更できるのはフルリリース (7.3.0 や 8.0.0 など)

のときだけで、リビジョンリリースでは変更できない。

唯一の例外は、現在のデフォルトにセキュリティ上の致命的な欠陥が発覚した場合の緊急リリースです。

</simpara>

</listitem>

</itemizedlist>

</para>

</note>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><function>password_verify</function></member>

<member><function>password_needs_rehash</function></member>

<member><function>crypt</function></member>

<member><function>sodium_crypto_pwhash_str</function></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

-->