rfc:password_hash
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionLast revisionBoth sides next revision | ||
rfc:password_hash [2012/07/13 20:57] – Add bit about Peppers ircmaxell | rfc:password_hash [2013/10/28 14:36] – Fine tune wording of "Cryptographically Secure Salt Requirement" ircmaxell | ||
---|---|---|---|
Line 1: | Line 1: | ||
====== Request for Comments: Adding simple password hashing API ====== | ====== Request for Comments: Adding simple password hashing API ====== | ||
- | * Version: 1.1 | + | * 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 ===== | ||
- | ==== 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, 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 446: | Line 399: | ||
* [[http:// | * [[http:// | ||
* [[http:// | * [[http:// | ||
+ | |||
+ | ===== Vote ===== | ||
+ | |||
+ | < | ||
+ | title=" | ||
+ | * Yes | ||
+ | * No | ||
+ | </ | ||
===== Changelog ===== | ===== Changelog ===== | ||
Line 458: | Line 419: | ||
* 1.0 - Proposed | * 1.0 - Proposed | ||
* 1.1 - Add pepper discussion | * 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.txt · Last modified: 2017/09/22 13:28 by 127.0.0.1