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

<!-- $Revision$ -->

<!-- EN-Revision: d76a7fe17dd2488e47d664a8ab38e161b13ac843 Maintainer: PhilDaiguille Status: ready -->

<!-- Reviewed: no -->

<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" xml:id="function.crypt">

<refnamediv>

<refname>crypt</refname>

<refpurpose>Hash de un solo sentido (indescifrable)</refpurpose>

</refnamediv>

<refsynopsisdiv>

&note.not-bin-safe;

</refsynopsisdiv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type>string</type><methodname>crypt</methodname>

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

<methodparam><type>string</type><parameter>salt</parameter></methodparam>

</methodsynopsis>

<para>

<function>crypt</function> devolverá una cadena con hash utilizando el algoritmo estándar de Unix basado en <abbrev>DES</abbrev>, o un algoritmo alternativo. La función <function>password_verify</function> es compatible con la función <function>crypt</function>. Así, una contraseña con hash de la función <function>crypt</function> puede ser utilizada con la función <function>password_verify</function>.

</para>

<para>

Anterior a PHP 8.0.0, el parámetro <parameter>salt</parameter> era opcional. Sin embargo, <function>crypt</function> crea un hash débil sin el <parameter>salt</parameter>, y genera un error <constant>E_NOTICE</constant> sin este. Asegúrese de especificar un salt lo suficientemente fuerte para una mejor seguridad.

</para>

<para>

<function>password_hash</function> utiliza un hash fuerte, genera un salt fuerte, y aplica todo automáticamente. <function>password_hash</function> es solo un gestor de <function>crypt</function> y es compatible con contraseñas con hash existentes. Se recomienda encarecidamente el uso de la función <function>password_hash</function>.

</para>

<para>

El tipo de hash es activado por el argumento <parameter>salt</parameter>. Si no se proporciona ningún <parameter>salt</parameter>, PHP generará dos caracteres (DES), a menos que el sistema predeterminado sea MD5, en cuyo caso se generará un <parameter>salt</parameter> compatible con MD5. PHP define una constante llamada <constant>CRYPT_SALT_LENGTH</constant> que permite conocer la longitud del <parameter>salt</parameter> disponible para el sistema de hash utilizado.

</para>

<para>

<function>crypt</function>, cuando se utiliza con el cifrado estándar DES, devuelve el <parameter>salt</parameter> en los dos primeros caracteres de la cadena devuelta. Solo utiliza los primeros 8 caracteres de <parameter>string</parameter>, lo que hace que todas las cadenas más largas, que tienen los mismos primeros 8 octetos, devuelvan el mismo resultado (siempre que el <parameter>salt</parameter> sea siempre el mismo).

</para>

<simpara>

Los siguientes tipos de hash son soportados:

</simpara>

<itemizedlist>

<listitem>

<simpara>

<constant>CRYPT_STD_DES</constant>: cifrado DES estándar de 2 caracteres desde la clase de caracteres "./0-9A-Za-z". El uso de caracteres inválidos en el salt hará fallar la función crypt().

</simpara>

</listitem>

<listitem>

<simpara>

<constant>CRYPT_EXT_DES</constant>: Hash DES extendido. El "salt" será una cadena de 9 caracteres compuesta de un guion bajo, seguido de 4 caracteres del contador de iteración y luego 4 caracteres del "salt". Cada una de estas cadenas de 4 caracteres codifica 24 bits, el carácter menos significativo primero. Los valores de <literal>0</literal> a <literal>63</literal> serán codificados como <literal>./0-9A-Za-z</literal>. El uso de caracteres inválidos en el salt hará fallar la función crypt().

</simpara>

</listitem>

<listitem>

<simpara>

<constant>CRYPT_MD5</constant>: hash MD5 de 12 caracteres que comienza con <literal>$1$</literal>

</simpara>

</listitem>

<listitem>

<simpara>

<constant>CRYPT_BLOWFISH</constant>: hash Blowfish cuyo salt está compuesto de la siguiente manera: "$2a$", "$2x$" o "$2y$", un parámetro de 2 dígitos, <literal>$</literal>, y 22 caracteres del alfabeto "./0-9A-Za-z". El uso de caracteres fuera de esta clase en el salt hará que la función crypt() devuelva una cadena vacía (de longitud 0). El parámetro de 2 dígitos es el logaritmo base-2 del contador de iteración para el algoritmo de hash basado en Blowfish subyacente y debe estar en el rango 04-31. De manera similar, si se utiliza un valor fuera de este rango, la función crypt() fallará.

Los hashes "$2x$" son potencialmente débiles; los hashes "$2a$" son compatibles y mitigan esta debilidad. Para nuevos hashes, "$2y$" debería ser utilizado.

</simpara>

</listitem>

<listitem>

<simpara>

<constant>CRYPT_SHA256</constant> - Hash SHA-256 cuyo salt está compuesto de 16 caracteres prefijados por <literal>$5$</literal>. Si el salt comienza con <literal>'rounds=&lt;N&gt;$'</literal>, el valor numérico de N será utilizado para indicar cuántas veces el bucle de hash debe ser ejecutado, algo similar al parámetro en el algoritmo Blowfish. El valor predeterminado de <literal>rounds</literal> es 5000, el mínimo puede ser 1000 y el máximo, 999,999,999. Cualquier otra selección de N fuera de este rango será truncada al límite más cercano de los 2.

</simpara>

</listitem>

<listitem>

<simpara>

<constant>CRYPT_SHA512</constant> - Hash SHA-512 cuyo salt está compuesto de 16 caracteres prefijados por <literal>$6$</literal>. Si el salt comienza con <literal>'rounds=&lt;N&gt;$'</literal>, el valor numérico de N será utilizado para indicar cuántas veces el bucle de hash debe ser ejecutado, algo similar al parámetro en el algoritmo Blowfish. El valor predeterminado de <literal>rounds</literal> es 5000, el mínimo puede ser 1000 y el máximo, 999,999,999. Cualquier otra selección de N fuera de este rango será truncada al límite más cercano de los 2.

</simpara>

</listitem>

</itemizedlist>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>string</parameter></term>

<listitem>

<para>

La cadena a hashear.

</para>

<caution>

<para>

Si se utiliza el algoritmo <constant>CRYPT_BLOWFISH</constant>, el resultado del parámetro <parameter>string</parameter> será truncado a una longitud máxima de 72 octetos.

</para>

</caution>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>salt</parameter></term>

<listitem>

<para>

Si el argumento <parameter>salt</parameter> no es proporcionado, el comportamiento está definido por la implementación del algoritmo y puede provocar resultados inesperados.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Devuelve la cadena con hash o una cadena que será inferior a 13 caracteres y que está garantizada para diferir del salt en caso de error.

</para>

<warning>

<simpara>

Al validar contraseñas, debe utilizarse una función de comparación de cadenas que no sea vulnerable a ataques temporales para comparar la salida de la función <function>crypt</function> con el hash conocido previamente. PHP proporciona <function>hash_equals</function> para esto.

</simpara>

</warning>

</refsect1>

<refsect1 role="changelog">

&reftitle.changelog;

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

<row>

<entry>8.0.0</entry>

<entry>

El <parameter>salt</parameter> ya no es opcional.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>Ejemplo con <function>crypt</function></title>

<programlisting role="php">

<![CDATA[

<?php

$user_input = 'rasmuslerdorf';

$hashed_password = '$6$rounds=1000000$NJy4rIPjpOaU$0ACEYGg/aKCY3v8O8AfyiO7CTfZQ8/W231Qfh2tRLmfdvFD6XfHk12u6hMr9cYIA4hnpjLNSTRtUwYr9km9Ij/';

// Validar un hash crypt() existente de una manera compatible con software no-PHP

if (hash_equals($hashed_password, crypt($user_input, $hashed_password))) {

echo "¡Contraseña correcta!";

}

?>

]]>

</programlisting>

</example>

</para>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

<note>

<simpara>

No existe una función de descifrado, ya que la función <function>crypt</function> utiliza un algoritmo de un solo sentido (inyección).

</simpara>

</note>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><function>hash_equals</function></member>

<member><function>password_hash</function></member>

<member>La página del manual Unix de la función crypt para más información</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

-->