rfc:password_hash
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision | ||
rfc:password_hash [2012/07/12 02:49] – [Examples] ircmaxell | rfc:password_hash [2012/10/16 09:05] – Implemented! ircmaxell | ||
---|---|---|---|
Line 1: | Line 1: | ||
====== Request for Comments: Adding simple password hashing API ====== | ====== Request for Comments: Adding simple password hashing API ====== | ||
- | * Version: 1.0 | + | * Version: 1.4 |
* 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 ===== | ||
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, int $salt_type = PASSWORD_SALT_BCRYPT)// | ||
* //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 53: | Line 51: | ||
* // | * // | ||
- | * // | + | * // |
- | * // | + | |
- | * // | + | |
==== Supported Algorithms ==== | ==== Supported Algorithms ==== | ||
Line 107: | 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 salt_type parameter is // | ||
- | |||
- | 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 239: | 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 317: | Line 286: | ||
=== Current Position === | === Current Position === | ||
- | The current position of this RFC sides with the " | + | The current position of this RFC sides with the " |
- | + | ||
- | ==== password_make_salt()' | + | |
- | + | ||
- | There has been discussion around | + | |
- | + | ||
- | === Should Be A Flag === | + | |
- | + | ||
- | The " | + | |
- | + | ||
- | === Should Be A Boolean === | + | |
- | + | ||
- | Currently the output type of // | + | |
- | + | ||
- | === Current Position === | + | |
- | + | ||
- | The current position of this RFC is that the parameter should be a flag to allow for future compatibility with unknown requirements. | + | |
==== password_needs_rehash() is not needed ==== | ==== password_needs_rehash() is not needed ==== | ||
Line 351: | Line 304: | ||
The current position of this RFC is that the function is needed, and is implemented. | The current position of this RFC is that the function is needed, and is implemented. | ||
- | === The Existence Of PASSWORD_DEFAULT === | + | ==== The Existence Of PASSWORD_DEFAULT |
There' | There' | ||
Line 382: | Line 335: | ||
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 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 424: | Line 399: | ||
* [[http:// | * [[http:// | ||
* [[http:// | * [[http:// | ||
+ | |||
+ | ===== Vote ===== | ||
+ | |||
+ | < | ||
+ | title=" | ||
+ | * Yes | ||
+ | * No | ||
+ | </ | ||
===== Changelog ===== | ===== Changelog ===== | ||
Line 435: | Line 418: | ||
* 0.8 - Add discussion points section, change password_make_salt to take flag for second parameter | * 0.8 - Add discussion points section, change password_make_salt to take flag for second parameter | ||
* 1.0 - Proposed | * 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! |
rfc/password_hash.txt · Last modified: 2017/09/22 13:28 by 127.0.0.1