hashy

Create, check and update password hashes.

npm install hashy
12 downloads in the last day
79 downloads in the last week
326 downloads in the last month

Hashy

Build Status Dependency Status devDependency Status

Hashy is small node.js library which aims to do passwords hashing the correct way.

It has been heavily inspired by the new PHP password hashing API but, following the node.js philosophy, hashing is done asynchronously.

Furthermore, to make the interfaces as easy to use as possible, async functions can either be used with callbacks or they return promises which will make them super easy to work with generators!

Why a new library?

The other ones I found were too complicated and/or were missing important features.

The main missing feature is the needRehash() function: cryptography is a fast-moving science and algorithms can quickly become obsolete or their parameters needs to be adjusted to compensate the performance increase of recent computers (e.g. bcrypt cost factor).

This is exactly what this function is for: checking whether a hash uses the correct algorithm (and options) to see if we need to compute a new hash for this password.

How to use it?

First, you may take a look at the available example.

Creating a hash

hashy.hash(password, function (error, hash) {
  if (error)
  {
    return console.log(error);
  }

  console.log('generated hash: ', hash);
});

hash() handles additionaly two parameters which may be passed before the callback:

  1. algo: which algorithm to use, it defaults to hashy.DEFAULT which currently equals to hash.BCRYPT;
  2. options: additional options for the current algorithm, for bcrypt it defaults to {cost: 10}..

Checking a password against a hash

hashy.verify(password, hash, function (error, success) {
  if (error)
  {
    return console.error(err);
  }

  if (success)
  {
    console.log('you are now authenticated!');
  }
  else
  {
    console.warn('invalid password!');
  }
});

Getting information about a hash

var info = hashy.getInfo(hash);

Checking whether a hash is up to date

As I said earlier, we must be able to check whether the hash is up to date, i.e. if it has been generated by the last algorithm available with the last set of options.

if (hashy.needsRehash(hash))
{
  // Rehash.
}

It handles the optional algo and options parameters like hash().

Changing default options.

The default options for a given algorithm is available at hashy.options[>algo<].

// Sets the default cost for bcrypt to 12.
hashy.options[hashy.BCRYPT].cost = 12.

Using promises

Same interface as above but without the callbacks!

// Hashing.
hashy.hash(password).then(function (hash) {
  console.log('generated hash:' hash);
});

// Checking.
hashy.verify(password, hash).then(function (success) {
  if (success)
  {
    console.log('you are now authenticated!');
  }
  else
  {
    console.warn('invalid password!');
  }
});

As you can see, you don't even have to handle errors if you don't want to!

Using generators

Note: only available since node.js 0.12.

Same interface as promises but much more similar to a synchronous code!

// Hashing.
var hash = yield hashy.hash(password);
console.log('generated hash:', hash);

// Checking.
if (yield hashy.verify(password, hash))
{
  console.log('you are now authenticated!');
}
else
{
  console.warn('invalid password!');
}

License

Hashy is released under the MIT license.

npm loves you