p4ssw0rd

README

p4ssw0rd

Go password strength validation utilizing the have i been pwned? API. Make sure you read and abide by their license

Usage

go get github.com/chanced/p4ssw0rd

package main

import(
    "context"
    "errors"

    "github.com/chanced/p4ssw0rd"
)

func main() {
    ctx := context.Background()
    pw, err := p4ssw0rd.New(p4ssw0rd.Config{
        UserAgent:               "your site", // required
        MinPasswordLength:       6,           // default: 6
        BreachLimit:             10,          // default: 10
        MaxPwnedRequestAttempts: 3,           // default: 3
        AddPadding:              false,       // default: false
    })
    if err != nil {
        // The only reason this would happen is if you didn't provide a user agent.
        // see https://haveibeenpwned.com/API/v3#UserAgent
        panic(err)
    }

    eval, err := pw.Evaluate(ctx, "password")
    if err != nil {
        // this shouldn't error unless something goes wrong with connecting to haveibeenpwned because
        // "password" satisfies the min length requirement
        panic(err)
    }
    _ = eval.Allowed // false because the count of breaches this value has been involved in exceeds BreachLimit
    _ = eval.BreachCount // 3861493 as of running this
    _ = eval.Notes // ""; it will remain blank for now. Add your own notes in your handler

    eval, err = pw.Evaluate(ctx, "pass")
    if err != nil {
        // err is a p4ssw0rd.MinLengthError because len("pass") < pw.MinPasswordLength
        var mlerr *p4ssw0rd.MinLengthError
        if errors.As(err, &mlerr) {
            _ = err.MinRequired // 6, as set by pw.MinPasswordLength
            _ = err.Length // 4
        } else {
            //connection issues with haveibeenpwned
            panic(err)
        }
    }
    err = pw.Validate(ctx, "password")
    if err != nil {
        var blerr *p4ssw0rd.BreachLimitError
        if errors.As(err, &blerr) {
            _ = blerr.BreachCount
        }
    }
}

Explanation

The way the package works is the password is hashed (SHA1) then the first 5 characters of that are used to query the API. The result set contains the remainder of the hash, if the password is present, and the count of breaches it has been discovered in. The results from have i been pwned look like this:

1E2AAA439972480CEC7F16C795BBB429372:1
1E3687A61BFCE35F69B7408158101C8E414:1
1E4C9B93F3F0682250B6CF8331B7EE68FD8:3861493
00306FB8A6E528F9B377D068C625E2D5B55:2
00415E48D704BA89B118934A33E202E41F9:1
00DFA98B45FE3EE9D2F7BF6872E37672D03:2
012562CD2D1BECE861B1566A974B52ACBF9:1
012BE47C832BEE70CAA8E89364FF59B09EA:1
0134585DCB1B38E99BD0CDA7E56D42A0C16:1
01D41F17FC9C9CF616DE7A6BA237929AC91:1
01ED16B974AE0010799BF0AE6F77E8F6CC5:10
01FFD148305A472EBCED1BF4E70089A0532:1

If you're still concerned about a man in the middle snooping responses, you can turn on padding which ensures that there are consistently 800 - 1,000 results. See https://haveibeenpwned.com/API/v3#PwnedPasswordsPadding

Documentation

https://pkg.go.dev/github.com/chanced/p4ssw0rd

License

p4ssw0rd is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.

Documentation

Overview

Package p4ssw0rd evaluates password strength utilizing the haveibeenpwned database

https://haveibeenpwned.com/API/v3#SearchingPwnedPasswordsByRange

Index

• Variables
• type BreachLimitError
  • func (e *BreachLimitError) Error() string
  • func (e *BreachLimitError) Unwrap() error
• type Config
• type Evaluation
• type Evaluator
• type EvaluatorValidator
• type MinLengthError
  • func (e *MinLengthError) Error() string
  • func (e *MinLengthError) Unwrap() error
• type P4ssw0rd
  • func New(config Config) (P4ssw0rd, error)
  • func (p P4ssw0rd) Evaluate(ctx context.Context, password string) (Evaluation, error)
  • func (p P4ssw0rd) Validate(ctx context.Context, password string) error
• type Validator

Variables

var (
	// ErrMinLengthNotSatisfied indicates that a password does not meet the
	// minimum length requirements
	ErrMinLengthNotSatisfied = errors.New("minimum password length not satisfied")
	// ErrBreachLimitExceeded indicates that the password's breach limit has
	// been exceeded
	ErrBreachLimitExceeded = errors.New("password breach limit exceeded")
	// ErrMissingUserAgent is returned when a UserAgent is not specified
	ErrMissingUserAgent = errors.New("UserAgent was not specified")
	// ErrTooManyRequests occurs when have i been pwned returns a 429 this
	// shouldn't happen per the docs: "There are 1,048,576 different hash
	// prefixes between 00000 and FFFFF (16^5) and every single one will return
	// HTTP 200; there is no circumstance in which the API should return HTTP
	// 404."
	ErrTooManyRequests = errors.New("error: too many requests — the rate limit has been exceeded")
	// Service unavailable — usually returned by Cloudflare if the underlying
	// service is not available
	ErrServiceUnavailable = errors.New("error: service unavailable")
)

Types

type BreachLimitError

type BreachLimitError struct {
	BreachCount uint32
	// contains filtered or unexported fields
}

func (*BreachLimitError) Error

func (e *BreachLimitError) Error() string

func (*BreachLimitError) Unwrap

func (e *BreachLimitError) Unwrap() error

type Config

type Config struct {
	// minimum length of a password to be checked.
	//
	// 	default: 6
	MinPasswordLength uint16

	// The max number of times a password is found in data breaches before
	// becoming invalid (or returning an error with Validate)
	//
	// 	default: 10
	BreachLimit uint32

	// Maximum number of attempts to retry reaching haveibeenpwned before
	// returning an error. p4ssw0rd employs exponential backoff.
	//
	// 	default: 3
	MaxPwnedRequestAttempts uint8

	UserAgent string

	// This is not required, per the HaveIBeenPwned API documentation:
	//
	// "Authorization is required for all APIs that enable searching HIBP by
	// email address, namely retrieving all breaches for an account and
	// retrieving all pastes for an account."
	//
	// Leaving it as a config option for those with keys that would like to
	// future-proof in the event their policy changes.
	//
	//
	// https://haveibeenpwned.com/API/v3#Authorisation
	APIKey string

	// see https://haveibeenpwned.com/API/v3#PwnedPasswordsPadding
	AddPadding bool
}

Config parameters when creating a new P4ssw0rd instance

type Evaluation

type Evaluation struct {
	BreachCount uint32 `json:"breachCount"`
	Notes       string `json:"notes"`
	Allowed     bool   `json:"allowed"`
}

Evaluation is a non-error summary of whether a password would be valid.

type Evaluator

type Evaluator interface {
	Evaluate(ctx context.Context, password string) (Evaluation, error)
}

Evaluator defines the single func Evaluate which returns an Evaluation or an error if the minimum length requirements are not satisfied.

type EvaluatorValidator

type EvaluatorValidator interface {
	Evaluator
	Validator
}

EvaluatorValidator is an interface comprised of both Validator and Evaluator

type MinLengthError

type MinLengthError struct {
	MinRequired uint16
	Length      uint16
	// contains filtered or unexported fields
}

func (*MinLengthError) Error

func (e *MinLengthError) Error() string

func (*MinLengthError) Unwrap

func (e *MinLengthError) Unwrap() error

type P4ssw0rd

type P4ssw0rd struct {
	Config
	// contains filtered or unexported fields
}

func New

func New(config Config) (P4ssw0rd, error)

func (P4ssw0rd) Evaluate

func (p P4ssw0rd) Evaluate(ctx context.Context, password string) (Evaluation, error)

Evaluate evaluates a password, checking the haveibeenpwned database for breaches. An error is returned if the password length is not long enough or errors occurred while querying pwned or hashing the password

func (P4ssw0rd) Validate

func (p P4ssw0rd) Validate(ctx context.Context, password string) error

Validate is like Evaluate but returns an error if the Evaluation fails (too many breaches)

type Validator

type Validator interface {
	Validate(ctx context.Context, password string) error
}

Validator defines the single func Validate which returns an error if the provided password does not meet the length requirements or if the breach count, obtained from the HIBP API, is exceeded.