http://php.net/manual/en/function.hash-pbkdf2.php
http://php.net/manual/en/function.hash-pbkdf2.php
hash_pbkdf2
(PHP 5 >= 5.5.0, PHP 7)
hash_pbkdf2 — Generate a PBKDF2 key derivation of a supplied password
Description
$algo
, string $password
, string $salt
, int $iterations
[, int $length
= 0 [, bool$raw_output
= FALSE
]] )Parameters
algo
-
Name of selected hashing algorithm (i.e. md5, sha256, haval160,4, etc..) See hash_algos() for a list of supported algorithms.
password
-
The password to use for the derivation.
salt
-
The salt to use for the derivation. This value should be generated randomly.
iterations
-
The number of internal iterations to perform for the derivation.
length
-
The length of the output string. If
raw_output
isTRUE
this corresponds to the byte-length of the derived key, ifraw_output
isFALSE
this corresponds to twice the byte-length of the derived key (as every byte of the key is returned as two hexits).If 0 is passed, the entire output of the supplied algorithm is used.
raw_output
-
When set to
TRUE
, outputs raw binary data.FALSE
outputs lowercase hexits.
Return Values
Returns a string containing the derived key as lowercase hexits unless raw_output
is set to TRUE
in which case the raw binary representation of the derived key is returned.
Errors/Exceptions
An E_WARNING
will be raised if the algorithm is unknown, the iterations
parameter is less than or equal to 0, the length
is less than 0 or the salt
is too long (greater than INT_MAX
- 4).
Changelog
Version | Description |
---|---|
7.2.0 | Usage of non-cryptographic hash functions (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) was disabled. |
Examples
Example #1 hash_pbkdf2() example, basic usage
<?php
$password = "password";
$iterations = 1000;
// Generate a random IV using openssl_random_pseudo_bytes()
// random_bytes() or another suitable source of randomness
$salt = openssl_random_pseudo_bytes(16);
$hash = hash_pbkdf2("sha256", $password, $salt, $iterations, 20);
echo $hash;
?>
The above example will output something similar to:
120fb6cffcf8b32c43e7
Notes
The PBKDF2 method can be used for hashing passwords for storage. However, it should be noted that password_hash() or crypt()with CRYPT_BLOWFISH
are better suited for password storage.
crypto.pbkdf2(password, salt, iterations, keylen, digest, callback)#
password
<string> | <Buffer> | <TypedArray> | <DataView>salt
<string> | <Buffer> | <TypedArray> | <DataView>iterations
<number>keylen
<number>digest
<string>-
callback
<Function>
Provides an asynchronous Password-Based Key Derivation Function 2 (PBKDF2) implementation. A selected HMAC digest algorithm specified by digest
is applied to derive a key of the requested byte length (keylen
) from thepassword
, salt
and iterations
.
The supplied callback
function is called with two arguments: err
and derivedKey
. If an error occurs while deriving the key, err
will be set; otherwise err
will be null
. By default, the successfully generated derivedKey
will be passed to the callback as a Buffer
. An error will be thrown if any of the input arguments specify invalid values or types.
If digest
is null
, 'sha1'
will be used. This behavior is deprecated, please specify a digest
explicitely.
The iterations
argument must be a number set as high as possible. The higher the number of iterations, the more secure the derived key will be, but will take a longer amount of time to complete.
The salt
should be as unique as possible. It is recommended that a salt is random and at least 16 bytes long. See NIST SP 800-132 for details.
const crypto = require('crypto');
crypto.pbkdf2('secret', 'salt', 100000, 64, 'sha512', (err, derivedKey) => {
if (err) throw err;
console.log(derivedKey.toString('hex')); // '3745e48...08d59ae'
});
The crypto.DEFAULT_ENCODING
property can be used to change the way the derivedKey
is passed to the callback. This property, however, has been deprecated and use should be avoided.
const crypto = require('crypto');
crypto.DEFAULT_ENCODING = 'hex';
crypto.pbkdf2('secret', 'salt', 100000, 512, 'sha512', (err, derivedKey) => {
if (err) throw err;
console.log(derivedKey); // '3745e48...aa39b34'
});
An array of supported digest functions can be retrieved using crypto.getHashes()
.
Note that this API uses libuv's threadpool, which can have surprising and negative performance implications for some applications, see the UV_THREADPOOL_SIZE
documentation for more information.