Password Hashing Functions
As more secure web services avoid storing passwords in plain text format, languages such as PHP provide various (undecryptable) hash functions to support the more secure industry standard. This topic provides documentation for proper hashing with PHP.
string password_hash ( string $password , integer $algo [, array $options ] )
boolean password_verify ( string $password , string $hash )
boolean password_needs_rehash ( string $hash , integer $algo [, array $options ] )
array password_get_info ( string $hash )
Prior to PHP 5.5, you may use the compatibility pack to provide the
password_* functions. It is highly recommended that you use the compatibility pack if you are able to do so.
With or without the compatibility pack, correct Bcrypt functionality through
crypt() relies on PHP 5.3.7+ otherwise you must restrict passwords to ASCII-only character sets.
Note: If you use PHP 5.5 or below you're using an unsupported version of PHP which does not receive any security updates anymore. Update as soon as possible, you can update your password hashes afterwards.
- bcrypt is your best option as long as you use key stretching to increase hash calculation time, since it makes brute force attacks extremely slow.
- argon2 is another option which will be available in PHP 7.2.
The following hashing algorithms are insecure or unfit for purpose and therefore should not be used. They were never suited for password hashing, as they're designed for fast digests instead of slow and hard to brute force password hashes.
If you use any of them, even including salts, you should switch to one of the recommended secure algorithms as soon as possible.
Algorithms considered insecure:
- MD4 - collision attack found in 1995
- MD5 - collision attack found in 2005
- SHA-1 - collision attack demonstrated in 2015
Some algorithms can be safely used as message digest algorithm to prove authenticity, but never as password hashing algorithm:
Note, strong hashes such as SHA256 and SHA512 are unbroken and robust, however it is generally more secure to use bcrypt or argon2 hash functions as brute force attacks against these algorithms are much more difficult for classical computers.
Creating a password hash
Create password hashes using
password_hash() to use the current industry best-practice standard hash or key derivation. At time of writing, the standard is bcrypt, which means, that
PASSWORD_DEFAULT contains the same value as
The third parameter is not mandatory.
'cost' value should be chosen based on your production server's hardware. Increasing it will make the password more costly to generate. The costlier it is to generate the longer it will take anyone trying to crack it to generate it also. The cost should ideally be as high as possible, but in practice it should be set so it does not slow down everything too much. Somewhere between 0.1 and 0.4 seconds would be okay. Use the default value if you are in doubt.
On PHP lower than 5.5.0 the
password_* functions are not available. You should use the compatibility pack to substitute those functions. Notice the compatibility pack requires PHP 5.3.7 or higher or a version that has the
$2y fix backported into it (such as RedHat provides).
If you are not able to use those, you can implement password hashing with
password_hash() is implemented as a wrapper around the
crypt() function, you need not lose any functionality.
Salt for password hash
Despite of reliability of crypt algorithm there is still vulnerability against rainbow tables. That's the reason, why it's recommended to use salt.
A salt is something that is appended to the password before hashing to make source string unique. Given two identical passwords, the resulting hashes will be also unique, because their salts are unique.
A random salt is one of the most important pieces of your password security. This means that even with a lookup table of known password hashes an attacker can’t match up your user’s password hash with the database password hashes since a random salt has been used. You should use always random and cryptographically secure salts. Read more
bcrypt algorithm, plain text salt is stored along with the resulting hash, which means that the hash can be transferred across different systems and platforms and still be matched against the original password.
Even when this is discouraged, you can use the
salt option to define your own random salt.
Important. If you omit this option, a random salt will be generated by password_hash() for each password hashed. This is the intended mode of operation.
The salt option has been deprecated as of PHP 7.0.0. It is now preferred to simply use the salt that is generated by default.
Determine if an existing password hash can be upgraded to a stronger algorithm
If you are using the
PASSWORD_DEFAULT method to let the system choose the best algorithm to hash your passwords with, as the default increases in strength you may wish to rehash old passwords as users log in
If the password_* functions are not available on your system (and you cannot use the compatibility pack linked in the remarks below), you can determine the algorithm and used to create the original hash in a method similar to the following:
Verifying a password against a hash
password_verify() is the built-in function provided (as of PHP 5.5) to verify the validity of a password against a known hash.
All supported hashing algorithms store information identifying which hash was used in the hash itself, so there is no need to indicate which algorithm you are using to encode the plaintext password with.
If the password_* functions are not available on your system (and you cannot use the compatibility pack linked in the remarks below) you can implement password verification with the
crypt() function. Please note that specific precautions must be taken to avoid timing attacks.