README

Introduction

The haveibeenpwned.com site is a project by Troy Hunt which allows you to check, if your account has been compromised in a recent password disclosure by submitting an email address. You can find more info about the site in the corresponding blogpost.

The site also provides a RESTful remote API. This library is a simple PHP client implementation, which can interact with that API. It is both a client library and a client CLI - you can use it in your project or you can use the provided CLI.

Features

lightweight and easily extendable
SSL support with peer verification
ready to use CLI

Dependencies

PHP >= 5.3.4
zendframework/zend-http - the ZF2 HTTP client implementation
zendframework/zend-json - the ZF2 JSON encoder/decoder implementation
symfony/console - the Console component from the Symfony object, used to implement the CLI
cURL - for SSL support

Installation

The easiest way to install the library is through composer.

To use it as a standalone CLI:

$ php composer.phar create-project ivan-novakov/php-haveibeenpwned-client php-haveibeenpwned-client ~1

To add it to your project:

$ php composer.phar require ivan-novakov/php-haveibeenpwned-client:~1

CLI

The library comes with ready to use command line interface based on the Symfony Console component.

Usage:

bin/hibp.php check [--ssl] [--ca-file="..."] [--plain] [--show-exceptions] email

Options:

--ssl - Use SSL when connecting to the remote service
--ca-file - Use an alternative CA file
--plain - Use simple output, suitable for parsing
--show-exceptions - Show the exception (if any) instead of the error message, suitable for debugging

Library

Basic usage

use InoHibp\Service;

$service = new Service();
try {
    $result = $service->checkEmail($email);
} catch (\Exception $e) {
    // handle exception
}

if (null === $result) {
    printf("Not pwned\n");
} else {
    printf("Pwned on these websites: %s\n", implode(', ', $result));
}

The checkEmail() method returns either null if the email has not been pwned, or an array of site names, where the corresponding account has been compromised. In case of an error an exception is thrown.

SSL connections

By default a HTTP connection is used. To enforce a SSL connection you need to initialize the service with the use_ssl option:

$service = new Service(array(
    'use_ssl' => true
));

The library uses the cURL PHP extension to handle SSL connections. It is configured to perform peer and host verification (CURLOPT_SSL_VERIFYPEER = true, CURLOPT_SSL_VERIFYHOST = 2). For more information on how to handle SSL connections in PHP (ZF2), see my blogpost HTTPS connections with Zend Framework 2.

The peer is verified against the CA root certificate of the haveibeenpwned.com site. The CA root certificate is stored in ssl/ca-bundle.pem. If for some reason you need to change that, you can specify alternative path to the bundle:

$service = new Service(array(
    'use_ssl' => true,
    'ca_file' => /alternative/path/ca-bundle.pem
));

Exceptions

InoHibp\Exception\InvalidEmailException - the site has returned status code 400, which means, that the email has wrong format
InoHibp\Exception\UnexpectedResponseException - unexpected status code, anything different from the supported codes (see the docs)
InoHibp\Exception\InvalidResponseFormatException - thrown when the status code is 200 and a JSON encoded list of sites is expected, but the parsing fails
InoHibp\Exception\TransportException - HTTP connection error
InoHibp\Exception\InvalidCaFileException - indicates a problem with the file containing the root CA certificate of the server (unreadable, invalid format, etc.)

License

BSD 3 Clause

Author

Ivan Novakov

ivan-novakov / php-haveibeenpwned-client

Maintainers

Details