hash_pbkdf2

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

hash_pbkdf2 — Genera una derivación de clave PBKDF2 de una contraseña proporcionada

Descripción

hash_pbkdf2(
    string $algo,
    string $password,
    string $salt,
    int $iterations,
    int $length = 0,
    bool $raw_output = false
): string

Parámetros

algo

El nombre del algoritmo hash seleccionado (esto es, "md5", "sha256", "haval160,4", etc.). Véase hash_algos() para una lista de los algoritmos admitidos.

password

La contraseña a usar para la derivación.

salt

La sal a usar para la derivación. Este valor debería ser generado aleatoriamente.

iterations

El número de iteraciones internas para realizar la derivación.

length

La longitud del string de salida. Si raw_output es true, se corresponde con la longitud en bytes de la clave derivada; si raw_output es false, se corresponde con dos veces la longitud en bytes de la clave derivada (ya que cada byte de la clave es devuelto como dos dígitos hexadecimales).

Si se pasa 0, se usará la salida completa del algoritmo proporcionado.

raw_output

Cuando se establece a true, genera datos binarios puros. false genera dígitos hexadecimales en minúsculas.

Valores devueltos

Devuelve un string que contiene la clave derivada como dígitos hexadecimales en minúsculas, a menos que raw_output sea establecido a true, en cuyo caso devuelve la represetación binaria pura de la clave derivada.

Errores/Excepciones

Se emitirá un E_WARNING si el algoritmo es desconocido, el parámetro iterations es menor o igual a 0, el parámetro length es menor que 0 o el parámetro salt es demasiado grande (mayor que INT_MAX - 4).

Ejemplos

Ejemplo #1 Ejemplo de uso básico de hash_pbkdf2()

<?php
$contraseña = "password";
$iteraciones = 1000;

// Generar una IV aleatoria usando mcrypt_create_iv(),
// openssl_random_pseudo_bytes() u otra fuente disponible de aleatoriedad
$sal = mcrypt_create_iv(16, MCRYPT_DEV_URANDOM);

$hash = hash_pbkdf2("sha256", $contraseña, $sal, $iteraciones, 20);
echo $hash;
?>

El resultado del ejemplo sería algo similar a:

120fb6cffcf8b32c43e7

Notas

Precaución

El método PBKDF2 se puede usar para el almacenamiento de contraseñas de hash. Sin embargo, se debería observar que password_hash() o crypt() con CRYPT_BLOWFISH son más adecuados para el almacenamiento de contraseñas.

Ver también

crypt() - Hash de cadenas de un sólo sentido
password_hash() - Crea un hash de contraseña
hash() - Generar un valor hash (resumen de mensaje)
hash_algos() - Devuelve una lista con los algoritmos de cifrado soportados
hash_init() - Iniciar un contexto de hashing incremental
hash_hmac() - Genera un valor cifrado mediante una clave especificada usando el método HMAC
hash_hmac_file() - Genera un valor cifrado mediante una clave especificada usando el método HMAC y el contenido de un fichero dado

Improve This Page

Learn How To Improve This Page • Submit a Pull Request • Report a Bug

＋add a note

User Contributed Notes 12 notes

down

clarence.pchy(at)gmail.com ¶

8 years ago

Please pay great attention to the **$length** parameter! It is exactly the **return string length**, NOT the length of raw binary hash result.

I had a big problem about this -- 
I thought that `hash_pbkdf2(...false)` should equals to `bin2hex(hash_pbkdf2(...true))` just like `md5($x)` equals `bin2hex(md5($x, true))`. However I was wrong:

hash_pbkdf2('sha256', '123456', 'abc', 10000, 50, false); // returns string(50) "584bc5b41005169f1fa15177edb78d75f9846afc466a4bae05"
hash_pbkdf2('sha256', '123456', 'abc', 10000, 50, true); // returns string(50) "XKŴ��Qw�u��j�FjK���BFW�YpG    �mp.g2�`;N�"
bin2hex(hash_pbkdf2('sha256', '123456', 'abc', 10000, 50, true)); // returns string(100) "584bc5b41005169f1fa15177edb78d75f9846afc466a4bae05119c82424657c81b5970471f098a6d702e6732b7603b194efe"

So I add such a note. Hope it will help someone else like me.

down

php . ober-mail . de ¶

3 years ago

If you are wondering what the requirements are for the salt, have a look at the RFC[1]:

"The salt parameter should be a random string containing at least 64 bits of entropy. That means when generated from a function like *mcrypt_create_iv*, at least 8 bytes long. But for salts that consist of only *a-zA-Z0-9* (or are base_64 encoded), the minimum length should be at least 11 characters. It should be generated random for each password that's hashed, and stored along side the generated key."

[1] https://wiki.php.net/rfc/hash_pbkdf2

down

does dot not at matter dot org ¶

11 years ago

this snippet was posted over a year ago on a dutch PHP community: (reference/source: http://www.phphulp.nl/php/script/beveiliging/pbkdf2-een-veilige-manier-om-wachtwoorden-op-te-slaan/1956/pbkdf2php/1757/)

<?php

/**
 * @author Chris Horeweg
 * @package Security_Tools
 */

function pbkdf2($password, $salt, $algorithm = 'sha512', $count = 20000, $key_length = 128, $raw_output = false)
{
    if(!in_array($algorithm, hash_algos(), true)) {
        exit('pbkdf2: Hash algoritme is niet geinstalleerd op het systeem.');
    }
    
    if($count <= 0 || $key_length <= 0) {
        $count = 20000;
        $key_length = 128;
    }

    $hash_length = strlen(hash($algorithm, "", true));
    $block_count = ceil($key_length / $hash_length);

    $output = "";
    for($i = 1; $i <= $block_count; $i++) {
        $last = $salt . pack("N", $i);
        $last = $xorsum = hash_hmac($algorithm, $last, $password, true);
        for ($j = 1; $j < $count; $j++) {
            $xorsum ^= ($last = hash_hmac($algorithm, $last, $password, true));
        }
        $output .= $xorsum;
    }

    if($raw_output) {
        return substr($output, 0, $key_length);
    }
    else {
        return base64_encode(substr($output, 0, $key_length));
    }
}

down

Trevor Herselman ¶

9 years ago

This is a light-weight drop-in replacement for PHP's hash_pbkdf2(); written for compatibility with older versions of PHP.
Written, formatted and tested by myself, but using code and ideas based on the following:
https://defuse.ca/php-pbkdf2.htm
https://github.com/rchouinard/hash_pbkdf2-compat/blob/master/src/hash_pbkdf2.php
https://gist.github.com/rsky/5104756

My main goals:
1) Maximum compatibility with PHP hash_pbkdf2(), ie. a drop-in replacement function
2) Minimum code size/bloat
3) Easy to copy/paste
4) No classes, and not encapsulated in a class! Why write a class when a simple function will do?
5) Eliminate calls to sprintf(). (used by other examples for the error reporting)
6) No other dependencies, ie. extra required functions

<?php
if (!function_exists('hash_pbkdf2'))
{
    function hash_pbkdf2($algo, $password, $salt, $count, $length = 0, $raw_output = false)
    {
        if (!in_array(strtolower($algo), hash_algos())) trigger_error(__FUNCTION__ . '(): Unknown hashing algorithm: ' . $algo, E_USER_WARNING);
        if (!is_numeric($count)) trigger_error(__FUNCTION__ . '(): expects parameter 4 to be long, ' . gettype($count) . ' given', E_USER_WARNING);
        if (!is_numeric($length)) trigger_error(__FUNCTION__ . '(): expects parameter 5 to be long, ' . gettype($length) . ' given', E_USER_WARNING);
        if ($count <= 0) trigger_error(__FUNCTION__ . '(): Iterations must be a positive integer: ' . $count, E_USER_WARNING);
        if ($length < 0) trigger_error(__FUNCTION__ . '(): Length must be greater than or equal to 0: ' . $length, E_USER_WARNING);

        $output = '';
        $block_count = $length ? ceil($length / strlen(hash($algo, '', $raw_output))) : 1;
        for ($i = 1; $i <= $block_count; $i++)
        {
            $last = $xorsum = hash_hmac($algo, $salt . pack('N', $i), $password, true);
            for ($j = 1; $j < $count; $j++)
            {
                $xorsum ^= ($last = hash_hmac($algo, $last, $password, true));
            }
            $output .= $xorsum;
        }

        if (!$raw_output) $output = bin2hex($output);
        return $length ? substr($output, 0, $length) : $output;
    }
}

down

Anonymous ¶

11 years ago

Sadly this function was added in PHP 5.5 but many webservers just provide PHP 5.3. But there exists a pure PHP implementation (found here: https://defuse.ca/php-pbkdf2.htm).
I took this implementation, put it into a class with comments for PHPDoc and added a switch so that the native PHP function is used if available.

Feel free to use it!
http://pastebin.com/f5PDq735
(Posted on pastebin.com since the text would have been too long)

down

Yahe ¶

5 years ago

On an error hash_pbkdf2() will not just raise an E_WARNING but it will also return FALSE.

down

nimasdj [AT] yahoo [DOT] com ¶

8 years ago

There is a mistake in the class provided by Binod Kumar Luitel (http://php.net/manual/en/function.hash-pbkdf2.php#113488):
this line:
return bin2hex(substr($this->output, 0, $this->key_length));
must be changed to:
return substr(bin2hex($this->output), 0, $this->key_length);

down

Flimm ¶

6 years ago

Note that if $raw_output is false, then the output will be encoded using lowercase hexits. Some other systems (such as Django 2.0) use base64 instead. So if you're trying to generate hash strings that are compatible with those systems, you can use the base64_encode function, like this:

<?php

echo base64_encode( hash_pbkdf2( "sha256", "example password", "BbirbJq1C1G7", 100000, 0, true ) );

?>

down

gfilippakis at sleed dot gr ¶

5 years ago

This is a very basic implementation of Rfc2898DeriveBytes class with only 2 of its constructors in case someone else finds it useful.

class Rfc2898DeriveBytes
{
    private $textToHash;
    private $saltByteSize;
    
    public $salt;
    
    public function __construct($arg1, $arg2)
    {
        if (is_string($arg1) && is_integer($arg2)) {
            $this->textToHash = $arg1;
            $this->saltByteSize = $arg2;
            $this->salt = substr(
                hex2bin(sha1(uniqid('', true))),
                0,
                $this->saltByteSize
            );
        } elseif (is_string($arg1) && is_string($arg2)) {
            $this->textToHash = $arg1;
            $this->salt = $arg2;
        }
    }
    
    public function getBytes($size)
    {
        return hash_pbkdf2(
            "sha1",
            $this->textToHash,
            $this->salt,
            1000,
            $size,
            true
        );
    }
}

down

-1

Binod Kumar Luitel ¶

11 years ago

People who wants pure PHP implementation of the function, i.e. who don't have PHP 5.5 installed within their server, can use the following implementation. Nothing has been modified so far as from reference https://defuse.ca/php-pbkdf2.htm but the OOP lovers might like this.
For more information about PBKDF2 see: http://en.wikipedia.org/wiki/PBKDF2

<?php
/**
 * PBKDF2 key derivation function as defined by RSA's PKCS #5: https://www.ietf.org/rfc/rfc2898.txt
 * $algorithm - The hash algorithm to use. Recommended: SHA256
 * $password - The password.
 * $salt - A salt that is unique to the password.
 * $count - Iteration count. Higher is better, but slower. Recommended: At least 1000.
 * $key_length - The length of the derived key in bytes.
 * $raw_output - If true, the key is returned in raw binary format. Hex encoded otherwise.
 * Returns: A $key_length-byte key derived from the password and salt.
 */
if (!function_exists("hash_pbkdf2")) {
    function hash_pbkdf2($algorithm, $password, $salt, $count, $key_length, $raw_output = false) {

        class pbkdf2 {
            public $algorithm;
            public $password;
            public $salt;
            public $count;
            public $key_length;
            public $raw_output;

            private $hash_length;
            private $output         = "";

            public function __construct($data = null)
            {
                if ($data != null) {
                    $this->init($data);
                }
            }

            public function init($data)
            {
                $this->algorithm  = $data["algorithm"];
                $this->password   = $data["password"];
                $this->salt       = $data["salt"];
                $this->count      = $data["count"];
                $this->key_length = $data["key_length"];
                $this->raw_output = $data["raw_output"];
            }

            public function hash()
            {
                $this->algorithm = strtolower($this->algorithm);
                if(!in_array($this->algorithm, hash_algos(), true))
                    throw new Exception('PBKDF2 ERROR: Invalid hash algorithm.');

                if($this->count <= 0 || $this->key_length <= 0)
                    throw new Exception('PBKDF2 ERROR: Invalid parameters.');

                $this->hash_length = strlen(hash($this->algorithm, "", true));
                $block_count = ceil($this->key_length / $this->hash_length);
                for ($i = 1; $i <= $block_count; $i++) {
                    // $i encoded as 4 bytes, big endian.
                    $last = $this->salt . pack("N", $i);
                    // first iteration
                    $last = $xorsum = hash_hmac($this->algorithm, $last, $this->password, true);
                    // perform the other $this->count - 1 iterations
                    for ($j = 1; $j < $this->count; $j++) {
                        $xorsum ^= ($last = hash_hmac($this->algorithm, $last, $this->password, true));
                    }
                    $this->output .= $xorsum;
                    if($this->raw_output)
                        return substr($this->output, 0, $this->key_length);
                    else
                        return bin2hex(substr($this->output, 0, $this->key_length));
                }
            }
        }

        $data = array('algorithm' => $algorithm, 'password' => $password, 'salt' => $salt, 'count' => $count, 'key_length' => $key_length, 'raw_output' => $raw_output);
        try {
            $pbkdf2 = new pbkdf2($data);
            return $pbkdf2->hash();
        } catch (Exception $e) {
            throw $e;
        }
    }
}

down

-1

php at ober-mail dot de ¶

3 years ago

If you are wondering what the requirements are for the salt, have a look at the RFC[1]:

"The salt parameter should be a random string containing at least 64 bits of entropy. That means when generated from a function like *mcrypt_create_iv*, at least 8 bytes long. But for salts that consist of only *a-zA-Z0-9* (or are base_64 encoded), the minimum length should be at least 11 characters. It should be generated random for each password that's hashed, and stored along side the generated key."

[1] https://wiki.php.net/rfc/hash_pbkdf2

down

-2

php - ober-mail - de ¶

3 years ago

If you are wondering what the requirements are for the salt, have a look at the RFC[1]:

"The salt parameter should be a random string containing at least 64 bits of entropy. That means when generated from a function like *mcrypt_create_iv*, at least 8 bytes long. But for salts that consist of only *a-zA-Z0-9* (or are base_64 encoded), the minimum length should be at least 11 characters. It should be generated random for each password that's hashed, and stored along side the generated key."

[1] https://wiki.php.net/rfc/hash_pbkdf2

＋add a note