NAME

    WebService::HIBP - An interface to the Have I Been Pwned webservice at
    haveibeenpwned.com

VERSION

    Version 0.02

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.

 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>.
    The entire data set is both downloadable and searchable online via the
    Pwned Passwords page <https://haveibeenpwned.com/Passwords>.

    Each password is stored as a SHA-1 hash of a UTF-8 encoded password.
    The downloadable source data delimits the full SHA-1 hash and the
    password count with a colon (:) and each line with a CRLF.

    In order to protect the value of the source password being searched
    for, this method implements a k-Anonymity model that searches for a
    password by partial hash. This method sends the first 5 characters of a
    SHA-1 password hash to be passed to the Pwned Passwords API
    <https://haveibeenpwned.com/API/v2#PwnedPasswords>.

    The Pwned Passwords API
    <https://haveibeenpwned.com/API/v2#PwnedPasswords> will respond 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 then searches the results of the response for the presence of
    their source hash and if not found, the password does not exist in the
    data set.

    It returns the count of how many times it appears in the data set or
    "0" if it dosen't appear.

 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.

    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.

 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).

 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.

 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.

 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.

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{no_proxy} and
    $ENV{HTTP_PROXY} as defaults for calls to the
    https://haveibeenpwned.com/api/v2/ API via the LWP::UserAgent module.

DEPENDENCIES

    WebService::HIBP requires the following non-core modules

      JSON
      LWP::UserAgent
      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 2018 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.

