mirror of
https://github.com/php/doc-es.git
synced 2026-04-26 08:38:05 +02:00
Pedro Antonio Gil Rodríguez
460afd45ca
git-svn-id: https://svn.php.net/repository/phpdoc/es/trunk@338254 c90b9560-bf6c-de11-be94-00142212c4b1
338 lines
11 KiB
XML
338 lines
11 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<!-- EN-Revision: a4706cc591a09215dc91f3bc94ee67489a9f0b84 Maintainer: seros Status: ready -->
|
|
<!-- Reviewed: no Maintainer: andresdzphp -->
|
|
|
|
<refentry xml:id="function.password-hash" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<refnamediv>
|
|
<refname>password_hash</refname>
|
|
<refpurpose>Crea un hash de contraseña</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1 role="description">
|
|
&reftitle.description;
|
|
<methodsynopsis>
|
|
<type>string</type><methodname>password_hash</methodname>
|
|
<methodparam><type>string</type><parameter>password</parameter></methodparam>
|
|
<methodparam><type>integer</type><parameter>algo</parameter></methodparam>
|
|
<methodparam choice="opt"><type>array</type><parameter>options</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>password_hash</function> crea un nuevo hash de contraseña usando un algoritmo de hash fuerte
|
|
de único sentido. <function>password_hash</function> es compatible con <function>crypt</function>.
|
|
Por lo tanto, los hash de contraseñas creados con <function>crypt</function> se pueden usar con
|
|
<function>password_hash</function>.
|
|
</para>
|
|
<simpara>
|
|
Actualmente se admiten los siguientes algoritmos:
|
|
</simpara>
|
|
<para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>
|
|
<constant>PASSWORD_DEFAULT</constant> - Usar el algoritmo bcrypt (predeterminado a partir de PHP 5.5.0).
|
|
Observe que esta constante está diseñada para cambiar siempre que se añada un algoritmo nuevo y más fuerte
|
|
a PHP. Por esta razón, la longitud del resultado de usar este identificador puede cambiar con el tiempo.
|
|
Por lo tanto, se recomienda almacenar el resultado en una columna de una base de datos que pueda
|
|
apliarse a más de 60 caracteres (255 caracteres sería una buena elección).
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<constant>PASSWORD_BCRYPT</constant> - Usar el algoritmo <constant>CRYPT_BLOWFISH</constant> para
|
|
crear el hash. Producirá un hash estándar compatible con <function>crypt</function> utilizando
|
|
el identificador "$2y$". El resultado siempre será un string de 60 caracteres, &return.falseforfailure;.
|
|
</simpara>
|
|
<para>
|
|
Opciones admitias:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<literal>salt</literal> - para proporcionar manualmente una sal a usar cuando se realiza el hash de la contraseña.
|
|
Observe que esto sobrescribirá y prevendrá que una sal sea generada automáticamente.
|
|
</para>
|
|
<para>
|
|
Si se omite, se generará una sal aleatoria mediante <function>password_hash</function> para
|
|
cada hash. Este es el modo de operación intencionado.
|
|
</para>
|
|
<warning>
|
|
<para>
|
|
La opción salt está obsoleta a partir de PHP 7.0.0. Ahora se
|
|
prefiere simplemente utilizar generada de manera predeterminada.
|
|
</para>
|
|
</warning>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>cost</literal> - denota el coste del algoritmo que debería usarse.
|
|
Se pueden encontrar ejemplo de estos valores en la página de <function>crypt</function>.
|
|
</para>
|
|
<para>
|
|
Si se omite, se usará el valor predeterminado <literal>10</literal>. Este es un buen
|
|
coste de referencia, pero se podría considerar aumentarlo dependiendo del hardware.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="parameters">
|
|
&reftitle.parameters;
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>password</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
&password.parameter.password;
|
|
</para>
|
|
<caution>
|
|
<para>
|
|
El uso de <constant>PASSWORD_BCRYPT</constant> como el
|
|
algoritmo resultará
|
|
en el truncamiento del parámetro <parameter>password</parameter> a
|
|
un máximo de 72 caracteres de longitud.
|
|
</para>
|
|
</caution>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>algo</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
&password.parameter.algo;
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>options</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
&password.parameter.options;
|
|
</para>
|
|
<para>
|
|
Si no se indica, se creará una sal aleatoria y el coste algorítmico por defecto será
|
|
utilizado.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1 role="returnvalues">
|
|
&reftitle.returnvalues;
|
|
<para>
|
|
Devuelve el hash de la contraseña, &return.falseforfailure;.
|
|
</para>
|
|
<para>
|
|
El algoritmo, coste y sal usados son devueltos como parte del hash. Por lo tanto,
|
|
toda la información que es necesaria para verificar el hash, está incluida en él. Esto permite
|
|
que la función <function>password_verify</function> verifique el hash sin tener
|
|
que almacenar por separado la información de la sal o del algoritmo.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<para>
|
|
<example>
|
|
<title>Ejemplo de <function>password_hash</function></title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
/**
|
|
* Queremos crear un hash de nuestra contraseña uando el algoritmo DEFAULT actual.
|
|
* Actualmente es BCRYPT, y producirá un resultado de 60 caracteres.
|
|
*
|
|
* Hay que tener en cuenta que DEFAULT puede cambiar con el tiempo, por lo que debería prepararse
|
|
* para permitir que el almacenamento se amplíe a más de 60 caracteres (255 estaría bien)
|
|
*/
|
|
echo password_hash("rasmuslerdorf", PASSWORD_DEFAULT)."\n";
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs.similar;
|
|
<screen>
|
|
<![CDATA[
|
|
$2y$10$.vGA1O9wmRjrwAVXD98HNOgsNpDczlqm3Jq7KnEd1rVAGv3Fykk1a
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Ejemplo de <function>password_hash</function> estableciendo el coste manualmente</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
/**
|
|
* En este caso, queremos aumentar el coste predeterminado de BCRYPT a 12.
|
|
* Observe que también cambiamos a BCRYPT, que tendrá siempre 60 caracteres.
|
|
*/
|
|
$opciones = [
|
|
'cost' => 12,
|
|
];
|
|
echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $opciones)."\n";
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs.similar;
|
|
<screen>
|
|
<![CDATA[
|
|
$2y$12$QjSH496pcT5CEbzjD/vtVeH03tfHKFy36d4J0Ltp3lRtee9HDxY3K
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
<example>
|
|
<title>Ejemplo de <function>password_hash</function> estableciendo la sal manualmente</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
/**
|
|
* Observe que la sal se genera aleatoriamente aquí.
|
|
* No use nunca una sal estática o una que no se genere aleatoriamente.
|
|
*
|
|
* Para la GRAN mayoría de los casos de uso, dejar que password_hash genere la sal aleatoriamente
|
|
*/
|
|
$opciones = [
|
|
'cost' => 11,
|
|
'salt' => mcrypt_create_iv(22, MCRYPT_DEV_URANDOM),
|
|
];
|
|
echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $opciones)."\n";
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs.similar;
|
|
<screen>
|
|
<![CDATA[
|
|
$2y$11$q5MkhSBtlsJcNEVsYh64a.aCluzHnGog7TQAKVmQwO9C8xb.t89F.
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Ejemplo de <function>password_hash</function> buscando un buen coste</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
/**
|
|
* Este código evaluará el servidor para determinar el coste permitido.
|
|
* Se establecerá el mayor coste posible sin disminuir demasiando la velocidad
|
|
* del servidor. 8-10 es una buena referencia, y más es bueno si los servidores
|
|
* son suficientemente rápidos. El código que sigue tiene como objetivo un tramo de
|
|
* ≤ 50 milisegundos, que es una buena referencia para sistemas con registros interactivos.
|
|
*/
|
|
$timeTarget = 0.05; // 50 milisegundos
|
|
|
|
$coste = 8;
|
|
do {
|
|
$coste++;
|
|
$inicio = microtime(true);
|
|
password_hash("test", PASSWORD_BCRYPT, ["cost" => $coste]);
|
|
$fin = microtime(true);
|
|
} while (($fin - $inicio) < $timeTarget);
|
|
|
|
echo "Coste apropiado encontrado: " . $coste . "\n";
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs.similar;
|
|
<screen>
|
|
<![CDATA[
|
|
Coste apropiado encontrado: 10
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="notes">
|
|
&reftitle.notes;
|
|
<caution>
|
|
<para>
|
|
Se recomienda encarecidamente que no se genere una sal propia para esta
|
|
función. Creará una sal segura automáticamente si no
|
|
se especifica una.
|
|
</para>
|
|
<para>
|
|
Como se ha observado arriba, proporcionar la opción <literal>salt</literal> en PHP 7.0
|
|
generará una advertencia de obsolescencia. El soporte para proporcionar una sal manualmente
|
|
podría ser eliminado en una versión futura de future.
|
|
</para>
|
|
</caution>
|
|
<note>
|
|
<para>
|
|
Se recomienda probar esta función en los servidores que se estén usando, y ajustar el parámetro de coste
|
|
para que la ejecución de la función tome menos de 100 milisegundos en sistemas interactivos.
|
|
El script en el ejemplo de antes le ayudará a elegir un buen valor de coste para su hardware.
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<simpara>
|
|
Las actualizaciones para los algoritmos admitidos por esta función (o los cambios al predeterminado)
|
|
deben serguir las siguientes reglas:
|
|
</simpara>
|
|
<para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>
|
|
Cualquier algoritmo nuevo debe estar en el núcleo por lo menos una versión completa de PHP
|
|
antes de convertirse en predeterminado. Por lo que si, por ejemplo, un nuevo algoritmo se añade
|
|
en la 7.5.5, no sería apto para ser el predeterminado hasta la 7.7 (ya que la 7.6
|
|
sería la primera versión completa). Pero si se añadió un algoritmo diferente
|
|
en la 7.6.0, también sería apto para ser el predeterminado en la 7.7.0.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
El predeterminado debería cambiar únicamente en una versión completa (7.3.0, 8.0.0, etc.)
|
|
y no en una versión de revisión. La única excepción es la emergencia de que se encuentre
|
|
un fallo de seguridad crítico en el predeterminado
|
|
actual.
|
|
</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</note>
|
|
</refsect1>
|
|
|
|
<refsect1 role="seealso">
|
|
&reftitle.seealso;
|
|
<para>
|
|
<simplelist>
|
|
<member><function>password_verify</function></member>
|
|
<member><function>crypt</function></member>
|
|
<member><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.password.compat;">implementación en el espacio de usuario</link></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
|
|
-->
|