1 | # Hashy
|
2 |
|
3 | [![Build Status](https://img.shields.io/travis/julien-f/nodejs-hashy/master.svg)](http://travis-ci.org/julien-f/nodejs-hashy)
|
4 | [![Dependency Status](https://david-dm.org/julien-f/nodejs-hashy/status.svg?theme=shields.io)](https://david-dm.org/julien-f/nodejs-hashy)
|
5 | [![devDependency Status](https://david-dm.org/julien-f/nodejs-hashy/dev-status.svg?theme=shields.io)](https://david-dm.org/julien-f/nodejs-hashy#info=devDependencies)
|
6 |
|
7 | Hashy is small [node.js](http://nodejs.org/) library which aims to do
|
8 | passwords hashing *[the correct
|
9 | way](https://wiki.php.net/rfc/password_hash)*.
|
10 |
|
11 | It has been heavily inspired by the new [PHP password hashing
|
12 | API](http://www.php.net/manual/en/book.password.php) but, following
|
13 | the node.js philosophy, hashing is done asynchronously.
|
14 |
|
15 | Furthermore, to make the interfaces as easy to use as possible, async
|
16 | functions can either be used with callbacks or they return
|
17 | [promises](https://en.wikipedia.org/wiki/Promise_%28programming%29)
|
18 | which will make them super easy to work with [generators](https://github.com/petkaantonov/bluebird/blob/master/API.md#generators)!
|
19 |
|
20 | Supported algorithms:
|
21 |
|
22 | - [Argon2](https://en.wikipedia.org/wiki/Argon2)
|
23 | - [bcrypt](https://en.wikipedia.org/wiki/Bcrypt)
|
24 |
|
25 | ## Why a new library?
|
26 |
|
27 | The other ones I found were too complicated and/or were missing
|
28 | important features.
|
29 |
|
30 | The main missing feature is the `needRehash()` function: cryptography
|
31 | is a fast-moving science and algorithms can quickly become obsolete or
|
32 | their parameters needs to be adjusted to compensate the performance
|
33 | increase of recent computers (e.g. [bcrypt cost
|
34 | factor](http://phpmaster.com/why-you-should-use-bcrypt-to-hash-stored-passwords/)).
|
35 |
|
36 | This is exactly what this function is for: checking whether a hash
|
37 | uses the correct algorithm (and options) to see if we need to compute
|
38 | a new hash for this password.
|
39 |
|
40 | ## Install
|
41 |
|
42 | Installation of the npm package:
|
43 |
|
44 | ```
|
45 | > npm install --save hashy
|
46 | ```
|
47 |
|
48 | Hashy requires promises support, for Node versions prior to 0.12 [see
|
49 | this page](https://github.com/julien-f/js-promise-toolbox#usage) to
|
50 | enable them.
|
51 |
|
52 | ## How to use it?
|
53 |
|
54 | First, you may take a look at examples: using [callbacks](https://github.com/julien-f/nodejs-hashy/blob/master/examples/callbacks.js), [promises](https://github.com/julien-f/nodejs-hashy/blob/master/examples/promises.js) or [generators](https://github.com/julien-f/nodejs-hashy/blob/master/examples/generators.js) (requires Node >= 0.11).
|
55 |
|
56 | ### Creating a hash
|
57 |
|
58 | ```js
|
59 | hashy.hash(password, function (error, hash) {
|
60 | if (error) {
|
61 | return console.log(error)
|
62 | }
|
63 |
|
64 | console.log('generated hash: ', hash)
|
65 | })
|
66 | ```
|
67 |
|
68 | `hash()` handles additionaly two parameters which may be passed before the callback:
|
69 |
|
70 | 1. `algo`: which algorithm to use, it defaults to `'bcrypt'`;
|
71 | 2. `options`: additional options for the current algorithm, for bcrypt
|
72 | it defaults to `{cost: 10}.`.
|
73 |
|
74 |
|
75 | ### Checking a password against a hash
|
76 |
|
77 | ```js
|
78 | hashy.verify(password, hash, function (error, success) {
|
79 | if (error) {
|
80 | return console.error(err)
|
81 | }
|
82 |
|
83 | if (success) {
|
84 | console.log('you are now authenticated!')
|
85 | } else {
|
86 | console.warn('invalid password!')
|
87 | }
|
88 | })
|
89 | ```
|
90 |
|
91 | ### Getting information about a hash
|
92 |
|
93 | ```js
|
94 | var info = hashy.getInfo(hash)
|
95 | ```
|
96 |
|
97 | ### Checking whether a hash is up to date
|
98 |
|
99 | As I said [earlier](#why-a-new-library), we must be able to check
|
100 | whether the hash is up to date, i.e. if it has been generated by the
|
101 | last algorithm available with the last set of options.
|
102 |
|
103 | ```js
|
104 | if (hashy.needsRehash(hash)) {
|
105 | // Rehash.
|
106 | }
|
107 | ```
|
108 |
|
109 | It handles the optional `algo` and `options` parameters like
|
110 | [`hash()`](#creating-a-hash).
|
111 |
|
112 | ### Changing default options.
|
113 |
|
114 | The default options for a given algorithm is available at `hashy.options[>algo<]`.
|
115 |
|
116 | ```js
|
117 | // Sets the default cost for bcrypt to 12.
|
118 | hashy.options.bcrypt.cost = 12
|
119 | ```
|
120 |
|
121 | ## Using promises
|
122 |
|
123 | Same interface as above but without the callbacks!
|
124 |
|
125 | ```javascript
|
126 | // Hashing.
|
127 | hashy.hash(password).then(function (hash) {
|
128 | console.log('generated hash:' hash)
|
129 | })
|
130 |
|
131 | // Checking.
|
132 | hashy.verify(password, hash).then(function (success) {
|
133 | if (success) {
|
134 | console.log('you are now authenticated!')
|
135 | } else {
|
136 | console.warn('invalid password!')
|
137 | }
|
138 | })
|
139 |
|
140 | ```
|
141 |
|
142 | As you can see, you don't even have to handle errors if you don't want
|
143 | to!
|
144 |
|
145 | ## Using generators
|
146 |
|
147 | **Note:** only available since node.js 0.12.
|
148 |
|
149 | Same interface as promises but much more similar to a synchronous
|
150 | code!
|
151 |
|
152 | ```javascript
|
153 | // Hashing.
|
154 | Bluebird.coroutine(function * () {
|
155 | var hash = yield hashy.hash(password)
|
156 | console.log('generated hash:', hash)
|
157 | })()
|
158 |
|
159 | // Checking.
|
160 | Bluebird.coroutine(function * () {
|
161 | if (yield hashy.verify(password, hash)) {
|
162 | console.log('you are now authenticated!')
|
163 | } else {
|
164 | console.warn('invalid password!')
|
165 | }
|
166 | })()
|
167 | ```
|
168 |
|
169 | ## Contributing
|
170 |
|
171 | Contributions are *very* welcome, either on the documentation or on
|
172 | the code.
|
173 |
|
174 | You may:
|
175 |
|
176 | - report any [issue](https://github.com/julien-f/nodejs-hashy/issues)
|
177 | you've encountered;
|
178 | - fork and create a pull request.
|
179 |
|
180 | ## License
|
181 |
|
182 | Hashy is released under the [MIT
|
183 | license](https://en.wikipedia.org/wiki/MIT_License).
|