Categories
bcrypt cryptography password-protection passwords php

How do you use bcrypt for hashing passwords in PHP? [duplicate]

1322

Every now and then I hear the advice “Use bcrypt for storing passwords in PHP, bcrypt rules”.

But what is bcrypt? PHP doesn’t offer any such functions, Wikipedia babbles about a file-encryption utility and Web searches just reveal a few implementations of Blowfish in different languages. Now Blowfish is also available in PHP via mcrypt, but how does that help with storing passwords? Blowfish is a general purpose cipher, it works two ways. If it could be encrypted, it can be decrypted. Passwords need a one-way hashing function.

What is the explanation?

7

  • 14

    This question has been addressed previously, and their suggestion of using a standard library is excellent. Security is a complicated matter, and by using a package designed by someone who knows what the hell they’re doing you’re only helping yourself.

    – eykanal

    May 23, 2011 at 1:44

  • 62

    @eykanal – that page doesn’t even mention bcrypt, much less explain what it is.

    – Vilx-

    May 23, 2011 at 8:18

  • 9

    @eykanal – I don’t ask an explanation of how it works. I just want to know what it is. Because whatever I can dig up on the net under the keyword “bcrypt”, can be in no way used for hashing passwords. Not directly anyway, and not in PHP. OK, by now I understand that it’s really the “phpass” package which uses blowfish to encrypt your password with a key that is derived from your password (in essence encrypting the password with itself). But referencing it as “bcrypt” is severely misleading, and that is what I wanted to clarify in this question.

    – Vilx-

    May 23, 2011 at 14:44


  • 4

    @Vilx: I’ve added more information as to why bcrypt is a one-way hashing algorithm versus an encryption scheme in my answer. There is this whole misconception that bcrypt is just Blowfish when in fact it has a totally different key schedule which ensures that plain text cannot be recovered from the cipher text without knowing the initial state of the cipher (salt, rounds, key).

    Sep 8, 2011 at 22:00

  • 1

    Also see Openwall’s Portable PHP password hashing framework (PHPass). Its hardened against a number of common attacks on user passwords.

    – jww

    Oct 11, 2014 at 23:25

1106

bcrypt is a hashing algorithm which is scalable with hardware (via a configurable number of rounds). Its slowness and multiple rounds ensures that an attacker must deploy massive funds and hardware to be able to crack your passwords. Add to that per-password salts (bcrypt REQUIRES salts) and you can be sure that an attack is virtually unfeasible without either ludicrous amount of funds or hardware.

bcrypt uses the Eksblowfish algorithm to hash passwords. While the encryption phase of Eksblowfish and Blowfish are exactly the same, the key schedule phase of Eksblowfish ensures that any subsequent state depends on both salt and key (user password), and no state can be precomputed without the knowledge of both. Because of this key difference, bcrypt is a one-way hashing algorithm. You cannot retrieve the plain text password without already knowing the salt, rounds and key (password). [Source]

How to use bcrypt:

Using PHP >= 5.5-DEV

Password hashing functions have now been built directly into PHP >= 5.5. You may now use password_hash() to create a bcrypt hash of any password:

<?php
// Usage 1:
echo password_hash('rasmuslerdorf', PASSWORD_DEFAULT)."\n";
// $2y$10$xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
// For example:
// $2y$10$.vGA1O9wmRjrwAVXD98HNOgsNpDczlqm3Jq7KnEd1rVAGv3Fykk1a

// Usage 2:
$options = [
  'cost' => 11
];
echo password_hash('rasmuslerdorf', PASSWORD_BCRYPT, $options)."\n";
// $2y$11$6DP.V0nO7YI3iSki4qog6OQI5eiO6Jnjsqg7vdnb.JgGIsxniOn4C

To verify a user provided password against an existing hash, you may use the password_verify() as such:

<?php
// See the password_hash() example to see where this came from.
$hash="$2y$07$BCryptRequires22Chrcte/VlQH0piJtjXl.0t1XkA8pw9dMXTpOq";

if (password_verify('rasmuslerdorf', $hash)) {
    echo 'Password is valid!';
} else {
    echo 'Invalid password.';
}

Using PHP >= 5.3.7, < 5.5-DEV (also RedHat PHP >= 5.3.3)

There is a compatibility library on GitHub created based on the source code of the above functions originally written in C, which provides the same functionality. Once the compatibility library is installed, usage is the same as above (minus the shorthand array notation if you are still on the 5.3.x branch).

Using PHP < 5.3.7 (DEPRECATED)

You can use crypt() function to generate bcrypt hashes of input strings. This class can automatically generate salts and verify existing hashes against an input. If you are using a version of PHP higher or equal to 5.3.7, it is highly recommended you use the built-in function or the compat library. This alternative is provided only for historical purposes.

class Bcrypt{
  private $rounds;

  public function __construct($rounds = 12) {
    if (CRYPT_BLOWFISH != 1) {
      throw new Exception("bcrypt not supported in this installation. See http://php.net/crypt");
    }

    $this->rounds = $rounds;
  }

  public function hash($input){
    $hash = crypt($input, $this->getSalt());

    if (strlen($hash) > 13)
      return $hash;

    return false;
  }

  public function verify($input, $existingHash){
    $hash = crypt($input, $existingHash);

    return $hash === $existingHash;
  }

  private function getSalt(){
    $salt = sprintf('$2a$%02d$', $this->rounds);

    $bytes = $this->getRandomBytes(16);

    $salt .= $this->encodeBytes($bytes);

    return $salt;
  }

  private $randomState;
  private function getRandomBytes($count){
    $bytes="";

    if (function_exists('openssl_random_pseudo_bytes') &&
        (strtoupper(substr(PHP_OS, 0, 3)) !== 'WIN')) { // OpenSSL is slow on Windows
      $bytes = openssl_random_pseudo_bytes($count);
    }

    if ($bytes === '' && is_readable('/dev/urandom') &&
       ($hRand = @fopen('/dev/urandom', 'rb')) !== FALSE) {
      $bytes = fread($hRand, $count);
      fclose($hRand);
    }

    if (strlen($bytes) < $count) {
      $bytes="";

      if ($this->randomState === null) {
        $this->randomState = microtime();
        if (function_exists('getmypid')) {
          $this->randomState .= getmypid();
        }
      }

      for ($i = 0; $i < $count; $i += 16) {
        $this->randomState = md5(microtime() . $this->randomState);

        if (PHP_VERSION >= '5') {
          $bytes .= md5($this->randomState, true);
        } else {
          $bytes .= pack('H*', md5($this->randomState));
        }
      }

      $bytes = substr($bytes, 0, $count);
    }

    return $bytes;
  }

  private function encodeBytes($input){
    // The following is code from the PHP Password Hashing Framework
    $itoa64 = './ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';

    $output="";
    $i = 0;
    do {
      $c1 = ord($input[$i++]);
      $output .= $itoa64[$c1 >> 2];
      $c1 = ($c1 & 0x03) << 4;
      if ($i >= 16) {
        $output .= $itoa64[$c1];
        break;
      }

      $c2 = ord($input[$i++]);
      $c1 |= $c2 >> 4;
      $output .= $itoa64[$c1];
      $c1 = ($c2 & 0x0f) << 2;

      $c2 = ord($input[$i++]);
      $c1 |= $c2 >> 6;
      $output .= $itoa64[$c1];
      $output .= $itoa64[$c2 & 0x3f];
    } while (true);

    return $output;
  }
}

You can use this code like this:

$bcrypt = new Bcrypt(15);

$hash = $bcrypt->hash('password');
$isGood = $bcrypt->verify('password', $hash);

Alternatively, you may also use the Portable PHP Hashing Framework.

13

  • @AndrewMoore Hi, I’ve actually made a question regarding my issue, I was wondering if you maybe able to spot something that I’m missing? I’m getting really desperate, and this is the only thing I need to do to go forth on my login page (stackoverflow.com/questions/11481199/…) Thank you so much!

    Jul 14, 2012 at 4:59

  • 1

    @AndrewMoore thanks, running microtime() from Bcrypt(4)to Bcrypt(9) the time goes from 0.010 to 0.314. So Bcrypt(9) is what i’ll probably do.

    Jul 16, 2012 at 23:37

  • 3

    Oh my god. Don’t use crypto code that isn’t uploaded to somewhere tied to, approved by, and peer-reviewed by people you can identify as real authorities on crypto. This isn’t about open vs. closed source. Whereever it’s uploaded to should offer visibility of the reviewed and verified source. This is about acknowledging that most of us don’t have the chops to critique crypto, and not letting the blind lead the blind. I’m seriously supposed to rely on anonymous upvotes on a wiki to tell me whether I’m compromising my customer’s data? Cause that’s all non-crypto experts can do with this.

    Aug 4, 2012 at 16:54


  • 18

    @MichaelLang: Good thing crypt() is peer-reviewed and verified then. The code above calls PHP’s crypt(), which calls the POSIX crypt() function. All the code above does more is generating a random salt (which doesn’t have to be cryptographically secure, the salt isn’t considered a secret) before calling crypt(). Maybe you should do a little research yourself before calling wolf.

    Aug 4, 2012 at 17:03


  • 32

    Please note that this answer, while good, is starting to show its age. This code (like any PHP implementation relying on crypt()) is subject to a security vulnerability pre-5.3.7, and is (very slightly) inefficient post-5.3.7 – details of the relevant issue can be found here. Please also note that the new password hashing API (backwards compat lib) is now the preferred method of implementing bcrypt password hashing in your application.

    Dec 19, 2012 at 14:48


309

+50

So, you want to use bcrypt? Awesome! However, like other areas of cryptography, you shouldn’t be doing it yourself. If you need to worry about anything like managing keys, or storing salts or generating random numbers, you’re doing it wrong.

The reason is simple: it’s so trivially easy to screw up bcrypt. In fact, if you look at almost every piece of code on this page, you’ll notice that it’s violating at least one of these common problems.

Face It, Cryptography is hard.

Leave it for the experts. Leave it for people whose job it is to maintain these libraries. If you need to make a decision, you’re doing it wrong.

Instead, just use a library. Several exist depending on your requirements.

Libraries

Here is a breakdown of some of the more common APIs.

PHP 5.5 API – (Available for 5.3.7+)

Starting in PHP 5.5, a new API for hashing passwords is being introduced. There is also a shim compatibility library maintained (by me) for 5.3.7+. This has the benefit of being a peer-reviewed and simple to use implementation.

function register($username, $password) {
    $hash = password_hash($password, PASSWORD_BCRYPT);
    save($username, $hash);
}

function login($username, $password) {
    $hash = loadHashByUsername($username);
    if (password_verify($password, $hash)) {
        //login
    } else {
        // failure
    }
}

Really, it’s aimed to be extremely simple.

Resources:

Zend\Crypt\Password\Bcrypt (5.3.2+)

This is another API that’s similar to the PHP 5.5 one, and does a similar purpose.

function register($username, $password) {
    $bcrypt = new Zend\Crypt\Password\Bcrypt();
    $hash = $bcrypt->create($password);
    save($user, $hash);
}

function login($username, $password) {
    $hash = loadHashByUsername($username);
    $bcrypt = new Zend\Crypt\Password\Bcrypt();
    if ($bcrypt->verify($password, $hash)) {
        //login
    } else {
        // failure
    }
}

Resources:

PasswordLib

This is a slightly different approach to password hashing. Rather than simply supporting bcrypt, PasswordLib supports a large number of hashing algorithms. It’s mainly useful in contexts where you need to support compatibility with legacy and disparate systems that may be outside of your control. It supports a large number of hashing algorithms. And is supported 5.3.2+

function register($username, $password) {
    $lib = new PasswordLib\PasswordLib();
    $hash = $lib->createPasswordHash($password, '$2y$', array('cost' => 12));
    save($user, $hash);
}

function login($username, $password) {
    $hash = loadHashByUsername($username);
    $lib = new PasswordLib\PasswordLib();
    if ($lib->verifyPasswordHash($password, $hash)) {
        //login
    } else {
        // failure
    }
}

References:

  • Source Code / Documentation: GitHub

PHPASS

This is a layer that does support bcrypt, but also supports a fairly strong algorithm that’s useful if you do not have access to PHP >= 5.3.2… It actually supports PHP 3.0+ (although not with bcrypt).

function register($username, $password) {
    $phpass = new PasswordHash(12, false);
    $hash = $phpass->HashPassword($password);
    save($user, $hash);
}

function login($username, $password) {
    $hash = loadHashByUsername($username);
    $phpass = new PasswordHash(12, false);
    if ($phpass->CheckPassword($password, $hash)) {
        //login
    } else {
        // failure
    }
}

Resources

Note: Don’t use the PHPASS alternatives that are not hosted on openwall, they are different projects!!!

About BCrypt

If you notice, every one of these libraries returns a single string. That’s because of how BCrypt works internally. And there are a TON of answers about that. Here are a selection that I’ve written, that I won’t copy/paste here, but link to:

Wrap Up

There are many different choices. Which you choose is up to you. However, I would HIGHLY recommend that you use one of the above libraries for handling this for you.

Again, if you’re using crypt() directly, you’re probably doing something wrong. If your code is using hash() (or md5() or sha1()) directly, you’re almost definitely doing something wrong.

Just use a library…

6

  • 7

    The salt has to be randomly generated, however it doesn’t need to come from a secure random source. The salt is not a secret. Being able to guess the next salt has no real security impact; as long as they come from a sufficiently large pool of data to generate different salts for each password encoded, you are fine. Remember, the salt is there to prevent the use of rainbow tables if your hashes come into bad hands. They are not secret.

    Jun 21, 2013 at 14:00


  • 7

    @AndrewMoore absolutely correct! However, the salt has to have enough entropy to be statistically unique. Not just in your application, but in all applications. So mt_rand() has a high enough period, but the seed value is only 32 bits. So using mt_rand() effectively limits you to only 32 bits of entropy. Which thanks to the Birthday Problem means that you have a 50% chance of collision at only 7k generated salts (globally). Since bcrypt accepts 128 bits of salt, it’s better to use a source that can supply all 128 bits ;-). (at 128 bits, 50% chance of collision happens at 2e19 hashes)…

    – ircmaxell

    Jun 21, 2013 at 14:09

  • 1

    @ircmaxell: Hense the “sufficiently large pool of data”. However your source doesn’t have to be a VERY HIGH entropy source, just high enough for the 128 bits. However, if you have exhausted all your available sources (don’t have OpenSSL, etc…) and your only fallback is mt_rand(), it is still better than the alternative (which is rand()).

    Jun 23, 2013 at 1:08


  • 4

    @AndrewMoore: absolutely. Not arguing that. Just that mt_rand and uniqid (and hence lcg_value and rand) are not first choices…

    – ircmaxell

    Jun 23, 2013 at 23:28

  • 1

    ircmaxell, thank you very much for the the password_compat library for 5.3.xx, we haven’t needed this before but now we do, on a 5.3.xx php server, and thank you for your clear advice to not try to do this logic oneself.

    – Lizardx

    Dec 8, 2015 at 23:23


48

You’ll get a lot of information in Enough With The Rainbow Tables: What You Need To Know About Secure Password Schemes or Portable PHP password hashing framework.

The goal is to hash the password with something slow, so someone getting your password database will die trying to brute force it (a 10 ms delay to check a password is nothing for you, a lot for someone trying to brute force it). Bcrypt is slow and can be used with a parameter to choose how slow it is.

10

  • 7

    Enforce whatever you want, users will manage to screw up and use the same password on multiple things. So you have to protect it as much as possible or implement something which let you not have to store any password (SSO, openID etc.).

    – Arkh

    Jan 25, 2011 at 15:49

  • 41

    No. Password hashing is used to protect against one attack : someone stole your database and want to get cleartext login + passwords.

    – Arkh

    Jan 25, 2011 at 15:54

  • 4

    @Josh K. I encourage you to try to crack some simple passwords after getting them through phpass tuned so it takes between 1ms and 10ms to compute it on your webserver.

    – Arkh

    Jan 25, 2011 at 16:02

  • 3

    Agreed. But the kind of user who will use qwerty as a password is also the kind of user who will mark down any complicated one somewhere he (and attackers) can easily read it. What using bcrypt accomplishes is that when your db goes public against your will, it’ll be harder to get to those user who have some password like ^|$$&ZL6-£ than if you used sha512 in one pass.

    – Arkh

    Jan 25, 2011 at 16:12

  • 4

    @coreyward worth noting that doing that is more harmful than not blocking at all; that is easily considered a “denial of service” vector. Just start spamming bad logins on any known accounts and you can disrupt many users very, very easily. It’s better to tarpit (delay) the attacker than outright deny access, especially if it’s a paying customer.

    – damianb

    May 21, 2012 at 0:17