rfc:password_hash
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
rfc:password_hash [2012/07/09 15:17] – Implement password_get_info() and password_needs_rehash() ircmaxell | rfc:password_hash [2017/09/22 13:28] (current) – external edit 127.0.0.1 | ||
---|---|---|---|
Line 1: | Line 1: | ||
====== Request for Comments: Adding simple password hashing API ====== | ====== Request for Comments: Adding simple password hashing API ====== | ||
- | * Version: | + | * Version: |
* Date: 2012-06-26 | * Date: 2012-06-26 | ||
* Author: Anthony Ferrara < | * Author: Anthony Ferrara < | ||
- | * Status: | + | * Status: |
* First Published at: http:// | * First Published at: http:// | ||
Line 22: | Line 22: | ||
==== Why Do We Need A Simple API ==== | ==== Why Do We Need A Simple API ==== | ||
- | 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, | + | 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, |
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. | 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. | ||
- | |||
===== Common Misconceptions ===== | ===== Common Misconceptions ===== | ||
- | ==== Salts Need To Be Cryptographically Secure | + | ==== Salts Need To Be True Random |
- | 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 unique | + | 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 |
==== Hash(password + salt) Is Fine ==== | ==== Hash(password + salt) Is Fine ==== | ||
Line 44: | Line 43: | ||
* //string password_hash(string $password, int $algo, array $options = array())// - The function which creates new password hashes. The second parameter //algo// indicates which algorithm should be used to execute the hash. You can use the default constant if you want the algorithm to automatically update itself to the strongest algorithm available as PHP is upgraded. If called with two parameters, it will auto-generate a salt. The // | * //string password_hash(string $password, int $algo, array $options = array())// - The function which creates new password hashes. The second parameter //algo// indicates which algorithm should be used to execute the hash. You can use the default constant if you want the algorithm to automatically update itself to the strongest algorithm available as PHP is upgraded. If called with two parameters, it will auto-generate a salt. The // | ||
* //bool password_verify($password, | * //bool password_verify($password, | ||
- | * //string password_make_salt(int $length, bool $raw_output = false)// - This function will create a new random salt of the specified length using psuedo-random algorithms. It will be used by // | ||
* //bool password_needs_rehash(string $hash, int $algo, array $options = array())// - This function checks to see if the supplied hash implements the algorithm and options provided. If not, it is assumed that the hash needs to be rehashed. | * //bool password_needs_rehash(string $hash, int $algo, array $options = array())// - This function checks to see if the supplied hash implements the algorithm and options provided. If not, it is assumed that the hash needs to be rehashed. | ||
* //array password_get_info(string $hash)// - This function gets the information used to generate a hash. The returned array has two keys, algo and options. | * //array password_get_info(string $hash)// - This function gets the information used to generate a hash. The returned array has two keys, algo and options. | ||
Line 50: | Line 48: | ||
==== New Constants ==== | ==== New Constants ==== | ||
- | Initially, | + | Initially, |
- | * // | + | * // |
- | * // | + | * // |
==== Supported Algorithms ==== | ==== Supported Algorithms ==== | ||
Line 105: | Line 103: | ||
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 // | 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_make_salt() === | ||
- | |||
- | Errors: | ||
- | * E_WARNING - When supplied an incorrect number of parameters. | ||
- | * E_WARNING - If the length parameter is less than or equal to zero | ||
- | * E_WARNING - If the length parameter is greater than // | ||
- | |||
- | Additionally, | ||
- | |||
- | On error, it will return false; | ||
- | |||
- | Normal Operation: | ||
- | |||
- | When the raw_output parameter is false (default), the function will generate a string of the specified length consisting of random characters from the alphabet // | ||
- | |||
- | It will use non-cryptographically safe, but strong random entropy sources, if possible for the salt generation. On windows, it will use // | ||
=== password_get_info() === | === password_get_info() === | ||
Line 237: | Line 218: | ||
</ | </ | ||
- | ===Generating Salts:=== | ||
- | <file php generate_salt.php> | ||
- | <?php | ||
- | // 15 characters in the alphabet a-zA-Z0-9./ | ||
- | $salt = password_make_salt(15); | ||
- | |||
- | // 15 characters of binary data (0-255) | ||
- | $raw_salt = password_make_salt(15, | ||
- | ?> | ||
- | </ | ||
==== Possible Future Implementation Details ==== | ==== Possible Future Implementation Details ==== | ||
Line 281: | Line 252: | ||
- The default algorithm is specified by a constant // | - The default algorithm is specified by a constant // | ||
- The default cost parameter to BCRYPT is specified in the php.ini file. This allows individual sites to tailor the cost of bcrypt for their needs. Additionally, | - The default cost parameter to BCRYPT is specified in the php.ini file. This allows individual sites to tailor the cost of bcrypt for their needs. Additionally, | ||
+ | - If an implemented algorithm is ever grossly compromised (to the point of uselessness), | ||
+ | |||
+ | ===== Discussion Points ===== | ||
+ | |||
+ | ==== password_hash() Algo Argument as optional ==== | ||
+ | |||
+ | 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. | ||
+ | |||
+ | === Should Have A Default === | ||
+ | |||
+ | The " | ||
+ | |||
+ | === Should Not Have A Default === | ||
+ | |||
+ | 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. | ||
+ | |||
+ | === Current Position === | ||
+ | |||
+ | The current position of this RFC sides with the " | ||
+ | |||
+ | ==== password_make_salt() Is Not Needed ==== | ||
+ | |||
+ | There has also been discussion around whether or not // | ||
+ | |||
+ | === It should not be exposed === | ||
+ | |||
+ | 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 // | ||
+ | |||
+ | === It should be exposed === | ||
+ | |||
+ | The argument that it should be exposed is that it needs to be implemented in C because it is needed for password_hash(), | ||
+ | |||
+ | === Current Position === | ||
+ | |||
+ | The current position of this RFC sides with the " | ||
+ | |||
+ | ==== password_needs_rehash() is not needed ==== | ||
+ | |||
+ | The function // | ||
+ | |||
+ | === Not Needed === | ||
+ | |||
+ | Since the function can be implemented in user-land, there is no need to implement it in core. | ||
+ | |||
+ | === Needed === | ||
+ | |||
+ | 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)... | ||
+ | |||
+ | === Current Position === | ||
+ | |||
+ | The current position of this RFC is that the function is needed, and is implemented. | ||
+ | |||
+ | ==== The Existence Of PASSWORD_DEFAULT ==== | ||
+ | |||
+ | There' | ||
+ | |||
+ | === Should Have It === | ||
+ | |||
+ | 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. | ||
+ | |||
+ | === Should Not Have It === | ||
+ | |||
+ | 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, | ||
+ | |||
+ | === Current Position === | ||
+ | |||
+ | 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. | ||
+ | |||
+ | ==== password_verify() Returns FALSE On Error ==== | ||
+ | |||
+ | There' | ||
+ | |||
+ | === NULL === | ||
+ | |||
+ | 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//. | ||
+ | |||
+ | === FALSE === | ||
+ | |||
+ | The argument is that password_verify should always return a strict boolean type. That way, a check of //if (false === password_verify(..))// | ||
+ | |||
+ | === Current Position === | ||
+ | |||
+ | 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). | ||
+ | |||
+ | ==== The API Does Not Support PEPPER ==== | ||
+ | |||
+ | A Pepper is similar to a salt, except that it's a unique site-wide value which is stored outside of the database. | ||
+ | |||
+ | === Should Have Pepper === | ||
+ | |||
+ | The " | ||
+ | |||
+ | === Should Not Have Pepper === | ||
+ | |||
+ | There are a few reasons we should not use peppers: | ||
+ | |||
+ | * No standard cryptographic algorithm or function accepts a unique " | ||
+ | * There are no peer-reviewed standards or research papers that indicate that using a pepper adds any significant value. | ||
+ | * Since the security value of the " | ||
+ | |||
+ | Additionally, | ||
+ | |||
+ | === Current Position === | ||
+ | |||
+ | This RFC takes the position that the core API should not directly use a pepper. | ||
===== References ===== | ===== References ===== | ||
Line 323: | Line 399: | ||
* [[http:// | * [[http:// | ||
* [[http:// | * [[http:// | ||
+ | |||
+ | ===== Vote ===== | ||
+ | |||
+ | < | ||
+ | title=" | ||
+ | * Yes | ||
+ | * No | ||
+ | </ | ||
===== Changelog ===== | ===== Changelog ===== | ||
Line 332: | Line 416: | ||
* 0.6 - Make //$algo// parameter to // | * 0.6 - Make //$algo// parameter to // | ||
* 0.7 - Implement password_get_info() and password_needs_rehash() | * 0.7 - Implement password_get_info() and password_needs_rehash() | ||
+ | * 0.8 - Add discussion points section, change password_make_salt to take flag for second parameter | ||
+ | * 1.0 - Proposed | ||
+ | * 1.1 - Add pepper discussion | ||
+ | * 1.2 - Removed // | ||
+ | * 1.3 - Open Voting | ||
+ | * 1.4 - Close Voting - Moving To Accepted | ||
+ | * 1.5 - Implemented! | ||
+ | * 1.5.1 - Fine tune wording of " |
rfc/password_hash.1341847071.txt.gz · Last modified: 2017/09/22 13:28 (external edit)