Skip to content

Commit 4fbc4be

Browse files
lacatoirelacatoire
authored
[Sync EN] Add documentation for 2 new openssl functions (PHP 8.4) (#2754)
Ajout des fichiers FR pour openssl_password_hash et openssl_password_verify (PHP 8.4, basees sur OpenSSL Argon2). Fixes #2753
1 parent f6f2491 commit 4fbc4be

2 files changed

Lines changed: 334 additions & 0 deletions

File tree

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

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- EN-Revision: 29cecd7f180bfdae00ebd6128b6dd4255eb30365 Maintainer: lacatoire Status: ready -->
3+
<!-- Reviewed: no -->
4+
<refentry xml:id="function.openssl-password-hash" xmlns="http://docbook.org/ns/docbook">
5+
<refnamediv>
6+
<refname>openssl_password_hash</refname>
7+
<refpurpose>Crée un hachage de mot de passe en utilisant l'implémentation Argon2 d'OpenSSL</refpurpose>
8+
</refnamediv>
9+
10+
<refsect1 role="description">
11+
&reftitle.description;
12+
<methodsynopsis>
13+
<type>string</type><methodname>openssl_password_hash</methodname>
14+
<methodparam><type>string</type><parameter>algo</parameter></methodparam>
15+
<methodparam><type>string</type><parameter>password</parameter></methodparam>
16+
<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>
17+
</methodsynopsis>
18+
<para>
19+
Crée un hachage de mot de passe en utilisant l'implémentation Argon2
20+
d'OpenSSL. Il s'agit d'une alternative à <function>password_hash</function>
21+
qui utilise OpenSSL comme moteur, ce qui peut offrir une accélération
22+
matérielle sur certaines plateformes.
23+
</para>
24+
<para>
25+
Cette fonction n'est disponible que lorsque PHP est compilé avec le
26+
support OpenSSL incluant Argon2 (<literal>HAVE_OPENSSL_ARGON2</literal>).
27+
</para>
28+
</refsect1>
29+
30+
<refsect1 role="parameters">
31+
&reftitle.parameters;
32+
<para>
33+
<variablelist>
34+
<varlistentry>
35+
<term><parameter>algo</parameter></term>
36+
<listitem>
37+
<para>
38+
L'algorithme de hachage du mot de passe. Valeurs supportées :
39+
<literal>"argon2id"</literal> et <literal>"argon2i"</literal>.
40+
</para>
41+
</listitem>
42+
</varlistentry>
43+
<varlistentry>
44+
<term><parameter>password</parameter></term>
45+
<listitem>
46+
<para>
47+
Le mot de passe de l'utilisateur.
48+
</para>
49+
</listitem>
50+
</varlistentry>
51+
<varlistentry>
52+
<term><parameter>options</parameter></term>
53+
<listitem>
54+
<para>
55+
Un &array; associatif d'options. Clés supportées :
56+
<simplelist>
57+
<member>
58+
<literal>memory_cost</literal> : mémoire maximale (en Kio) pouvant
59+
être utilisée pour calculer le hachage
60+
</member>
61+
<member>
62+
<literal>time_cost</literal> : temps maximal pouvant être pris pour
63+
calculer le hachage
64+
</member>
65+
<member>
66+
<literal>threads</literal> : nombre de threads à utiliser pour
67+
calculer le hachage
68+
</member>
69+
</simplelist>
70+
</para>
71+
</listitem>
72+
</varlistentry>
73+
</variablelist>
74+
</para>
75+
</refsect1>
76+
77+
<refsect1 role="returnvalues">
78+
&reftitle.returnvalues;
79+
<para>
80+
Retourne le hachage du mot de passe sous forme de &string;.
81+
</para>
82+
</refsect1>
83+
84+
<refsect1 role="errors">
85+
&reftitle.errors;
86+
<para>
87+
Lance une <classname>ValueError</classname> si <parameter>algo</parameter>
88+
n'est pas l'une des valeurs supportées
89+
(<literal>"argon2i"</literal> ou <literal>"argon2id"</literal>).
90+
</para>
91+
<para>
92+
Lance une <classname>Error</classname> si l'opération de hachage échoue
93+
pour une raison inconnue.
94+
</para>
95+
</refsect1>
96+
97+
<refsect1 role="changelog">
98+
&reftitle.changelog;
99+
<informaltable>
100+
<tgroup cols="2">
101+
<thead>
102+
<row>
103+
<entry>&Version;</entry>
104+
<entry>&Description;</entry>
105+
</row>
106+
</thead>
107+
<tbody>
108+
<row>
109+
<entry>8.4.0</entry>
110+
<entry>
111+
Ajout de la fonction.
112+
</entry>
113+
</row>
114+
</tbody>
115+
</tgroup>
116+
</informaltable>
117+
</refsect1>
118+
119+
<refsect1 role="examples">
120+
&reftitle.examples;
121+
<example>
122+
<title>Exemple avec <function>openssl_password_hash</function></title>
123+
<programlisting role="php">
124+
<![CDATA[
125+
<?php
126+
$hash = openssl_password_hash('argon2id', 'mon-mot-de-passe-secret');
127+
echo $hash;
128+
?>
129+
]]>
130+
</programlisting>
131+
&example.outputs.similar;
132+
<screen>
133+
<![CDATA[
134+
$argon2id$v=19$m=65536,t=4,p=1$c29tZXNhbHR2YWx1ZQ$hashvalue...
135+
]]>
136+
</screen>
137+
</example>
138+
<example>
139+
<title><function>openssl_password_hash</function> avec des options personnalisées</title>
140+
<programlisting role="php">
141+
<![CDATA[
142+
<?php
143+
$hash = openssl_password_hash('argon2id', 'mon-mot-de-passe-secret', [
144+
'memory_cost' => 65536,
145+
'time_cost' => 4,
146+
'threads' => 1,
147+
]);
148+
?>
149+
]]>
150+
</programlisting>
151+
</example>
152+
</refsect1>
153+
154+
<refsect1 role="seealso">
155+
&reftitle.seealso;
156+
<para>
157+
<simplelist>
158+
<member><function>openssl_password_verify</function></member>
159+
<member><function>password_hash</function></member>
160+
</simplelist>
161+
</para>
162+
</refsect1>
163+
164+
</refentry>
165+
<!-- Keep this comment at the end of the file
166+
Local variables:
167+
mode: sgml
168+
sgml-omittag:t
169+
sgml-shorttag:t
170+
sgml-minimize-attributes:nil
171+
sgml-always-quote-attributes:t
172+
sgml-indent-step:1
173+
sgml-indent-data:t
174+
indent-tabs-mode:nil
175+
sgml-parent-document:nil
176+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
177+
sgml-exposed-tags:nil
178+
sgml-local-catalogs:nil
179+
sgml-local-ecat-files:nil
180+
End:
181+
vim600: syn=xml fen fdm=syntax fdl=2 si
182+
vim: et tw=78 syn=sgml
183+
vi: ts=1 sw=1
184+
-->

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

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- EN-Revision: 29cecd7f180bfdae00ebd6128b6dd4255eb30365 Maintainer: lacatoire Status: ready -->
3+
<!-- Reviewed: no -->
4+
<refentry xml:id="function.openssl-password-verify" xmlns="http://docbook.org/ns/docbook">
5+
<refnamediv>
6+
<refname>openssl_password_verify</refname>
7+
<refpurpose>Vérifie un mot de passe par rapport à un hachage en utilisant l'implémentation Argon2 d'OpenSSL</refpurpose>
8+
</refnamediv>
9+
10+
<refsect1 role="description">
11+
&reftitle.description;
12+
<methodsynopsis>
13+
<type>bool</type><methodname>openssl_password_verify</methodname>
14+
<methodparam><type>string</type><parameter>algo</parameter></methodparam>
15+
<methodparam><type>string</type><parameter>password</parameter></methodparam>
16+
<methodparam><type>string</type><parameter>hash</parameter></methodparam>
17+
</methodsynopsis>
18+
<para>
19+
Vérifie qu'un mot de passe correspond à un hachage créé par
20+
<function>openssl_password_hash</function>.
21+
</para>
22+
<para>
23+
Cette fonction n'est disponible que lorsque PHP est compilé avec le
24+
support OpenSSL incluant Argon2 (<literal>HAVE_OPENSSL_ARGON2</literal>).
25+
</para>
26+
</refsect1>
27+
28+
<refsect1 role="parameters">
29+
&reftitle.parameters;
30+
<para>
31+
<variablelist>
32+
<varlistentry>
33+
<term><parameter>algo</parameter></term>
34+
<listitem>
35+
<para>
36+
L'algorithme de hachage du mot de passe. Valeurs supportées :
37+
<literal>"argon2id"</literal> et <literal>"argon2i"</literal>.
38+
</para>
39+
</listitem>
40+
</varlistentry>
41+
<varlistentry>
42+
<term><parameter>password</parameter></term>
43+
<listitem>
44+
<para>
45+
Le mot de passe de l'utilisateur.
46+
</para>
47+
</listitem>
48+
</varlistentry>
49+
<varlistentry>
50+
<term><parameter>hash</parameter></term>
51+
<listitem>
52+
<para>
53+
Un hachage créé par <function>openssl_password_hash</function>.
54+
</para>
55+
</listitem>
56+
</varlistentry>
57+
</variablelist>
58+
</para>
59+
</refsect1>
60+
61+
<refsect1 role="returnvalues">
62+
&reftitle.returnvalues;
63+
<para>
64+
Retourne &true; si le mot de passe et le hachage correspondent, ou &false;
65+
sinon.
66+
</para>
67+
</refsect1>
68+
69+
<refsect1 role="errors">
70+
&reftitle.errors;
71+
<para>
72+
Lance une <classname>ValueError</classname> si <parameter>algo</parameter>
73+
n'est pas l'une des valeurs supportées
74+
(<literal>"argon2i"</literal> ou <literal>"argon2id"</literal>).
75+
</para>
76+
</refsect1>
77+
78+
<refsect1 role="changelog">
79+
&reftitle.changelog;
80+
<informaltable>
81+
<tgroup cols="2">
82+
<thead>
83+
<row>
84+
<entry>&Version;</entry>
85+
<entry>&Description;</entry>
86+
</row>
87+
</thead>
88+
<tbody>
89+
<row>
90+
<entry>8.4.0</entry>
91+
<entry>
92+
Ajout de la fonction.
93+
</entry>
94+
</row>
95+
</tbody>
96+
</tgroup>
97+
</informaltable>
98+
</refsect1>
99+
100+
<refsect1 role="examples">
101+
&reftitle.examples;
102+
<example>
103+
<title>Exemple avec <function>openssl_password_verify</function></title>
104+
<programlisting role="php">
105+
<![CDATA[
106+
<?php
107+
$hash = openssl_password_hash('argon2id', 'mon-mot-de-passe-secret');
108+
109+
if (openssl_password_verify('argon2id', 'mon-mot-de-passe-secret', $hash)) {
110+
echo 'Le mot de passe correspond.';
111+
} else {
112+
echo 'Le mot de passe ne correspond pas.';
113+
}
114+
?>
115+
]]>
116+
</programlisting>
117+
</example>
118+
</refsect1>
119+
120+
<refsect1 role="seealso">
121+
&reftitle.seealso;
122+
<para>
123+
<simplelist>
124+
<member><function>openssl_password_hash</function></member>
125+
<member><function>password_verify</function></member>
126+
</simplelist>
127+
</para>
128+
</refsect1>
129+
130+
</refentry>
131+
<!-- Keep this comment at the end of the file
132+
Local variables:
133+
mode: sgml
134+
sgml-omittag:t
135+
sgml-shorttag:t
136+
sgml-minimize-attributes:nil
137+
sgml-always-quote-attributes:t
138+
sgml-indent-step:1
139+
sgml-indent-data:t
140+
indent-tabs-mode:nil
141+
sgml-parent-document:nil
142+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
143+
sgml-exposed-tags:nil
144+
sgml-local-catalogs:nil
145+
sgml-local-ecat-files:nil
146+
End:
147+
vim600: syn=xml fen fdm=syntax fdl=2 si
148+
vim: et tw=78 syn=sgml
149+
vi: ts=1 sw=1
150+
-->

0 commit comments

Comments
 (0)