PHP RFC: password_hash() function behavior


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.

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

// $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);)

Backward Incompatible Changes

password_hash() E_NOTICE may break apps.

Proposed PHP Version(s)

PHP 5.5.x

RFC Impact

To Existing Extensions

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


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



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

Rejected Features

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

rfc/password_hash_spec.txt · Last modified: 2018/03/01 23:20 by carusogabriel