Use crypt() for password storage

Tutorials

Authentication, security, password, hash, hashing

Storing passwords in web apps

----

> There is now a `CPasswordHelper` class in `system.utils` <a href="http://github.com/yiisoft/yii/blob/master/framework/utils/CPasswordHelper.php">at GitHub</a>

> that provides an API to simplify the use of `crypt()` for password storage.

> While this wiki article remains valid, it will in due course be rewritten

> to refer to the new class as well as explain how it works.

There are many tutorials and examples that show storage of passwords in a table.

Often the methods used are substandard and very easy to crack. There are many web pages and tutorials that show how to do it wrong.

You cannot rely on a user to use a (practically) unguessable password or to not

use that password in systems other than yours. And you should not assume that

your systems are so secure that an attacker cannot get hold of the password table or a backup of it. So you need to ensure that the password hashes in the database are useless to an attacker.

A very common error I see in what I read and other people's code is fast hashes.

MD5, for example, is very fast (as are all the SHA hashes). As of Nov

2011 you can check 350 million MD5 keys per second on a commodity nVidia processor.

So no matter what you do with salts, the combination of short passwords and fast

brute force checking means your system is open to intruders if you rely on a

non-iterated message digest such as MD5 or any of the SHA algos. Most

hash functions are indeed designed to be fast to compute.

The Blowfish hash algorithm, on the other hand, is designed to be computationally expensive and is currently considered pretty good for hashing passwords. The implementation in PHP's `crypt()` is easy to use. Set a cost parameter high enough to make a brute force attack really slow. I set it so that it takes about 250 ms

on the production server which is fast enough for users to tolerate but slow enough to

defeat a brute-force attack.

Each password should have a unique salt. The salt's purpose is to make the

dictionary size in a [rainbow table](http://en.wikipedia.org/wiki/Rainbow_table)

or [dictionary attack](http://en.wikipedia.org/wiki/Dictionary_attack) so large that the attack is not

feasible. Salts used with the Blowfish hash [do not need to be

cryptographically secure](http://security.stackexchange.com/questions/7193/cryptographic-security-of-dynamically-generated-non-random-salts/7195#7195)

random strings. A salt based on a decent pseudo-random number is sufficient to defeat a rainbow table.

Some people advocate re-salting every time a user logs in. I think this is only

useful if you also limit the time interval between user logins, e.g. by locking out users that have not logged in for a long time.

As computer speed increases with time, so does the attacker's chance of succeeding with brute force. So if your software will be in use for many years it should increase the Blowfish cost parameter in line with increases in computer speed and rehash passwords next time the user logs on.

Using PHP's crypt() to store passwords

--------------------------------------

> If your PHP is older than 5.3, please read the section **Availability of crypt()’s

Blowfish option** below.

People often get confused about how to use implement a password store using `crypt()`.

It is actually very simple but it helps to know that:

* It is safe to store the salt together with the password hash. An attacker cannot use

it to make a dictionary attack easier.

* The return value from `crypt()` is the string concatenation of the salt you give it and the

hash.

* `crypt()` ignores excess characters in the input salt string.

The built-in PHP `crypt()` function's signature is:

* string **crypt** (string `$str`[, string `$salt`])



in which the

salt string's format determines the hash method. For a Blowfish hash, the format is:

`"$2a$"`, a two digit cost parameter, `"$"`, and 22 characters from the alphabet

`"./0-9A-Za-z"`. The cost must be between `04` and `31`.

For example:

```php
crypt('EgzamplPassword', '$2a$10$1qAz2wSx3eDc4rFv5tGb5t')

    >> '$2a$10$1qAz2wSx3eDc4rFv5tGb5e4jVuld5/KF2Kpy.B8D2XoC031sReFGi'

```

Notice that the first 29 characters of the returned value are the same as the salt string.

Append anything to the salt string argument and the result is unchanged:

```php
crypt('EgzamplPassword', '$2a$10$1qAz2wSx3eDc4rFv5tGb5t12345678901234567890')

    >> '$2a$10$1qAz2wSx3eDc4rFv5tGb5e4jVuld5/KF2Kpy.B8D2XoC031sReFGi'

crypt('EgzamplPassword', '$2a$10$1qAz2wSx3eDc4rFv5tGb5t$2a$10$1qAz2wSx3eDc4rFv5tGb5t')

    >> '$2a$10$1qAz2wSx3eDc4rFv5tGb5e4jVuld5/KF2Kpy.B8D2XoC031sReFGi'

```

And in particular, passing the value returned from `crypt()` back in as the salt argument:

```php
crypt('EgzamplPassword', '$2a$10$1qAz2wSx3eDc4rFv5tGb5e4jVuld5/KF2Kpy.B8D2XoC031sReFGi')

    >> '$2a$10$1qAz2wSx3eDc4rFv5tGb5e4jVuld5/KF2Kpy.B8D2XoC031sReFGi'

```

Thus we can use `crypt()` to authenticate a user by passing the hash value it

gave us previously back in as a salt when checking a password input. It is fiendishly simple:

**Create new hash**

```php
$hash = crypt($password, $salt)

```

**Validate password against a stored hash**

Compare the strings `$hash` and `crypt($password, $hash)`.

**NOTE:** We should use a constant-time string comparison algorithm to defeat

the possibility of

[timing attacks](http://blog.astrumfutura.com/2010/10/nanosecond-scale-remote-timing-attacks-on-php-applications-time-to-take-them-seriously/)

learning the result of validation. See below for an example.

## Generate a Blowfish salt

The following function will generate a salt suitable for use with `crypt()`.

```php
/**

* Generate a random salt in the crypt(3) standard Blowfish format.

*

* @param int $cost Cost parameter from 4 to 31.

*

* @throws Exception on invalid cost parameter.

* @return string A Blowfish hash salt for use in PHP's crypt()

*/

function blowfishSalt($cost = 13)

{

    if (!is_numeric($cost) || $cost < 4 || $cost > 31) {

        throw new Exception("cost parameter must be between 4 and 31");

    }

    $rand = array();

    for ($i = 0; $i < 8; $i += 1) {

        $rand[] = pack('S', mt_rand(0, 0xffff));

    }

    $rand[] = substr(microtime(), 2, 6);

    $rand = sha1(implode('', $rand), true);

    $salt = '$2a$' . str_pad((int) $cost, 2, '0', STR_PAD_RIGHT) . '$';

    $salt .= strtr(substr(base64_encode($rand), 0, 22), array('+' => '.'));

    return $salt;

}

```

Example

-------

Say I have a `user` table like this

~~~

[sql]

create table user (

    id int not null auto_increment primary key,

    username varchar(255) not null,

    password_hash char(64) not null,

    unique key (email)

)

~~~

First, consider processing the form to create a new user acount. I have (already sanitized) form input in `$form->email` and `$form->password`. I can generate the hash from the password and a salt from the `blowfishSalt()` function above:

```php
$passwordHash = crypt($form->password, blowfishSalt());

```

I can insert a row into `user` containing `$form->username` and `$passwordHash`.

When a user submits a login form, I have sanitized form input in `$form->username` and `$form->password`. To authenticate these inputs I select the record from the `user` table with matching username loading the password hash into `$record->passwordHash`

```php
if ($password_hash === crypt($form->password, $record->passwordHash))

    // password is correct

else

    // password is wrong

```

So there is no need to store the salt in a separate column from the hash value because

`crypt()` conveniently keeps it in the same string as the hash.

In a Yii webapp

------

Using `crypt()` requires very little code. Just one line in user registration and one in authentication plus the `blowfishSalt()` function from above.

### Registration

In a Yii webapp I usually have an Active Record model class `User` for the user records in the `user` DB table. In this example I have a controller action that processes the website's new account generation form. The form input is in `$form`, a `CForm` model instance with attributes `username` and `password`. Assume the model validated OK.

The controller action where you register new users might include:

```php
$user = new User;

$user->email = $form->email;

$user->password = crypt($form->password, self::blowfishSalt());

if ($user->save()) {

    ...

}

```

This assumes I put the `blowfishSalt()` function from above is a static method of this controller class.

### Authentication

To authenticate a user at logon, I follow the [auth topic in the Yii Guide](http://www.yiiframework.com/doc/guide/1.1/en/topics.auth) and write the `UserIdentity::authenticate()` method as follows. In a default `yiic webapp` this `authenticate()` is in `protected/components`.

```php
public function authenticate()

{

    $record = User::model()->findByAttributes(array('username' => $this->username));

    if ($record === null) {

        $this->errorCode = self::ERROR_USERNAME_INVALID;

    } else if ($record->password !== crypt($this->password, $record->password)) {

        $this->errorCode = self::ERROR_PASSWORD_INVALID;

    } else {

        $this->_id = $record->id;

        $this->setState('title', $record->title);

        $this->errorCode = self::ERROR_NONE;

    }

    return !$this->errorCode;

}

```

## Constant-time string comparison.

This function is based on

[this](http://codereview.stackexchange.com/questions/13512/constant-time-string-comparision-in-php-to-prevent-timing-attacks)

and

[this](https://github.com/ircmaxell/password_compat/blob/master/lib/password.php).

```php
function same($a, $b) {

    /**

     * @see http://codereview.stackexchange.com/questions/13512

     */

    if (!is_string($a) || !is_string($b)) {

        return false;

    }

    $mb = function_exists('mb_strlen');

    $length = $mb ? mb_strlen($a, '8bit') : strlen($a);

    if ($length !== ($mb ? mb_strlen($b, '8bit') : strlen($b))) {

        return false;

    }

    $check = 0;

    for ($i = 0; $i < $length; $i += 1) {

        $check |= (ord($a[$i]) ^ ord($b[$i]));

    }

    return $check === 0;

}

```

## Availability of `crypt()`'s Blowfish option

The `crypt()` function has ben part of PHP for a long time but not all PHP installations

have all its options.

I use the Blowfish hash option which is available in all PHP systems since 5.3.0.

It is also available in pre-5.3 PHPs (including PHP 4) if the operating system has the Blowfish hash option in

its standard library [`crypt(3)`](http://www.freebsd.org/cgi/man.cgi?query=crypt&sektion=3) function, as many *nix systems do. Failing this, the [Suhosin patch](http://www.hardened-php.net/suhosin/index.html) will provide the Blowfish hash in an old PHP system.

PHP's `CRYPT_BLOWFISH` constant is `true` if and only if the system has Blowfish.

It can

be tricky to implement good password hashing on PHP systems that do not have Blowfish in `crypt()`. I do not have any recommendations other than to upgrade your PHP or

move to a host with an up-to-date PHP.

Be careful of slow hash function implementations in PHP. The important thing is that the hash takes a lot of compute time *on the attackers equipment* and takes the minimum possible on yours. A hash implemented in PHP puts you at a disadvantage relative to the attacker. For example, imagine you iterate SHA-1 in in PHP for one second on a Micro instance on Amazon EC2 while the attacker has the same algorithm optimized to run on $5k's worth of modern GPUs. I don't know how many orders of magnitude faster the attacker's algorithm is than yours but I think its enough so that you should feel unsafe with such an implementation.**Update**: This wiki has been rewritten to be in line with Yii 1.1.14. Since many of the detailed complexities are now handled by Yii, the article focuses on how the `crypt()` built-in function works and why it's important to use it correctly.

# Storing passwords in php web apps

There are many tutorials and examples that show storage of passwords in a table.

Often the methods used are substandard and very easy to crack. For example, the

["Agile Web Application Development with Yii1.1 and PHP5"](http://www.yiiframework.com/doc/)

book's example stores `md5($password)` in the DB and calls it

"encryption". It is not. ["The Yii Blog Tutorial"](http://www.yiiframework.com/doc/blog/1.1/en/prototype.auth),

(prior to Yii version 1.1.13) was a little better in

that it used a salt but it still used md5 and is easy to crack. (Since 1.1.14 Yii has a

[CPasswordHelper](http://www.yiiframework.com/doc/api/1.1/CPasswordHelper) class which

the Blog Tutorial uses.)

The [yii-user](http://www.yiiframework.com/extension/yii-user)

and [yii-user-management](http://www.yiiframework.com/extension/yii-user-management) extensions

are similarly insecure.

Examples of the same errors abound and are by no means limited to webapps implemented in Yii or PHP.

You cannot rely on a user to use a (practically) unguessable password or to not

use that password in systems other than yours. And you should not assume that

your server is so secure that an attacker cannot get hold of the password file/table or a backup of it.

A very common error I see in what I read and other people's code is fast hashes.

MD5, for example, is very fast. As of Nov

2011 you can check 350 million keys per second on a commodity nVidia processor.

(Update: two years later the technology for brute force password cracking has

advanced to a frightening degree and is moving fast.)

So no matter what you do with salts, the combination of short passwords and fast

brute force checking means your system is open to intruders if you rely on a

non-iterated message digest such as MD5 or any of the SHA algos. Most

hash fuctions are indeed designed to be fast to compute.

The Blowfish hash function is currently considered pretty good. It is designed to be slow. The

implementation in PHP's `crypt()` is easy to use. Set a cost parameter high enough

to make a brute force attack really slow. I set it so that it takes about 250 ms

on the production server which is fast enough for users to tolerate but slow enough to

defeat a brute-force attack.

Each password should have its own salt. The salt's purpose is to make the

dictionary size in a [rainbow table](http://en.wikipedia.org/wiki/Rainbow_table)

or [dictionary attack](http://en.wikipedia.org/wiki/Dictionary_attack) so large that the attack is not

feasible. Salts used with the Blowfish hash [do not need to be

cryptographically secure](http://security.stackexchange.com/questions/7193/cryptographic-security-of-dynamically-generated-non-random-salts/7195#7195)

random strings but they do need to be unique. A long enough string from

an operating system's CSPRNG in

non-blocking mode (e.g. `/dev/urandom` on Linux) is pretty good.

Some people advocate resalting every time a user logs in. I think this is only

useful if you also limit the time interval between user logins, e.g. block an

account if the user hasn't logged in in more than *N* weeks.

If your software will be in use for many years then  you should increase the cost

factor in line with increases in computer speed. You will need to rehash passwords

when do.

Using PHP's crypt() to store passwords

--------------------------------------

People often get confused about how to use implement a password store using `crypt()`.

It is actually very simple but it helps to know that:

* It is safe to store the salt together with the password hash. An attacker cannot use

it to make a dictionary attack easier.

* The string `crypt()` returns is the concatenation of the salt you give it and the

hash value.

* `crypt()` ignores excess characters in the input salt string.

`crypt()` has function signature `string crypt (string $str, string $salt)` and the

salt string format determines the hash method. For Blowfish hashing, the format is:

`"$2a$"`, a two digit cost parameter, `"$"`, and 22 digits from the alphabet

`"./0-9A-Za-z"`. The cost must be between `04` and `31`.

Notice how the first 29 characters are the same as the salt string:

    crypt('EgzamplPassword', '$2a$10$1qAz2wSx3eDc4rFv5tGb5t')

        >> '$2a$10$1qAz2wSx3eDc4rFv5tGb5e4jVuld5/KF2Kpy.B8D2XoC031sReFGi'

The characters from position 30 onwards are the hash.

Notice also how anthing appended to the salt string argument has no effect on the result:

    crypt('EgzamplPassword', '$2a$10$1qAz2wSx3eDc4rFv5tGb5t12345678901234567890')

        >> '$2a$10$1qAz2wSx3eDc4rFv5tGb5e4jVuld5/KF2Kpy.B8D2XoC031sReFGi'

    crypt('EgzamplPassword', '$2a$10$1qAz2wSx3eDc4rFv5tGb5t$2a$10$1qAz2wSx3eDc4rFv5tGb5t')

        >> '$2a$10$1qAz2wSx3eDc4rFv5tGb5e4jVuld5/KF2Kpy.B8D2XoC031sReFGi'

And in particular, pass the value returned from `crypt()` back in as the salt argument:

    crypt('EgzamplPassword', '$2a$10$1qAz2wSx3eDc4rFv5tGb5e4jVuld5/KF2Kpy.B8D2XoC031sReFGi')

        >> '$2a$10$1qAz2wSx3eDc4rFv5tGb5e4jVuld5/KF2Kpy.B8D2XoC031sReFGi'

So we can use `crypt()` to authenticate a user by passing the hash value it

gave us previously back in as a salt when checking a password input.

##Example (simplistic)

Say we have a `user` table like this

    create table user (

        id int,

        email varchar(255),

        password_hash varchar(64)

    )

From a user account generation form, assume that we have (already sanitized) user input in

`$form->email` and `$form->password`. We generate the hash:

    $salt = openssl_random_pseudo_bytes(22);

    $salt = '$2a$%13$' . strtr($salt, array('_' => '.', '~' => '/'));

    $password_hash = crypt($form->password, $salt);

And insert a row into `user` containing `$form->email` and `$password_hash`.

At user logon assume we again have sanitized user input in `$form->email` and `$form->password`.

To authenticate these against the accounts in `user` we select the `password_hash` field from table `user` where `email` = `$form->email` and, with that value in `$password_hash`

    if ($password_hash === crypt($form->password, $password_hash))

        // password is correct

    else

        // password is wrong

So there is no need to store the salt in a separate column from the hash value because

`crypt()` conveniently keeps it in the same string as the hash.

While this example shows how `crypt()` works, it is too simplistic for practical

use. It glosses over several important

details including: how to obtain a decent salt (the example assumes OpenSSL

is available), what value to use for the cost parameter (the example arbitrarily

uses 13), and what function to use to compare the retrieved database hash value with

the computed value (`===` is simple but might be vulnerable to timing attacks).

The APIs in Yii's CSecurityManager and CPasswordHelper are intended to help the

user deal with these matters.

### In Yii

As of version 1.1.14, Yii has an API to help users with secure password storage:

[CPasswordHelper](http://www.yiiframework.com/doc/api/1.1/CPasswordHelper). The

[Blog Tutorial](http://www.yiiframework.com/doc/blog/1.1/en/prototype.auth)

shows how it can be used.

# Availability of crypt()'s Blowfish option

The `crypt()` function has ben part of PHP for a long time but not all PHP installations

have all its options. The Blowfish hash option is available in all PHP systems since 5.3.

It is also available in older PHPs if either the operating system has the option in

its standard library [`crypt(3)`](http://en.wikipedia.org/wiki/Crypt_(Unix)) function

(e.g. many Unix and Linux systems) or if

PHP has the [Suhosin patch](http://www.hardened-php.net/suhosin/index.html).

PHP's `CRYPT_BLOWFISH` constant is `true` if the system has Blowfish.

I have not found a solution that I can recommend to provide secure password storage

when `crypt()`'s Blowfish option is absent. If you want to be secure you have to make

this a requirement of your PHP runtime environemnt or take matters into your own

hands.

Some people have commented that [phpass](http://www.openwall.com/phpass/) has fallback

algorithms when `CRYPT_BLOWFISH` is false and asked what's wrong with that. They

are not sufficiently secure, in my opinion, to recommend and that's why [I don't

recommend phpass](https://github.com/yiisoft/yii/issues/2788).

Categories

Popular Tags

Recent Comments

Difference between #11 and #14 of
Use crypt() for password storage

Changes

Title unchanged

Category unchanged

Yii version unchanged

Tags unchanged

Content changed

Revisions