1 | # Hashy
|
2 |
|
3 | [![Node compatibility](https://badgen.net/npm/node/hashy)](https://npmjs.org/package/hashy) [![License](https://badgen.net/npm/license/hashy)](https://npmjs.org/package/hashy) [![PackagePhobia](https://badgen.net/packagephobia/install/hashy)](https://packagephobia.now.sh/result?p=hashy)
|
4 |
|
5 | [![Package Version](https://badgen.net/npm/v/hashy)](https://npmjs.org/package/hashy) [![Build Status](https://travis-ci.org/JsCommunity/hashy.png?branch=master)](https://travis-ci.org/JsCommunity/hashy) [![Latest Commit](https://badgen.net/github/last-commit/JsCommunity/hashy)](https://github.com/JsCommunity/hashy/commits/master)
|
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 | ### Checking a password against a hash
|
77 |
|
78 | ```js
|
79 | hashy.verify(password, hash, function(error, success) {
|
80 | if (error) {
|
81 | return console.error(err);
|
82 | }
|
83 |
|
84 | if (success) {
|
85 | console.log("you are now authenticated!");
|
86 | } else {
|
87 | console.warn("invalid password!");
|
88 | }
|
89 | });
|
90 | ```
|
91 |
|
92 | ### Getting information about a hash
|
93 |
|
94 | ```js
|
95 | const info = hashy.getInfo(hash);
|
96 | ```
|
97 |
|
98 | ### Checking whether a hash is up to date
|
99 |
|
100 | As I said [earlier](#why-a-new-library), we must be able to check
|
101 | whether the hash is up to date, i.e. if it has been generated by the
|
102 | last algorithm available with the last set of options.
|
103 |
|
104 | ```js
|
105 | if (hashy.needsRehash(hash)) {
|
106 | // Rehash.
|
107 | }
|
108 | ```
|
109 |
|
110 | It handles the optional `algo` and `options` parameters like
|
111 | [`hash()`](#creating-a-hash).
|
112 |
|
113 | ### Changing default options.
|
114 |
|
115 | The default options for a given algorithm is available at `hashy.options[>algo<]`.
|
116 |
|
117 | ```js
|
118 | // Sets the default cost for bcrypt to 12.
|
119 | hashy.options.bcrypt.cost = 12;
|
120 | ```
|
121 |
|
122 | ## Using promises
|
123 |
|
124 | Same interface as above but without the callbacks!
|
125 |
|
126 | ```javascript
|
127 | // Hashing.
|
128 | hashy.hash(password).then(function (hash) {
|
129 | console.log('generated hash:' hash)
|
130 | })
|
131 |
|
132 | // Checking.
|
133 | hashy.verify(password, hash).then(function (success) {
|
134 | if (success) {
|
135 | console.log('you are now authenticated!')
|
136 | } else {
|
137 | console.warn('invalid password!')
|
138 | }
|
139 | })
|
140 |
|
141 | ```
|
142 |
|
143 | As you can see, you don't even have to handle errors if you don't want
|
144 | to!
|
145 |
|
146 | ## Using async functions
|
147 |
|
148 | **Note:** only available since Node.js 7.6.
|
149 |
|
150 | Same interface as promises but much more similar to a synchronous
|
151 | code!
|
152 |
|
153 | ```javascript
|
154 | // Hashing.
|
155 | (async function() {
|
156 | const hash = await hashy.hash(password);
|
157 | console.log("generated hash:", hash);
|
158 | })()(
|
159 | // Checking.
|
160 | async function() {
|
161 | if (await hashy.verify(password, hash)) {
|
162 | console.log("you are now authenticated!");
|
163 | } else {
|
164 | console.warn("invalid password!");
|
165 | }
|
166 | }
|
167 | )();
|
168 | ```
|
169 |
|
170 | ## Contributing
|
171 |
|
172 | Contributions are _very_ welcome, either on the documentation or on
|
173 | the code.
|
174 |
|
175 | You may:
|
176 |
|
177 | - report any [issue](https://github.com/JsCommunity/hashy/issues)
|
178 | you've encountered;
|
179 | - fork and create a pull request.
|
180 |
|
181 | ## License
|
182 |
|
183 | Hashy is released under the [MIT
|
184 | license](https://en.wikipedia.org/wiki/MIT_License).
|