How to hash passwords in PHP

The complete step-by-step tutorial

PHP password encryption security

As a PHP developer, you must know how to store passwords securely.

For the following reasons:

• Many web attacks aim at stealing your users’ passwords.
  If passwords are stolen, you must make sure the attacker cannot decrypt them.
• Today’s strict privacy regulations require sensitive data, like passwords, to be protected. Failing to comply can result in fines.
• Password security is one of the basic PHP security features your clients expect from you.
  If you learn how to do it properly, your reputation will improve and your clients will trust you.

So, let’s start from this question: 

Are MD5 and SHA hashes secure?

(Short answer: no)

Back in the day, passwords were stored using an MD5 or SHA1 hash.

Like this:

/* User's password. */
$password = 'my secret password';

/* MD5 hash to be saved in the database. */
$hash = md5($password);

However, this technique is not safe enough.

For two reasons:

1. MD5 and SHA algorithms are too weak for today’s computational power.
2. Simple, not-salted hashes are vulnerable to “rainbow tables” and dictionary attacks.

If an attacker steals an MD5 or SHA hash, he or she can easily find out the original password too.

In other words, these hashes are almost as insecure as plain text passwords.

The solution is to use a secure hashing function: password_hash().

Let’s see how it works.

password_hash()

The password_hash() function creates a secure hash of your password.

This is how you can use it:

/* User's password. */
$password = 'my secret password';

/* Secure password hash. */
$hash = password_hash($password, PASSWORD_DEFAULT);

The result hash from password_hash() is secure because:

• It uses a strong hashing algorithm.
• It adds a random salt to prevent rainbow tables and dictionary attacks.

Once you have the password hash, you can save it directly in the database.

Let’s see how with the next examples.

How to use password_hash()

First, you need a database users table.

For example, let’s use a simplified version of the “accounts” table from my Authentication Tutorial.

This table has the following columns:

• account_id: the unique identifier of the account.
• account_name: the account username.
• account_passwd: the password hash.

This is the SQL code to create the table (you can use it with PhpMyAdmin to create the table on your development environment):

CREATE TABLE `accounts` (
  `account_id` int(10) UNSIGNED NOT NULL,
  `account_name` varchar(255) NOT NULL,
  `account_passwd` varchar(255) NOT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

ALTER TABLE `accounts`
  ADD PRIMARY KEY (`account_id`);

ALTER TABLE `accounts`
  MODIFY `account_id` int(10) UNSIGNED NOT NULL AUTO_INCREMENT;

Important:

Be sure to set the password column as a varchar.

(A varchar is a text column of variable length.)

The reason is that the size of the hash from password_hash() can change (more details on this later).

If you need help with SQL, you can find all you need here: How to use PHP with MySQL

Now, you need to connect to the database from your PHP script.

If you don’t know how, here is a simple PDO connection script you can use right away.

Just edit the connection parameters to make it work with your own environment:

/* Host name of the MySQL server. */
$host = 'localhost';

/* MySQL account username. */
$user = 'myUser';

/* MySQL account password. */
$passwd = 'myPasswd';

/* The default schema you want to use. */
$schema = 'mySchema';

/* The PDO object. */
$pdo = NULL;

/* Connection string, or "data source name". */
$dsn = 'mysql:host=' . $host . ';dbname=' . $schema;

/* Connection inside a try/catch block. */
try
{  
   /* PDO object creation. */
   $pdo = new PDO($dsn, $user,  $passwd);
   
   /* Enable exceptions on errors. */
   $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
}
catch (PDOException $e)
{
   /* If there is an error, an exception is thrown. */
   echo 'Database connection failed.';
   die();
}

Now you are ready to add a new user to the table.

Here is a full example (pdo.php is the script containing the previous database connection snippet):

/* Include the database connection script. */
include 'pdo.php';

/* Username. */
$username = 'John';

/* Password. */
$password = 'my secret password';

/* Secure password hash. */
$hash = password_hash($password, PASSWORD_DEFAULT);

/* Insert query template. */
$query = 'INSERT INTO accounts (account_name, account_passwd) VALUES (:name, :passwd)';

/* Values array for PDO. */
$values = [':name' => $username, ':passwd' => $hash];

/* Execute the query. */
try
{
  $res = $pdo->prepare($query);
  $res->execute($values);
}
catch (PDOException $e)
{
  /* Query error. */
  echo 'Query error.';
  die();
}

How to change a user’s password

The next example shows how to change the password of an existing user.

First, get the new password and create its hash with password_hash():

/* New password. */
$password = $_POST['password'];

/* Remember to validate the password. */

/* Create the new password hash. */
$hash = password_hash($password, PASSWORD_DEFAULT);

Then, update the table row having the same account ID of the current user and set the new hash.

Note: we assume the $accountId variable contains the account ID.

/* Include the database connection script. */
include 'pdo.php';

/* ID of the account to edit. */
$accountId = 1;

/* Update query template. */
$query = 'UPDATE accounts SET account_passwd = :passwd WHERE account_id = :id';

/* Values array for PDO. */
$values = [':passwd' => $hash, ':id' => $accountId];

/* Execute the query. */
try
{
  $res = $pdo->prepare($query);
  $res->execute($values);
}
catch (PDOException $e)
{
  /* Query error. */
  echo 'Query error.';
  die();
}

How to use password_verify()

To verify the password provided by a remote user, you need to use the password_verify() function.

password_verify() takes two arguments:

• the password you need to verify, as first argument
• the hash from password_hash() of the original password, as second argument

If the password is correct, password_verify() returns true.

Here is an example:

/* Include the database connection script. */
include 'pdo.php';

/* Login status: false = not authenticated, true = authenticated. */
$login = FALSE;

/* Username from the login form. */
$username = $_POST['username'];

/* Password from the login form. */
$password = $_POST['password'];

/* Remember to validate $username and $password. */

/* Look for the username in the database. */
$query = 'SELECT * FROM accounts WHERE (account_name = :name)';

/* Values array for PDO. */
$values = [':name' => $username];

/* Execute the query */
try
{
  $res = $pdo->prepare($query);
  $res->execute($values);
}
catch (PDOException $e)
{
  /* Query error. */
  echo 'Query error.';
  die();
}

$row = $res->fetch(PDO::FETCH_ASSOC);

/* If there is a result, check if the password matches using password_verify(). */
if (is_array($row))
{
  if (password_verify($password, $row['account_passwd']))
  {
    /* The password is correct. */
    $login = TRUE;
  }
}

Important:

You cannot just compare two different hashes to see if they match.

The reason is that password_hash() creates salted hashes.

Salted hashes include a random string, named “salt”, as a protection against rainbow tables and dictionary attacks.

Therefore, every hash will be different even if the source password is the same.

Try the following code. You will see that the two hashes are different, even if the password is the same:

$password = 'my password';

echo password_hash($password, PASSWORD_DEFAULT);
echo '<br>';
echo password_hash($password, PASSWORD_DEFAULT);

Note:

password_verify() only works with hashes created by password_hash().

You cannot use it to check a password against a MD5 or SHA hash.

How to increase hash security

The hash generated by password_hash() is very secure.

But you can make it even stronger with two simple techniques:

1. Increasing the Bcrypt cost.
2. Automatically updating the hashing algorithm.

Bcrypt cost

Bcrypt is the current default hashing algorithm used by password_hash().

This algorithm takes an option parameter named “cost”. The default cost value is 10.

By increasing the cost, you can make the hash more difficult to compute. The higher the cost, the longer the time needed to create the hash.

A higher cost makes more difficult to break the hash. However, it also makes the hash creation and check longer, too.

So, you want to find a compromise between security and server load.

This is how you can set a custom cost value for password_hash():

/* Password. */
$password = 'my secret password';

/* Set the "cost" parameter to 12. */
$options = ['cost' => 12];

/* Create the hash. */
$hash = password_hash($password, PASSWORD_DEFAULT, $options);

But what cost value should you set?

A good compromise is a cost value that lets your server create the hash in about 100ms.

Here is a simple test to find this value:

/* 100 ms. */
$time = 0.1;

/* Initial cost. */
$cost = 10;

/* Loop until the time required is more than 100ms. */
do
{
  /* Increase the cost. */
  $cost++;
  
  /* Check how much time we need to create the hash. */
  $start = microtime(true);
  password_hash('test', PASSWORD_BCRYPT, ['cost' => $cost]);
  $end = microtime(true);
}
while (($end - $start) < $time);

echo 'Cost found: ' . $cost;

Once you have found your cost, you can use it every time you execute password_hash() like in the previous example.

Keeping your hashes up to date with password_needs_rehash()

To understand this step, let’s see how password_hash() works.

password_hash() takes three arguments:

1. The password you need to hash
2. The hashing algorithm you want to use
3. An array of options to pass to the hashing algorithm

PHP supports different hashing algorithms, but you usually want to use the default one.

You can select the default algorithm by using the PASSWORD_DEFAULT constant, as you have seen in the previous examples.

As of June 2020, the default algorithm is Bcrypt.

However, PHP can change the default algorithm in the future, if a better and more secure algorithm is implemented.

When that happens, the PASSWORD_DEFAULT constant will point to the new algorithm. So, all the new hashes will be created using the new algorithm.

But what if you want to take all your old hashes, made with the previous algorithm, and automatically create them again with the new one?

This is where password_needs_rehash() comes into play.

This function checks if a hash has been created with a given algorithm and parameters.

For example:

/* Password. */
$password = 'my secret password';

/* Set the "cost" parameter to 10. */
$options = ['cost' => 10];

/* Create the hash. */
$hash = password_hash($password, PASSWORD_DEFAULT, $options);

/* Now, change the cost. */
$options['cost'] = 12;

/* Check if the hash needs to be created again. */
if (password_needs_rehash($hash, PASSWORD_DEFAULT, $options))
{
  echo 'You need to rehash the password.';
}

If the current default hashing algorithm is different from the algorithm used to create the hash, password_needs_rehash() returns true.

password_needs_rehash() also checks if the options parameter is different.

This is very handy if you want to update your hashes after you change a parameter like the Bcrypt cost.

This example shows how you can automatically check a password hash and update it if needed, when a remote user logs in:

/* Include the database connection script. */
include 'pdo.php';

/* Set the "cost" parameter to 12. */
$options = ['cost' => 12];

/* Login status: false = not authenticated, true = authenticated. */
$login = FALSE;

/* Username from the login form. */
$username = $_POST['username'];

/* Password from the login form. */
$password = $_POST['password'];

/* Remember to validate $username and $password. */

/* Look for the username in the database. */
$query = 'SELECT * FROM accounts WHERE (account_name = :name)';

/* Values array for PDO. */
$values = [':name' => $username];

/* Execute the query */
try
{
  $res = $pdo->prepare($query);
  $res->execute($values);
}
catch (PDOException $e)
{
  /* Query error. */
  echo 'Query error.';
  die();
}

$row = $res->fetch(PDO::FETCH_ASSOC);

/* If there is a result, check if the password matches using password_verify(). */
if (is_array($row))
{
  if (password_verify($password, $row['account_passwd']))
  {
    /* The password is correct. */
    $login = TRUE;
	
	/* Check if the hash needs to be created again. */
    if (password_needs_rehash($row['account_passwd'], PASSWORD_DEFAULT, $options))
    {
      $hash = password_hash($password, PASSWORD_DEFAULT, $options);
      
      /* Update the password hash on the database. */
      $query = 'UPDATE accounts SET account_passwd = :passwd WHERE account_id = :id';
      $values = [':passwd' => $hash, ':id' => $row['account_id']];
      
      try
      {
        $res = $pdo->prepare($query);
        $res->execute($values);
      }
      catch (PDOException $e)
      {
        /* Query error. */
        echo 'Query error.';
        die();
      }
    }
  }
}

How to automatically convert old hashes

In this example, you will implement a simple script to automatically convert old, MD5-based hashes to secure hashes created with password_hash().

This is how it works:

• When a user logs in, you first check its password with password_verify().
• If the login fails, check if the hash in the database is the MD5 hash if the password.
• If it is, then you update the hash with the one generated by password_hash().

Here is the script:

/* Include the database connection script. */
include 'pdo.php';

/* Set the "cost" parameter to 12. */
$options = ['cost' => 12];

/* Login status: false = not authenticated, true = authenticated. */
$login = FALSE;

/* Username from the login form. */
$username = $_POST['username'];

/* Password from the login form. */
$password = $_POST['password'];

/* Remember to validate $username and $password. */

/* Look for the username in the database. */
$query = 'SELECT * FROM accounts WHERE (account_name = :name)';

/* Values array for PDO. */
$values = [':name' => $username];

/* Execute the query */
try
{
  $res = $pdo->prepare($query);
  $res->execute($values);
}
catch (PDOException $e)
{
  /* Query error. */
  echo 'Query error.';
  die();
}

$row = $res->fetch(PDO::FETCH_ASSOC);

/* If there is a result, check if the password matches using password_verify(). */
if (is_array($row))
{
  if (password_verify($password, $row['account_passwd']))
  {
    /* The password is correct. */
    $login = TRUE;
    
    /* You can also use password_needs_rehash() here, as shown in the previous example. */
  }
  else
  {
    /* Check if the database contains the MD5 hash of the password. */
    if (md5($password) == $row['account_passwd'])
    {
      /* The password is correct. */
      $login = TRUE;
      
      /* Update the database with a new, secure hash. */
      $hash = password_hash($password, PASSWORD_DEFAULT, $options);
      $query = 'UPDATE accounts SET account_passwd = :passwd WHERE account_id = :id';
      $values = [':passwd' => $hash, ':id' => $row['account_id']];
      
      try
      {
        $res = $pdo->prepare($query);
        $res->execute($values);
      }
      catch (PDOException $e)
      {
        /* Query error. */
        echo 'Query error.';
        die();
      }
    }
  }
}

Conclusion

In this tutorial you learned how to use password_hash() and password_verify() to create secure hashes of your passwords (and why you should not use MD5).

You also learned how to make your password hashes more secure by setting a proper Bcrypt cost and automatically rehashing your passwords as needed.

Now it’s your turn: leave your questions and your comments below.

Images designed by Freepik.