Update more information about the options, restructuring the location and detail of the supported options. Additionally, refactor the needs rehash and get info documentation slightly.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@330608 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Anthony Ferrara 2013-06-21 11:57:00 +00:00
parent 6fbb2db68c
commit 95f6764aef
5 changed files with 90 additions and 19 deletions

View file

@ -531,7 +531,7 @@ conn</parameter></term><listitem><para>An MCVE_CONN resource returned by
<!ENTITY password.parameter.hash 'A hash created by <function xmlns="http://docbook.org/ns/docbook">password_hash</function>.'>
<!ENTITY password.parameter.options 'An associative array containing options. Currently, two options are supported: <literal xmlns="http://docbook.org/ns/docbook">salt</literal>, to provide a salt to use when hashing the password, and <literal xmlns="http://docbook.org/ns/docbook">cost</literal>, which denotes the algorithmic cost that should be used. Examples of these values can be found on the <function xmlns="http://docbook.org/ns/docbook">crypt</function> page.'>
<!ENTITY password.parameter.options '<para xmlns="http://docbook.org/ns/docbook">An associative array containing options. See the <link xmlns="http://docbook.org/ns/docbook" linkend="password.constants">password algorithm constants</link> for documentation on the supported options for each algorithm.</para>'>
<!ENTITY password.parameter.password 'The user&apos;s password.'>

View file

@ -13,10 +13,34 @@
(<type>integer</type>)
</term>
<listitem>
<simpara>
<para>
<constant>PASSWORD_BCRYPT</constant> is used to create new password
hashes using the <constant>CRYPT_BLOWFISH</constant> algorithm.
</simpara>
</para>
<para>
This will always result in a hash using the "$2y$" crypt format,
which is always 60 characters wide.
</para>
<para>
Supported Options:
</para>
<itemizedlist>
<listitem>
<para>
<literal>salt</literal> - to manually provide a salt to use when hashing the password.
Note that this will override and prevent a salt from being automatically generated.
</para>
<para>
If omitted, a random salt will be generated by <function>password_hash</function> for
each password hashed. This is the intended mode of operation.
</para>
</listitem>
<listitem>
<para>
<literal>cost</literal> - which denotes the algorithmic cost that should be used. Examples of these values can be found on the <function>crypt</function> page.
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.password-default">
@ -25,11 +49,28 @@
(<type>integer</type>)
</term>
<listitem>
<simpara>
<para>
The default algorithm to use for hashing if no algorithm is provided.
This may change in newer PHP releases when newer, stronger hashing
algorithms are supported.
</simpara>
</para>
<para>
It is worth noting that over time this constant can (and likely will)
change. Therefore you should be aware that the length of the resulting
hash can change. Therefore, if you use <constant>PASSWORD_DEFAULT</constant>
you should store the resulting hash in a way that can store more than 60
characters (255 is the recomended width).
</para>
<para>
Values for this constant:
</para>
<itemizedlist>
<listitem>
<simpara>
PHP 5.5.0 - <constant>PASSWORD_BCRYPT</constant>
</simpara>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
</variablelist>

View file

@ -37,12 +37,27 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns an associative array with three elements: <literal>algo</literal>,
which will match a
<link linkend="password.constants">password algorithm constant</link>;
<literal>algoName</literal>, which has the human readable name of the
algorithm; and <literal>options</literal>, which includes the options
provided when calling <function>password_hash</function>.
Returns an associative array with three elements:
<itemizedlist>
<listitem>
<simpara>
<literal>algo</literal>, which will match a
<link linkend="password.constants">password algorithm constant</link>
</simpara>
</listitem>
<listitem>
<simpara>
<literal>algoName</literal>, which has the human readable name of the
algorithm
</simpara>
</listitem>
<listitem>
<simpara>
<literal>options</literal>, which includes the options
provided when calling <function>password_hash</function>
</simpara>
</listitem>
</itemizedlist>
</para>
</refsect1>
</refentry>

View file

@ -39,6 +39,26 @@
create the hash. This will produce a standard <function>crypt</function> compatible hash using
the "$2y$" identifier. The result will always be a 60 character string, &return.falseforfailure;.
</simpara>
<para>
Supported Options:
</para>
<itemizedlist>
<listitem>
<para>
<literal>salt</literal> - to manually provide a salt to use when hashing the password.
Note that this will override and prevent a salt from being automatically generated.
</para>
<para>
If omitted, a random salt will be generated by <function>password_hash</function> for
each password hashed. This is the intended mode of operation.
</para>
</listitem>
<listitem>
<para>
<literal>cost</literal> - which denotes the algorithmic cost that should be used. Examples of these values can be found on the <function>crypt</function> page.
</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</para>

View file

@ -12,8 +12,8 @@
<methodsynopsis>
<type>boolean</type><methodname>password_needs_rehash</methodname>
<methodparam><type>string</type><parameter>hash</parameter></methodparam>
<methodparam><type>integer</type><parameter>algo</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>options</parameter></methodparam>
<methodparam><type>string</type><parameter>algo</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>options</parameter></methodparam>
</methodsynopsis>
<para>
This function checks to see if the supplied hash implements the algorithm
@ -44,12 +44,7 @@
<varlistentry>
<term><parameter>options</parameter></term>
<listitem>
<para>
&password.parameter.options;
</para>
<para>
If omitted, the default <literal>cost</literal> will be used.
</para>
&password.parameter.options;
</listitem>
</varlistentry>
</variablelist>