README.md

Pwned Passwords

This package provides a Laravel validation rule that can be used to check a password against TroyHunt's Pwned Passwords (haveibeenpwned.com), a database containing 517,238,891 real world passwords previously exposed in data breaches.

By using this validation rule, you can prevent re-use of passwords that are unsuitable for ongoing usage, resulting in a more secure application, as your users will have a much lower risk of having their accounts taken over.

How it works

In order to protect the value of the source password being searched for, Pwned Passwords implements a k-Anonymity model that allows a password to be searched for by partial hash. This works by hashing the source password with SHA-1, and only sending the first 5 characters of that hash to the API. By checking whether the rest of the SHA-1 hash occurs within the output, we can verify both whether the password was pwned previously, and how frequently.

Installation

You can install the package via composer:

composer require ubient/laravel-pwned-passwords

Usage

Here's a few short examples of what you can do:

/**
 * Get a validator for an incoming registration request.
 *
 * @param  array  $data
 * @return \Illuminate\Contracts\Validation\Validator
 */
protected function validator(array $data)
{
    return Validator::make($data, [
        'name' => 'required|string|max:255',
        'email' => 'required|string|email|max:255|unique:users',
        'password' => 'required|string|min:6|confirmed|pwned',
    ]);
}

You can also relax the rule, allowing passwords that have been pwned multiple times. In the example below, passwords that have been pwned between 0 and 4 times are allowed:

$request->validate([
    'password' => 'required|string|min:6|confirmed|pwned:5',
]);

Of course, you can also use a Rule object instead:

use Ubient\PwnedPasswords\Rules\Pwned;

$request->validate([
    'password' => ['required', 'string', 'min:6', 'confirmed', new Pwned(5)],
]);

Handling Lookup Errors

When the Pwned Passwords API cannot be queried, the default behavior is to accept the password as non-pwned and to send a warning message to the log. While this doesn't add much value, it does allow you to be aware of when a pwned password was allowed, and to potentially manually act on this.

If you would like to automatically do something else based on this lookup error (such as marking the request as potentially pwned), or want to decline the password instead, you may create your own implementation of the LookupErrorHandler and overwrite the default binding in your application:

use Ubient\PwnedPasswords\Contracts\LookupErrorHandler;

$this->app->bind(LookupErrorHandler::class, MyCustomErrorHandler::class);

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

License

The MIT License (MIT). Please see License File for more information.