Skip to content

Commit 3d5baac

Browse files
veprozaveproza
committed
Added readme for CS-CZ version
1 parent ebda10e commit 3d5baac

File tree

1 file changed

+29
-284
lines changed

1 file changed

+29
-284
lines changed

‎README.md

+29-284
Original file line numberDiff line numberDiff line change
@@ -1,288 +1,33 @@
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-
1+
ZXCVBN password strength estimator with Czech (CS-CZ) dictionaries. Other than localization of the feedback and wordlists, the API is identical to [original zxcvbn.js](https://github.com/dropbox/zxcvbn).
2+
443
# 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-
<script src="bower_components/zxcvbn/dist/zxcvbn.js">
63-
</script>
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-
<script type="text/javascript" src="path/to/zxcvbn.js"></script>
4+
Download [dist/zxcvbn.js](https://raw.githubusercontent.com/veproza/zxcvbn/master/dist/zxcvbn.js), then add script reference to your HTML
5+
```html
6+
<script src="path/to/zxcvbn.js"></script>
1367
```
1378

1389
# 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-
# <a name="perf"></a>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 `<script src="zxcvbn.js">` tag at the end of your html, just before the closing `</body>` tag. This ensures 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.
223-
224-
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.
225-
226-
3. Use the HTML5 [`async`](http://www.w3schools.com/tags/att_script_async.asp) script attribute. Downside: [doesn't work](http://caniuse.com/#feat=script-async) in IE7-9 or Opera Mini.
227-
228-
4. Include an inline `<script>` in `<head>` that asynchronously loads `zxcvbn.js` in the background. Advantage over (3): it works in older browsers.
229-
230-
``` javascript
231-
// cross-browser asynchronous script loading for zxcvbn.
232-
// adapted from http://friendlybit.com/js/lazy-loading-asyncronous-javascript/
233-
234-
(function() {
235-
236-
var ZXCVBN_SRC = 'path/to/zxcvbn.js';
237-
238-
var async_load = function() {
239-
var first, s;
240-
s = document.createElement('script');
241-
s.src = ZXCVBN_SRC;
242-
s.type = 'text/javascript';
243-
s.async = true;
244-
first = document.getElementsByTagName('script')[0];
245-
return first.parentNode.insertBefore(s, first);
246-
};
247-
248-
if (window.attachEvent != null) {
249-
window.attachEvent('onload', async_load);
250-
} else {
251-
window.addEventListener('load', async_load, false);
252-
}
253-
254-
}).call(this);
255-
```
256-
257-
# Development
258-
259-
Bug reports and pull requests welcome!
260-
261-
``` shell
262-
git clone https://github.com/dropbox/zxcvbn.git
263-
```
264-
265-
zxcvbn is built with CoffeeScript, browserify, and uglify-js. CoffeeScript source lives in `src`, which gets compiled, bundled and minified into `dist/zxcvbn.js`.
266-
267-
``` shell
268-
npm run build # builds dist/zxcvbn.js
269-
npm run watch # same, but quickly rebuilds as changes are made in src.
270-
```
271-
272-
For debugging, both `build` and `watch` output an external source map `dist/zxcvbn.js.map` that points back to the original CoffeeScript code.
273-
274-
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.
275-
276-
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.
277-
278-
# Acknowledgments
279-
280-
[Dropbox](https://dropbox.com) for supporting open source!
281-
282-
Mark Burnett for releasing his 10M password corpus and for his 2005 book, [Perfect Passwords: Selection, Protection, Authentication](http://www.amazon.com/Perfect-Passwords-Selection-Protection-Authentication/dp/1597490415).
283-
284-
Wiktionary contributors for building a [frequency list of English words](http://en.wiktionary.org/wiki/Wiktionary:Frequency_lists) as used in television and movies.
285-
286-
Researchers at Concordia University for [studying password estimation rigorously](http://www.concordia.ca/cunews/main/stories/2015/03/25/does-your-password-pass-muster.html) and recommending zxcvbn.
287-
288-
And [xkcd](https://xkcd.com/936/) for the inspiration :+1::horse::battery::heart:
10+
Please refer to original ZXCVBN [Usage section](https://github.com/dropbox/zxcvbn#usage), as the API is completely identical.
11+
12+
# Demo
13+
You can try the estimator on the [demo](https://1gr.cz/test/marcel/zxcvbn/index.html) (with full feedback and reasoning displayed), or you can see a live deployment at [idnes.cz Registration page](https://muj.idnes.cz/registrace.aspx).
14+
> Tip: Try typical Czech passwords such as `heslo` (Czech for *password*), `honzik` (frequent name) or `ěščřžýá` (keyboard walk on Czech keyboard). Compare results with [English zxcvbn demo](https://lowe.github.io/tryzxcvbn/).
15+
16+
# About the dictionaries
17+
The Czech dictionaries were constructed using the original zxcvbn's scripts, just using Czech sources.
18+
- Wikipedia wordlist used Czech Wikipedia mutation
19+
- TV+Film wordlist used a query for Czech subtitles on OpenSubtitles
20+
- Names and surnames were pulled off Czech Statistical Offices' database
21+
- Passwords were obtained from Exploit.in and AntiPublic combolists, `grep`-ed for lines containing `\.cz` (as in name@email<b>.cz</b>:password). There are some artefacts remaining (like `a838hfiD` being #7 most popular password, which is not likely), but overall, the wordlist seems to reflect real world reasonably well.
22+
23+
# Size
24+
Addition of Czech dictionaries doubled the number of dictionaries to be shipped. To keep the size on par with the original zxcvbn, the length of each dictionary in the built library (in `/dist/zxcvbn.js`) was decreased to one-half of the original value. The final file is 409 kB gzipped, similar to original's 390 kB.
25+
> Tip: If you can use [zopfli](https://github.com/google/zopfli) gzip algorithm, you can reduce the size to 393 kB.
26+
27+
If you wish to change the dictionary size (increase, decrease, or change Czech:English ratio), you can do so in `/data-scripts/build_frequency_lists.py`.
28+
29+
# Authors
30+
Localization and testing was done by [idnes.cz](https://www.idnes.cz/) developers.
31+
32+
# License
33+
MIT, same as original.

0 commit comments

Comments
 (0)