Request for Comments: Adding simple password hashing API

• Version: 0.4
• Date: 2012-06-26
• Author: Anthony Ferrara ircmaxell@php.net
• Status: Draft
• First Published at: http://wiki.php.net/rfc/password_hash

This RFC describes a new API for simplified password hashing.

Password Hashing is a way to convert a user-supplied password into a one-way derived token for storage. By using the derived token, it makes it impossible to reverse the stored token and get the original password used by the user. This adds a layer of defense in case an attacker gets access to the database storing the password.

As it turns out, just hashing a password using md5() or even sha512() isn't good enough. Cryptographic hash functions (such as those supplied by hash()) are designed to be fast. This is good for cryptographic needs such as signing. But for password hashing, that's a problem since it allows an attacker to brute force a lot of passwords very quickly. Adding a salt makes it resistent to rainbow tables, but not resistent to brute forcing where that salt is known.

By using either a stretched algorithm (Such as PBKDF2) or an algorithm designed to be slow (Such as bcrypt), a much better defense against brute forcing will be had.

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, salts are reasonably difficult to generate randomly (not too difficult, but requires a fair bit of code). Additionally, checking the return when validating a password can expose the application to http://en.wikipedia.org/wiki/Timing_attack.

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.

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 in a system. There is no requirement for them to be cryptographically secure.

No, it's not. There's plenty of information out there to dispel this myth. See the references section for some details.

The proposal is to add a new set of password hashing APIs to the standard PHP library. These hashing APIs will initially be thin wrappers around crypt() to allow for automatic salt generation and better error checking. The APIs are designed such that they can easily be extended in the future as additional strong hashing algorithms are introduced into PHP's core (Such as scrypt).

• string password_hash(string $password, string $algo = PASSWORD_DEFAULT, array $options = array()) - The function which creates new password hashes. If called with one parameter, it will auto-generate a salt, and use the defined default algorithm (currently bcrypt). The $options array allows for passing in algorithm specific options. In the case of bcrypt, two options are supported: salt and cost. The salt parameter, if provided, will be used in place of an auto-generated salt. The cost parameter is passed to crypt() to control the amount of CPU time that should be expended creating the hash (higher is more resistent to brute forcing, lower is kinder on the servers. A balance should be achieved).
• bool password_verify($password, $hash) - The function which verifies an existing hash. This hash can be created via password_hash(), or a normal crypt() hash. The only thing it provides on top of crypt() is resistance to timing attacks by using a constant-time comparison function.
• string password_make_salt(int $length, bool $raw_output = false) - This function will create a new random salt of the specified length using psuedo-random algorithms. It will be used by password_hash() if a salt is not provided. But it can also be used to generate salts for other crypt() algorithms that password_hash() does not support. It can also be used to generate strong salts for other algorithms, such as PBKDF2 (which exists as an RFC now), or 3pd libraries like PHPASS.

Initially, two constants are defined:

• PASSWORD_BCRYPT = “2y” - Create new password hashes using the CRYPT_BLOWFISH algorithm
• PASSWORD_DEFAULT = PASSWORD_BCRYPT - The default algorithm to use for hashing if no algorithm is provided. This can change in future releases if a new, stronger hashing algorithm (such as scrypt is supported).

• password.bcrypt_cost = 11 - This ini setting (E_ALL) allows for defining the default cost of a bcrypt hash in an ini file.

* BCrypt - The CRYPT_BLOWFISH algorithm. The strongest algorithm currently supported by PHP.

Errors:

• E_WARNING - When CRYPT is not included in core (was disabled compile-time, or is listed in disabled_functions declaration)
• E_WARNING - When supplied an incorrect number of arguments.
• E_WARNING - When supplied a non-string first parameter (password)
• E_WARNING - If an algorithm is specified in the algo parameter that is not supported
• E_WARNING - If a bcrypt cost parameter is outside of the range 4-31 (by ini or specified in the options array)
• E_WARNING - If a non-string salt option is provided
• E_WARNING - If a provided salt option is too short for the specified algorithm

If any error is raise, false is returned by the function.

Normal Operation: With BCrypt, the output of crypt() is checked for error states (output < 13 characters). If there was an error in hashing, false is returned (this shouldn't happen due to the verification of the parameters, but it's there in case something fails). Otherwise, the output of crypt() is returned directly.

It's important to note that the output of crypt() (and hence password_hash()) contains all the information that will be needed to verify the hash later. If we look at the output format of a hash:

basic_usage.php

<?php
var_dump(password_hash("rasmuslerdorf", PASSWORD_BCRYPT, array("cost" => 7, "salt" => "usesomesillystringfor")));
// string(60) "$2y$07$usesomesillystringfore2uDLvp1Ii2e./U9C8sBjqp8I90dH6hi"
?>

Note that $2y$ indicates the algorithm to use (in this case, bcrypt). The 07$ indicates the cost parameter supplied. The usesomesillystringfor is the salt we provided. And the final part, e2uDLvp1Ii2e./U9C8sBjqp8I90dH6hi is the generated hash.

So this final hash string consists of everything that crypt() or password_verify() will need to test the hash. Therefore, there is no need to store the salt separately, it's included in the generated hash.

Errors:

• E_WARNING - When CRYPT is not included in core (was disabled compile-time, or is listed in disabled_functions declaration)
• E_WARNING - When supplied incorrect number of parameters.

On error, it will return false.

Normal Operation:

When passed a correct password and the generated hash from password_hash(), the function will return a boolean true. If there is any failure (hash is invalid, password is incorrect, hash is corrupted, etc), the function will return a boolean false.

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 PHP_INT_MAX / 3 (needed to ensure safe allocations)

Additionally, an E_WARNING error can be thrown if the generated salt is too short to encode fully. This should never happen, and is just a sanity check to prevent an inconsistent state due to a failure in other parts of the system.

On error, it will return false;

Normal Operation:

When the raw_output parameter is false (default), the function will generate a string of the specified length consisting of random characters from the alphabet a-zA-Z0-9/.. When raw_output is true, the function will generate a string of the specified length consisting of random bytes (characters 0 - 255).

It will use non-cryptographically safe, but strong random entropy sources, if possible for the salt generation. On windows, it will use php_win32_get_random_bytes(). On other platforms, it will read from /dev/urandom. If neither can generate enough entropy for the request, it will fall back to using php_rand() to supplement the provided randomness (it xor-s the php_rand() value with the existing one).

basic_usage.php

<?php
$password = "foo";
$hash = password_hash($password);
// Store Hash
 
if (password_verify($password, $hash)) {
    // Password Is Correct
} else {
    // Password Is Not Correct
}
?>

specify_algorithm.php

<?php
$password = "foo";
$hash = password_hash($password, PASSWORD_BCRYPT);
// Store Hash
 
if (password_verify($password, $hash)) {
    // Password Is Correct
} else {
    // Password Is Not Correct
}
?>

specify_cost.php

<?php
$password = "foo";
$hash = password_hash($password, PASSWORD_BCRYPT, array("cost" => 14);
// Store Hash
 
if (password_verify($password, $hash)) {
    // Password Is Correct
} else {
    // Password Is Not Correct
}
?>

specify_salt.php

<?php
$password = "foo";
$salt = mcrypt_create_iv(22, MCRYPT_DEV_URANDOM); 
$hash = password_hash($password, PASSWORD_BCRYPT, array("cost" => 14, "salt" => $salt);
// Store Hash
 
if (password_verify($password, $hash)) {
    // Password Is Correct
} else {
    // Password Is Not Correct
}
?>

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, true);
?>

• INI setting for default algo - Presently, the default algorithm is identified by a constant that can be updated only with a source-code change. It may be worth while implementing an INI setting to allow that to be chosen by the host. As the proposed implementation has only a single algorithm, this may be a choice to be made in the future.

Currently, the proposed patch is not yet complete. The basic functionality is there, but it needs some refactoring and testing prior to official proposal. The Work-In-Progress can be seen on the hash_password branch of ircmaxell's fork.

The specific implementation is at password.c

Additionally, a compatibility version in PHP is maintained at Github. This can be used in PHP versions 5.3 and 5.4 and for testing.

With the nature of cryptography, future compatibility is a significant concern. In order to be safe, this functionality would need to be able to adapt to changing requirements in the future. There are a few provisions that enable future compatibility in future versions of PHP:

1. New algorithms can be added to the API. It's already designed to be extended with new algorithms. The existance of the `$algo` and `$options` parameters to `password_hash()` are designed to allow arbitrary algorithms to be implemented in the future.
2. The default algorithm is specified by a constant PASSWORD_DEFAULT. As new and stronger algorithms are added, this constant can be updated to point to the strongest at the time.
3. The default cost parameter to BCRYPT is specified in the php.ini file. This allows individual sites to tailor the cost of bcrypt for their needs. Additionally, the default value (if not set in PHP.ini) can be updated in the source from release to release to compensate for faster hardware.

• LinkedIn
• LastFM
• Hotmail
• Gawker Media

Blog Posts:

• The Rainbow Table Is Dead
• GPU Acclerated Hashing
• Speed Hashing
• How to safely store a password
• Use BCrypt Fool!

Stack Overflow Questions/Answers:

• Fundamental Difference Between Hashing And Encryption
• Many Hash Iterations: Append Salt Every Time?
• OpenSSL Digest vs Hash vs Hash_HMAC - Difference between salt - hmac
• Secure Hash and Salt for PHP Passwords
• Why do salts make dictionary attacks impossible
• SHA512 vs Blowfish and BCrypt

• Exploiting Remote Timing Attacks
• Timing Independent Array Comparison
• SSL Timing Attacks (PDF)
• Nanosecond Scale Remote Timing Attacks on PHP Applications

• BCrypt
• Crypt_BCrypt
• PBKDF2
• SCrypt

• 0.1 - Initial Draft
• 0.2 - Add ini directive for bcrypt cost
• 0.3 - Add section on future concerns
• 0.4 - Add behavioral semantics for each function