shotishu / zxcvbn

A realistic password strength estimator.

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

zxcvbn is a password strength estimator inspired by password crackers. Through pattern matching and conservative entropy calculations, it recognizes and weighs 10k common passwords, common names and surnames according to US census data, popular English words, and other common patterns like dates, repeats (aaa), sequences (abcd), keyboard patterns (qwertyuiop), and l33t speak.

Consider using zxcvbn as an algorithmic alternative to password policy — it is more secure, flexible, and usable when sites require a minimal complexity score in place of annoying rules like "passwords must contain three of {lower, upper, numbers, symbols}".

• More secure: policies often fail both ways, allowing weak passwords (P@ssword1) and disallowing strong passwords.
• More flexible: zxcvbn allows many password styles to flourish so long as it detects sufficient complexity — passphrases are rated highly given enough uncommon words, keyboard patterns are either terrible or great depending on length and number of turns, and capitalization adds more complexity when it's unpredictaBle. Neither crackers nor zxcvbn are fooled by '@' for 'a' or '0' for 'o'.
• More usable: Dumping a list of password rules onto users hurts usability. Understanding and satisfying said rules can be time-consuming and frustrating, leading to passwords that are harder to remember. Use zxcvbn instead to build simple, rule-free interfaces that give instant feedback.

At Dropbox we use zxcvbn on our signup page and change/reset password flows. zxcvbn is designed for node and the browser, but we use our python port inside the Dropbox desktop client, Objective C port in our iOS app, and Java port (not yet open sourced) on Android.

Release notes

For more motivation, see:

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

Installation

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

Bower

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

Get zxcvbn:

cd /path/to/project/root
bower install zxcvbn

Add this script to your index.html:

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

To make sure it loaded properly, open your html in a browser and type zxcvbn('Tr0ub4dour&3') into the console.

To pull in updates and bug fixes:

bower update zxcvbn

Node / npm

zxcvbn works identically on the server.

$ npm install zxcvbn
$ node
> var zxcvbn = require('zxcvbn');
> zxcvbn('Tr0ub4dour&3');

RequireJS

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

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

Browserify / Webpack

If you're using npm and have require('zxcvbn') somewhere in your code, browserify and webpack should just work.

$ npm install zxcvbn
$ echo "console.log(require('zxcvbn'))" > mymodule.js
$ browserify mymodule.js > browserify_bundle.js
$ webpack mymodule.js webpack_bundle.js

But we recommend against bundling zxcvbn via tools like browserify and webpack, for three reasons:

• Minified and gzipped, zxcvbn is still several hundred kilobytes. (Significantly grows bundle size.)
• Most sites will only need zxcvbn on a few pages (registration, password reset).
• Most sites won't need zxcvbn() immediately upon page load; since zxcvbn() is typically called in response to user events like filling in a password, there's ample time to fetch zxcvbn.js after initial html/css/js loads and renders.

See the performance section below for tips on loading zxcvbn stand-alone.

Tangentially, if you want to build your own standalone, consider tweaking the browserify pipeline used to generate dist/zxcvbn.js:

$ browserify --debug --standalone zxcvbn \
    -t coffeeify --extension='.coffee' \
    -t uglifyify \
    src/main.coffee | exorcist dist/zxcvbn.js.map >| dist/zxcvbn.js

• --debug adds an inline source map to the bundle. exorcist pulls it out into dist/zxcvbn.js.map.
• --standalone zxcvbn exports a global zxcvbn when CommonJS/AMD isn't detected.
• -t coffeeify --extension='.coffee' compiles .coffee to .js before bundling. This is convenient as it allows .js modules to import from .coffee modules and vice-versa. Instead of this transform, one could also compile everything to .js first (npm run prepublish) and point browserify to lib instead of src.
• -t uglifyify minifies the bundle through UglifyJS, maintaining proper source mapping.

Manual installation

Download zxcvbn.js.

Add to your .html:

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

Usage

zxcvbn(password, user_inputs=[])

zxcvbn() 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 zxcvbn to calculate an answer,
                          # in milliseconds.

The optional user_inputs argument is an array of strings that zxcvbn will treat as an extra 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 a user's personal information can be heavily penalized. This list is also good for site-specific vocabulary — Acme Brick Co. might want to include ['acme', 'brick', 'acmebrick', etc].

Performance

runtime latency

zxcvbn operates below human perception of delay for most input: ~5-20ms for ~25 char passwords on modern browsers/CPUs, ~100ms for passwords around 100 characters. To bound runtime latency for really long passwords, consider sending zxcvbn() only the first 100 characters or so of user input.

script load latency

zxcvbn.js bundled and minified is about 320kb gzipped or 680kb uncompressed, most of which is dictionaries. Consider these tips if you're noticing page load latency on your site.

• Make sure your server is configured to compress static assets for browsers that support it. (nginx tutorial, apache/IIS tutorial.)

Then try one of these alternatives:

1. Put your <script src="zxcvbn.js"> tag at the end of your html, just before the closing </body> tag. This insures your page loads and renders before the browser fetches and loads zxcvbn.js. The downside with this approach is zxcvbn() becomes available later than had it been included in <head> — not an issue on most signup pages where users are filling out other fields first.

2. If you're using requirejs, try loading zxcvbn.js separately from your main bundle. Something to watch out for: if zxcvbn.js is required inside a keyboard handler waiting for user input, the entire script might be loaded only after the user presses their first key, creating nasty latency. Avoid this by calling your handler once upon page load, independent of user input, such that the requirejs() call runs earlier.

3. Use the HTML5 async script attribute. Downside: doesn't work in IE7-9 or Opera Mini.

4. Include an inline <script> in <head> that asynchronously loads zxcvbn.js in the background. Despite the extra code I prefer this over (3) because it works in older browsers.

// cross-browser asynchronous script loading for zxcvbn.
// adapted from http://friendlybit.com/js/lazy-loading-asyncronous-javascript/

(function() {
  var ZXCVBN_SRC = 'path/to/zxcvbn.js';   // eg. for a standard bower setup, 'bower_components/zxcvbn/zxcvbn.js'

  var async_load = function() {
    var first, s;
    s = document.createElement('script');
    s.src = ZXCVBN_SRC;
    s.type = 'text/javascript';
    s.async = true;
    first = document.getElementsByTagName('script')[0];
    return first.parentNode.insertBefore(s, first);
  };

  if (window.attachEvent != null) {
    window.attachEvent('onload', async_load);
  } else {
    window.addEventListener('load', async_load, false);
  }

}).call(this);

Development

Bug reports and pull requests welcome!

git clone https://github.com/dropbox/zxcvbn.git

zxcvbn is built with CoffeeScript, browserify, and uglify-js. CoffeeScript source lives in src, which gets compiled, bundled and minified into dist/zxcvbn.js.

npm run build    # builds dist/zxcvbn.js
npm run watch    # same, but quickly rebuilds as changes are made in src.

For debugging, both build and watch output an external source map dist/zxcvbn.js.map that points back to the original CoffeeScript code.

Two source files, adjacency_graphs.coffee and frequency_lists.coffee, are generated by python scripts in data-scripts that read raw data from the data directory.

For node developers, in addition to dist, the zxcvbn npm module includes a lib directory (hidden from git) that includes one compiled .js and .js.map file for every .coffee in src. See prepublish in package.json to learn more.

Acknowledgments

Dropbox for supporting open source!

Leah Culver and Ryan Pearl for porting zxcvbn to Objective C and python.

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 estimation rigorously and recommending zxcvbn.

And xkcd for the inspiration 👍🐴🔋❤️