README.md

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.