go-password-validator

Simple password validator using raw entropy values. Hit the project with a star if you find it useful ⭐

Supported by Qvault

This project can be used to front a password strength meter, or simply validate password strength on the server. Benefits:

• No stupid rules (doesn't require uppercase, numbers, special characters, etc)
• Everything is based on entropy (raw cryptographic strength of the password)
• Doesn't load large sets of data into memory - very fast and lightweight
• Doesn't contact any API's or external systems
• Inspired by this XKCD

⚙️ Installation

Outside of a Go module:

go get github.com/wagslane/go-password-validator

🚀 Quick Start

package main

import (
    passwordvalidator "github.com/wagslane/go-password-validator"
)

func main(){
    entropy := passwordvalidator.GetEntropy("a longer password")
    // entropy is a float64, representing the strength in base 2 (bits)

    const minEntropyBits = 60
    err := passwordvalidator.Validate("some password", minEntropyBits)
    // if the password has enough entropy, err is nil
    // otherwise, a formatted error message is provided explaining
    // how to increase the strength of the password
    // (safe to show to the client)
}

What Entropy Value Should I Use?

It's up to you. That said, here is a graph that shows some common timings for different values, somewhere in the 50-70 range seems "reasonable".

Keep in mind that attackers likely aren't just brute-forcing passwords, if you want protection against common passwords or PWNed passwords you'll need to do additional work. This library is lightweight, doesn't load large datasets, and doesn't contact external services.

How It Works

First, we determine the "base" number. The base is a sum of the different "character sets" found in the password.

We've arbitrarily chosen the following character sets:

• 26 lowercase letters
• 26 uppercase letters
• 10 digits
• 5 replacement characters - [email protected]$&*
• 5 seperator characters - _-.,
• 22 less common special characters - "#%'()+/:;<=>?[\]^{|}~

Using at least one character from each set your base number will be 94: 26+26+10+5+5+22 = 94

Every unique character that doesn't match one of those sets will add 1 to the base.

If you only use, for example, lowercase letters and numbers, your base will be 36: 26+10 = 36.

After we have calculated a base, the total number of brute-force-guesses is found using the following formulae: base^length

A password using base 26 with 7 characters would require 26^7, or 8031810176 guesses.

Once we know the number of guesses it would take, we can calculate the actual entropy in bits using log2(guesses). That calculation is done in log space in practice to avoid numeric overflow.

Additional Safety

We try to err on the side of reporting less entropy rather than more.

Same Character

With repeated characters like aaaaaaaaaaaaa, or 111222, we modify the length of the sequence to count as no more than 2.

• aaaa has length 2
• 111222 has length 4

Common Sequences

Common sequences of length three or greater count as length 2.

• 12345 has length 2
• 765432 has length 2
• abc has length 2
• qwerty has length 2

The sequences are checked from back->front and front->back. Here are the sequences we've implemented so far, and they're case-insensitive:

• 0123456789
• qwertyuiop
• asdfghjkl
• zxcvbnm
• abcdefghijklmnopqrstuvwxyz

Not ZXCVBN

There's another project that has a similar purpose, zxcvbn, and you may want to check it out as well. Our goal is not to be zxcvbn, because it's already good at what it does. go-password-validator doesn't load any large datasets of real-world passwords, we write simple rules to calculate an entropy score. It's up to the user of this library to decide how to use that entropy score, and what scores constitute "secure enough" for their application.

💬 Contact

Submit an issue (above in the issues tab)

Transient Dependencies

None! And it will stay that way, except of course for the standard library.

👏 Contributing

I love help! Contribute by forking the repo and opening pull requests. Please ensure that your code passes the existing tests and linting, and write tests to test your changes if applicable.

All pull requests should be submitted to the main branch.

make test
make fmt
make vet
make lint