HIBP-PHP is a composer library for accessing the Have I Been Pwned and Pwned Passwords APIs (currently v3).
The HIBP API now requires an API Key that needs to be purchased at the HIBP site for any lookups that use an email address. This currently means that if you're only using this package for lookups from the PwnedPassword section of the API, then an API key isn't required.
Version 5.x has dropped support for older PHP versions (< 7.4). If you still need a version of this package to run on an older PHP version, then please use the icawebdesign/hibp-php:^4.0 tag, though the 4.x branch will no longer receive updates.
Version 6.x now requires PHP 8.1+. If you need to support previous versions of PHP, please use the icawebdesign/hibp-php:^5.0 tag. This version however, will only receive security fixes.
- PHP 8.1+
composer require icawebdesign/hibp-php:"^6.0"Now that we're targeting a minimum of PHP 8.1, this gives us the ability to utilise ReadOnly properties in objects. With this, entity getters have been removed and properties can now be accessed directly on the object.
use Icawebdesign\Hibp\Breach\Breach;
use Icawebdesign\Hibp\HibpHttp;
$breach = new Breach(new HibpHttp($apiKey));
$breachSites = $breach->getAllBreachSites();This will return a Collection of BreachSiteEntity objects.
Or we can filter for a domain the breach was listed in:
use Icawebdesign\Hibp\Breach\Breach;
use Icawebdesign\Hibp\HibpHttp;
$breach = new Breach(new HibpHttp($apiKey));
$breachSites = $breach->getAllBreachSites('adobe.com');This will return a Collection of BreachSiteEntity objects.
use Icawebdesign\Hibp\Breach\Breach;
use Icawebdesign\Hibp\HibpHttp;
$breach = new Breach(new HibpHttp($apiKey));
$breachSite = $breach->getBreach('adobe');This will return a single BreachSiteEntity.
use Icawebdesign\Hibp\Breach\Breach;
use Icawebdesign\Hibp\HibpHttp;
$breach = new Breach(new HibpHttp($apiKey));
$dataClasses = $breach->getAllDataClasses();This will return an array of Data Classes, eg;
[
"Account balances",
"Address book contacts",
"Age groups",
"Ages",
...
]use Icawebdesign\Hibp\Breach\Breach;
use Icawebdesign\Hibp\HibpHttp;
$breach = new Breach(new HibpHttp($apiKey));
$data = $breach->getBreachedAccount('[email protected]');We can retrieve unverified accounts too by specifying true for the second param (not retrieved by default):
use Icawebdesign\Hibp\Breach\Breach;
use Icawebdesign\Hibp\HibpHttp;
$breach = new Breach(new HibpHttp($apiKey));
$data = $breach->getBreachedAccount('[email protected]', includeUnverified: true);We can also filter results back to a specific breached domain by adding a domain as the 3rd param
use Icawebdesign\Hibp\Breach\Breach;
use Icawebdesign\Hibp\HibpHttp;
$breach = new Breach(new HibpHttp($apiKey));
$data = $breach->getBreachedAccount(
'[email protected]',
includeUnverified: true,
domainFilter: 'adobe.com',
);These calls will return a Collection of BreachSiteEntity objects.
The PwnedPasswd methods can now take a second param of an array to specify GuzzleHttp request options.
use Icawebdesign\Hibp\Password\PwnedPassword;
use Icawebdesign\Hibp\HibpHttp;
$pwnedPassword = new PwnedPassword(new HibpHttp($apiKey));
$count = $pwnedPassword->rangeFromHash('5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8');This will return an int of the count.
You can also check against NTLM hashes:
use Icawebdesign\Hibp\Password\PwnedPassword;
use Icawebdesign\Hibp\HibpHttp;
$pwnedPassword = new PwnedPassword(new HibpHttp($apiKey));
$count = $pwnedPassword->ntlmRangeFromHash('8846F7EAEE8FB117AD06BDD830B7586C');Get number of times the start of a hash appears in the system as above, but with padded values to help prevent fingerprinting
use Icawebdesign\Hibp\Password\PwnedPassword;
use Icawebdesign\Hibp\HibpHttp;
$pwnedPassword = new PwnedPassword(new HibpHttp($apiKey));
$hashData = $pwnedPassword->paddedRangeDataFromHash('5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8');You can also check against NTLM hashes:
use Icawebdesign\Hibp\Password\PwnedPassword;
use Icawebdesign\Hibp\HibpHttp;
$pwnedPassword = new PwnedPassword(new HibpHttp($apiKey));
$hashData = $pwnedPassword->paddedNtlmRangeDataFromHash('5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8');This will return a Collection of PwnedPassword model objects.
use Icawebdesign\Hibp\Password\PwnedPassword;
use Icawebdesign\Hibp\HibpHttp;
$pwnedPassword = new PwnedPassword(new HibpHttp($apiKey));
$hashData = $pwnedPassword->rangeDataFromHash('5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8');This will return a Collection of PwnedPassword model objects.
Get a collection of hash data from a start of a hash and matching against a full hash as above, but with padded values to help prevent fingerprinting
use Icawebdesign\Hibp\Password\PwnedPassword;
use Icawebdesign\Hibp\HibpHttp;
$pwnedPassword = new PwnedPassword(new HibpHttp($apiKey));
$hashData = $pwnedPassword->paddedRangeDataFromHash('5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8');
// Strip padded values from results
$hashData = PwnedPassword::stripZeroMatchesData($hashData, '5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8');This will return a Collection of PwnedPassword model objects.
use Icawebdesign\Hibp\Paste\Paste;
use Icawebdesign\Hibp\HibpHttp;
$paste = new Paste(new HibpHttp($apiKey));
$data = $paste->lookup('[email protected]');This will return a Collection of PasteEntity objects.
use Icawebdesign\Hibp\HibpHttp;
use Icawebdesign\Hibp\Subscription\Subscription;
$subscription = new Subscription(new HibpHttp($apiKey));
$status = $subscription->status();This will return a SubscriptionStatusEntity object.
If using the package within a Laravel application, you can use the provided facades.
First, you need to add your HIBP API key to your .env file, or your preferred method for adding values to your server environment variables.
HIBP_API_KEY=abcdefgh123456789
You can then use the facades to call the relevant methods:
// Breach
use Icawebdesign\Hibp\Facades\Breach;
$breachSites = Breach::getAllBreachSites();
// Paste
use Icawebdesign\Hibp\Facades\Paste;
$paste = Paste::lookup('[email protected]');
// PwnedPassword
use Icawebdesign\Hibp\Facades\PwnedPassword;
$count = PwnedPassword::rangeFromHash('5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8');Please see CHANGELOG for more information what has changed recently.
Please see CONTRIBUTING for details.
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
Thank you to Artem Fomenko for being the first external contributor to the package providing request options for Guzzle for the PwnedPassword methods.
The MIT License (MIT). Please see License File for more information.