NAME
WebService::HIBP - An interface to the Have I Been Pwned webservice at
haveibeenpwned.com
VERSION
Version 0.15
SYNOPSIS
Check the security of your accounts/email addresses and passwords
use WebService::HIBP();
use IO::Prompt();
my $hibp = WebService::HIBP->new();
my $new_password = IO::Prompt::prompt(-echo => q[*], 'Enter your new password:');
my $count = $hibp->password($new_password);
if ($count == 0) {
} elsif ($count <= 2) {
warn "This password has been found in a data breach\n";
} elsif ($count) {
die "This password is too insecure\n";
}
DESCRIPTION
This is a client module for the https://haveibeenpwned.com/api/v2/ API,
which provides a searchable interface to account/password breaches and
pastes on sites such as pastebin.com
SUBROUTINES/METHODS
new
a new WebService::HIBP object, ready to check how bad the pwnage is. It
accepts an optional hash as a parameter. Allowed keys are below;
* user_agent - A pre-configured instance of LWP::UserAgent that will
be used instead of the automatically created one. This allows full
control of the user agent properties if desired
* api_key - User provided API key to access HaveIBeenPwned API, see
https://haveibeenpwned.com/API/v3#Authorisation and
https://haveibeenpwned.com/API/Key for details.
password
The Pwned Passwords API
<https://haveibeenpwned.com/API/v2#PwnedPasswords> has more than half a
billion passwords which have previously been exposed in data breaches.
The service is detailed in the launch blog post
<https://www.troyhunt.com/introducing-306-million-freely-downloadable-pwned-passwords/>
then further expanded on with the release of version 2
<https://www.troyhunt.com/ive-just-launched-pwned-passwords-version-2>.
In order to protect the value of the source password being searched
for, this method implements a k-Anonymity
<https://en.wikipedia.org/wiki/K-anonymity> model that searches for a
password by partial hash. This method therefore only sends the first 5
characters of a SHA-1 hash of the password (the prefix) to the Pwned
Passwords API <https://haveibeenpwned.com/API/v2#PwnedPasswords>.
The Pwned Passwords API
<https://haveibeenpwned.com/API/v2#PwnedPasswords> responds with a list
of the suffix of every hash beginning with the specified prefix,
followed by a count of how many times it appears in the data set. This
method searches the results of the response for a matching hash suffix.
This method then returns the count of how many times it appears in the
data set or "0" if it doesn't appear.
use WebService::HIBP();
use IO::Prompt();
my $hibp = WebService::HIBP->new();
my $new_password = IO::Prompt::prompt(-echo => q[*], 'Enter your new password:');
my $count = $hibp->password($new_password);
if ($count == 0) {
} elsif ($count <= 2) {
warn "This password has been found in a data breach\n";
} elsif ($count) {
die "This password is too insecure\n";
}
account
The most common use of the API is to return a list of all breaches a
particular account has been involved in. The API takes a single
parameter which is the account to be searched for. The account is not
case sensitive and will be trimmed of leading or trailing white spaces.
Returns a list of breaches.
Parameters:
* truncate - Returns only the name of the breach.
* domain - Filters the result set to only breaches against the domain
specified. It is possible that one site (and consequently domain), is
compromised on multiple occasions.
* unverified - Returns breaches that have been flagged as
"unverified". By default, only verified breaches are returned web
performing a search.
use WebService::HIBP();
use v5.10;
my $hibp = WebService::HIBP->new();
foreach my $breach ( $hibp->account( 'test@example.com', domain => 'adobe.com' ) ) {
say $breach->name();
}
breach
Sometimes just a single breach is required and this can be retrieved by
the breach name. This is the stable value which may or may not be the
same as the breach title (which can change). Returns a list of
breaches.
use WebService::HIBP();
use v5.10;
my $hibp = WebService::HIBP->new();
my $breach = $hibp->breach( 'Adobe' );
say $breach->title();
breaches
A breach is an instance of a system having been compromised by an
attacker and the data disclosed. For example, Adobe was a breach,
Gawker was a breach etc. This method returns the details of each of
breach in the system.
Parameters:
* domain - Filters the result set to only breaches against the domain
specified. It is possible that one site (and consequently domain), is
compromised on multiple occasions. Returns a list of breaches.
use WebService::HIBP();
use v5.10;
my $hibp = WebService::HIBP->new();
foreach my $breach ( $hibp->breaches( domain => 'adobe.com' ) ) {
say $breach->name();
}
data_classes
A "data class" is an attribute of a record compromised in a breach. For
example, many breaches expose data classes such as "Email addresses"
and "Passwords". The values returned by this service are ordered
alphabetically in a string array and will expand over time as new
breaches expose previously unseen classes of data.
use WebService::HIBP();
use v5.10;
my $hibp = WebService::HIBP->new();
foreach my $class ( $hibp->data_classes() ) {
say $class;
}
pastes
This method takes a single parameter which is the email address to be
searched for. Unlike searching for breaches, usernames that are not
email addresses cannot be searched for. The email is not case sensitive
and will be trimmed of leading or trailing white spaces. Returns a list
of pastes.
use WebService::HIBP();
use v5.10;
my $hibp = WebService::HIBP->new();
foreach my $paste ( $hibp->pastes( 'test@example.com' ) ) {
say $paste->source();
}
last_request
This method returns the request that was sent to the
https://haveibeenpwned.com/api/v2/ API. This method is intended to only
aid troubleshooting in the event of an error response.
last_response
This method returns the response that came from the
https://haveibeenpwned.com/api/v2/ API. This method is intended to only
aid troubleshooting in the event of an error response.
DIAGNOSTICS
Failed to retrieve %s
The URL could not be retrieved. Check network and proxy settings.
CONFIGURATION AND ENVIRONMENT
WebService::HIBP requires no configuration files or environment
variables. However, it will use the values of $ENV{HTTPS_PROXY} as a
default for calls to the https://haveibeenpwned.com/api/v2/ API via the
LWP::UserAgent module.
DEPENDENCIES
WebService::HIBP requires the following non-core modules
Encode
Unicode::Normalize
JSON
LWP::UserAgent
LWP::Protocol::https
URI::Escape
Digest::SHA
INCOMPATIBILITIES
None reported
BUGS AND LIMITATIONS
Please report any bugs or feature requests to bug-webservice-hibp at
rt.cpan.org, or through the web interface at
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WebService-HIBP. I will
be notified, and then you'll automatically be notified of progress on
your bug as I make changes.
AUTHOR
David Dick, <ddick at cpan.org>
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc WebService::HIBP
You can also look for information at:
* RT: CPAN's request tracker (report bugs here)
http://rt.cpan.org/NoAuth/Bugs.html?Dist=WebService-HIBP
* AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/WebService-HIBP
* CPAN Ratings
http://cpanratings.perl.org/d/WebService-HIBP
* Search CPAN
http://search.cpan.org/dist/WebService-HIBP/
ACKNOWLEDGEMENTS
Thanks to Troy Hunt for providing the service at
https://haveibeenpwned.com
POD was extracted from the API help at
https://haveibeenpwned.com/API/v2
LICENSE AND COPYRIGHT
Copyright 2019 David Dick.
This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.