j3j5/hmac-bcrypt-laravel

A laravel hasher for the HMAC-BCrypt implementation for password hashing

0.2 2024-04-17 23:07 UTC

Requires

• illuminate/hashing: ^11.0
• illuminate/support: ^11.0

Requires (Dev)

• larastan/larastan: ^2.2
• orchestra/testbench: ^9.0
• phpunit/phpunit: ^10.0

MIT

• Julio Foulquie

README

This repository contains an implementation of the hmac-bcrypt password hashing function for the Laravel Framework. It is based on the reference implementation created by @epixoip (specifically the PHP one).

If you are asking yourself why, you can read the technical justification on the original implementation.

Installation

If you want to use it, you can use composer:

composer require j3j5/hmac-bcrypt-laravel

Configuration

On your config/hashing.php you can change the driver to hmac-bcrypt. In order to work, you need to set a pepper which should be a unique (per project) secret string. You have two options, either set HMAC_BCRYPT_PEPPER on your .env or as an environment variable, or add to your own hashing.php config file the following array:

'hmac-bcrypt' => [
    'pepper' => 'black-pepper'
],

The amount of rounds used by bcrypt is also customizable. You can use HMAC_BCRYPT_ROUNDS on your .env (or as environment variable) or add the key rounds to the hmac-bcrypt key on your hashing config.

'hmac-bcrypt' => [
    'rounds' => 15
],

Use

Now you can use it like you would use the hasher on Laravel:

$clearTextPass = 'supersecret';

$hash = Hash::make($clearTextPass);

// Now store it on the db

Later on...

if (Hash::check($clearTextPass, $hash)) {
    // eccoli qua! you can log in your user!

    // Check whether your settings have changed since last time
    if (Hash::needsRehash($hash)) {
        $newHash = Hash::make($clearTextPass);
        // Store the new hash on the db
    }
}

Final notes

Although I tried to be very careful and thorough on the implementation, I made this driver for fun so use at your own risk. I encourage you to take a dive into the code to make sure I did not miss anything important or into the tests so you can check for yourself what currently works. Underneath it uses the native PHP functions for SHA512 hash_hmac() and crypt() for the Bcrypt encryption (with a salt generated by random_bytes()), so this is not a case of building your own crypto libraries but instead, using the already available ones.