sodium_crypto_pwhash

(PHP 7 >= 7.2.0)

sodium_crypto_pwhash — Derive a key from a password

Description

string sodium_crypto_pwhash ( int $length , string $password , string $salt , int $opslimit , int $memlimit [, int $alg ] )

Warning

This function is currently not documented; only its argument list is available.

Parameters

length: integer; The length of the password hash to generate, in bytes.
password: string; The password to generate a hash for.
salt: string A salt to add to the password before hashing. The salt should be unpredictable, ideally generated from a good random mumber source such as random_bytes(), and have a length of at least SODIUM_CRYPTO_PWHASH_SALTBYTES bytes.
opslimit: Represents a maximum amount of computations to perform. Raising this number will make the function require more CPU cycles to compute a key. There are some constants available to set the operations limit to appropriate values depending on intended use, in order of strength: SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE and SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE.
memlimit: The maximum amount of RAM that the function will use, in bytes. There are constants to help you choose an appropriate value, in order of size: SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE, and SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE. Typically these should be paired with the matching opslimit values.
alg: integer A number indicating the hash algorithm to use. By default SODIUM_CRYPTO_PWHASH_ALG_DEFAULT (the currently recommended algorithm, which can change from one version of libsodium to another), or explicitly using SODIUM_CRYPTO_PWHASH_ALG_ARGON2I13, representing the Argon2id algorithm version 1.3.

Return Values

Returns the hashed password, or FALSE on failure.

The used algorithm, opslimit, memlimit and salt are embedded within the hash, so all information needed to verify the hash is included. This allows the password_verify() function to verify the hash without needing separate storage for the salt or algorithm information.

Notes

Note:
It is recommended that you test this function on your servers, and adjust the opslimit and memlimit parameters so that execution of the function takes less than 100 milliseconds on interactive systems, and also verify that it fits with your PHP memory_limit setting. The constants will help you choose good limits for your hardware.

In order to produce the same password hash from the same password, the same algorithm, the same salt, and the same values for opslimit and memlimit must to be used. Therefore, these parameters must be stored for each user, or be used consistently for your whole application.