Skip to content

Commit 29cecd7

Browse files
lacatoirelacatoire
authored
Add documentation for 2 new openssl functions (PHP 8.4) (#5352)
Add documentation pages for openssl functions available since PHP 8.4: - openssl_password_hash: Create a password hash using OpenSSL Argon2 - openssl_password_verify: Verify a password against a hash using OpenSSL Argon2
1 parent ac2b471 commit 29cecd7

2 files changed

Lines changed: 328 additions & 0 deletions

File tree

‎reference/openssl/functions/openssl-password-hash.xml‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<refentry xml:id="function.openssl-password-hash" xmlns="http://docbook.org/ns/docbook">
3+
<refnamediv>
4+
<refname>openssl_password_hash</refname>
5+
<refpurpose>Create a password hash using OpenSSL's Argon2 implementation</refpurpose>
6+
</refnamediv>
7+
8+
<refsect1 role="description">
9+
&reftitle.description;
10+
<methodsynopsis>
11+
<type>string</type><methodname>openssl_password_hash</methodname>
12+
<methodparam><type>string</type><parameter>algo</parameter></methodparam>
13+
<methodparam><type>string</type><parameter>password</parameter></methodparam>
14+
<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>
15+
</methodsynopsis>
16+
<para>
17+
Creates a password hash using OpenSSL's Argon2 implementation. This is an
18+
alternative to <function>password_hash</function> that uses OpenSSL as
19+
the backend, which may offer hardware acceleration on some platforms.
20+
</para>
21+
<para>
22+
This function is only available when PHP is compiled with OpenSSL
23+
support that includes Argon2 (<literal>HAVE_OPENSSL_ARGON2</literal>).
24+
</para>
25+
</refsect1>
26+
27+
<refsect1 role="parameters">
28+
&reftitle.parameters;
29+
<para>
30+
<variablelist>
31+
<varlistentry>
32+
<term><parameter>algo</parameter></term>
33+
<listitem>
34+
<para>
35+
The password hashing algorithm. Supported values:
36+
<literal>"argon2id"</literal> and <literal>"argon2i"</literal>.
37+
</para>
38+
</listitem>
39+
</varlistentry>
40+
<varlistentry>
41+
<term><parameter>password</parameter></term>
42+
<listitem>
43+
<para>
44+
The user's password.
45+
</para>
46+
</listitem>
47+
</varlistentry>
48+
<varlistentry>
49+
<term><parameter>options</parameter></term>
50+
<listitem>
51+
<para>
52+
An associative &array; of options. Supported keys:
53+
<simplelist>
54+
<member>
55+
<literal>memory_cost</literal> - Maximum memory (in KiB) that may
56+
be used to compute the hash
57+
</member>
58+
<member>
59+
<literal>time_cost</literal> - Maximum amount of time it may take
60+
to compute the hash
61+
</member>
62+
<member>
63+
<literal>threads</literal> - Number of threads to use for
64+
computing the hash
65+
</member>
66+
</simplelist>
67+
</para>
68+
</listitem>
69+
</varlistentry>
70+
</variablelist>
71+
</para>
72+
</refsect1>
73+
74+
<refsect1 role="returnvalues">
75+
&reftitle.returnvalues;
76+
<para>
77+
Returns the password hash as a &string;.
78+
</para>
79+
</refsect1>
80+
81+
<refsect1 role="errors">
82+
&reftitle.errors;
83+
<para>
84+
Throws a <classname>ValueError</classname> if <parameter>algo</parameter>
85+
is not one of the supported values
86+
(<literal>"argon2i"</literal> or <literal>"argon2id"</literal>).
87+
</para>
88+
<para>
89+
Throws an <classname>Error</classname> if the hashing operation fails
90+
for an unknown reason.
91+
</para>
92+
</refsect1>
93+
94+
<refsect1 role="changelog">
95+
&reftitle.changelog;
96+
<informaltable>
97+
<tgroup cols="2">
98+
<thead>
99+
<row>
100+
<entry>&Version;</entry>
101+
<entry>&Description;</entry>
102+
</row>
103+
</thead>
104+
<tbody>
105+
<row>
106+
<entry>8.4.0</entry>
107+
<entry>
108+
Function added.
109+
</entry>
110+
</row>
111+
</tbody>
112+
</tgroup>
113+
</informaltable>
114+
</refsect1>
115+
116+
<refsect1 role="examples">
117+
&reftitle.examples;
118+
<example>
119+
<title><function>openssl_password_hash</function> example</title>
120+
<programlisting role="php">
121+
<![CDATA[
122+
<?php
123+
$hash = openssl_password_hash('argon2id', 'my-secret-password');
124+
echo $hash;
125+
?>
126+
]]>
127+
</programlisting>
128+
&example.outputs.similar;
129+
<screen>
130+
<![CDATA[
131+
$argon2id$v=19$m=65536,t=4,p=1$c29tZXNhbHR2YWx1ZQ$hashvalue...
132+
]]>
133+
</screen>
134+
</example>
135+
<example>
136+
<title><function>openssl_password_hash</function> with custom options</title>
137+
<programlisting role="php">
138+
<![CDATA[
139+
<?php
140+
$hash = openssl_password_hash('argon2id', 'my-secret-password', [
141+
'memory_cost' => 65536,
142+
'time_cost' => 4,
143+
'threads' => 1,
144+
]);
145+
?>
146+
]]>
147+
</programlisting>
148+
</example>
149+
</refsect1>
150+
151+
<refsect1 role="seealso">
152+
&reftitle.seealso;
153+
<para>
154+
<simplelist>
155+
<member><function>openssl_password_verify</function></member>
156+
<member><function>password_hash</function></member>
157+
</simplelist>
158+
</para>
159+
</refsect1>
160+
161+
</refentry>
162+
<!-- Keep this comment at the end of the file
163+
Local variables:
164+
mode: sgml
165+
sgml-omittag:t
166+
sgml-shorttag:t
167+
sgml-minimize-attributes:nil
168+
sgml-always-quote-attributes:t
169+
sgml-indent-step:1
170+
sgml-indent-data:t
171+
indent-tabs-mode:nil
172+
sgml-parent-document:nil
173+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
174+
sgml-exposed-tags:nil
175+
sgml-local-catalogs:nil
176+
sgml-local-ecat-files:nil
177+
End:
178+
vim600: syn=xml fen fdm=syntax fdl=2 si
179+
vim: et tw=78 syn=sgml
180+
vi: ts=1 sw=1
181+
-->

‎reference/openssl/functions/openssl-password-verify.xml‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<refentry xml:id="function.openssl-password-verify" xmlns="http://docbook.org/ns/docbook">
3+
<refnamediv>
4+
<refname>openssl_password_verify</refname>
5+
<refpurpose>Verify a password against a hash using OpenSSL's Argon2 implementation</refpurpose>
6+
</refnamediv>
7+
8+
<refsect1 role="description">
9+
&reftitle.description;
10+
<methodsynopsis>
11+
<type>bool</type><methodname>openssl_password_verify</methodname>
12+
<methodparam><type>string</type><parameter>algo</parameter></methodparam>
13+
<methodparam><type>string</type><parameter>password</parameter></methodparam>
14+
<methodparam><type>string</type><parameter>hash</parameter></methodparam>
15+
</methodsynopsis>
16+
<para>
17+
Verifies that a password matches a hash created by
18+
<function>openssl_password_hash</function>.
19+
</para>
20+
<para>
21+
This function is only available when PHP is compiled with OpenSSL
22+
support that includes Argon2 (<literal>HAVE_OPENSSL_ARGON2</literal>).
23+
</para>
24+
</refsect1>
25+
26+
<refsect1 role="parameters">
27+
&reftitle.parameters;
28+
<para>
29+
<variablelist>
30+
<varlistentry>
31+
<term><parameter>algo</parameter></term>
32+
<listitem>
33+
<para>
34+
The password hashing algorithm. Supported values:
35+
<literal>"argon2id"</literal> and <literal>"argon2i"</literal>.
36+
</para>
37+
</listitem>
38+
</varlistentry>
39+
<varlistentry>
40+
<term><parameter>password</parameter></term>
41+
<listitem>
42+
<para>
43+
The user's password.
44+
</para>
45+
</listitem>
46+
</varlistentry>
47+
<varlistentry>
48+
<term><parameter>hash</parameter></term>
49+
<listitem>
50+
<para>
51+
A hash created by <function>openssl_password_hash</function>.
52+
</para>
53+
</listitem>
54+
</varlistentry>
55+
</variablelist>
56+
</para>
57+
</refsect1>
58+
59+
<refsect1 role="returnvalues">
60+
&reftitle.returnvalues;
61+
<para>
62+
Returns &true; if the password and hash match, or &false; otherwise.
63+
</para>
64+
</refsect1>
65+
66+
<refsect1 role="errors">
67+
&reftitle.errors;
68+
<para>
69+
Throws a <classname>ValueError</classname> if <parameter>algo</parameter>
70+
is not one of the supported values
71+
(<literal>"argon2i"</literal> or <literal>"argon2id"</literal>).
72+
</para>
73+
</refsect1>
74+
75+
<refsect1 role="changelog">
76+
&reftitle.changelog;
77+
<informaltable>
78+
<tgroup cols="2">
79+
<thead>
80+
<row>
81+
<entry>&Version;</entry>
82+
<entry>&Description;</entry>
83+
</row>
84+
</thead>
85+
<tbody>
86+
<row>
87+
<entry>8.4.0</entry>
88+
<entry>
89+
Function added.
90+
</entry>
91+
</row>
92+
</tbody>
93+
</tgroup>
94+
</informaltable>
95+
</refsect1>
96+
97+
<refsect1 role="examples">
98+
&reftitle.examples;
99+
<example>
100+
<title><function>openssl_password_verify</function> example</title>
101+
<programlisting role="php">
102+
<![CDATA[
103+
<?php
104+
$hash = openssl_password_hash('argon2id', 'my-secret-password');
105+
106+
if (openssl_password_verify('argon2id', 'my-secret-password', $hash)) {
107+
echo 'Password matches.';
108+
} else {
109+
echo 'Password does not match.';
110+
}
111+
?>
112+
]]>
113+
</programlisting>
114+
</example>
115+
</refsect1>
116+
117+
<refsect1 role="seealso">
118+
&reftitle.seealso;
119+
<para>
120+
<simplelist>
121+
<member><function>openssl_password_hash</function></member>
122+
<member><function>password_verify</function></member>
123+
</simplelist>
124+
</para>
125+
</refsect1>
126+
127+
</refentry>
128+
<!-- Keep this comment at the end of the file
129+
Local variables:
130+
mode: sgml
131+
sgml-omittag:t
132+
sgml-shorttag:t
133+
sgml-minimize-attributes:nil
134+
sgml-always-quote-attributes:t
135+
sgml-indent-step:1
136+
sgml-indent-data:t
137+
indent-tabs-mode:nil
138+
sgml-parent-document:nil
139+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
140+
sgml-exposed-tags:nil
141+
sgml-local-catalogs:nil
142+
sgml-local-ecat-files:nil
143+
End:
144+
vim600: syn=xml fen fdm=syntax fdl=2 si
145+
vim: et tw=78 syn=sgml
146+
vi: ts=1 sw=1
147+
-->

0 commit comments

Comments
 (0)