[DOC-CVS] [doc-en] master: Add documentation for 2 new openssl functions (PHP 8.4) (#5352)
[email protected] (Louis-Arnaud via GitHub) Wed, 22 Apr 2026 11:59:02 +0000
| Newsgroups | php.doc.cvs |
|---|---|
| Message-ID | <[email protected]> |
Author: Louis-Arnaud (lacatoire)
Committer: GitHub (web-flow)
Pusher: cweiske
Date: 2026-04-22T13:58:59+02:00
Commit: https://github.com/php/doc-en/commit/29cecd7f180bfdae00ebd6128b6dd4255eb30365
Raw diff: https://github.com/php/doc-en/commit/29cecd7f180bfdae00ebd6128b6dd4255eb30365.diff
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
Changed paths:
A reference/openssl/functions/openssl-password-hash.xml
A reference/openssl/functions/openssl-password-verify.xml
Diff:
diff --git a/reference/openssl/functions/openssl-password-hash.xml b/reference/openssl/functions/openssl-password-hash.xml
new file mode 100644
index 000000000000..652044de6d40
--- /dev/null
+++ b/reference/openssl/functions/openssl-password-hash.xml
@@ -0,0 +1,181 @@
+<?xml version="1.0" encoding="utf-8"?>
+<refentry xml:id="function.openssl-password-hash" xmlns="http://docbook.org/ns/docbook">
+ <refnamediv>
+ <refname>openssl_password_hash</refname>
+ <refpurpose>Create a password hash using OpenSSL's Argon2 implementation</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+ &reftitle.description;
+ <methodsynopsis>
+ <type>string</type><methodname>openssl_password_hash</methodname>
+ <methodparam><type>string</type><parameter>algo</parameter></methodparam>
+ <methodparam><type>string</type><parameter>password</parameter></methodparam>
+ <methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>
+ </methodsynopsis>
+ <para>
+ Creates a password hash using OpenSSL's Argon2 implementation. This is an
+ alternative to <function>password_hash</function> that uses OpenSSL as
+ the backend, which may offer hardware acceleration on some platforms.
+ </para>
+ <para>
+ This function is only available when PHP is compiled with OpenSSL
+ support that includes Argon2 (<literal>HAVE_OPENSSL_ARGON2</literal>).
+ </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>algo</parameter></term>
+ <listitem>
+ <para>
+ The password hashing algorithm. Supported values:
+ <literal>"argon2id"</literal> and <literal>"argon2i"</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>password</parameter></term>
+ <listitem>
+ <para>
+ The user's password.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>options</parameter></term>
+ <listitem>
+ <para>
+ An associative &array; of options. Supported keys:
+ <simplelist>
+ <member>
+ <literal>memory_cost</literal> - Maximum memory (in KiB) that may
+ be used to compute the hash
+ </member>
+ <member>
+ <literal>time_cost</literal> - Maximum amount of time it may take
+ to compute the hash
+ </member>
+ <member>
+ <literal>threads</literal> - Number of threads to use for
+ computing the hash
+ </member>
+ </simplelist>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ Returns the password hash as a &string;.
+ </para>
+ </refsect1>
+
+ <refsect1 role="errors">
+ &reftitle.errors;
+ <para>
+ Throws a <classname>ValueError</classname> if <parameter>algo</parameter>
+ is not one of the supported values
+ (<literal>"argon2i"</literal> or <literal>"argon2id"</literal>).
+ </para>
+ <para>
+ Throws an <classname>Error</classname> if the hashing operation fails
+ for an unknown reason.
+ </para>
+ </refsect1>
+
+ <refsect1 role="changelog">
+ &reftitle.changelog;
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>&Version;</entry>
+ <entry>&Description;</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>8.4.0</entry>
+ <entry>
+ Function added.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title><function>openssl_password_hash</function> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$hash = openssl_password_hash('argon2id', 'my-secret-password');
+echo $hash;
+?>
+]]>
+ </programlisting>
+ &example.outputs.similar;
+ <screen>
+<![CDATA[
+$argon2id$v=19$m=65536,t=4,p=1$c29tZXNhbHR2YWx1ZQ$hashvalue...
+]]>
+ </screen>
+ </example>
+ <example>
+ <title><function>openssl_password_hash</function> with custom options</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$hash = openssl_password_hash('argon2id', 'my-secret-password', [
+ 'memory_cost' => 65536,
+ 'time_cost' => 4,
+ 'threads' => 1,
+]);
+?>
+]]>
+ </programlisting>
+ </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <para>
+ <simplelist>
+ <member><function>openssl_password_verify</function></member>
+ <member><function>password_hash</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
+-->
diff --git a/reference/openssl/functions/openssl-password-verify.xml b/reference/openssl/functions/openssl-password-verify.xml
new file mode 100644
index 000000000000..d44a41e22dd7
--- /dev/null
+++ b/reference/openssl/functions/openssl-password-verify.xml
@@ -0,0 +1,147 @@
+<?xml version="1.0" encoding="utf-8"?>
+<refentry xml:id="function.openssl-password-verify" xmlns="http://docbook.org/ns/docbook">
+ <refnamediv>
+ <refname>openssl_password_verify</refname>
+ <refpurpose>Verify a password against a hash using OpenSSL's Argon2 implementation</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+ &reftitle.description;
+ <methodsynopsis>
+ <type>bool</type><methodname>openssl_password_verify</methodname>
+ <methodparam><type>string</type><parameter>algo</parameter></methodparam>
+ <methodparam><type>string</type><parameter>password</parameter></methodparam>
+ <methodparam><type>string</type><parameter>hash</parameter></methodparam>
+ </methodsynopsis>
+ <para>
+ Verifies that a password matches a hash created by
+ <function>openssl_password_hash</function>.
+ </para>
+ <para>
+ This function is only available when PHP is compiled with OpenSSL
+ support that includes Argon2 (<literal>HAVE_OPENSSL_ARGON2</literal>).
+ </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>algo</parameter></term>
+ <listitem>
+ <para>
+ The password hashing algorithm. Supported values:
+ <literal>"argon2id"</literal> and <literal>"argon2i"</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>password</parameter></term>
+ <listitem>
+ <para>
+ The user's password.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>hash</parameter></term>
+ <listitem>
+ <para>
+ A hash created by <function>openssl_password_hash</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ Returns &true; if the password and hash match, or &false; otherwise.
+ </para>
+ </refsect1>
+
+ <refsect1 role="errors">
+ &reftitle.errors;
+ <para>
+ Throws a <classname>ValueError</classname> if <parameter>algo</parameter>
+ is not one of the supported values
+ (<literal>"argon2i"</literal> or <literal>"argon2id"</literal>).
+ </para>
+ </refsect1>
+
+ <refsect1 role="changelog">
+ &reftitle.changelog;
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>&Version;</entry>
+ <entry>&Description;</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>8.4.0</entry>
+ <entry>
+ Function added.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title><function>openssl_password_verify</function> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$hash = openssl_password_hash('argon2id', 'my-secret-password');
+
+if (openssl_password_verify('argon2id', 'my-secret-password', $hash)) {
+ echo 'Password matches.';
+} else {
+ echo 'Password does not match.';
+}
+?>
+]]>
+ </programlisting>
+ </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <para>
+ <simplelist>
+ <member><function>openssl_password_hash</function></member>
+ <member><function>password_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
+-->