Subscribe

Checking passwords against Have I Been Pwned in golang using k-anonymity

Send only the first 5 characters of the SHA-1 hash to the Pwned Passwords API, compare the rest locally, and decide what happens when the API is down. A small Go client with padding, a 5 second timeout and tests that never hit the network.

Checking passwords against Have I Been Pwned in golang using k-anonymity

A password can be long, mixed case and full of symbols and still be useless, because it already sits in a breach dump that every attacker has. Length rules don't catch that. A check against a list of breached passwords does.

Have I Been Pwned has a free API for exactly this, Pwned Passwords. The nice part is you never send the password, or even its full hash. In this blog we will look at how the k-anonymity range query works, a small Go client for it, and the one decision you have to make yourself: what to do when the API doesn't answer.

How the range query works

First, take the SHA-1 of the password and write it as 40 uppercase hex characters. Then send only the first 5 characters:

printf 'password' | shasum
curl -s https://api.pwnedpasswords.com/range/5BAA6 | head -3

The API returns every hash suffix it knows that starts with that prefix, one per line, with a count:

003CD215739D7C1B2218670D26F81408237:2
003D68EB55068C33ACE09247EE4C639306B:29
00658BFD1E05761042698D19D32CD9F1A8F:15

You compare the remaining 35 characters locally. If your suffix is in the list, the password has been seen in a breach, and the number after the colon is how many times.

The server only ever learns a 5 character prefix. Thousands of different hashes share each prefix, so it can't tell which one you were checking. That's the k-anonymity part. No API key is needed for this endpoint and the docs say there is no rate limit on it.

SHA-1 is fine here, by the way. It is used as a lookup key into a public list, not to store anything.

Padding

There is still a small leak. The size of the response depends on the prefix, so someone watching encrypted traffic could guess the prefix from the byte count. The Add-Padding: true header fixes that: the API adds fake lines with a count of 0.

I checked it from my Mac for the prefix of "password":

curl -s https://api.pwnedpasswords.com/range/5BAA6 | wc -l
curl -s -H 'Add-Padding: true' https://api.pwnedpasswords.com/range/5BAA6 | wc -l

The plain response had 1977 lines both times. With padding I got 2106 and then 2140, a different size each request. The docs mention around 800 lines for a typical prefix; this one and ABCDE, which I tried too, are both at about 2000 now. Doesn't matter for the code.

The one thing to remember is that padding lines have a count of 0. If you only check "is my suffix in the list", a padded line that happens to match would be a false hit. The odds are tiny, but treating count 0 as "not found" costs one strconv.Atoi, so I do it.

Also, lines end in \r\n. I saw that in od -c output. Trim them before comparing or nothing ever matches.

The Go client

Here is the client I wrote for this post.

// Package pwned checks passwords against the Have I Been Pwned "Pwned
// Passwords" range API. Only the first 5 hex characters of the SHA-1 hash
// leave the process (k-anonymity).
package pwned

import (
    "bufio"
    "context"
    "crypto/sha1"
    "encoding/hex"
    "errors"
    "fmt"
    "io"
    "log/slog"
    "net/http"
    "strconv"
    "strings"
    "time"
)

const DefaultBaseURL = "https://api.pwnedpasswords.com"

// ErrUnavailable means we could not ask HIBP. The caller picks fail open
// or fail closed.
var ErrUnavailable = errors.New("pwned: breach check unavailable")

type Client struct {
    BaseURL   string
    HTTP      *http.Client
    UserAgent string
}

func New() *Client {
    return &Client{
        BaseURL:   DefaultBaseURL,
        HTTP:      &http.Client{Timeout: 5 * time.Second},
        UserAgent: "pwcheck-example/1.0",
    }
}

// Count returns how many times the password appears in known breaches.
// 0 means not found.
func (c *Client) Count(ctx context.Context, password string) (int, error) {
    sum := sha1.Sum([]byte(password))
    hash := strings.ToUpper(hex.EncodeToString(sum[:]))
    prefix, suffix := hash[:5], hash[5:]

    req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.BaseURL+"/range/"+prefix, nil)
    if err != nil {
        return 0, err
    }
    req.Header.Set("Add-Padding", "true")
    req.Header.Set("User-Agent", c.UserAgent)

    resp, err := c.HTTP.Do(req)
    if err != nil {
        return 0, fmt.Errorf("%w: %v", ErrUnavailable, err)
    }
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusOK {
        return 0, fmt.Errorf("%w: status %d", ErrUnavailable, resp.StatusCode)
    }

    sc := bufio.NewScanner(io.LimitReader(resp.Body, 1<<20))
    for sc.Scan() {
        s, n, ok := strings.Cut(strings.TrimSpace(sc.Text()), ":")
        if !ok || !strings.EqualFold(s, suffix) {
            continue
        }
        count, err := strconv.Atoi(n)
        if err != nil {
            return 0, fmt.Errorf("%w: bad count %q", ErrUnavailable, n)
        }
        return count, nil // padding lines have count 0, which reads as "not found"
    }
    if err := sc.Err(); err != nil {
        return 0, fmt.Errorf("%w: %v", ErrUnavailable, err)
    }
    return 0, nil
}

A few small things in there. The 5 second timeout is on the http.Client, so a slow API can't hold a signup request forever. The body goes through io.LimitReader with a 1 MiB cap; the padded response I got was around 80 KB, so that's plenty and still protects you from something odd coming back. The User-Agent isn't required for this endpoint but the docs ask you to identify your app, so set one.

To try it against the real API, a tiny command that reads the password from stdin (so it doesn't end up in shell history):

package main

import (
    "context"
    "fmt"
    "io"
    "os"
    "strings"

    "example.com/pwcheck/pwned"
)

func main() {
    b, err := io.ReadAll(io.LimitReader(os.Stdin, 1024))
    if err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
    pw := strings.TrimRight(string(b), "\r\n")

    n, err := pwned.New().Count(context.Background(), pw)
    if err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(2)
    }
    fmt.Printf("seen %d times\n", n)
}
printf 'password' | go run ./cmd/pwcheck
seen 52373976 times

Fifty two million. A random passphrase I typed come back with 0.

Fail open or fail closed

This is the real decision. If the API times out or returns a 500, do you block the password change or let it through?

I went with fail open for password saves, and I think it is the right default for most apps. The breach check is one layer on top of your own rules (minimum length, rate limits on login, maybe MFA). Making signup depend on a third party's uptime means their bad day becomes your outage, and users who can't set a password will pick something worse later or just leave.

But I didn't want that choice buried inside the client. So Count returns ErrUnavailable and the caller decides. The fail-open wrapper is three lines plus a log:

// IsPwned is the fail-open helper for password saves: if HIBP can't be
// reached we log it and let the password through.
func (c *Client) IsPwned(ctx context.Context, password string) bool {
    n, err := c.Count(ctx, password)
    if err != nil {
        slog.Warn("skipping breach check", "err", err)
        return false
    }
    return n > 0
}

Where would I fail closed? An admin account, or a password reset for a high value account, where a short wait and a "try again in a minute" message is acceptable. Same client, different wrapper.

Whatever you pick, make sure the log line is there and that you would notice it. A breach check that has been silently skipped for a week is worse than knowing it is off.

Tests that don't touch the network

All of the tests use httptest.NewServer as a fake HIBP. The one I care about most checks that only the prefix leaves the process:

// "password" has SHA-1 5BAA61E4C9B93F3F0682250B6CF8331B7EE68FD8.
const pwPrefix, pwSuffix = "5BAA6", "1E4C9B93F3F0682250B6CF8331B7EE68FD8"

func TestFoundAndOnlyPrefixSent(t *testing.T) {
    body := "0018A45C4D1DEF81644B54AB7F969B88D65:3\r\n" + pwSuffix + ":52256179\r\n"
    c, paths := fakeHIBP(t, body)

    n, err := c.Count(context.Background(), "password")
    if err != nil || n != 52256179 {
        t.Fatalf("got %d, %v", n, err)
    }
    if (*paths)[0] != "/range/"+pwPrefix {
        t.Fatalf("sent %s", (*paths)[0])
    }
    if strings.Contains((*paths)[0], pwSuffix) {
        t.Fatal("suffix leaked")
    }
}

The others cover a padding line (suffix:0 must not count as a hit), a 503 that has to come back as ErrUnavailable with IsPwned returning false, and a server that never answers, with the client timeout cut to 100ms so the test stays quick. Run them with:

go vet ./... && go test ./...

Where to call it

Call it wherever a new password is set: signup, change password and reset. (Make sure those routes have an owner check too; the ratchet test post is how I keep gin routes honest.) Never on login. On login you'd be sending a hash prefix of every attempt, wrong ones included, and it adds latency for no gain. If you want to warn existing users, do it once after a successful login and ask them to change it, rather than blocking them.

And don't log the password or the full hash anywhere in this flow. Only the prefix ever needs to leave the function. If you want a build check for that, the post on failing the golang build when someone logs a password or token with zap shows one.

Everything here was run with Go 1.27.3 against the live API on 19 November 2026.