Github url

zxcvbn

by dropbox

dropbox /zxcvbn

Low-Budget Password Strength Estimation

11.3K Stars 758 Forks Last release: over 3 years ago (v4.4.2) MIT License 379 Commits 30 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_/\/\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ \_/\/\/\/\/\_\_/\/\_\_/\/\_\_\_\_/\/\/\/\_\_/\/\_\_/\/\_\_/\/\_\_\_\_\_\_\_\_/\/\/\/\_\_\_ \_\_\_\_\_/\/\_\_\_\_\_\_/\/\/\_\_\_\_/\/\_\_\_\_\_\_\_\_/\/\_\_/\/\_\_/\/\/\/\_\_\_\_/\/\_\_/\/\_ \_\_\_/\/\_\_\_\_\_\_\_\_/\/\/\_\_\_\_/\/\_\_\_\_\_\_\_\_\_\_/\/\/\_\_\_\_/\/\_\_/\/\_\_/\/\_\_/\/\_ \_/\/\/\/\/\_\_/\/\_\_/\/\_\_\_\_/\/\/\/\_\_\_\_\_\_/\_\_\_\_\_\_/\/\/\/\_\_\_\_/\/\_\_/\/\_ \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_

Build StatusSauce Test Status

zxcvbn

is a password strength estimator inspired by password crackers. Through pattern matching and conservative estimation, it recognizes and weighs 30k common passwords, common names and surnames according to US census data, popular English words from Wikipedia and US television and movies, 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 composition 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 (
    [email protected]
    ) 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 ranked based on length and number of turns, and capitalization adds more complexity when it's unpredictaBle.
  • More usable: zxcvbn is designed to power simple, rule-free interfaces that give instant feedback. In addition to strength estimation, zxcvbn includes minimal, targeted verbal feedback that can help guide users towards less guessable passwords.

For further detail and motivation, please refer to the USENIX Security '16 paper and presentation.

At Dropbox we use zxcvbn (Release notes) on our web, desktop, iOS and Android clients. If JavaScript doesn't work for you, others have graciously ported the library to these languages:

Integrations with other frameworks: * [

angular-zxcvbn

](https://github.com/ghostbar/angular-zxcvbn) (AngularJS)

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

](https://nodejs.org/download/) and [

bower

](http://bower.io/) if you haven't already.

Get

zxcvbn

:

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

Add this script to your

index.html

:

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

To make sure it loaded properly, open in a browser and type

zxcvbn('Tr0ub4dour&3')

into the console.

To pull in updates and bug fixes:

bower update zxcvbn

Node / npm / MeteorJS

zxcvbn works identically on the server.

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

RequireJS

Add [

zxcvbn.js

](https://raw.githubusercontent.com/dropbox/zxcvbn/master/dist/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

try zxcvbn interactively to see these docs in action.

zxcvbn(password, user\_inputs=[])
zxcvbn()

takes one required argument, a password, and returns a result object with several properties:

result.guesses # estimated guesses needed to crack password result.guesses\_log10 # order of magnitude of result.guesses result.crack\_times\_seconds # dictionary of back-of-the-envelope crack time # estimations, in seconds, based on a few scenarios: { # online attack on a service that ratelimits password auth attempts. online\_throttling\_100\_per\_hour # online attack on a service that doesn't ratelimit, # or where an attacker has outsmarted ratelimiting. online\_no\_throttling\_10\_per\_second # offline attack. assumes multiple attackers, # proper user-unique salting, and a slow hash function # w/ moderate work factor, such as bcrypt, scrypt, PBKDF2. offline\_slow\_hashing\_1e4\_per\_second # offline attack with user-unique salting but a fast hash # function like SHA-1, SHA-256 or MD5. A wide range of # reasonable numbers anywhere from one billion - one trillion # guesses per second, depending on number of cores and machines. # ballparking at 10B/sec. offline\_fast\_hashing\_1e10\_per\_second } result.crack\_times\_display # same keys as result.crack\_times\_seconds, # with friendlier display string values: # "less than a second", "3 hours", "centuries", etc. result.score # Integer from 0-4 (useful for implementing a strength bar) 0 # too guessable: risky password. (guesses \< 10^3) 1 # very guessable: protection from throttled online attacks. (guesses \< 10^6) 2 # somewhat guessable: protection from unthrottled online attacks. (guesses \< 10^8) 3 # safely unguessable: moderate protection from offline slow-hash scenario. (guesses \< 10^10) 4 # very unguessable: strong protection from offline slow-hash scenario. (guesses \>= 10^10) result.feedback # verbal feedback to help choose better passwords. set when score \<= 2. result.feedback.warning # explains what's wrong, eg. 'this is a top-10 common password'. # not always set -- sometimes an empty string result.feedback.suggestions # a possibly-empty list of suggestions to help choose a less # guessable password. eg. 'Add another word or two' result.sequence # the list of patterns that zxcvbn based the # guess 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 400kB gzipped or 820kB uncompressed, most of which is dictionaries. Consider these tips if you're noticing page load latency on your site.

Then try one of these alternatives:

  1. Put your

<script src="zxcvbn.js"></script>

tag at the end of your html, just before the closing

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.