README

HIBP-PHP 是一个用于访问 Have I Been Pwned 和 Pwned Passwords API（当前为 v3）的 composer 库。

现在 HIBP API 需要一个 API 密钥，该密钥需要在 HIBP 网站上购买，用于任何使用电子邮件地址进行查找的操作。这意味着，如果您仅使用此包从 API 的 PwnedPassword 部分进行查找，则不需要 API 密钥。

版本 5.x 已取消对旧 PHP 版本（< 7.4）的支持。如果您仍然需要在此包的旧 PHP 版本上运行，请使用 icawebdesign/hibp-php:^4.0 标签，尽管 4.x 分支将不再接收更新。

版本 6.x 现在需要 PHP 8.1+。如果您需要支持之前的 PHP 版本，请使用 icawebdesign/hibp-php:^5.0 标签。然而，此版本将只接收安全修复。

需求

• PHP 8.1+

安装

composer require icawebdesign/hibp-php:"^6.0"

只读属性

由于我们现在针对的是 PHP 的最低版本 8.1，这使得我们能够利用对象中的只读属性。因此，实体获取器已被删除，现在可以直接在对象上访问属性。

Breach Sites 数据的使用示例

获取所有泄露网站

use Icawebdesign\Hibp\Breach\Breach;
use Icawebdesign\Hibp\HibpHttp;

$breach = new Breach(new HibpHttp($apiKey));
$breachSites = $breach->getAllBreachSites();

这将返回一个包含 BreachSiteEntity 对象的 Collection。

或我们可以根据泄露网站中列出的域名进行过滤

use Icawebdesign\Hibp\Breach\Breach;
use Icawebdesign\Hibp\HibpHttp;

$breach = new Breach(new HibpHttp($apiKey));
$breachSites = $breach->getAllBreachSites('adobe.com');

这将返回一个包含 BreachSiteEntity 对象的 Collection。

获取单个泄露网站

use Icawebdesign\Hibp\Breach\Breach;
use Icawebdesign\Hibp\HibpHttp;

$breach = new Breach(new HibpHttp($apiKey));
$breachSite = $breach->getBreach('adobe');

这将返回一个 BreachSiteEntity。

获取泄露网站的 数据类列表

use Icawebdesign\Hibp\Breach\Breach;
use Icawebdesign\Hibp\HibpHttp;

$breach = new Breach(new HibpHttp($apiKey));
$dataClasses = $breach->getAllDataClasses();

这将返回一个包含数据类的 array，例如；

[
  "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('test@example.com');

我们也可以通过将第二个参数指定为 true 来检索未经验证的账户（默认不检索）

use Icawebdesign\Hibp\Breach\Breach;
use Icawebdesign\Hibp\HibpHttp;

$breach = new Breach(new HibpHttp($apiKey));
$data = $breach->getBreachedAccount('test@example.com', includeUnverified: true);

我们还可以通过添加域名作为第三个参数来将结果过滤回特定的泄露域名

use Icawebdesign\Hibp\Breach\Breach;
use Icawebdesign\Hibp\HibpHttp;

$breach = new Breach(new HibpHttp($apiKey));
$data = $breach->getBreachedAccount(
    'test@example.com', 
    includeUnverified: true,
    domainFilter: 'adobe.com', 
);

这些调用将返回一个包含 BreachSiteEntity 对象的 Collection。

Pwned Passwords 的使用示例

PwnedPasswd 方法现在可以接受一个 array 作为第二个参数来指定 GuzzleHttp 请求选项。

获取哈希值的开始部分在系统中匹配完整哈希的次数

use Icawebdesign\Hibp\Password\PwnedPassword;
use Icawebdesign\Hibp\HibpHttp;

$pwnedPassword = new PwnedPassword(new HibpHttp($apiKey));
$count = $pwnedPassword->rangeFromHash('5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8');

这将返回一个表示计数的 int。

您也可以检查对 NTLM 哈希的匹配

use Icawebdesign\Hibp\Password\PwnedPassword;
use Icawebdesign\Hibp\HibpHttp;

$pwnedPassword = new PwnedPassword(new HibpHttp($apiKey));
$count = $pwnedPassword->ntlmRangeFromHash('8846F7EAEE8FB117AD06BDD830B7586C');

以填充值帮助防止指纹的方式，获取哈希值的开始部分在系统中匹配完整哈希的次数，就像上面一样

use Icawebdesign\Hibp\Password\PwnedPassword;
use Icawebdesign\Hibp\HibpHttp;

$pwnedPassword = new PwnedPassword(new HibpHttp($apiKey));
$hashData = $pwnedPassword->paddedRangeDataFromHash('5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8');

您也可以检查对 NTLM 哈希的匹配

use Icawebdesign\Hibp\Password\PwnedPassword;
use Icawebdesign\Hibp\HibpHttp;

$pwnedPassword = new PwnedPassword(new HibpHttp($apiKey));
$hashData = $pwnedPassword->paddedNtlmRangeDataFromHash('5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8');

这将返回一个包含 PwnedPassword 模型对象的 Collection。

从哈希值的开始部分获取与完整哈希匹配的哈希数据集合

use Icawebdesign\Hibp\Password\PwnedPassword;
use Icawebdesign\Hibp\HibpHttp;

$pwnedPassword = new PwnedPassword(new HibpHttp($apiKey));
$hashData = $pwnedPassword->rangeDataFromHash('5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8');

这将返回一个包含 PwnedPassword 模型对象的 Collection。

从哈希值的开始部分获取与完整哈希匹配的哈希数据集合，就像上面一样，但使用填充值帮助防止指纹

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');

这将返回一个包含 PwnedPassword 模型对象的 Collection。

Paste 列表的使用示例

获取包含指定电子邮件账户的粘贴的集合

use Icawebdesign\Hibp\Paste\Paste;
use Icawebdesign\Hibp\HibpHttp;

$paste = new Paste(new HibpHttp($apiKey));
$data = $paste->lookup('test@example.com');

这将返回一个包含 PasteEntity 对象的 Collection。

Laravel 特性

如果在Laravel应用程序中使用此包，您可以使用提供的门面。首先，您需要将您的HIBP API密钥添加到您的.env文件中，或者添加到服务器环境变量的其他方法中。

HIBP_API_KEY=abcdefgh123456789

然后，您可以使用门面来调用相关方法

// Breach
use Icawebdesign\Hibp\Facades\Breach;

$breachSites = Breach::getAllBreachSites();

// Paste
use Icawebdesign\Hibp\Facades\Paste;

$paste = Paste::lookup('test@example.com');

// PwnedPassword
use Icawebdesign\Hibp\Facades\PwnedPassword;

$count = PwnedPassword::rangeFromHash('5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8');

变更日志

有关最近更改的更多信息，请参阅变更日志。

贡献

有关详细信息，请参阅贡献指南。

安全性

如果您发现任何安全相关的问题，请通过电子邮件ian.h@digiserv.net与我们联系，而不是使用问题跟踪器。

鸣谢

• Ian.H
• 所有贡献者

感谢Artem Fomenko作为第一个外部贡献者，为PwnedPassword方法提供了Guzzle请求选项。

许可证

MIT许可证（MIT）。有关更多信息，请参阅许可证文件。