1# zxcvbn-cpp
2
3This is a C++ port of [`zxcvbn`](https://github.com/dropbox/zxcvbn),
4an advanced password strength estimation library. For more details on how
5`zxcvbn` works and its advantages, check out
6[the blog post](https://tech.dropbox.com/2012/04/zxcvbn-realistic-password-strength-estimation/).
7
8This port is a direct translation of the original CoffeeScript
9source. This allows this port to easily stay in sync with the original
10source. Additionally, this port uses the same exact test scripts from
11the original with the help of emscripten.
12
13This port also provides C, Python, and JS bindings from the same
14codebase.
15
16## Python Bindings
17
18### Build
19
20```shell
21$ python setup.py install
22```
23
24### Use
25
26```python
27>>> import zxcvbncpp
28>>> print(zxcvbncpp.password_strength("Tr0ub4dour&3"))
29```
30
31## JS Bindings
32
33### Build
34
35Building the JS bindings requires a POSIX environment, including
36`make`, and [Emscripten](https://emscripten.org/).
37
38First make sure `emcc` is in your `$PATH`. You can do so using the
39Emscripten Portable SDK as follows:
40
41```shell
42$ source /path/to/emsdk_portable/emsdk_env.sh
43```
44
45Then simply run:
46
47```shell
48$ RELEASE=1 make -f jsmakefile lib/zxcvbn.js
49```
50
51### Use
52
53Add this script to your `index.html`:
54
55``` html
56<script src="path/to/zxcvbn.js"></script>
57```
58
59To make sure it loaded properly, open in a browser and type
60`zxcvbn('Tr0ub4dour&3')` into the console. For more information on how
61to use the JS port see the
62[original documentation](https://github.com/dropbox/zxcvbn#usage).
63
64### Use From Node
65
66Usage from node is straight-forward:
67
68```javascript
69var zxcvbn = require("./path/to/zxcvbn.js");
70console.log(zxcvbn("Tr0ub4dour&3"));
71```
72
73## How to build for your C/C++ project
74
75Adapt these instructions to your build environment.
76
77First generate adjacency graphs and frequency lists:
78
79```shell
80$ python ./data-scripts/build_frequency_lists.py ./data ./native-src/zxcvbn _frequency_lists.hpp
81$ python ./data-scripts/build_frequency_lists.py ./data ./native-src/zxcvbn _frequency_lists.cpp
82$ python ./data-scripts/build_keyboard_adjacency_graphs.py ./native-src/zxcvbn/adjacency_graphs.hpp
83$ python ./data-scripts/build_keyboard_adjacency_graphs.py ./native-src/zxcvbn/adjacency_graphs.cpp
84```
85
86Add `/absolute_path/to/zxcvbn-repo/native-src` to your include path,
87then build all the `.cpp` files in
88`/absolute_path/to/zxcvbn-repo/native-src/zxcvbn`. Make sure you
89use the `-std=c++14` compiler flag.
90
91## Testing
92
93`zxcvbn-cpp` uses the test scripts from the original codebase, this
94makes it easy to verify that it is 100% compatible with the original.
95In addition to requiring a POSIX environment and Emscripten, testing
96also requires a NodeJS environment. Here's how you set it up:
97
98```shell
99$ npm install
100```
101
102Then to run the tests:
103
104```shell
105$ make -f jsmakefile test
106```
107
108## Development
109
110Bug reports and pull requests welcome!
111
112Please note `zxcvbn-cpp` is written using modern C++14 techniques, no
113passing around stray pointers!
114