README.md (5308B)
1 # go-password-validator 2 3 Simple password validator using raw entropy values. Hit the project with a star if you find it useful ⭐ 4 5 Supported by [Qvault](https://qvault.io) 6 7 [](https://godoc.org/github.com/wagslane/go-password-validator)  8 [](https://github.com/avelino/awesome-go) 9 10 This project can be used to front a password strength meter, or simply validate password strength on the server. Benefits: 11 12 * No stupid rules (doesn't require uppercase, numbers, special characters, etc) 13 * Everything is based on entropy (raw cryptographic strength of the password) 14 * Doesn't load large sets of data into memory - very fast and lightweight 15 * Doesn't contact any API's or external systems 16 * Inspired by this [XKCD](https://xkcd.com/936/) 17 18  19 20 ## ⚙️ Installation 21 22 Outside of a Go module: 23 24 ```bash 25 go get github.com/wagslane/go-password-validator 26 ``` 27 28 ## 🚀 Quick Start 29 30 ```go 31 package main 32 33 import ( 34 passwordvalidator "github.com/wagslane/go-password-validator" 35 ) 36 37 func main(){ 38 entropy := passwordvalidator.GetEntropy("a longer password") 39 // entropy is a float64, representing the strength in base 2 (bits) 40 41 const minEntropyBits = 60 42 err := passwordvalidator.Validate("some password", minEntropyBits) 43 // if the password has enough entropy, err is nil 44 // otherwise, a formatted error message is provided explaining 45 // how to increase the strength of the password 46 // (safe to show to the client) 47 } 48 ``` 49 50 ## What Entropy Value Should I Use? 51 52 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". 53 54 Keep in mind that attackers likely aren't just brute-forcing passwords, if you want protection against common passwords or [PWNed passwords](https://haveibeenpwned.com/) you'll need to do additional work. This library is lightweight, doesn't load large datasets, and doesn't contact external services. 55 56  57 58 ## How It Works 59 60 First, we determine the "base" number. The base is a sum of the different "character sets" found in the password. 61 62 We've *arbitrarily* chosen the following character sets: 63 64 * 26 lowercase letters 65 * 26 uppercase letters 66 * 10 digits 67 * 5 replacement characters - `!@$&*` 68 * 5 seperator characters - `_-., ` 69 * 22 less common special characters - `"#%'()+/:;<=>?[\]^{|}~` 70 71 72 Using at least one character from each set your base number will be 94: `26+26+10+5+5+22 = 94` 73 74 Every unique character that doesn't match one of those sets will add `1` to the base. 75 76 If you only use, for example, lowercase letters and numbers, your base will be 36: `26+10 = 36`. 77 78 After we have calculated a base, the total number of brute-force-guesses is found using the following formulae: `base^length` 79 80 A password using base 26 with 7 characters would require `26^7`, or `8031810176` guesses. 81 82 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. 83 84 ### Additional Safety 85 86 We try to err on the side of reporting *less* entropy rather than *more*. 87 88 #### Same Character 89 90 With repeated characters like `aaaaaaaaaaaaa`, or `111222`, we modify the length of the sequence to count as no more than `2`. 91 92 * `aaaa` has length 2 93 * `111222` has length 4 94 95 #### Common Sequences 96 97 Common sequences of length three or greater count as length `2`. 98 99 * `12345` has length 2 100 * `765432` has length 2 101 * `abc` has length 2 102 * `qwerty` has length 2 103 104 The sequences are checked from back->front and front->back. Here are the sequences we've implemented so far, and they're case-insensitive: 105 106 * `0123456789` 107 * `qwertyuiop` 108 * `asdfghjkl` 109 * `zxcvbnm` 110 * `abcdefghijklmnopqrstuvwxyz` 111 112 ## Not ZXCVBN 113 114 There's another project that has a similar purpose, [zxcvbn](https://github.com/dropbox/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. 115 116 ## 💬 Contact 117 118 [](https://twitter.com/intent/follow?screen_name=wagslane) 119 120 Submit an issue (above in the issues tab) 121 122 ## Transient Dependencies 123 124 None! And it will stay that way, except of course for the standard library. 125 126 ## 👏 Contributing 127 128 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. 129 130 All pull requests should be submitted to the `main` branch. 131 132 ```bash 133 make test 134 make fmt 135 make vet 136 make lint 137 ```