Skip to content
The ultimate Java library for Troy Hunt's ';-- Have I Been Pwned (v3).
Java
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/workflows
src
.gitignore
LICENSE
README.md
SECURITY.md
pom.xml
sonar-project.properties

README.md

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 ✔
  • No (yes, you are reading right... NO!) dependencies ✔
  • Apache License Version 2.0 ✔
  • Available from Maven Central ✔

Getting Started

Prerequisites

Install Java on your system

  • 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>1.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("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

Develop

git clone https://github.com/pingunaut/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 - @pingunaut

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

Acknowledgements

You can’t perform that action at this time.