hash-equals.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.hash-equals" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>hash_equals</refname>
  <refpurpose>Timing attack safe string comparison</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>hash_equals</methodname>
   <methodparam><modifier role="attribute">#[\SensitiveParameter]</modifier><type>string</type><parameter>known_string</parameter></methodparam>
   <methodparam><modifier role="attribute">#[\SensitiveParameter]</modifier><type>string</type><parameter>user_string</parameter></methodparam>
  </methodsynopsis>
  <para>
   Checks whether two strings are equal without leaking information about the
   contents of <parameter>known_string</parameter> via the execution time.
  </para>
  <para>
   This function can be used to mitigate timing attacks. Performing a regular
   comparison with <code>===</code> will take more or less time to execute
   depending on whether the two values are different or not and at which
   position the first difference can be found, thus leaking information about
   the contents of the secret <parameter>known_string</parameter>.
  </para>
  <caution>
   <para>
    It is important to provide the user-supplied string as the second
    parameter, rather than the first.
   </para>
  </caution>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <varlistentry>
    <term><parameter>known_string</parameter></term>
    <listitem>
     <para>
       The known &string; that must be kept secret.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>user_string</parameter></term>
    <listitem>
     <para>
      The user-supplied &string; to compare against.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
    Returns &true; when the two strings are equal, &false; otherwise.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example xml:id="foobar.examples.basic">
    <title><function>hash_equals</function> example</title>
    <programlisting role="php">
<![CDATA[
<?php
$secretKey = '8uRhAeH89naXfFXKGOEj';

// Value and signature are provided by the user, e.g. within the URL
// and retrieved using $_GET.
$value = 'username=rasmuslerdorf';
$signature = '8c35009d3b50caf7f5d2c1e031842e6b7823a1bb781d33c5237cd27b57b5f327';

if (hash_equals(hash_hmac('sha256', $value, $secretKey), $signature)) {
    echo "The value is correctly signed.", PHP_EOL;
} else {
    echo "The value was tampered with.", PHP_EOL;
}
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
The value is correctly signed.
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Both arguments must be of the same length to be compared successfully.
    When arguments of differing length are supplied, &false; is returned immediately and
    the length of the known string may be leaked in case of a timing attack.
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>hash_hmac</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
-->