JarCastinghaveibeenpwned4j
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 v3implemented (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
✔
- Check if a password has been breached
- 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
- Include the dependency in your pom.xml
<dependency>
<groupId>de.martinspielmann.haveibeenpwned4j</groupId>
<artifactId>haveibeenpwned4j</artifactId>
<version>2.0.0</version>
</dependency>
- Create a new
HaveIBeenPwnedApiClientand 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:
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature) - Push to the Branch (
git push origin feature/AmazingFeature) - 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