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