PHP Password Library

Overview

PHPassLib is a simple, easy to use password hashing library for PHP 5.3+. Several password hashing schemes are supported by the library, including bcrypt and PBKDF2. The project is inspired by Python's Passlib.

Features

require_once 'PHPassLib.php';

Installation

PHPassLib supports multiple installation methods.

Installing via Composer

Install composer into your project, or system-wide following directions on the Composer download page.

curl -s https://getcomposer.org/installer | php

Create a composer.json configuration file in your project root.

{
    "require": {
        "rych/phpass": "3.0.*@beta"
    }
}

Finally, run the Composer installer.

php composer.phar install

Composer will download the library and install it under the vendor directory. You can then include the autoloader into your project and begin using the PHPassLib classes.

require 'vendor/autoload.php';

Installing via PEAR

pear channel-discover rchouinard.github.com/pear
pear install rych/PHPassLib-beta

Assuming your PEAR library is in your include path, you can now include the PHPassLib.php file to autoload the library classes.

require 'PHPassLib.php';

Examples

Hashing Passwords

Each hashing module is preset with sane defaults which are very easy to override if required. The available options vary from module to module, so be sure to check the documentation.

// Calculate a bcrypt hash from a password
$hash = PHPassLib\Hash\BCrypt::hash($password);

// Calculate a bcrypt hash with a specific number of rounds
$hash = PHPassLib\Hash\BCrypt::hash($password, array ('rounds' => 16));

// Check supplied password against a stored hash
if (PHPassLib\Hash\BCrypt::verify($password, $hash)) {
    // Password is valid!
}

Application Contexts

Some applications may need to pass around hashing configuration details. For this, PHPassLib provides application contexts. Contexts make it easy to configure hashing requirements in a central location.

// Configure a context to use bcrypt with a specific number of rounds
$context = new PHPassLib\Application\Context;
$context->addConfig('bcrypt', array ('rounds' => 16));

// Hash a password
$hash = $context->hash($password);

// Check supplied password against a stored hash
if ($context->verify($password, $hash)) {
    // Password is valid!
}

Migrating password schemes is also made easy thanks to application contexts. The first configuration added to a context becomes the default. All new hashes are created using the default, while passwords may be verified against any number of registered configurations. The context class also provides a needsUpdate() method, which is used to determine if the matched password hash needs to be updated using the default hash module or not.

// Passwords are currently stored as MD5-Crypt, and we need to migrate to BCrypt

// Configure a context to use bcrypt by default
$context = new PHPassLib\Application\Context;
$context->addConfig('bcrypt');

// Add the md5-crypt module so the context can verify with it
$context->addConfig('md5crypt');

// If a user attemtps to log in with either a bcrypt or md5-crypt password,
// the context will verify it.
if ($context->verify($password, $hash)) {
    // Check if the user's hash needs to be updated to bcrypt
    if ($context->needsUpdate($hash)) {
        // It does, so create a new bcrypt hash
        $newHash = $context->hash($password);
        // Store the new hash with the user record
        // ...
    }
    // ...
}

The needsUpdate() method will identify any configured hash which does not match the default configuration. This means that updating the parameters within the same module is easy as well.

Documentation

API documentation is available here. End-user documentation is on its way.