<?xml version="1.0" encoding="utf-8"?>

<!-- EN-Revision: 5003a6ea92eb50ac92121782eedfc5ad3fe9d061 Maintainer: PhilDaiguille Status: ready -->

<!-- Reviewed: no -->

<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 una clave de hash para una contraseña</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type>string</type><methodname>password_hash</methodname>

<methodparam><modifier role="attribute">#[\SensitiveParameter]</modifier><type>string</type><parameter>password</parameter></methodparam>

<methodparam><type class="union"><type>string</type><type>int</type><type>null</type></type><parameter>algo</parameter></methodparam>

<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>

</methodsynopsis>

<para>

La función <function>password_hash</function> crea un nuevo

hash utilizando un algoritmo de hash fuerte e irreversible.

</para>

<simpara>

Los siguientes algoritmos son actualmente soportados:

</simpara>

<para>

<itemizedlist>

<listitem>

<simpara>

<constant>PASSWORD_DEFAULT</constant> - Uso del algoritmo bcrypt (por omisión desde

PHP 5.5.0). Tenga en cuenta que esta constante está diseñada para cambiar con el tiempo, a medida

que se añaden algoritmos más recientes y fuertes a PHP. Por esta razón, la longitud del resultado

de este algoritmo puede cambiar con el tiempo, por lo que se recomienda almacenar el resultado en

una columna de la base de datos que pueda contener al menos 60 caracteres

(255 bytes puede ser una muy buena opción).

</simpara>

</listitem>

<listitem>

<simpara>

<constant>PASSWORD_BCRYPT</constant> - Uso del algoritmo bcrypt

para crear la clave de hash. Esto creará una clave de hash estándar <function>crypt</function>

utilizando el identificador <literal>$2y$</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

<constant>PASSWORD_ARGON2I</constant> - Utiliza el algoritmo de hash Argon2i para crear el hash.

Este algoritmo solo está disponible si PHP ha sido compilado con el soporte de Argon2

</simpara>

</listitem>

<listitem>

<simpara>

<constant>PASSWORD_ARGON2ID</constant> - Utiliza el algoritmo de hash Argon2id para crear el hash.

Este algoritmo solo está disponible si PHP ha sido compilado con el soporte de Argon2

</simpara>

</listitem>

</itemizedlist>

</para>

<simpara>

Opciones soportadas para <constant>PASSWORD_BCRYPT</constant>:

</simpara>

<para>

<itemizedlist>

<listitem>

<para>

<literal>salt</literal> (<type>string</type>) - para proporcionar manualmente un salt a utilizar durante el hash de

la contraseña. Tenga en cuenta que esta opción evitará la generación automática.

</para>

<para>

Si se omite, un salt aleatorio será generado por la función <function>password_hash</function>

para cada contraseña hash. Este es el modo de funcionamiento previsto.

</para>

<warning>

<para>

La opción Salt está obsoleta. Es preferible utilizar simplemente

el salt que se genera por omisión.

A partir de PHP 8.0.0, un salt proporcionado explícitamente es ignorado.

</para>

</warning>

</listitem>

<listitem>

<para>

<literal>cost</literal> (<type>int</type>) - determina el costo algorítmico que debe ser utilizado.

Ejemplos de estos valores pueden ser encontrados en la página de documentación

de la función <function>crypt</function>.

</para>

<para>

Si se omite, el valor por omisión <literal>12</literal> será utilizado. Este es un buen compromiso,

pero debe ser ajustado según el hardware utilizado.

</para>

</listitem>

</itemizedlist>

</para>

<simpara>

Opciones soportadas para <constant>PASSWORD_ARGON2I</constant> y <constant>PASSWORD_ARGON2ID</constant>:

</simpara>

<para>

<itemizedlist>

<listitem>

<para>

<literal>memory_cost</literal> (<type>int</type>) - Memoria máxima

(en kilobytes binarios) que puede ser utilizada para calcular el hash Argon2. Por

omisión a <constant>PASSWORD_ARGON2_DEFAULT_MEMORY_COST</constant>.

</para>

</listitem>

<listitem>

<para>

<literal>time_cost</literal> (<type>int</type>) - Duración máxima de

tiempo que puede tomar para calcular el hash Argon2. Por

omisión a <constant>PASSWORD_ARGON2_DEFAULT_TIME_COST</constant>.

</para>

</listitem>

<listitem>

<para>

<literal>threads</literal> (<type>int</type>) - Número de hilos a

utilizar para calcular el hash Argon2. Por omisión a <constant>PASSWORD_ARGON2_DEFAULT_THREADS</constant>.

</para>

<warning>

<para>

Solo disponible cuando PHP utiliza libargon2,

y no la implementación libsodium.

</para>

</warning>

</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 la constante <constant>PASSWORD_BCRYPT</constant>

para el algoritmo hará que el parámetro

<parameter>password</parameter> sea truncado a una longitud máxima de

72 bytes.

</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>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Retorna la contraseña hash.

</para>

<para>

El algoritmo utilizado, el costo y el salt están contenidos en el hash retornado.

También, toda la información útil para verificar este último está incluida.

Esto permite que la función <function>password_verify</function> verifique el

hash sin necesidad de almacenar por separado esta información.

</para>

</refsect1>

<refsect1 role="changelog">

&reftitle.changelog;

<para>

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

<row>

<entry>8.4.0</entry>

<entry>

El valor por omisión de la opción <literal>cost</literal> del

algoritmo <constant>PASSWORD_BCRYPT</constant> ha sido aumentado de

<literal>10</literal> a <literal>12</literal>.

</entry>

</row>

<row>

<entry>8.3.0</entry>

<entry>

<function>password_hash</function> ahora asocia la excepción

<exceptionname>Random\RandomException</exceptionname> subyacente a

<property>Exception::$previous</property> cuando una

<exceptionname>ValueError</exceptionname> es lanzada debido a un fallo

en la generación del salt.

</entry>

</row>

<row>

<entry>8.0.0</entry>

<entry>

<function>password_hash</function> ya no retorna &false; en caso de fallo, una

<classname>ValueError</classname> será lanzada si el algoritmo de hash de contraseña

no es válido, o una <classname>Error</classname> si el hash de contraseña falló por una razón desconocida.

</entry>

</row>

<row>

<entry>8.0.0</entry>

<entry>

<parameter>algo</parameter> ahora es nullable.

</entry>

</row>

<row>

<entry>7.4.0</entry>

<entry>

El parámetro <parameter>algo</parameter> ahora espera una &string;, pero

sigue aceptando un &integer; para mantener la compatibilidad hacia atrás.

</entry>

</row>

<row>

<entry>7.4.0</entry>

<entry>

La extensión sodium proporciona una implementación alternativa para las

contraseñas Argon2.

</entry>

</row>

<row>

<entry>7.3.0</entry>

<entry>

Añadido el soporte para contraseñas Argon2id utilizando <constant>PASSWORD_ARGON2ID</constant>.

</entry>

</row>

<row>

<entry>7.2.0</entry>

<entry>

Añadido el soporte para contraseñas Argon2i utilizando <constant>PASSWORD_ARGON2I</constant>.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>Ejemplo con <function>password_hash</function></title>

<programlisting role="php">

<![CDATA[

<?php

echo password_hash("rasmuslerdorf", PASSWORD_DEFAULT);

?>

]]>

</programlisting>

&example.outputs.similar;

<screen>

<![CDATA[

$2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.

]]>

</screen>

</example>

</para>

<para>

<example>

<title>Ejemplo con <function>password_hash</function> definiendo manualmente la opción cost</title>

<programlisting role="php">

<![CDATA[

<?php

$options = [

// Aumenta el costo de bcrypt de 12 a 13.

'cost' => 13,

];

echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options);

?>

]]>

</programlisting>

&example.outputs.similar;

<screen>

<![CDATA[

$2y$13$xeDfQumlmdm0Sco.4qmH1OGfUUmOcuRmfae0dPJhjX1Bq0yYhqbNi

]]>

</screen>

</example>

</para>

<para>

<example>

<title>Ejemplo con <function>password_hash</function> para encontrar un buen costo (cost)</title>

<simpara>

Este código realizará un benchmark de la máquina para determinar el costo máximo

que puede ser utilizado sin degradar la experiencia del usuario. Se recomienda

elegir el costo más alto posible sin ralentizar otras operaciones

que la máquina debe ejecutar. 11 es una buena base, y un valor más

alto es preferible si la máquina es suficientemente rápida. El código de abajo

apunta a un tiempo de estiramiento ≤ 350 milisegundos, lo cual representa un retraso adecuado

para sistemas que manejan conexiones interactivas.

</simpara>

<programlisting role="php">

<![CDATA[

<?php

$timeTarget = 0.350; // 350 milisegundos

$cost = 11;

do {

$cost++;

$start = microtime(true);

password_hash("test", PASSWORD_BCRYPT, ["cost" => $cost]);

$end = microtime(true);

} while (($end - $start) < $timeTarget);

echo "Valor de 'cost' más apropiado: " . $cost - 1;

?>

]]>

</programlisting>

&example.outputs.similar;

<screen>

<![CDATA[

Valor de 'cost' más apropiado: 13

]]>

</screen>

</example>

</para>

<para>

<example>

<title>Ejemplo con <function>password_hash</function> y Argon2i</title>

<programlisting role="php">

<![CDATA[

<?php

echo 'Argon2i hash: ' . password_hash('rasmuslerdorf', PASSWORD_ARGON2I);

?>

]]>

</programlisting>

&example.outputs.similar;

<screen>

<![CDATA[

Argon2i hash: $argon2i$v=19$m=1024,t=2,p=2$YzJBSzV4TUhkMzc3d3laeg$zqU/1IN0/AogfP4cmSJI1vc8lpXRW9/S0sYY2i2jHT0

]]>

</screen>

</example>

</para>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

<caution>

<para>

Se recomienda encarecidamente no proporcionar un salt explícito para esta función.

Un salt seguro será generado automáticamente si no se especifica ningún salt.

</para>

<para>

Como se mencionó anteriormente, el uso de la opción <literal>salt</literal> a partir de PHP 7.0.0

generará una advertencia de deprecación. El soporte para un salt explícito fue eliminado

a partir de PHP 8.0.0.

</para>

</caution>

<note>

<para>

Se recomienda probar esta función en la máquina utilizada y ajustar el/los parámetro(s)

de costo para que la ejecución de la función tome menos de 350 milisegundos para conexiones

interactivas. El script del ejemplo anterior ayudará a elegir un costo bcrypt adecuado para la máquina dada.

</para>

</note>

<note>

<simpara>

La actualización de los algoritmos soportados por esta función (o el cambio al por omisión) debe seguir las siguientes reglas:

</simpara>

<para>

<itemizedlist>

<listitem>

<simpara>

Cada nuevo algoritmo debe formar parte del núcleo de PHP durante al menos 1 versión completa

antes de aspirar a convertirse en el algoritmo por omisión. También, si, por ejemplo, un nuevo

algoritmo es añadido en la versión 7.5.5, no será elegible como algoritmo por omisión hasta

PHP 7.7 (sabiendo que 7.6 será la primera versión completa). Pero si un algoritmo diferente ha sido

añadido en 7.6.0, también será elegible como algoritmo por omisión

a partir de la versión 7.7.0.

</simpara>

</listitem>

<listitem>

<simpara>

El algoritmo por omisión solo puede ser cambiado durante una versión completa (7.3.0, 8.0.0, etc...)

y no durante una versión de revisión. La única excepción a este principio básico sería una

emergencia, por ejemplo, al descubrir un bug crítico de seguridad

en el algoritmo por omisión.

</simpara>

</listitem>

</itemizedlist>

</para>

</note>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><function>password_verify</function></member>

<member><function>password_needs_rehash</function></member>

<member><function>crypt</function></member>

<member><function>sodium_crypto_pwhash_str</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

-->