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

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 survey 20% of PHP users are still using PHP4 and 25% of PHP5 users are using pre PHP5.3.

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

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.)

<?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
}
?>

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.

password_hash() behavior:

1. Add E_NOTICE error to password_hash() with PASSWORD_BCRYPT and password longer than 72 bytes. (password_hash() return result with truncated password)
2. 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,

1. Suggest PBKDF2 SHA512 functions (hash or openssl) as an alternative. (rounds larger than 10,000)
2. Suggest workaround (not recommend) by prehash with raw SHA512. (e.g. password_hash(hash('sha512', SOME_STATIC_SCRET_SALT . $password), PASSWORD_DEFAULT);)

password_hash() E_NOTICE may break apps.

PHP 5.5.x

• Password Hashing

• PASSWORD_SHA512 for crypt-sha512

If there are any php.ini settings then list:

• hardcoded default values
• php.ini-development values
• php.ini-production values

None

More edit

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

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

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)

TDB

After the project is implemented, this section should contain

1. the version(s) it was merged to
2. a link to the git commit(s)
3. a link to the PHP manual entry for the feature

Links to external references, discussions or RFCs

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