node-argon2

Bindings to the reference Argon2 implementation.

Before installing

You MUST have a node-gyp global install before proceeding with install. node-argon2 works only and is tested against >=4.0.0 .

Usage

It's possible to hash a password using both Argon2i (default) and Argon2d, sync and async, and to verify if a password matches a hash, and also generate random cryptographically-safe salts. Salts must be exactly 16-byte long buffers but strings will automatically be converted (this is deprecated and should NOT be relied upon).

To hash a password:

var argon2 = require('argon2');

argon2.hash('password', 'somesalt', function (err, hash) {
  if (err) // hashing failure
    throw err;

  doSomethingWith(hash);
});

// OR

try {
  var hash = argon2.hashSync('password', 'somesaltwith16ch');
} catch (err) {
  console.log(err);
}

Resultant hashes will be 90 characters long. You can choose between Argon2i and Argon2d by passing an object as the third argument with the argon2d key set to whether or not you want Argon2d:

var argon2 = require('argon2');

argon2.hash('password', 'somesalt', {
  argon2d: true
}, function (err, hash) {
  // ...
});

// OR

try {
  var hash = argon2.hashSync('password', 'somesaltwith16ch', {
    argon2d: true
  });
} catch (err) {
  // ...
}

The argon2d option is flexible and accepts any truthy or falsy values.

You can provide your own salt as the second parameter. It is recommended to use the salt generating methods instead of a hardcoded, constant salt:

var argon2 = require('argon2');

argon2.generateSalt(function (err, salt) {
  doSomethingWith(salt);
});

// OR

var salt = argon2.generateSaltSync();

You can also modify time, memory and parallelism constraints passing the object as the third parameter, with keys timeCost, memoryCost and parallelism, respectively defaulted to 3, 12 (meaning 2^12 KB) and 1 (threads):

var argon2 = require('argon2');

argon2.generateSalt(function (err, salt) {
  argon2.hash('password', salt, {
    timeCost: 4, memoryCost: 13, parallelism: 2
  }, function (err, hash) {
    // ...
  });
});

// OR

var hash = argon2.hashSync('password', argon2.generateSaltSync(), {
  timeCost: 4, memoryCost: 13, parallelism: 2
});

The default parameters for Argon2 can be accessed with defaults:

var argon2 = require('argon2');

console.log(argon2.defaults);
// => { timeCost: 3, memoryCost: 12, parallelism: 1, argon2d: false }

To verify a password:

var argon2 = require('argon2');

argon2.verify('<big long hash>', 'password', function (err) {
  if (err) // password did not match
    throw err;

  authenticate();
});

// OR

if (argon2.verifySync('<big long hash>', 'password')) {
  authenticate();
} else {
  fail();
}

First parameter must have been generated by an Argon2 encoded hashing method, not raw.

License

Work licensed under the MIT License. Please check [P-H-C/phc-winner-argon2] (https://github.com/P-H-C/phc-winner-argon2) for license over Argon2 and the reference implementation.