How to use zxcvbn: install and read password strength scores

What zxcvbn checks in a password

zxcvbn is a password strength estimator inspired by password crackers. It uses pattern matching and conservative estimation to recognize common passwords, common names and surnames, popular English words, dates, repeats, sequences, keyboard patterns and l33t speak.

Because it looks for patterns rather than applying fixed rules, it can rate passphrases and other styles highly when they contain enough uncommon words. The README presents it as an alternative to composition rules such as requiring three of lowercase, uppercase, numbers and symbols.

• Common passwords, names, census surnames and dictionary words
• Dates, repeats such as aaa, and sequences such as abcd
• Keyboard patterns such as qwertyuiop and simple substitutions like l33t speak

Install zxcvbn with npm

For Node.js projects, the README gives the npm install method. Node.js is the prerequisite for this method. zxcvbn works the same on the server as in the browser.

The README also documents Bower and manual installation, where you add dist/zxcvbn.js with a script tag. When no CommonJS or AMD loader is detected, the library adds a single zxcvbn() function to the global namespace.

Call zxcvbn and read the result

zxcvbn() takes one required argument, the password, and an optional list of user inputs. The README shows a quick check in Node.js using a sample password. The result object includes guesses, guesses_log10, crack_times_seconds, crack_times_display, score and feedback.

The score is an integer from 0 to 4. The README defines 0 as too guessable, 1 as very guessable, 2 as somewhat guessable, 3 as safely unguessable and 4 as very unguessable. The feedback object is set when the score is 2 or lower and includes a warning field that explains what is wrong.

• score: integer 0-4, useful for a strength bar
• guesses: estimated guesses needed to crack the password
• crack_times_display: friendly strings such as less than a second or centuries
• feedback.warning: explains what is wrong when score is 2 or lower

Show the strength meter in a sign-up form

The README says zxcvbn() is typically called in response to user events such as filling in a password. You can run it on each change to the password field and map the score to a strength bar.

The library is several hundred kilobytes minified and gzipped, so the README recommends not bundling it into every page. Load it on registration and password reset pages, and fetch it after the initial page renders, since the check is not needed on page load.

• Call zxcvbn on each input event of the password field
• Map result.score (0-4) to your bar or label
• Pass user-specific words such as the username as user_inputs
• Load the script only on pages where passwords are entered

Load zxcvbn in the browser

For a plain web page, add the script from dist/zxcvbn.js to your HTML. To check that it loaded, open the page in a browser and type zxcvbn('Tr0ub4dour&3') into the console. If you use RequireJS, import the module as a dependency and call zxcvbn inside the callback.

The README also explains how the browserify build is generated, including the coffeeify transform, since the source is written in CoffeeScript.

Know the limits before you rely on it

The README describes zxcvbn's output as estimates, not certainty. A high score does not guarantee security, so treat the score as guidance for users and keep your server-side protections such as salted, slow password hashing.

The crack time figures are back-of-the-envelope scenarios. The README lists online throttled and unthrottled attacks, and offline slow and fast hashing, each with an assumed guess rate.