PHP password_hash() Function

The PHP password_hash() function creates a password hash using a strong one-way hashing algorithm. It is compatible with crypt(). Therefore, password hashes created by crypt() can be used with this function.

The following algorithms are currently supported:

• PASSWORD_DEFAULT - Use the BCRYPT algorithm by default as of PHP 5.5.0. Note that this constant may change over time as new and stronger algorithms are added to PHP, therefore allow storage to expand past 60 characters (255 recommended).
• PASSWORD_BCRYPT - Use the CRYPT_BLOWFISH algorithm to create the hash. This will produce a standard crypt() compatible hash using the "$2y$" identifier. The result will always be a 60 character string, or false on failure.
• PASSWORD_ARGON2I - Use the Argon2i hashing algorithm to create the hash. This algorithm is only available if PHP has been compiled with Argon2 support.
• PASSWORD_ARGON2ID - Use the Argon2id hashing algorithm to create the hash. This algorithm is only available if PHP has been compiled with Argon2 support.

Supported options for PASSWORD_BCRYPT:

• salt (string) - to manually provide a salt to use when hashing the password. This will override and prevent a salt from being automatically generated.

  If omitted, a random salt will be generated by password_hash() for each password hashed. This is the intended mode of operation and as of PHP 7.0.0 the salt option has been deprecated.

• cost (int) - which denotes the algorithmic cost that should be used.

  If omitted, a default value of 10 will be used. This is a good baseline cost, but you may want to consider increasing it depending on your hardware.

Supported options for PASSWORD_ARGON2I and PASSWORD_ARGON2ID:

• memory_cost (int) - Maximum memory (in bytes) that may be used to compute the Argon2 hash. Default is PASSWORD_ARGON2_DEFAULT_MEMORY_COST.
• time_cost (int) - Maximum amount of time it may take to compute the Argon2 hash. Default is PASSWORD_ARGON2_DEFAULT_TIME_COST.
• threads (int) - Number of threads to use for computing the Argon2 hash. Default is PASSWORD_ARGON2_DEFAULT_THREADS. Only available with libargon2, not with libsodium implementation.

Syntax

password_hash(password, algo, options)

Parameters

Return Value

Returns the hashed password.

The used algorithm, cost and salt are returned as part of the hash. Therefore, all information that is needed to verify the hash is included in it. This allows the password_verify() function to verify the hash without needing separate storage for the salt or algorithm information.

Example: password_hash() example

The example below shows the usage of password_hash() function.

<?php
//hashing the password using the current DEFAULT 
//algorithm which is presently BCRYPT, and 
//produces a 60 character result. Note that DEFAULT 
//may change over time, therefore allow storage 
//to expand past 60 characters (255 recommended)
echo password_hash("myPassword", PASSWORD_DEFAULT);
?>

The output of the above code will be similar to:

$2y$10$Hm6KC1/82.P4Nq.BxTRHt.2W38QueusDaa6rCvO5KhP79RyDyXq7C

Example: setting cost manually

In the example below the cost of the BCRYPT algorithm is set manually.

<?php
//increasing the default cost for BCRYPT to 11
$options = array('cost' => 11);

//hashing the password using the BCRYPT algorithm
echo password_hash("myPassword", PASSWORD_BCRYPT, $options);
?>

The output of the above code will be similar to:

$2y$11$qy1hDCTAxJ7WL7pZn0H4Le6oWEgo63nTGzrpxSCpP3MK1yJzc/O1G

Example: finding a good cost

The example below explains how to find a good cost for the BCRYPT hash algorithm.

<?php
//below code will benchmark the server to determine 
//how high of a cost it can afford without slowing down
//too much. 8-10 is a good baseline, and more is good 
//if the servers are fast enough. The code below aims 
//for ≤ 50 milliseconds stretching time, which is a good 
//baseline for systems handling interactive logins

$timeTarget = 0.05; // 50 milliseconds 

$cost = 8;
do {
  $cost++;
  $start = microtime(true);
  password_hash("myPassword", PASSWORD_BCRYPT, ["cost" => $cost]);
  $end = microtime(true);
} while (($end - $start) < $timeTarget);

echo "Appropriate Cost Found: " . $cost;
?>

The output of the above code will be similar to:

Appropriate Cost Found: 10

Example: using Argon2i

Consider one more example where ARGON2I hashing algorithm is used to create the hash.

<?php
//hashing the password using ARGON2I algorithm
echo "Argon2i hash: \n";
echo password_hash('myPassword', PASSWORD_ARGON2I);
?>

The output of the above code will be similar to (word wrapped for readability):

Argon2i hash: 
$argon2i$v=19$m=65536,t=4,p=1$ZUl3S2V6LnJBWS5EM1FybQ$E
fVOU5v98/oM1EExvYUM0mFcWUHZ+QrWLqsohVvuixs