This RFC describes a new API for simplified password hashing.
Password Hashing is a way to convert a user-supplied password into a one-way derived token for storage. By using the derived token, it makes it impossible to reverse the stored token and get the original password used by the user. This adds a layer of defense in case an attacker gets access to the database storing the password.
As it turns out, just hashing a password using md5() or even sha512() isn't good enough. Cryptographic hash functions (such as those supplied by hash()) are designed to be fast. This is good for cryptographic needs such as signing. But for password hashing, that's a problem since it allows an attacker to brute force a lot of passwords very quickly. Adding a salt makes it resistent to rainbow tables, but not resistent to brute forcing where that salt is known.
By using either a stretched algorithm (Such as PBKDF2) or an algorithm designed to be slow (Such as bcrypt), a much better defense against brute forcing will be had.
As recent attacks have shown, strong password hashing is something that the vast majority of PHP developers don't understand, or don't think is worth the effort. The current core implementations of strong password hashing using crypt() are actually fairly difficult to work with. The error states are difficult to check for (returning *0 or *1 on error). The salt format is difficult to generate as it uses a custom base64 alphabet (. instead of + and no padded =). Additionally, salts are reasonably difficult to generate randomly (not too difficult, but requires a fair bit of code). Additionally, checking the return when validating a password can expose the application to remote timing attacks.
By providing a simple API that can be called, which takes care of all of those issues for you, hopefully more projects and developers will be able to use secure password hashing.
Salts exist for a single reason: To make it so that any time (CPU effort) spent cracking a single password hash cannot be amortized across multiple hashes. That means that attacking a single password hash will have no impact on the time it will take attacking another hash. Based on that reason, salts only need to be statistically globally unique. There is no requirement for them to be true random (as you would need for an encryption key). This means that /dev/urandom is acceptable, while mt_rand() and rand() are not (except as fallbacks).
No, it's not. There's plenty of information out there to dispel this myth. See the references section for some details.
The proposal is to add a new set of password hashing APIs to the standard PHP library. These hashing APIs will initially be thin wrappers around crypt() to allow for automatic salt generation and better error checking. The APIs are designed such that they can easily be extended in the future as additional strong hashing algorithms are introduced into PHP's core (Such as scrypt).
Initially, several new constants are defined:
* BCrypt - The CRYPT_BLOWFISH algorithm. The strongest algorithm currently supported by PHP.
Errors:
If any error is raise, false is returned by the function.
Normal Operation: With BCrypt, the output of crypt() is checked for error states (output < 13 characters). If there was an error in hashing, false is returned (this shouldn't happen due to the verification of the parameters, but it's there in case something fails). Otherwise, the output of crypt() is returned directly.
It's important to note that the output of crypt() (and hence password_hash()) contains all the information that will be needed to verify the hash later. Therefore, if the default hashing algorithm changes, or the user changes their algorithm, old hashed passwords would still continue to function and will be validated properly.
If we look at the output format of a hash:
<?php var_dump(password_hash("rasmuslerdorf", PASSWORD_BCRYPT, array("cost" => 7, "salt" => "usesomesillystringfor"))); // string(60) "$2y$07$usesomesillystringfore2uDLvp1Ii2e./U9C8sBjqp8I90dH6hi" ?>
Note that $2y$ indicates the algorithm to use (in this case, bcrypt). The 07$ indicates the cost parameter supplied. The usesomesillystringfor is the salt we provided. And the final part, e2uDLvp1Ii2e./U9C8sBjqp8I90dH6hi is the generated hash.
So this final hash string consists of everything that crypt() or password_verify() will need to test the hash. Therefore, there is no need to store the salt separately, it's included in the generated hash. And there is no need to store the algorithm separately, as it is also stored in the generated hash.
Errors:
On error, it will return false.
Normal Operation:
When passed a correct password and the generated hash from password_hash(), the function will return a boolean true. If there is any failure (hash is invalid, password is incorrect, hash is corrupted, etc), the function will return a boolean false.
It's important to note that this function does not take any indication of the algorithm or salt. That's because both are included in the resulting $hash return value from password_hash().
Errors:
On error, it will return NULL
Normal Operation:
When passed in a valid hash created by a supported password_hash algorithm, this function will return an array of information about that hash. The first associative element, “algo” is the algorithm that was used to generate the hash (or 0 if not found). The second element is “options”, which includes the used options by the hashing algorithm, with the exception of the salt used.
Errors:
On error, it will return NULL
Normal Operation:
The supplied hash parameter is tested to see if the algorithm and options supplied match. Basically, this is similar to a wrapper over password_get_info() to validate if the supplied hash matches the configuration options passed in. This can be used to determine if a hash needs to be re-hashed after modifying the options (such as increasing bcrypt cost, changing algorithms, etc).
<?php $password = "rasmuslerdorf"; $hash = password_hash($password, PASSWORD_BCRYPT, array("cost" => 7, "salt" => "usesomesillystringfor"))); if (password_verify($password, $hash)) { if (password_needs_rehash($hash, PASSWORD_BCRYPT, array('cost' => 8))) { update_password_in_db($password); } log_user_in(); } else { error_wrong_password(); } ?>
It could be implemented in user-land by:
<?php function password_needs_rehash($hash, $algo, array $options = array()) { $info = password_get_info($hash); $return = $algo != $info['algo']; // Skip salt parameter if supplied to options $return |= array() != array_diff_assoc($info['options'], $options); return $return; } ?>
<?php $password = "foo"; $hash = password_hash($password, PASSWORD_DEFAULT); // Store Hash if (password_verify($password, $hash)) { // Password Is Correct } else { // Password Is Not Correct } ?>
<?php $password = "foo"; $hash = password_hash($password, PASSWORD_BCRYPT); // Store Hash if (password_verify($password, $hash)) { // Password Is Correct } else { // Password Is Not Correct } ?>
<?php $password = "foo"; $hash = password_hash($password, PASSWORD_BCRYPT, array("cost" => 14); // Store Hash if (password_verify($password, $hash)) { // Password Is Correct } else { // Password Is Not Correct } ?>
<?php $password = "foo"; $salt = mcrypt_create_iv(22, MCRYPT_DEV_URANDOM); $hash = password_hash($password, PASSWORD_BCRYPT, array("cost" => 14, "salt" => $salt); // Store Hash if (password_verify($password, $hash)) { // Password Is Correct } else { // Password Is Not Correct } ?>
I'd propose the following policy for updating the default hashing algorithm in future releases of PHP.
Currently, the proposed patch is not yet complete. The basic functionality is there, but it needs some refactoring and testing prior to official proposal. The Work-In-Progress can be seen on the hash_password branch of ircmaxell's fork.
The specific implementation is at password.c
Additionally, a compatibility version in PHP is maintained at Github. This can be used in PHP versions 5.3 and 5.4 and for testing.
With the nature of cryptography, future compatibility is a significant concern. In order to be safe, this functionality would need to be able to adapt to changing requirements in the future. There are a few provisions that enable future compatibility in future versions of PHP:
There has been some discussion around the second argument of password_hash() (The algorithm argument) and whether it should have a default value or not.
The “should have a default setting” argument is that it makes the API easier to use. All you would need to do is password_hash($password) to safely hash a password. The default would be updated according to the “Updating PASSWORD_DEFAULT” guidelines above. The API would become string password_hash(string $password, int $algo = PASSWORD_DEFAULT, array $options = array())
By not having a default value (and hence being a mandatory argument), it forces implementing developers to understand that the default argument can change over time. This has a few benefits in that developers need to recognize that storage requirements may change over time, that portability may be affected, etc.
The current position of this RFC sides with the “should not have a default” argument. Therefore, the function has a required second argument.
There has also been discussion around whether or not password_make_salt() should be exposed to user-land.
The argument that it should not be exposed is that it's not really doing anything generic. It produces a random salt of the specified length. This can already be accomplished in user-land via combinations of functions such as mcrypt_create_iv() and base64_encode(). Therefore, its existence is not really necessary.
The argument that it should be exposed is that it needs to be implemented in C because it is needed for password_hash(), so it should be exposed so that it can be used for other things in userland. One of these other uses is that the format for the string (a-zA-Z0-9./) is already correct for crypt(). Therefore, a single function call can create salts for the other crypt() algorithms. Whereas to safely create them now requires a combination of at least 3 function calls.
The current position of this RFC sides with the “should not be exposed” argument. The function has been removed from the proposal.
The function password_needs_rehash() can be implemented in user-land with the information returned by password_get_info().
Since the function can be implemented in user-land, there is no need to implement it in core.
There are a few reasons to include it in core. It makes it significantly easier to implement as otherwise implementation specific changes would need to be made over time to ensure that new algorithms are correctly identified (with their options). It also provides the ability to always reject hashes made using a grossly compromised algorithm (letting password_verify work, but rejecting password_hash attempts)...
The current position of this RFC is that the function is needed, and is implemented.
There's been some discussion around the existence of the PASSWORD_DEFAULT constant.
The argument for the constant is that it provides the ability for code to take advantage of the most secure algorithm for the current release of PHP. This would change over time, but over a long term period of time (would only change every major release). Therefore, it would make it easier to implement code that would stay secure over a long period of time.
By not having the constant, developers would be forced to choose a specific algorithm at author time. This would allow them to understand the different algorithms available and make an intelligent choice. Additionally, it would prevent migration issues that could be caused by a changing algorithm (storage requirements, etc).
The current position of this RFC is that the benefits of the constant relating to long term security outweigh the bad parts for the average developer. Therefore, the constant exists.
There's been discussion about the return value on parameter parse errors.
The argument that password_verify should return NULL on a parameter parse error (invalid types, invalid numbers of types, etc) because that's the standard way PHP internal functions deal with parameter errors. For consistency it should also return NULL.
The argument is that password_verify should always return a strict boolean type. That way, a check of if (false === password_verify(..)) would not accidentally return a false condition when the password was not verified. As such, it would become possible for password_verify() to return falsy, but non-false results when it did not successfully verify the password hash.
The current position is that the security context of the function justifies the break of consistency with other core functions. Therefore password_verify() currently only ever returns a boolean (never NULL).
A Pepper is similar to a salt, except that it's a unique site-wide value which is stored outside of the database.
The “should have” pepper argument is that it provides an added level of defense in case a database with salts and hashes is leaked.
There are a few reasons we should not use peppers:
Additionally, the same benefit can be had by encrypting the hash using the secret “pepper” value prior to storage. In practice this will be the better alternative (although for most use-cases not necessary) because it uses standard algorithms with correct inputs for them.
This RFC takes the position that the core API should not directly use a pepper.
Blog Posts:
Stack Overflow Questions/Answers: