README.md
1This is a goLang port of python-zxcvbn and [zxcvbn](https://github.com/dropbox/zxcvbn), which are python and JavaScript password strength
2generators. zxcvbn attempts to give sound password advice through pattern
3matching and conservative entropy calculations. It finds 10k common passwords,
4common American names and surnames, common English words, and common patterns
5like dates, repeats (aaa), sequences (abcd), and QWERTY patterns.
6
7Please refer to https://dropbox.tech/security/zxcvbn-realistic-password-strength-estimation for the full details and
8motivation behind zxcbvn. The source code for the original JavaScript (well,
9actually CoffeeScript) implementation can be found at:
10
11https://github.com/lowe/zxcvbn
12
13Python at:
14
15https://github.com/dropbox/python-zxcvbn
16
17For full motivation, see:
18
19https://dropbox.tech/security/zxcvbn-realistic-password-strength-estimation
20
21------------------------------------------------------------------------
22Use
23------------------------------------------------------------------------
24
25The zxcvbn module has the public method PasswordStrength() function. Import zxcvbn, and
26call PasswordStrength(password string, userInputs []string). The function will return a
27result dictionary with the following keys:
28
29Entropy # bits
30
31CrackTime # estimation of actual crack time, in seconds.
32
33CrackTimeDisplay # same crack time, as a friendlier string:
34 # "instant", "6 minutes", "centuries", etc.
35
36Score # [0,1,2,3,4] if crack time is less than
37 # [10^2, 10^4, 10^6, 10^8, Infinity].
38 # (useful for implementing a strength bar.)
39
40MatchSequence # the list of patterns that zxcvbn based the
41 # entropy calculation on.
42
43CalcTime # how long it took to calculate an answer,
44 # in milliseconds. usually only a few ms.
45
46The userInputs argument is an splice of strings that zxcvbn
47will add to its internal dictionary. This can be whatever list of
48strings you like, but is meant for user inputs from other fields of the
49form, like name and email. That way a password that includes the user's
50personal info can be heavily penalized. This list is also good for
51site-specific vocabulary.
52
53Bug reports and pull requests welcome!
54
55------------------------------------------------------------------------
56Project Status
57------------------------------------------------------------------------
58
59Use zxcvbn_test.go to check how close to feature parity the project is.
60
61------------------------------------------------------------------------
62Acknowledgment
63------------------------------------------------------------------------
64
65Thanks to Dan Wheeler (https://github.com/lowe) for the CoffeeScript implementation
66(see above.) To repeat his outside acknowledgements (which remain useful, as always):
67
68Many thanks to Mark Burnett for releasing his 10k top passwords list:
69https://xato.net/passwords/more-top-worst-passwords
70and for his 2006 book,
71"Perfect Passwords: Selection, Protection, Authentication"
72
73Huge thanks to Wiktionary contributors for building a frequency list
74of English as used in television and movies:
75https://en.wiktionary.org/wiki/Wiktionary:Frequency_lists
76
77Last but not least, big thanks to xkcd :)
78https://xkcd.com/936/
79