doc-es/reference/hash/functions/hash-equals.xml at master · php/doc-es · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 6ba84e3a5b33eb27bae2f6df337c9a4305d11106 Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: no -->

<refentry xml:id="function.hash-equals" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>hash_equals</refname>
  <refpurpose>Comparación de strings resistente a ataques temporales</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>hash_equals</methodname>
   <methodparam><modifier role="attribute">#[\SensitiveParameter]</modifier><type>string</type><parameter>known_string</parameter></methodparam>
   <methodparam><modifier role="attribute">#[\SensitiveParameter]</modifier><type>string</type><parameter>user_string</parameter></methodparam>
  </methodsynopsis>
  <para>
   Verifica si dos strings son iguales sin revelar información
   sobre el contenido de <parameter>known_string</parameter> mediante el tiempo de ejecución.
  </para>
  <para>
   Esta función puede ser utilizada para mitigar ataques temporales.
   La ejecución de una comparación regular con <code>===</code> tomará más
   o menos tiempo dependiendo de si las dos valores son diferentes o no y
   según la posición en la que la primera diferencia pueda ser encontrada,
   dejando así filtrar información sobre el contenido
   de la <parameter>known_string</parameter> secreta.
  </para>
  <caution>
   <para>
    Es importante pasar el string proporcionado por el usuario como segundo
    argumento en lugar del primero.
   </para>
  </caution>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <varlistentry>
    <term><parameter>known_string</parameter></term>
    <listitem>
     <para>
      El string conocido que debe ser mantenido en secreto.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>user_string</parameter></term>
    <listitem>
     <para>
      El string proporcionado por el usuario a comparar.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
    Retorna &true; si los dos strings son iguales, &false; en caso contrario.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example xml:id="foobar.examples.basic">
    <title>Ejemplo de<function>hash_equals</function></title>
    <programlisting role="php">
<![CDATA[
<?php
$secretKey = '8uRhAeH89naXfFXKGOEj';

// El valor y la firma son proporcionados por el usuario, p. ej. en la URL
// y recuperados mediante $_GET.
$value = 'username=rasmuslerdorf';
$signature = '8c35009d3b50caf7f5d2c1e031842e6b7823a1bb781d33c5237cd27b57b5f327';

if (hash_equals(hash_hmac('sha256', $value, $secretKey), $signature)) {
    echo "El valor está firmado correctamente.", PHP_EOL;
} else {
    echo "El valor ha sido manipulado.", PHP_EOL;
}
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
El valor está firmado correctamente.
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Ambos argumentos deben tener la misma longitud para ser comparados con éxito.
    Cuando se pasan argumentos de longitud diferente, &false; es retornado inmediatamente y
    la longitud del string conocido puede ser revelada en caso de ataque temporal.
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>hash_hmac</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
-->