Password Review

Introduction

Password Review is a feature of Codebook (for macOS and iOS) that allows you to check if a password you are using appears in a massive database of over half a billion hacked and leaked passwords compiled by security researchers called HaveIBeenPwned.com. Specifically, Codebook uses the service's /range API, which uses a k-Anonymity model to prevent the service from learning the password being tested. From the results Codebook can determine if your password has been found in online password breaches, and how many times. Codebook does not at any time send your actual password to any web service.

Reviewing a password on iOS is a snap:

  1. Launch Codebook and login
  2. Tap on any entry record with a Password
  3. Tap on your Password row to bring up the Password Options menu
  4. Tap on Review Password

The first time you tap on Review Password, Codebook will ask you to confirm if you want to continue, and will check for confirmation again if you tap on Cancel or Learn More (which brings you to this page!), until you tap Continue.

Password Options menu Confirmation prompt No breaches found Password breached

To review an existing password entry:

  1. Click on any entry record with a Password
  2. Right click on your Password row to bring up the Password Options menu, (keyboard shortcut ⌘R)
  3. Click on Review Password

Codebook can also be set up to review your password as you enter it. Password Review is disabled by default. To enable the feature, click on the Codebook menu > Preferences (keyboard shortcut ⌘,), and select the Passwords tab. Click on the checkbox "Automatically review passwords with HaveIBeenPwned.com" and it's ready to go.

Passwords Preferences

As you type in password fields Codebook reviews the password locally for weakness warnings. Once you stop typing Password Review will automatically check the password against HaveIBeenPwned.com's API, displaying the results right above any other warnings.

Codebook Password Review from Zetetic on Vimeo.

Codebook never sends the password being tested to HaveIBeenPwned.com, and the service is incapable of learning the password being tested based on the data Codebook sends and the data it provides in response. In practical terms, Codebook takes an SHA-1 hash of the password being tested. Then it extracts the first five characters from that hash and queries the API with it for a range of breached passwords which have a hash matching the first five characters. The service returns these hundreds of hashes back to Codebook, which searches them for a match to the password being tested. If a match is found, it means the password you are testing has been collected in a breach of an online service at least once.

The mathematical principle supporting this type of lookup is called k-Anonymity. Cloud Flare has provided an excellent description of it in their article on how it is used in HaveIBeenPwned.com:

Instead, our approach adds an additional layer of security by utilising a mathematical property known as k-Anonymity and applying it to password hashes in the form of range queries. As such, the Pwned Passwords API service never gains enough information about a non-breached password hash to be able to breach it later.

k-Anonymity is used in multiple fields to release anonymised but workable datasets; for example, so that hospitals can release patient information for medical research whilst withholding information that discloses personal information. Formally, a data set can be said to hold the property of k-Anonymity, if for every record in a released table, there are k − 1 other records identical to it.

By using this property, we are able to seperate hashes into anonymised "buckets". A client is able to anonymise the user-supplied hash and then download all leaked hashes in the same anonymised "bucket" as that hash, then do an offline check to see if the user-supplied hash is in that breached bucket.