reference/hash/functions/hash-init.xml
fe4ff341037cab316f76ca414f9a1a8ecdc4abfd
...
...
@@ -11,8 +11,9 @@
11
11
<methodsynopsis>
12
12
<type>HashContext</type><methodname>hash_init</methodname>
13
13
<methodparam><type>string</type><parameter>algo</parameter></methodparam>
14
-
<methodparam choice="opt"><type>int</type><parameter>options</parameter><initializer>0</initializer></methodparam>
15
-
<methodparam choice="opt"><type>string</type><parameter>key</parameter><initializer>&null;</initializer></methodparam>
14
+
<methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>0</initializer></methodparam>
15
+
<methodparam choice="opt"><modifier role="attribute">#[\SensitiveParameter]</modifier><type>string</type><parameter>key</parameter><initializer>""</initializer></methodparam>
16
+
<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>
16
17
</methodsynopsis>
17
18

18
19
</refsect1>
...
...
@@ -24,12 +25,19 @@
24
25
<term><parameter>algo</parameter></term>
25
26
<listitem>
26
27
<para>
27
-
Name of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..). For a list of supported algorithms see <function>hash_algos</function>.
28
+
Name of selected hashing algorithm (e.g. <literal>"sha256"</literal>).
29
+
For a list of supported algorithms see <function>hash_algos</function>.
30
+
<note>
31
+
<para>
32
+
Non-cryptographic hash functions are not allowed if the <constant>HASH_HMAC</constant>
33
+
flag is specified.
34
+
</para>
35
+
</note>
28
36
</para>
29
37
</listitem>
30
38
</varlistentry>
31
39
<varlistentry>
32
-
<term><parameter>options</parameter></term>
40
+
<term><parameter>flags</parameter></term>
33
41
<listitem>
34
42
<para>
35
43
Optional settings for hash generation, currently supports only one option:
...
...
@@ -42,12 +50,22 @@
42
50
<term><parameter>key</parameter></term>
43
51
<listitem>
44
52
<para>
45
-
When <constant>HASH_HMAC</constant> is specified for <parameter>options</parameter>,
53
+
When <constant>HASH_HMAC</constant> is specified for <parameter>flags</parameter>,
46
54
a shared secret key to be used with the HMAC hashing method must be supplied in this
47
55
parameter.
48
56
</para>
49
57
</listitem>
50
58
</varlistentry>
59
+
<varlistentry>
60
+
<term><parameter>options</parameter></term>
61
+
<listitem>
62
+
<para>
63
+
An array of options for the various hashing algorithms.
64
+
Currently, only the <literal>"seed"</literal> parameter is
65
+
supported by the MurmurHash variants.
66
+
</para>
67
+
</listitem>
68
+
</varlistentry>
51
69
</variablelist>
52
70
</para>
53
71
</refsect1>
...
...
@@ -61,6 +79,29 @@
61
79
</para>
62
80
</refsect1>
63
81

82
+
<refsect1 role="errors">
83
+
&reftitle.errors;
84
+
<itemizedlist>
85
+
<listitem>
86
+
<simpara>
87
+
Throws a <classname>ValueError</classname> exception if
88
+
<parameter>algo</parameter> is unknown or is a non-cryptographic hash
89
+
function, or if <parameter>key</parameter> is empty.
90
+
</simpara>
91
+
</listitem>
92
+
<listitem>
93
+
<simpara>
94
+
Passing configurations options of the wrong type in
95
+
<parameter>options</parameter> will now emit an
96
+
<constant>E_DEPRECATED</constant> error because they can be interpreted
97
+
incorrectly.
98
+
This will become a <exceptionname>ValueError</exceptionname> in the
99
+
future.
100
+
</simpara>
101
+
</listitem>
102
+
</itemizedlist>
103
+
</refsect1>
104
+

64
105
<refsect1 role="changelog">
65
106
&reftitle.changelog;
66
107
<para>
...
...
@@ -73,6 +114,24 @@
73
114
</row>
74
115
</thead>
75
116
<tbody>
117
+
<row>
118
+
<entry>8.4.0</entry>
119
+
<entry>Passing options of a wrong type is now deprecated.</entry>
120
+
</row>
121
+
<row>
122
+
<entry>8.1.0</entry>
123
+
<entry>The <parameter>options</parameter> parameter has been added.</entry>
124
+
</row>
125
+
<row>
126
+
<entry>8.0.0</entry>
127
+
<entry>
128
+
Now throws an <classname>ValueError</classname> exception if the
129
+
<parameter>algo</parameter> is unknown or is a non-cryptographic hash
130
+
function, or if <parameter>key</parameter> is empty. Previously,
131
+
&false; was returned and an <constant>E_WARNING</constant> message was
132
+
emitted.
133
+
</entry>
134
+
</row>
76
135
<row>
77
136
<entry>7.2.0</entry>
78
137
<entry>Usage of non-cryptographic hash functions (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) with <constant>HASH_HMAC</constant> was disabled.</entry>
...
...
@@ -97,17 +156,23 @@
97
156
<programlisting role="php">
98
157
<![CDATA[
99
158
<?php
100
-
$ctx = hash_init('md5');
159
+
$hash = hash('sha256', 'The quick brown fox jumped over the lazy dog.');
160
+

161
+
$ctx = hash_init('sha256');
101
162
hash_update($ctx, 'The quick brown fox ');
102
163
hash_update($ctx, 'jumped over the lazy dog.');
103
-
echo hash_final($ctx);
164
+
$incremental_hash = hash_final($ctx);
165
+

166
+
echo $incremental_hash, PHP_EOL;
167
+
var_dump($hash === $incremental_hash);
104
168
?>
105
169
]]>
106
170
</programlisting>
107
171
&example.outputs;
108
172
<screen>
109
173
<![CDATA[
110
-
5c6ffbdd40d9556b73a21e63c3e0e904
174
+
68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483
175
+
bool(true)
111
176
]]>
112
177
</screen>
113
178
</example>
...
...
@@ -118,17 +183,16 @@ echo hash_final($ctx);
118
183
&reftitle.seealso;
119
184
<para>
120
185
<simplelist>
121
-
<member><function>hash</function></member>
122
186
<member><function>hash_algos</function></member>
123
-
<member><function>hash_file</function></member>
124
-
<member><function>hash_hmac</function></member>
125
-
<member><function>hash_hmac_file</function></member>
187
+
<member><function>hash_update</function></member>
188
+
<member><function>hash_update_file</function></member>
189
+
<member><function>hash_update_stream</function></member>
190
+
<member><function>hash_final</function></member>
126
191
</simplelist>
127
192
</para>
128
193
</refsect1>
129
194

130
195
</refentry>
131
-

132
196
<!-- Keep this comment at the end of the file
133
197
Local variables:
134
198
mode: sgml
135
199



Translation status