DOCSEARCHbyAlgolia
Submit Docs

zxcvbn

repository·master·Indexed 12 days ago

https://github.com/dropbox/zxcvbn

A realistic password strength estimator version 4.4.2 that uses pattern matching to recognize common passwords, names, and sequences to provide crack-time estimates and actionable feedback.

Tokens
1.7K
Snippets
8
Records
10
Agent score
47%

What's inside zxcvbn

  1. Optimize zxcvbn performance

    master
    To maintain low runtime latency, especially for very long inputs, consider only passing the first 100 characters of the user's input to zxcvbn(). Most passwords will be processed in ~5-20ms, but latency can increase to ~100ms for inputs around 100 characters.

  2. Optimize zxcvbn.js script load latency

    master

    The bundled and minified zxcvbn.js is approximately 400kB gzipped or 820kB uncompressed due to its large dictionaries. To prevent page load latency, follow these best practices:

    1. Enable Compression: Ensure your server (e.g., Nginx, Apache, or IIS) is configured to compress static assets using Gzip.
    2. Placement: Place the <script src="zxcvbn.js"> tag at the end of your HTML, just before the closing </body> tag. This allows the page to render before the script is fetched.
    3. RequireJS: Load zxcvbn.js separately from your main bundle. Avoid requiring it inside a user-input handler (like a keyboard event) to prevent latency when the user first types; instead, call the handler once upon page load to trigger the requirejs() call early.
    4. Async Attribute: Use the HTML5 async attribute on your script tag (note: this does not work in IE7-9 or Opera Mini).
    5. Cross-browser Asynchronous Loading: For older browser support, use an inline script in the <head> to load the file asynchronously.
    // 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';

  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);

  4. Install zxcvbn via Bower

    master

    If you are using Bower, install the package and include the distributed script in your index.html.

    To update the package, use bower update zxcvbn.

    cd /path/to/project/root
bower install zxcvbn
    <script src="bower_components/zxcvbn/dist/zxcvbn.js">
</script>

  5. Install zxcvbn via RequireJS

    master

    Add zxcvbn.js to your project (via bower, npm, or direct download) and import it using the standard requirejs syntax.

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

  6. Install zxcvbn via Browserify or Webpack

    master

    If you use require('zxcvbn') in your source code, Browserify and Webpack will automatically bundle it.

    Note: The maintainers recommend against bundling zxcvbn directly into your main application bundle because it is several hundred kilobytes (even minified/gzipped). Instead, consider loading it on demand when a user interacts with a password field to avoid increasing initial page load time.

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

  8. Build zxcvbn from source

    master

    If you are developing on zxcvbn, you can build the project using npm. The CoffeeScript source in src is compiled, bundled, and minified into dist/zxcvbn.js using browserify and uglify-js. Both build and watch commands generate an external source map dist/zxcvbn.js.map for debugging.

    To build the project:

    • Use npm run build for a one-time build.
    • Use npm run watch to automatically rebuild as changes are made to the src directory.
    npm run build    # builds dist/zxcvbn.js
npm run watch    # same, but quickly rebuilds as changes are made in src.

  9. Use the zxcvbn() API

    master

    The zxcvbn() function estimates password strength. It takes a required password string and an optional user_inputs array.

    user_inputs is an array of strings (e.g., username, email, or site-specific vocabulary) that zxcvbn will use to penalize passwords that contain personal or predictable information.

    zxcvbn(password, user_inputs=[])
    zxcvbn('Tr0ub4dour&3');

  10. Understand the zxcvbn result object

    master

    The zxcvbn() function returns a result object containing strength metrics, crack time estimates, and user feedback.

    Strength Score

    result.score is an integer from 0 to 4:

    • 0: too guessable (risky)
    • 1: very guessable
    • 2: somewhat guessable
    • 3: safely unguessable
    • 4: very unguessable

    Crack Time Estimations

    • result.crack_times_seconds: A dictionary of crack time estimates in seconds for various scenarios (online throttling, online no throttling, offline slow hashing, offline fast hashing).
    • result.crack_times_display: The same dictionary as above, but with human-friendly strings (e.g., "3 hours", "centuries").

    Feedback

    result.feedback provides verbal guidance when score <= 2:

    • result.feedback.warning: A string explaining what is wrong (e.g., 'this is a top-10 common password').
    • result.feedback.suggestions: An array of strings suggesting improvements (e.g., 'Add another word or two').

    Other Properties

    • result.guesses: Estimated number of guesses needed to crack the password.
    • result.guesses_log10: The order of magnitude of result.guesses.
    • result.sequence: The list of patterns used for the calculation.
    • result.calc_time: Calculation time in milliseconds.