Skip to content

[Sync EN] Add documentation for 2 new openssl functions (PHP 8.4) #2754

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lacatoire merged 1 commit into from
Apr 22, 2026
Merged

[Sync EN] Add documentation for 2 new openssl functions (PHP 8.4) #2754

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
184 changes: 184 additions & 0 deletions reference/openssl/functions/openssl-password-hash.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,184 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 29cecd7f180bfdae00ebd6128b6dd4255eb30365 Maintainer: lacatoire Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.openssl-password-hash" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>openssl_password_hash</refname>
<refpurpose>Crée un hachage de mot de passe en utilisant l'implémentation Argon2 d'OpenSSL</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>
Crée un hachage de mot de passe en utilisant l'implémentation Argon2
d'OpenSSL. Il s'agit d'une alternative à <function>password_hash</function>
qui utilise OpenSSL comme moteur, ce qui peut offrir une accélération
matérielle sur certaines plateformes.
</para>
<para>
Cette fonction n'est disponible que lorsque PHP est compilé avec le
support OpenSSL incluant Argon2 (<literal>HAVE_OPENSSL_ARGON2</literal>).
</para>
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>algo</parameter></term>
<listitem>
<para>
L'algorithme de hachage du mot de passe. Valeurs supportées :
<literal>"argon2id"</literal> et <literal>"argon2i"</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>password</parameter></term>
<listitem>
<para>
Le mot de passe de l'utilisateur.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>options</parameter></term>
<listitem>
<para>
Un &array; associatif d'options. Clés supportées :
<simplelist>
<member>
<literal>memory_cost</literal> : mémoire maximale (en Kio) pouvant
être utilisée pour calculer le hachage
</member>
<member>
<literal>time_cost</literal> : temps maximal pouvant être pris pour
calculer le hachage
</member>
<member>
<literal>threads</literal> : nombre de threads à utiliser pour
calculer le hachage
</member>
</simplelist>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Retourne le hachage du mot de passe sous forme de &string;.
</para>
</refsect1>

<refsect1 role="errors">
&reftitle.errors;
<para>
Lance une <classname>ValueError</classname> si <parameter>algo</parameter>
n'est pas l'une des valeurs supportées
(<literal>"argon2i"</literal> ou <literal>"argon2id"</literal>).
</para>
<para>
Lance une <classname>Error</classname> si l'opération de hachage échoue
pour une raison inconnue.
</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>
Ajout de la fonction.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<example>
<title>Exemple avec <function>openssl_password_hash</function></title>
<programlisting role="php">
<![CDATA[
<?php
$hash = openssl_password_hash('argon2id', 'mon-mot-de-passe-secret');
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> avec des options personnalisées</title>
<programlisting role="php">
<![CDATA[
<?php
$hash = openssl_password_hash('argon2id', 'mon-mot-de-passe-secret', [
'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
-->
150 changes: 150 additions & 0 deletions reference/openssl/functions/openssl-password-verify.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,150 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 29cecd7f180bfdae00ebd6128b6dd4255eb30365 Maintainer: lacatoire Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.openssl-password-verify" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>openssl_password_verify</refname>
<refpurpose>Vérifie un mot de passe par rapport à un hachage en utilisant l'implémentation Argon2 d'OpenSSL</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>
Vérifie qu'un mot de passe correspond à un hachage créé par
<function>openssl_password_hash</function>.
</para>
<para>
Cette fonction n'est disponible que lorsque PHP est compilé avec le
support OpenSSL incluant Argon2 (<literal>HAVE_OPENSSL_ARGON2</literal>).
</para>
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>algo</parameter></term>
<listitem>
<para>
L'algorithme de hachage du mot de passe. Valeurs supportées :
<literal>"argon2id"</literal> et <literal>"argon2i"</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>password</parameter></term>
<listitem>
<para>
Le mot de passe de l'utilisateur.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>hash</parameter></term>
<listitem>
<para>
Un hachage créé par <function>openssl_password_hash</function>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Retourne &true; si le mot de passe et le hachage correspondent, ou &false;
sinon.
</para>
</refsect1>

<refsect1 role="errors">
&reftitle.errors;
<para>
Lance une <classname>ValueError</classname> si <parameter>algo</parameter>
n'est pas l'une des valeurs supportées
(<literal>"argon2i"</literal> ou <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>
Ajout de la fonction.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<example>
<title>Exemple avec <function>openssl_password_verify</function></title>
<programlisting role="php">
<![CDATA[
<?php
$hash = openssl_password_hash('argon2id', 'mon-mot-de-passe-secret');

if (openssl_password_verify('argon2id', 'mon-mot-de-passe-secret', $hash)) {
echo 'Le mot de passe correspond.';
} else {
echo 'Le mot de passe ne correspond pas.';
}
?>
]]>
</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
-->
Loading