Pwned by Core Theory

A simple application to check if an email or password has been pwned using the HaveIbeenPwned? API v3.

Emails

This library currently implements simple email checking against data breaches with the HaveIBeenPwned? API v3. It requires a purchased api-key in order to work.

The Pwned.check_email/1 function returns the total number of times an email address has appeared in known data breaches, or an "email not pwned" message.

Passwords

This library uses HaveIBeenPwned? to verify if a password has appeared in a data breach.

In order to protect the value of the source password being searched, the value is not sent through the network. Instead it uses a k-Anonymity model that allows a password to be searched for by partial hash. This allows the first 5 characters of a SHA-1 password hash to be passed to the API. Then, it searches the results of the response for the presence of the source hash. If the source hash is not found, then the password does not exist in the data set.

Additionally, we implement padding to further protect the privacy of the password source hash in accordance with password padding in API v3.

Table of Contents

• Dependencies
• Install
• Usage
• Changelog
• Contributing
• Further Reading
• License
• Notice
• Special Thanks

Dependencies

This package requires httpoison v1.8. If you have v1.7 in your mix.lock file, then you will need to update it to 1.8 to successfully run mix deps.get.

It also requires Elixir 1.11 to work. If you need functionality for earlier versions of Elixir, then we'd be happy to receive a PR.

Install

Recommended

This package can be installed by adding :pwned_coretheory to your list of dependencies in mix.exs:

defp deps do
  [
    ...
    {:pwned_coretheory, "~> 1.5"},
  ]
end

Then, run mix deps.get. Additionally, run mix deps.update pwned_coretheory occasionally to ensure you have the latest release.

Running on master

If you would like to run on the master branch, then update your dependencies as such:

defp deps do
  [
    ...
    {:pwned_coretheory, github: "coretheory/pwned_coretheory"},
  ]
end

Usage

Usage is incredibly simple and straightforward. You can check if an email or password has been pwned with calls to their respective functions.

In the case of checking for an email, you will need to have purchased a hibp-api-key.

You can use this library for password checking without the need for an API key. However, if this is the case, then keep in mind that not all tests will pass. If you do not need email checking, then we encourage you to use the pwned library by Thiago Santos.

Check for pwned passwords

To check whether a password has been pwned you can make a simple call to the Pwned.check_password/1 function:

iex> Pwned.check_password("P@ssw0rd")
      {:ok, 47205}

iex> Pwned.check_password("Z76okiy2X1m5PFud8iPUQGqusShCJhg")
      {:ok, false}

When implementing in an application, we can use a straightforward case statement like this:

case Pwned.check_password("somepassword") do
  {:ok, false} ->
    IO.puts("Good news — no pwnage found!")

  {:ok, count} ->
    IO.puts("Oh, no! This password appeared #{count} times in data breaches.")

  :error ->
    IO.puts("Something went wrong.")
end

Check for pwned emails

First, let's make sure our hibp-api-key is ready to go.

Purchase your hibp-api-key and add it to an environment file

You will first need to purchase a hibp-api-key from haveibeenpwned?.

Then, create a .env file at the root of your project (e.g. beside your .gitignore. Be sure to update your .gitignore file to ignore environment files: *.env.

Once you are certain that you will not be pushing your environment files up to a source control repository, add your purchased hibp-api-key to your .env file: export HIBP_API_KEY=your_hibp_api_key. Next, you'll want to run source .env from your terminal.

For production, you'll want to have your hibp-api-key safely stored in your production host's environment variables configuration with the key: HIBP_API_KEY.

Lastly, you can easily configure the :user_agent for the HIBP API, like so:

# In your config.exs.
config :pwned_coretheory,
  user_agent: "YourApp Pwned Client"

We highly recommend you set the configuration as it is good practice and informs the HaveIBeenPwned? service that it is your application accessing the data and not a spammer or malicious account.

Checking emails

To check whether an email has been pwned you can make a simple call to the Pwned.check_email/1 function:

iex> Pwned.check_email("[email protected]")
    {:pwned_email, 4893554722}

iex> Pwned.check_email("[email protected]")
    {:safe_email, "email not pwned"}

When implementing in an application, we can use a straightforward case statement like this:

case Pwned.check_email("[email protected]") do
  {:safe_email, message} ->
    IO.puts(message)

  {:pwned_email, pwned_count} ->
    IO.puts("Ohh, sorry! This email has appeared #{pwned_count} times in data breaches.")

  {:error, message} ->
    IO.puts("An error occurred: " <> message)
  
  :error ->
    IO.puts("Something went wrong.")
end

Changelog

See the changelog file.

Contributing

See the contributing file.

Further Reading

See the further reading file.

License

Apache License, Version 2.0 © 2021 Core Theory, Inc.

Notice

This is a modified version of the pwned package © @thiamsantos.

Special thanks

This extension was built from the simple and wonderful package, pwned, by Thiago Santos. ♥