haveibeenpwned4j

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

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

• Java: Windows Install Java 11: E.g. OpenJDK or Oracle JDK

Usage

1. Include the dependency in your pom.xml

<dependency>
  <groupId>de.martinspielmann.haveibeenpwned4j</groupId>
  <artifactId>haveibeenpwned4j</artifactId>
  <version>2.0.0</version>
</dependency>

2. 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("foo.bar@example.com");

// 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("foo.bar@example.com");

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

• Java and Apache Maven: Windows
  • Install Java 11: E.g. OpenJDK or Oracle JDK
  • Download Apache Maven and install like described here

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

• ';-- Have I Been Pwned