├── .gitignore ├── .npmignore ├── .travis.yml ├── .zuul.yml ├── LICENSE.txt ├── README.md ├── bower.json ├── data-scripts ├── build_frequency_lists.py ├── build_keyboard_adjacency_graphs.py ├── count_us_census.py ├── count_wikipedia.py ├── count_wiktionary.py └── count_xato.coffee ├── data ├── english_wikipedia.txt ├── female_names.txt ├── male_names.txt ├── passwords.txt ├── surnames.txt └── us_tv_and_film.txt ├── demo ├── demo.coffee ├── index.html ├── jquery.js ├── mustache.js └── require.js ├── dist ├── zxcvbn.js └── zxcvbn.js.map ├── package.json ├── src ├── adjacency_graphs.coffee ├── feedback.coffee ├── frequency_lists.coffee ├── main.coffee ├── matching.coffee ├── scoring.coffee └── time_estimates.coffee └── test ├── test-matching.coffee └── test-scoring.coffee /.gitignore: -------------------------------------------------------------------------------- 1 | *.js 2 | !zxcvbn*.js 3 | !demo/jquery.js 4 | !demo/require.js 5 | !demo/mustache.js 6 | node_modules 7 | lib 8 | *~ 9 | *.swp 10 | *.swo 11 | tmux-*.log 12 | -------------------------------------------------------------------------------- /.npmignore: -------------------------------------------------------------------------------- 1 | .git 2 | .gitignore 3 | bower.json 4 | data 5 | data-scripts 6 | demo 7 | test 8 | 9 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | sudo: false 2 | language: node_js 3 | node_js: 4 | - node 5 | script: npm run test 6 | -------------------------------------------------------------------------------- /.zuul.yml: -------------------------------------------------------------------------------- 1 | ui: tape 2 | browsers: 3 | - name: chrome 4 | version: [36, -2..latest] 5 | - name: safari 6 | version: -2..latest 7 | - name: firefox 8 | version: -2..latest 9 | - name: ie 10 | version: 9..latest 11 | - name: opera 12 | version: -1..latest 13 | - name: android 14 | version: -2..latest 15 | browserify: 16 | - transform: coffeeify 17 | - options: 18 | extensions: 19 | - .coffee 20 | -------------------------------------------------------------------------------- /LICENSE.txt: -------------------------------------------------------------------------------- 1 | Copyright (c) 2012-2016 Dan Wheeler and Dropbox, Inc. 2 | 3 | Permission is hereby granted, free of charge, to any person obtaining 4 | a copy of this software and associated documentation files (the 5 | "Software"), to deal in the Software without restriction, including 6 | without limitation the rights to use, copy, modify, merge, publish, 7 | distribute, sublicense, and/or sell copies of the Software, and to 8 | permit persons to whom the Software is furnished to do so, subject to 9 | the following conditions: 10 | 11 | The above copyright notice and this permission notice shall be 12 | included in all copies or substantial portions of the Software. 13 | 14 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 15 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 16 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 17 | NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE 18 | LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 19 | OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 20 | WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 21 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ``` 2 | _________________________________________________/\/\___________________ 3 | _/\/\/\/\/\__/\/\__/\/\____/\/\/\/\__/\/\__/\/\__/\/\________/\/\/\/\___ 4 | _____/\/\______/\/\/\____/\/\________/\/\__/\/\__/\/\/\/\____/\/\__/\/\_ 5 | ___/\/\________/\/\/\____/\/\__________/\/\/\____/\/\__/\/\__/\/\__/\/\_ 6 | _/\/\/\/\/\__/\/\__/\/\____/\/\/\/\______/\______/\/\/\/\____/\/\__/\/\_ 7 | ________________________________________________________________________ 8 | ``` 9 | 10 | [![Build Status](https://travis-ci.org/dropbox/zxcvbn.svg?branch=master)](https://travis-ci.org/dropbox/zxcvbn) 11 | [![Sauce Test Status](https://saucelabs.com/browser-matrix/dropbox-zxcvbn.svg)](https://saucelabs.com/u/dropbox-zxcvbn) 12 | 13 | `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. 14 | 15 | 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}". 16 | 17 | * __More secure__: policies often fail both ways, allowing weak passwords (`P@ssword1`) and disallowing strong passwords. 18 | * __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. 19 | * __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. 20 | 21 | For further detail and motivation, please refer to the USENIX Security '16 [paper and presentation](https://www.usenix.org/conference/usenixsecurity16/technical-sessions/presentation/wheeler). 22 | 23 | At Dropbox we use zxcvbn ([Release notes](https://github.com/dropbox/zxcvbn/releases)) on our web, desktop, iOS and Android clients. If JavaScript doesn't work for you, others have graciously ported the library to these languages: 24 | 25 | * [`zxcvbn-python`](https://github.com/dwolfhub/zxcvbn-python) (Python) 26 | * [`zxcvbn-cpp`](https://github.com/rianhunter/zxcvbn-cpp) (C/C++/Python/JS) 27 | * [`zxcvbn-c`](https://github.com/tsyrogit/zxcvbn-c) (C/C++) 28 | * [`zxcvbn-rs`](https://github.com/shssoichiro/zxcvbn-rs) (Rust) 29 | * [`zxcvbn-go`](https://github.com/nbutton23/zxcvbn-go) (Go) 30 | * [`zxcvbn4j`](https://github.com/nulab/zxcvbn4j) (Java) 31 | * [`nbvcxz`](https://github.com/GoSimpleLLC/nbvcxz) (Java) 32 | * [`zxcvbn-ruby`](https://github.com/envato/zxcvbn-ruby) (Ruby) 33 | * [`zxcvbn-js`](https://github.com/bitzesty/zxcvbn-js) (Ruby [via ExecJS]) 34 | * [`zxcvbn-ios`](https://github.com/dropbox/zxcvbn-ios) (Objective-C) 35 | * [`zxcvbn-cs`](https://github.com/mickford/zxcvbn-cs) (C#/.NET) 36 | * [`szxcvbn`](https://github.com/tekul/szxcvbn) (Scala) 37 | * [`zxcvbn-php`](https://github.com/bjeavons/zxcvbn-php) (PHP) 38 | * [`zxcvbn-api`](https://github.com/wcjr/zxcvbn-api) (REST) 39 | * [`ocaml-zxcvbn`](https://github.com/cryptosense/ocaml-zxcvbn) (OCaml bindings for `zxcvbn-c`) 40 | 41 | Integrations with other frameworks: 42 | * [`angular-zxcvbn`](https://github.com/ghostbar/angular-zxcvbn) (AngularJS) 43 | 44 | # Installation 45 | 46 | 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. 47 | 48 | ## Bower 49 | 50 | Install [`node`](https://nodejs.org/download/) and [`bower`](http://bower.io/) if you haven't already. 51 | 52 | Get `zxcvbn`: 53 | 54 | ``` shell 55 | cd /path/to/project/root 56 | bower install zxcvbn 57 | ``` 58 | 59 | Add this script to your `index.html`: 60 | 61 | ``` html 62 | 64 | ``` 65 | 66 | To make sure it loaded properly, open in a browser and type `zxcvbn('Tr0ub4dour&3')` into the console. 67 | 68 | To pull in updates and bug fixes: 69 | 70 | ``` shell 71 | bower update zxcvbn 72 | ``` 73 | 74 | ## Node / npm / MeteorJS 75 | 76 | zxcvbn works identically on the server. 77 | 78 | ``` shell 79 | $ npm install zxcvbn 80 | $ node 81 | > var zxcvbn = require('zxcvbn'); 82 | > zxcvbn('Tr0ub4dour&3'); 83 | ``` 84 | 85 | ## RequireJS 86 | 87 | 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: 88 | 89 | ``` javascript 90 | requirejs(["relpath/to/zxcvbn"], function (zxcvbn) { 91 | console.log(zxcvbn('Tr0ub4dour&3')); 92 | }); 93 | ``` 94 | 95 | ## Browserify / Webpack 96 | 97 | If you're using `npm` and have `require('zxcvbn')` somewhere in your code, browserify and webpack should just work. 98 | 99 | ``` shell 100 | $ npm install zxcvbn 101 | $ echo "console.log(require('zxcvbn'))" > mymodule.js 102 | $ browserify mymodule.js > browserify_bundle.js 103 | $ webpack mymodule.js webpack_bundle.js 104 | ``` 105 | 106 | But we recommend against bundling zxcvbn via tools like browserify and webpack, for three reasons: 107 | 108 | * Minified and gzipped, zxcvbn is still several hundred kilobytes. (Significantly grows bundle size.) 109 | * Most sites will only need zxcvbn on a few pages (registration, password reset). 110 | * 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. 111 | 112 | See the [performance](#perf) section below for tips on loading zxcvbn stand-alone. 113 | 114 | Tangentially, if you want to build your own standalone, consider tweaking the browserify pipeline used to generate `dist/zxcvbn.js`: 115 | 116 | ``` shell 117 | $ browserify --debug --standalone zxcvbn \ 118 | -t coffeeify --extension='.coffee' \ 119 | -t uglifyify \ 120 | src/main.coffee | exorcist dist/zxcvbn.js.map >| dist/zxcvbn.js 121 | ``` 122 | 123 | * `--debug` adds an inline source map to the bundle. `exorcist` pulls it out into `dist/zxcvbn.js.map`. 124 | * `--standalone zxcvbn` exports a global `zxcvbn` when CommonJS/AMD isn't detected. 125 | * `-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`. 126 | * `-t uglifyify` minifies the bundle through UglifyJS, maintaining proper source mapping. 127 | 128 | ## Manual installation 129 | 130 | Download [zxcvbn.js](https://raw.githubusercontent.com/dropbox/zxcvbn/master/dist/zxcvbn.js). 131 | 132 | Add to your .html: 133 | 134 | ``` html 135 | 136 | ``` 137 | 138 | # Usage 139 | 140 | [try zxcvbn interactively](https://lowe.github.io/tryzxcvbn/) to see these docs in action. 141 | 142 | ``` javascript 143 | zxcvbn(password, user_inputs=[]) 144 | ``` 145 | 146 | `zxcvbn()` takes one required argument, a password, and returns a result object with several properties: 147 | 148 | ``` coffee 149 | result.guesses # estimated guesses needed to crack password 150 | result.guesses_log10 # order of magnitude of result.guesses 151 | 152 | result.crack_times_seconds # dictionary of back-of-the-envelope crack time 153 | # estimations, in seconds, based on a few scenarios: 154 | { 155 | # online attack on a service that ratelimits password auth attempts. 156 | online_throttling_100_per_hour 157 | 158 | # online attack on a service that doesn't ratelimit, 159 | # or where an attacker has outsmarted ratelimiting. 160 | online_no_throttling_10_per_second 161 | 162 | # offline attack. assumes multiple attackers, 163 | # proper user-unique salting, and a slow hash function 164 | # w/ moderate work factor, such as bcrypt, scrypt, PBKDF2. 165 | offline_slow_hashing_1e4_per_second 166 | 167 | # offline attack with user-unique salting but a fast hash 168 | # function like SHA-1, SHA-256 or MD5. A wide range of 169 | # reasonable numbers anywhere from one billion - one trillion 170 | # guesses per second, depending on number of cores and machines. 171 | # ballparking at 10B/sec. 172 | offline_fast_hashing_1e10_per_second 173 | } 174 | 175 | result.crack_times_display # same keys as result.crack_times_seconds, 176 | # with friendlier display string values: 177 | # "less than a second", "3 hours", "centuries", etc. 178 | 179 | result.score # Integer from 0-4 (useful for implementing a strength bar) 180 | 181 | 0 # too guessable: risky password. (guesses < 10^3) 182 | 183 | 1 # very guessable: protection from throttled online attacks. (guesses < 10^6) 184 | 185 | 2 # somewhat guessable: protection from unthrottled online attacks. (guesses < 10^8) 186 | 187 | 3 # safely unguessable: moderate protection from offline slow-hash scenario. (guesses < 10^10) 188 | 189 | 4 # very unguessable: strong protection from offline slow-hash scenario. (guesses >= 10^10) 190 | 191 | result.feedback # verbal feedback to help choose better passwords. set when score <= 2. 192 | 193 | result.feedback.warning # explains what's wrong, eg. 'this is a top-10 common password'. 194 | # not always set -- sometimes an empty string 195 | 196 | result.feedback.suggestions # a possibly-empty list of suggestions to help choose a less 197 | # guessable password. eg. 'Add another word or two' 198 | 199 | result.sequence # the list of patterns that zxcvbn based the 200 | # guess calculation on. 201 | 202 | result.calc_time # how long it took zxcvbn to calculate an answer, 203 | # in milliseconds. 204 | ```` 205 | 206 | 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]. 207 | 208 | # Performance 209 | 210 | ## runtime latency 211 | 212 | 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. 213 | 214 | ## script load latency 215 | 216 | `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. 217 | 218 | * Make sure your server is configured to compress static assets for browsers that support it. ([nginx tutorial](https://rtcamp.com/tutorials/nginx/enable-gzip/), [Apache/IIS tutorial](http://betterexplained.com/articles/how-to-optimize-your-site-with-gzip-compression/).) 219 | 220 | Then try one of these alternatives: 221 | 222 | 1. Put your ` 7 | 9 | 11 | 12 | 13 | 40 |

introduction

41 |

zxcvbn on github

42 |

demo

43 | 44 | 45 |
46 |
47 | 48 |
49 |

examples

50 |
51 |
52 | 53 | 54 | 55 | -------------------------------------------------------------------------------- /demo/mustache.js: -------------------------------------------------------------------------------- 1 | /*! 2 | * mustache.js - Logic-less {{mustache}} templates with JavaScript 3 | * http://github.com/janl/mustache.js 4 | */ 5 | var Mustache = (typeof module !== "undefined" && module.exports) || {}; 6 | 7 | (function (exports) { 8 | 9 | exports.name = "mustache.js"; 10 | exports.version = "0.5.0-dev"; 11 | exports.tags = ["{{", "}}"]; 12 | exports.parse = parse; 13 | exports.compile = compile; 14 | exports.render = render; 15 | exports.clearCache = clearCache; 16 | 17 | // This is here for backwards compatibility with 0.4.x. 18 | exports.to_html = function (template, view, partials, send) { 19 | var result = render(template, view, partials); 20 | 21 | if (typeof send === "function") { 22 | send(result); 23 | } else { 24 | return result; 25 | } 26 | }; 27 | 28 | var _toString = Object.prototype.toString; 29 | var _isArray = Array.isArray; 30 | var _forEach = Array.prototype.forEach; 31 | var _trim = String.prototype.trim; 32 | 33 | var isArray; 34 | if (_isArray) { 35 | isArray = _isArray; 36 | } else { 37 | isArray = function (obj) { 38 | return _toString.call(obj) === "[object Array]"; 39 | }; 40 | } 41 | 42 | var forEach; 43 | if (_forEach) { 44 | forEach = function (obj, callback, scope) { 45 | return _forEach.call(obj, callback, scope); 46 | }; 47 | } else { 48 | forEach = function (obj, callback, scope) { 49 | for (var i = 0, len = obj.length; i < len; ++i) { 50 | callback.call(scope, obj[i], i, obj); 51 | } 52 | }; 53 | } 54 | 55 | var spaceRe = /^\s*$/; 56 | 57 | function isWhitespace(string) { 58 | return spaceRe.test(string); 59 | } 60 | 61 | var trim; 62 | if (_trim) { 63 | trim = function (string) { 64 | return string == null ? "" : _trim.call(string); 65 | }; 66 | } else { 67 | var trimLeft, trimRight; 68 | 69 | if (isWhitespace("\xA0")) { 70 | trimLeft = /^\s+/; 71 | trimRight = /\s+$/; 72 | } else { 73 | // IE doesn't match non-breaking spaces with \s, thanks jQuery. 74 | trimLeft = /^[\s\xA0]+/; 75 | trimRight = /[\s\xA0]+$/; 76 | } 77 | 78 | trim = function (string) { 79 | return string == null ? "" : 80 | String(string).replace(trimLeft, "").replace(trimRight, ""); 81 | }; 82 | } 83 | 84 | var escapeMap = { 85 | "&": "&", 86 | "<": "<", 87 | ">": ">", 88 | '"': '"', 89 | "'": ''' 90 | }; 91 | 92 | function escapeHTML(string) { 93 | return String(string).replace(/&(?!\w+;)|[<>"']/g, function (s) { 94 | return escapeMap[s] || s; 95 | }); 96 | } 97 | 98 | /** 99 | * Adds the `template`, `line`, and `file` properties to the given error 100 | * object and alters the message to provide more useful debugging information. 101 | */ 102 | function debug(e, template, line, file) { 103 | file = file || "