Skip to content

The ultimate Java library for Troy Hunt's ';-- Have I Been Pwned (v3).

License

Notifications You must be signed in to change notification settings

martinspielmann/haveibeenpwned4j

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

45 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

haveibeenpwned4j

The ultimate Java library for Troy Hunt's ';-- Have I Been Pwned: API v3.

Build Status Contributors Apache-2.0 Vulnerabilities Coverage

About The Project

Troy Hunt's ';-- Have I Been Pwned is an awesome project that lets you check if you have an account that has been compromised in a data breach.

As you can see on the Consumers page of https://haveibeenpwned.com, there are already Java clients available for the API. Unfortunately some do not fully implement the API or have weird dependencies.

Here comes haveibeenpwned4j awesomeness:

  • All features of ';-- Have I Been Pwned: API v3 implemented (incl. support for providing your API key) ✔
    • Check if a password has been breached ✔
    • Check if an account has been breached ✔
    • Check if an account has been in a paste ✔
    • Get all breaches (or based on a domain) ✔
    • Get a single breach ✔
  • Apache License Version 2.0 ✔
  • Available from Maven Central ✔

Getting Started

Prerequisites

Install Java on your system. Java version 11 is the minimum required version

  • Java: Ubuntu
sudo apt install default-jdk
  • Java: Fedora
sudo dnf install java-11-openjdk

Usage

  1. Include the dependency in your pom.xml
<dependency>
  <groupId>de.martinspielmann.haveibeenpwned4j</groupId>
  <artifactId>haveibeenpwned4j</artifactId>
  <version>2.0.0</version>
</dependency>
  1. Create a new HaveIBeenPwnedApiClient and start using it
/**
 * <strong>Watch out:</strong> Authorization is required for all APIs that enable searching HIBP
 * by email address, namely getting breaches for an account, and getting pastes for and account. 
 * An API key is required to make an authorized call and can
 * be obtained on the API key page.
 * 
 * @see https://haveibeenpwned.com/API/v3#Authorisation
 * @see https://haveibeenpwned.com/API/Key
 */
 
HaveIBeenPwnedApiClient client = new HaveIBeenPwnedApiClient("my-super-secret-api-key");

// find out if given password has been breached
boolean isPasswordPwned = client.isPasswordPwned("password123");

// get breaches for an account (needs API key)
List<Breach> breachesByAccount = client.getBreachesForAccount("[email protected]");

// get all breaches
List<Breach> allBreaches = client.getBreaches();

// find breach by name
Breach singleBreach = client.getSingleBreach("Example Breach");

// get pastes for an account (needs API key)
List<Paste> pastes = client.getPastesForAccount("[email protected]");

Contributing

If you have any problem or idea, dont hesitate to report a bug or request a feature.

If you want to help out with some code, tests or documentation, just follow these steps:

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature)
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

Any contributions you make are highly appreciated.

Prepare

Install Apache Maven on your developer system

  • Java and Apache Maven: Ubuntu
sudo apt install maven
  • Java and Apache Maven: Fedora
sudo dnf install maven

Develop

git clone https://github.com/martinspielmann/haveibeenpwned4j.git
cd haveibeenpwned4j

# to make all the tests run, you need to provide your HIBP API key as an environment variable
HIPB_API_KEY=your-super-secret-key && mvn test

Versioning

This project uses Semantic Versioning

License

Distributed under the Apache License Version 2.0. See LICENSE for more information.

Contact

Martin Spielmann - @martspielmann

Project Link: https://github.com/martinspielmann/haveibeenpwned4j

Acknowledgements