p4ssw0rd

README

p4ssw0rd

Go password strength validation utilizing the have i been pwned? API

Make sure you read and abide by their license

usage:

package main

import(
    "github.com/chanced/p4ssw0rd"

)

func main() {
    ctx := context.Background()
    pw, err := p4ssw0rd.New(p4ssw0rd.Config{
        UserAgent:               "your site",
        MinPasswordLength:       6,    // defaults to 6
        BreachLimit:             10,   // defaults to 10
        MaxPwnedRequestAttempts: 3,    // defaults to 3
        AddPadding:              true, // defaults to false
    })
    if err != nil {
        // 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
        panic(err)
    }
    _ = eval.Allowed // false because the limit 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
        }
    }
}

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
• type Config
• type Err
  • func (e *Err) Unwrap() error
• type Evaluation
• type MinLengthError
  • func (e *MinLengthError) Error() string
• 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, pw string) error

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 {
	Err
	BreachCount uint32
}

func (*BreachLimitError) Error

func (e *BreachLimitError) Error() string

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
	// Authorisation 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 and requires an API key
	// for non-.
	//
	// 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 Err

type Err struct {
	Err error
}

func (*Err) Unwrap

func (e *Err) Unwrap() error

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 MinLengthError

type MinLengthError struct {
	Err
	MinRequired uint16
	Length      uint16
}

func (*MinLengthError) Error

func (e *MinLengthError) Error() string

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, pw string) error

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