pwcheck

README

pwcheck

pwCheck is a utility package that gives password strength and verifies passphrase has not been compromised in a previous breach using the https://haveibeenpwned.com API and the Dropbox zxcvbn method for estimating passphrase strength.

---

Get Started

go get github.com/dwin/pwCheck

Settings:

// ClientTimeout specifies the timeout of the HTTP API Client in seconds
// A Timeout of zero means no timeout.
	ClientTimeout = 5

Types:

// Pwd is returned as a struct pointer when calling CheckForPwnage
type Pwd struct {
	Pwned      bool   // Pwned returns true if passphrase is found pwned via API
	Pass       string // Pass returns the passphrase string passed to the function
	TimesPwned int    // TimesPwned returns the number of times the passphrase was found in the database
}


// CheckResult is returned as a struct when calling CheckPass()
type CheckResult struct {
	Pwned            bool    // Pwned indicates if the pass given was found in previous breach
	Pass             string  // Pass returns the string passed to the function
	Score            int     // Score returns a 0-4 score of password strength, useful for gauge etc.
	CrackTimeSeconds float64 // CrackTimeSeconds indicates the estimated time to crack this password at ~ 10ms per guess in seconds
	CrackTimeDisplay string  // CrackTimeDisplay indicates the estimated time in seconds to years or centuries to crack password at ~ 10ms per guess
}

Functions:

CheckPass() sends SHA1 partial hash of password to HaveIBeenPwned.com API to check for previous compromise and also computes strength using the Dropbox "zxcvbn: realistic password strength estimation" method using zxcvbn-go.

Example Usage:

See other examples.

func example() {
	userPass := form.Data("password")

	checkRes, err := pwcheck.CheckPass(passFromUser)
	if err != nil {
		// Handle Error
	}

	if result.Pwned {
		// If pwned this password was found in compromised password database 
		// and you should handle or inform user.
	}

	if result.Score < 1 {
		// If score is less than 1 this is a weak password and should not be used
	}
}

ToDo:

• HTTP Client Timeout

Credits:

• Inspired by: https://github.com/masonj88/pwchecker
• zxcvbn-go - by Nathan Button
• Have I Been Pwned API - by Troy Hunt
• Testify - by Stretchr, Inc.

Documentation

Index

• Variables
• func IsPwned(pw string) error
• type CheckResult
  • func CheckPass(pw string) (result CheckResult, err error)
• type Pwd
  • func CheckForPwnage(pw string) (pwd *Pwd, err error)

Variables

var (
	// ClientTimeout specifies the timeout of the HTTP API Client in seconds
	ClientTimeout = 5
	// ErrPassphraseEmpty indicates passphrase input was less than 1 character
	ErrPassphraseEmpty = errors.New("Passphrase Input Empty")
)

Functions

func IsPwned

func IsPwned(pw string) error

IsPwned check passphrase input string and returns error, returns nil if password is not pwned and no other errors occur.

Types

type CheckResult

type CheckResult struct {
	Pwned            bool    // Pwned indicates if the pass given was found in previous breach
	Pass             string  // Pass returns the string passed to the function
	Score            int     // Score returns a 0-4 score of password strength, useful for gauge etc.
	CrackTimeSeconds float64 // CrackTimeSeconds indicates the estimated time to crack this password at ~ 10ms per guess in seconds
	CrackTimeDisplay string  // CrackTimeDisplay indicates the estimated time in seconds to years or centuries to crack password at ~ 10ms per guess
}

CheckResult is returned as a struct when calling CheckPass()

func CheckPass

func CheckPass(pw string) (result CheckResult, err error)

CheckPass

type Pwd

type Pwd struct {
	Pwned      bool   // Pwned returns true if passphrase is found pwned via API
	Pass       string // Pass returns the passphrase string passed to the function
	TimesPwned int    // TimesPwned returns the number of times the passphrase was found in the database
}

Pwd is returned as a struct pointer when calling CheckForPwnage()

func CheckForPwnage

func CheckForPwnage(pw string) (pwd *Pwd, err error)

CheckForPwnage takes passphrase as string, sends request to API and returns Pwd and error