_________________________________________________/\/\___________________
_/\/\/\/\/\__/\/\__/\/\____/\/\/\/\__/\/\__/\/\__/\/\________/\/\/\/\___
_____/\/\______/\/\/\____/\/\________/\/\__/\/\__/\/\/\/\____/\/\__/\/\_
___/\/\________/\/\/\____/\/\__________/\/\/\____/\/\__/\/\__/\/\__/\/\_
_/\/\/\/\/\__/\/\__/\/\____/\/\/\/\______/\______/\/\/\/\____/\/\__/\/\_
________________________________________________________________________

zxcvbn, named after a crappy password, is a JavaScript password strength estimation library. Use it to implement a custom strength bar on a signup form near you!

zxcvbn attempts to give sound password advice through pattern matching and conservative entropy calculations. It finds 10k common passwords, common names and surnames according to US census data, common English words, and common patterns like dates, repeats (aaa), sequences (abcd), and QWERTY patterns.

For full motivation, see:

http://tech.dropbox.com/?p=165

Installation

zxcvbn automatically detects and supports CommonJS (node, browserify) and AMD (RequireJS). In the absense of those, it adds a single function zxcvbn to the global namespace.

Using bower

Install node and bower if you haven't already. This won't make your codebase dependent on node.

Get zxcvbn:

cd /path/to/project/root # your index.html lives here
bower install zxcvbn

Add this script to your index.html:

<script type="text/javascript" src="bower_components/zxcvbn/zxcvbn-async-bower.js">
</script>

That's it!

To pull in updates and bugfixes:

bower update zxcvbn

How loading works: zxcvbn-async-bower.js is a tiny script. On window.load, after your page loads and renders, it'll fetch zxcvbn.js in the background, which is more like 680kb (320kb gzipped), most of which is a series of dictionaries.

680kb may seem large for a script, but since it loads in the background, and because passwords come later in most registration flows, we've never had an issue.

Using RequireJS

Add zxcvbn.js to your project (using bower or direct download) and import as usual:

requirejs(["relpath/to/zxcvbn"], function (zxcvbn) {
    console.log(zxcvbn('Tr0ub4dour&3'));
});

Note: zxcvbn-async.js is for manual installations. There is no need to add it to a RequireJS setup, which already provides the same asynchronous loading support.

Manual installation

This works the same as the bower instructions, without the bower dependency.

Copy zxcvbn.js and zxcvbn-async.js into your codebase.

Add to your index.html:

<script type="text/javascript" src="path/to/zxcvbn-async.js">
</script>

Open zxcvbn-async.js and edit the ZXCVBN_SRC variable to point to wherever you put zxcvbn.js. If index.html and zxcvbn.js sit next to each other, it'll work as-is.

Note that zxcvbn.js can also be included directly:

<script type="text/javascript" src="zxcvbn.js">
</script>

But this isn't recommended, as the 680k download will block your initial page load. Note: the advantage of using zxcvbn-async.js over the HTML5 async script attribute is that it works in old browsers.

Usage

zxcvbn(password, user_inputs)

It takes one required argument, a password, and returns a result object. The result includes a few properties:

result.entropy            # bits

result.crack_time         # estimation of actual crack time, in seconds.

result.crack_time_display # same crack time, as a friendlier string:
                          # "instant", "6 minutes", "centuries", etc.

result.score              # [0,1,2,3,4] if crack time is less than
                          # [10**2, 10**4, 10**6, 10**8, Infinity].
                          # (useful for implementing a strength bar.)

result.match_sequence     # the list of patterns that zxcvbn based the
                          # entropy calculation on.

result.calc_time          # how long it took to calculate an answer,
                          # in milliseconds. usually only a few ms.

The optional user_inputs argument is an array of strings that zxcvbn will add to its internal dictionary. This can be whatever list of strings you like, but is meant for user inputs from other fields of the form, like name and email. That way a password that includes the user's personal info can be heavily penalized. This list is also good for site-specific vocabulary.

When zxcvbn loads (after the async script fetch is complete), it'll check if a function named zxcvbn_load_hook is defined, and run it with no arguments if so. Most sites shouldn't need this.

Development

Bug reports and pull requests welcome!

zxcvbn is written in CoffeeScript and Python. zxcvbn.js is built with compile_and_minify.sh, which compiles CoffeeScript into JavaScript, then JavaScript into efficient, minified JavaScript.

For development, include these scripts instead of zxcvbn.js:

<script type="text/javascript" src="adjacency_graphs.js">
</script>
<script type="text/javascript" src="frequency_lists.js">
</script>
<script type="text/javascript" src="matching.js">
</script>
<script type="text/javascript" src="scoring.js">
</script>
<script type="text/javascript" src="init.js">
</script>

Data lives in the first two scripts. These are produced by:

scripts/build_keyboard_adjacency_graph.py
scripts/build_frequency_lists.py

matching.coffee, scoring.coffee, and init.coffee make up the rest of the library.

init.js needs to come last, otherwise script order doesn't matter.

I recommend setting up coffee-mode in emacs, or whatever equivalent, so that CoffeeScript compiles to js on save. Otherwise you'll need to repetitively run compile_and_minify.js

Acknowledgments

Dropbox for supporting open source!

Mark Burnett for releasing his 10k top passwords list and for his 2006 book, Perfect Passwords: Selection, Protection, Authentication.

Wiktionary contributors for building a frequency list of English as used in television and movies.

Researchers at Concordia University for studying password meters rigorously and recommending zxcvbn.

And xkcd for the inspiration <3

RajUmadas / zxcvbn