password-verify.xml

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

<refentry xml:id="function.password-verify" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>password_verify</refname>
  <refpurpose>Verifies that a password matches a hash</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>password_verify</methodname>
   <methodparam><type>string</type><parameter>password</parameter></methodparam>
   <methodparam><type>string</type><parameter>hash</parameter></methodparam>
  </methodsynopsis>
  <para>
   Verifies that the given hash matches the given password.
   <function>password_verify</function> is compatible with <function>crypt</function>.
   Therefore, password hashes created by <function>crypt</function> can be used with
   <function>password_verify</function>.
  </para>
  <para>
   Note that <function>password_hash</function> returns the algorithm, cost and salt 
   as part of the returned hash. Therefore, all information that's needed to verify
   the hash is included in it. This allows the verify function to verify the hash
   without needing separate storage for the salt or algorithm information.
  </para>
  <para>
   This function is safe against timing attacks.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <varlistentry>
    <term><parameter>password</parameter></term>
    <listitem>
     <para>
      &password.parameter.password;
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>hash</parameter></term>
    <listitem>
     <para>
      &password.parameter.hash;
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns &true; if the password and hash match, or &false; otherwise.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>password_verify</function> example</title>
    <para>
     This is a simplified example; it is recommended to rehash a correct password
     if necessary; see <function>password_needs_rehash</function> for an example.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
// See the password_hash() example to see where this came from.
$hash = '$2y$10$.vGA1O9wmRjrwAVXD98HNOgsNpDczlqm3Jq7KnEd1rVAGv3Fykk1a';

if (password_verify('rasmuslerdorf', $hash)) {
    echo 'Password is valid!';
} else {
    echo 'Invalid password.';
}
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Password is valid!
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>password_needs_rehash</function></member>
    <member><function>password_hash</function></member>
    <member><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.password.compat;">userland implementation</link></member>
    <member><function>sodium_crypto_pwhash_str_verify</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
-->