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