1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
|
<?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
-->
|
