====== PHP RFC: password_hash() function behavior ======
  * Version: 0.9
  * DateCreated: 2014-07-23
  * DateModified: 2014-07-23
  * Author: Yasuo Ohgaki <yohgaki@ohgaki.net>
  * Status: Under Discussion 
  * First Published at: http://wiki.php.net/rfc/password_hash_spec

===== Introduction =====
[[http://jp2.php.net/password_hash|password_hash()]] is introduced from PHP 5.5 as crypt() wrapper and has Blowfish(PASSWORD_BCRYPT) hash algorithm as the only hash function available. 

Unlike other hash functions, Blowfish is designed to take limited length as its parameter. Bytes longer than 72 bytes are truncated to compute hash value. Current implementation does not have check against too long parameter. Therefore, too long parameter is silently ignored. Average users expect "hash" functions compute hash value based on parameter, not part of it.

Before PHP 5.3, crypt() could not be used reliably because it didn't have required hash function internally. Therefore, code like below is used commonly. Note: According to this [[http://w3techs.com/technologies/details/pl-php/5/all|survey]] 20% of PHP users are still using PHP4 and 25% of PHP5 users are using pre PHP5.3.

<code php>
<?php
$password_hash = sha1(SOME_STATIC_SECRET_SALT . $_POST['password']);
if ($password_hash === get_password_hash_from_db($_POST['username'])) {
  // authenticated
} else {
  // not authenticated
?>
</code>

If user writes code like below, password_hash() does not work for authentication when SOME_STATIC_SECRET_SALT is long enough. (e.g. const = SOME_STATIC_SECRET_SLAT = hash('sha512', 'some secret string'); hash('sha512', 'str') returns 128 bytes which is longer than 72.)

<code php>
<?php
// $password_hash = password_hash(SOME_STATIC_SECRET_SALT . $_POST['password']) is saved in password DB
if (password_verify(SOME_STATIC_SECRET_SALT . $_POST['password'], get_password_hash_from_db($_POST['username']))) {
  // authenticated
} else {
  // not authenticated
}
?>
</code>

In general, users are recommended to use crypt related functions as is and this is documented currently. However, SOME_STATIC_SECRET_SALT is still useful as mitigation when password database is stolen while SOME_STATIC_SECRET_SALT is _not_ stolen. (e.g. Stolen password DB via SQL injection, stolen password db backup, etc) Therefore, some organizations require to add secret salt for an additional mitigation. 72 bytes limits is real problem in this case.
 

This RFC is for
  * Changing password_hash() behavior.
  * How to document password hash related functions.

===== Proposal =====

password_hash() behavior:

  - Add E_NOTICE error to password_hash() with PASSWORD_BCRYPT and password longer than 72 bytes. (password_hash() return result with truncated password)
  - Add PASSWORD_SHA512 hashing to password_hash() that is compatible with crypt-sha512

Password hashing related documentation:

Recommend plain use of password_hash() with less than 72 bytes.

In case we decided not to have PASSWORD_SHA512, 

  - Suggest PBKDF2 SHA512 functions ([[http://jp2.php.net/manual/en/function.hash-pbkdf2.php|hash]] or [[http://jp2.php.net/manual/en/function.openssl-pbkdf2.php|openssl]]) as an alternative. (rounds larger than 10,000)
  - Suggest workaround (not recommend) by prehash with raw SHA512. (e.g. password_hash(hash('sha512', SOME_STATIC_SCRET_SALT . $password), PASSWORD_DEFAULT);)


===== Backward Incompatible Changes =====

password_hash() E_NOTICE may break apps.

===== Proposed PHP Version(s) =====

PHP 5.5.x

===== RFC Impact =====
==== To Existing Extensions ====

  * [[http://jp2.php.net/manual/en/book.password.php|Password Hashing]]


==== New Constants ====

  * PASSWORD_SHA512 for crypt-sha512

==== php.ini Defaults ====
If there are any php.ini settings then list:
  * hardcoded default values
  * php.ini-development values
  * php.ini-production values

None

===== Open Issues =====

More edit

===== Unaffected PHP Functionality =====

return value of password_hash() function will not be changed.

===== Future Scope =====

When better crypt is available, password_hash()/crypt() and documentations should be updated.

===== Proposed Voting Choices =====
Include these so readers know where you are heading and can discuss the proposed voting options.

State whether this project requires a 2/3 or 50%+1 majority (see [[voting]])

===== Patches and Tests =====

TDB

===== Implementation =====
After the project is implemented, this section should contain 
  - the version(s) it was merged to
  - a link to the git commit(s)
  - a link to the PHP manual entry for the feature

===== References =====
Links to external references, discussions or RFCs

===== Rejected Features =====
Keep this updated with features that were discussed on the mail lists.