View source for Storing Passwords Safely

== Storing passwords securely and safely ==

One of the really common things you do when building web apps is storing passwords for user accounts. Here's what you need to know:

* Don't store the actual password typed in by the user. Use hashing instead.                   
* But actually, don't hash the password alone - use a salt, and a different one for each password            
* And don't use a simple hash function like md5 - if you are using PHP 5.5.0 or greater (which you really '''should be''') you should use '''password_hash()''' and '''password_verify()''' directly, otherwise use the [https://github.com/ircmaxell/password_compat compatibility library] for those functions.
* Don't ever implement your own password hashing - use a library or the built in password functions.

I'll go into each of these in detail. Please note that the sections below on how hashes work are for reference only and '''should not be copy and pasted into any script'''. As mentioned, you should never ever write your own hashing in a real world situation and you really should only be using password_verify() and password_hash(), or a library which uses these functions. 

== Don't store the actual password typed in by the user. Use hashing instead. == 

Doing this is incredibly bad because:
* if your password file is disclosed people can log in using those passwords
* people re-use passwords, so an attack on your site can lead to you being responsible for other sites being hacked

So, if you're not storing passwords, how do you check user logins? The most obvious answer is to store a simple hash of the password, and this is what most beginners to PHP would use. A hash is a one-way process - the idea is that if you hash the string 'abc', you'll get something like '5eb63bbbe01eeed093cb22bb8f5acdc3', and there's no simple function to go backwards. Hashes are used for lots of things in computer science, and there are lots of different hash algorithms, ''some more secure than others''.

To check that a user's password matches the hash you have on file, you don't 'decrypt' the hash. Instead, you run the hash algorithm again, and check that the results match. Hashes are deterministic - they always return the same result for the same input. 

So, in pseudocode, where you might do the following; 

<source>
 store($userpassword);
 // some time later
 $userpassword = fetch();
 if($suppliedpassword == $userpassword) { 
 	// log in 
 } else { 
 	// failed login 
 }
</source>

Instead, you might try something like:

<source>
 store(hashpassword($userpassword));
 // some time later
 $userpassword = fetch();
 if(hashpassword($suppliedpassword) == $userpassword) { 
 	// log in 
 } else {  
 	// failed login 
 }
</source>

This won't solve the problem though, as it has many inherent flaws (this is why this is provided in pseudocode rather than PHP, to discourage copy and paste). To find out why this is bad, and for better solutions, keep reading!

== Don't hash the password alone - use a salt, and a different one for each password ==

One approach to breaking hashed passwords is to pre-compute dictionaries of hashes for a sensible set of possible passwords. That is, since we know that lots of people use 'password123' as their password, we can pre-compute the hash of that password, and in fact all short words or strings.

Salting is a straightforward way of making dictionary attacks useless - it still allows brute forcing, but it helps a lot. A salt is a random string that's added to the user's password before it's hashed, and is then stored with the resulting hash. When you come back to check the password later, you take the same salt, add it to the password again, and rehash.

There are few things you should note about salts:

* The salt should be different for every hash - never use a single salt for your whole application!
* It's most convenient to store the salt with the hash - many hashing libraries will actually give you back both the hash and the salt packed together in one string by concatenation.
* Salts should really be generated by a cryptographically secure PRNG (pseudo-random number generator) - this is not something you should attempt yourself. As with most security functions, it is best left to tried and tested, peer reviewed existing functionality.

== Don't use a simple hash function like md5 - use password_verify() and password_hash(), or a cryptographic hash function such as bcrypt ==

There are lots of hash functions and they have quite different features. md5 is probably the most well-known, but it's actually a terrible hash for use with passwords - the thing is that md5 is designed to be fast. This is actually a major failing in a password hash, because the faster the hash, the faster you can brute force it.

In modern PHP you should use [http://php.net/manual/en/function.password-hash.php password_hash()] and [http://php.net/manual/en/function.password-verify.php password_verify()], which are available as built in functions since PHP 5.5 which has been around since mid-2013. These have tried and tested security, and are future-proof as they allow you to re-hash your passwords (increase the length of time taken to verify them) as and when required.

=== Using password_hash() and password_verify() - RECOMMENDED ===

To use [http://php.net/manual/en/function.password-hash.php password_hash()] and [http://php.net/manual/en/function.password-verify.php password_verify()], pass the password provided by the user and the password from your database to the password_verify() function. To create a new password for a user, use the [http://php.net/manual/en/function.password-hash.php password_hash()] function.

For example, to verify a password:

<source>
 <?php
 
 if (password_verify($plaintext_password_from_user, $password_hash_from_database)) {
     echo 'Password is valid!';
 } else {
     echo 'Invalid password.';
 }
</source>

And to create a new password in the database:

<source>
 <?php
 
 $hashed_secure_password = password_hash($plaintext_password_from_user, PASSWORD_DEFAULT);
 
 // You'll have to implement this yourself...
 savePasswordtoDatabase($username, $hashed_secure_password);
</source>

As time progresses, computers will become more powerful and the possibility of someone using end-user hardware to break your passwords will increase. To prevent this, you should periodically re-hash your passwords whenever PHP says you should, you should check this when users log in, for example:

<source>
 <?php
 
 // The cost parameter is a metric of how long the hash takes to generate. It should be increased as hardware and ability to brute force passwords improves.
 $options = array('cost' => 11);

 if (password_verify($plaintext_password_from_user, $hashed_password_from_database)) {
     // Check if a newer hashing algorithm is available
     // or the cost has changed
     if (password_needs_rehash($hashed_password_from_database, PASSWORD_DEFAULT, $options)) {
         // If so, create a new hash, and replace the old one
         $newHash = password_hash($plaintext_password_from_user, PASSWORD_DEFAULT, $options);

         // This is left as an exercise to the reader...
         saveUpdatedPasswordToDatabase($newHash);

     } 
 
     // Log user in
 }
</source>

=== Using the compatibility library for 5.3 ===

There is a [https://github.com/ircmaxell/password_compat compatibility library] available for PHP 5.3 and above, which implements the password_hash and password_verify functions on older PHP. You can use these to add the functionality to older PHP if for some reason you are forced to use an older version of PHP.

For example, first install it via composer:

<source>
 $ composer require ircmaxell/password_compat
</source>

Then, you can simply autoload it and it will operate exactly like the built-in functions:

<source>
 <?php
 require 'vendor/autoload.php';
 
 $hashed_secure_password = password_hash("somepasswordhere123!", PASSWORD_DEFAULT);
</source>

=== Using bcrypt (discouraged) ===

A good cryptographic hash is bcrypt, or CRYPT_BLOWFISH. It's designed for just this purpose - it's very slow, and you can turn the knob to make it slower by adjusting its cost. This means that as computers become faster, you can rebuild your hashes to become slower and slower to process. It sounds silly to have functions be deliberately slow, but the point is that when you're using it to check a password, generally it doesn't matter if the hash takes a tenth of a second or whatever to finish - you're only doing it once. But for someone brute forcing millions of passwords, that's suddenly very hard for them.

Here's how to use bcrypt in PHP. '''Remember, don't actually use this in your code. Use password_hash and password_verify, and consider this just for educational purposes!'''

<source>
 <?php
 function hashpassword($password) {
 $rounds = '09'; // the cost of the hash - increase as hardware permits
 // generate a random salt - borrowed from http://nz.php.net/manual/en/function.crypt.php#102278
 $salt = substr(str_replace('+', '.', base64_encode(pack('N4', mt_rand(), mt_rand(), mt_rand(), mt_rand()))), 0, 22);

 // build a bcrypt formatted hash
 $hashformat = '$2a$'.$rounds.'$'.$salt;

 // do the hash
 $hash = crypt($password,$hashformat);
 return $hash;
 }

 function checkpassword($password, $hash) {
 if(crypt($password,$hash) == $hash) {
 return true;
 } else {
 return false;
 }
 }

 $hash = hashpassword('password123');

 echo "Hash was $hash";

 if(checkpassword('password123',$hash) {
 echo 'Authentication succeeded';
 } else {
 echo 'Authentication failed';
 }
</source>

== Don't implement your own hashing - use a library or the built in password functions ==

Ignoring everything above, the problem with writing your own security software is that you're likely to have bugs in it. In general, it's a better idea to use code written by someone else who's a security professional and that's been reviewed and used in practice.

If you are unable to use the built in password_verify and password_hash functions, or the compatibility library ('''WHY?''' PHP 5.3 has been out since 2009!) You could use [http://www.openwall.com/phpass/ phpass], which has been well-tested and is used by a wide variety of open source apps. It implements bcrypt as above, with various other nice features. '''Please note however that as of 2017 even the authors of phpass recommend that instead of using their library, you should use password_verify and password_hash wherever possible.'''

Here's the equivalent code using phpass:

<source>
 <?php
 
 require 'PasswordHash.php';
 
 $hasher = new PasswordHash(9, false);
 $hash = $hasher->HashPassword('password123');
 
 if ($hasher->CheckPassword('password123', $hash)) {
 echo 'Authentication succeeded';
 } else {
 echo 'Authentication failed';
 }
</source>

== Important sidenote ==

If your website uses passwords at all, you should consider only allowing access to your website over SSL. If you do not, you are introducing a weak link in the chain and as previously mentioned people re-use their passwords, so if your site is the only one not using SSL, it will become the target for sniffing of plaintext passwords "off the wire" by attackers.

SSL is free and easy to obtain via [https://letsencrypt.org/ letsencrypt], so there really is no excuse to avoid it these days. This is not directly related to securely storing passwords, but if you disregard this important note, you will severely weaken the security of any other technical measures you put into effect, no matter how securely your passwords are stored.

== Further reading == 

* http://php.net/manual/en/function.password-verify.php
* http://php.net/manual/en/function.password-hash.php
* http://php.net/manual/en/function.password-needs-rehash.php
* http://www.php.net/manual/en/faq.passwords.php
* http://hashphp.org/hashing.html
* http://php.ss23.geek.nz/2011/01/12/Using-crypt.html
* http://codahale.com/how-to-safely-store-a-password/
* http://www.openwall.com/phpass/
* http://en.wikipedia.org/wiki/Salt_%28cryptography%29
* http://en.wikipedia.org/wiki/Hash_function