node-scrypt

Scrypt For Node

#WARNING!!! This module is deprecated. Instead, use https://nodejs.org/api/crypto.html#crypto_crypto_scrypt_password_salt_keylen_options_callback

Scrypt for Node/IO is a native node/io C++ wrapper for Colin Percival's scrypt cryptographic hash utility.

As should be the case with any security tool, this library should be scrutinized by anyone using it. If you find or suspect an issue with the code- please bring it to my attention and I'll spend some time trying to make sure that this tool is as secure as possible.

Node-Scrypt Version 6

Version 6 is a major new release. It is by and large compatible with version 5.

• Scrypt version 1.2.0 is being used (a very recently released version of Scrypt)
• Using Node's internal cryptographic libraries - for windows users, there is no need to use an external OpenSSL library anymore.
• Using Node's OS module to check for freemem, meaning no need to use any system calls and therefore no external dependencies

Version 6 should work much better on all platforms

Past Releases

Node-Scrypt Version 5

Version 5 is a major new release that is not backward compatible with any previous version. Some highlights:

• C++ addon code rewritten:
  • Using Nan 2.x
  • Code has been greatly simplified
• ES6 Promise aware.
• API has changed:
  • Every output is a buffer.
  • Separated functions into async and sync versions.
  • Api name swap: What was kdf in previous versions is now hash (and vice versa).
  • Async functions will return a Promise if no callback function is present and Promises are available (else it will throw a SyntaxError).
• Using correct JavaScript Error object for all errors.

Migrating To Version 5

Version 5 is not backward compatible, but it should still be easy to migrate. Please read the api section to see what's changed. One big change that is worth noting is a name change: What used to be called hash has now been changed to kdf and conversely, what was kdf is now called hash.

Table Of Contents

• Scrypt
• Installation Instructions
• API - The module consists of four functions:
  • params - a translation function that produces scrypt parameters
  • kdf - a key derivation function designed for password hashing
  • verifyKdf - checks if a key matches a kdf
  • hash - the raw underlying scrypt hash function
• Example Usage
• FAQ
• Roadmap and Changelog
• Credits

Scrypt

Scrypt is an advanced crypto library used mainly for key derivation: More information can be found here:

• Tarsnap blurb about scrypt - Colin Percival (the author of scrypt) explains a bit about it.
• Academic paper explaining scrypt.
• Wikipedia Article on scrypt.

Installation Instructions

Pre-Requisistes

Windows

• Node-Gyp for Windows:
  • Installation instructions: node-gyp for windows
  • Look here for additional information/helpful hints.

Linux/MacOS

Node-gyp is needed to build this module. It should be installed globally, that is, with the -g switch:

npm install -g node-gyp

Install From NPM

npm install scrypt

Install From Source

git clone https://github.com/barrysteyn/node-scrypt.git
cd node-scrypt
npm install
node-gyp configure build

Testing

To test, go to the folder where scrypt was installed, and type:

npm test

API

params

Translates human understandable parameters to scrypt's internal parameters.

scrypt.paramsSync

scrypt.params(maxtime, [maxmem, [max_memfrac]], [function(err, obj) {}])

• maxtime - [REQUIRED] - a decimal (double) representing the maximum amount of time in seconds scrypt will spend when computing the derived key.
• maxmem - [OPTIONAL] - an integer, specifying the maximum number of bytes of RAM used when computing the derived encryption key. If not present, will default to 0.
• maxmemfrac - [OPTIONAL only if maxmem is present] - a double value between 0.0 and 1.0, representing the fraction (normalized percentage value) of the available RAM used when computing the derived key. If not present, will default to 0.5.
• callback_function - [OPTIONAL] - not applicable to synchronous function. If present in async function, then it will be treated as a normal async callback. If not present, a Promise will be returned if ES6 promises are available. If not present and ES6 promises are not present, a SyntaxError will be thrown.

kdf

Note: In previous versions, this was called hash.

Produces a key derivation function that uses the scrypt hash function. This should be used for hashing and checking passwords as it incorporates salt as well as HMAC into its format. It is based on a design by Colin Percival, the author of scrypt. The format can be seen here.

scrypt.kdfSync

scrypt.kdf(key, paramsObject, [function(err, obj){}])

• key - [REQUIRED] - a string (or buffer) representing the key (password) that is to be hashed.
• paramsObject - [REQUIRED] - parameters to control scrypt hashing (see params above).
• callback_function - [OPTIONAL] - not applicable to synchronous function. If present in async function, then it will be treated as a normal async callback. If not present, a Promise will be returned if ES6 promises are available. If not present and ES6 promises are not present, a SyntaxError will be thrown.

verifyKdf

Checks if a key (password) matches a kdf.

scrypt.verifyKdfSync

scrypt.verifyKdf(kdf, key, [function(err, result){}])

• kdf [REQUIRED] - see kdf above.
• key - [REQUIRED] - a string (or buffer) representing the key (password) that is to be checked.
• callback_function - [OPTIONAL] - not applicable to synchronous function. If present in async function, then it will be treated as a normal async callback. If not present, a Promise will be returned if ES6 promises are available. If not present and ES6 promises are not present, a SyntaxError will be thrown.

hash

Note: In previous versions, this was called kdf.

This is the raw scrypt hash function.

scrypt.hashSync

scrypt.hash(key, paramsObject, output_length, salt, function(err, obj){})

• key - [REQUIRED] - a string (or buffer) representing the key (password) that is to be checked.
• paramsObject - [REQUIRED] - parameters to control scrypt hashing (see params above).
• output_length - [REQUIRED] - the length of the resulting hashed output.
• salt - [REQUIRED] - a string (or buffer) used for salt. The string (or buffer) can be empty.
• callback_function - [OPTIONAL] - not applicable to synchronous function. If present in async function, then it will be treated as a normal async callback. If not present, a Promise will be returned if ES6 promises are available. If not present and ES6 promises are not present, a SyntaxError will be thrown.

Example Usage

params

var scrypt = require("scrypt");

//Synchronous
try {
  //Uses 0.1 for maxtime, and default values maxmem and maxmemfrac
  var scryptParameters = scrypt.paramsSync(0.1);
  console.log(scryptParameters);
} catch(err) {
  //handle error
}

//Asynchronous with callback
scrypt.params(0.1, function(err, scryptParameters) {
  console.log(scryptParameters);
});

//Asynchronous with promise
scrypt.params(0.1).then(function(result){
  console.log(result);
}, function(err) {
  console.log(err);
});

kdf

…

verifyKdf

var scrypt = require("scrypt");
var scryptParameters = scrypt.paramsSync(0.1);
var kdfResult = scrypt.kdfSync("password", scryptParameters);

//Synchronous
scrypt.verifyKdfSync(kdfResult, "password"); // returns true
scrypt.verifyKdfSync(kdfResult, "incorrect password"); // returns false

//Asynchronous
scrypt.verifyKdf(kdfResult, new Buffer("password"), function(err, result) {
  //result will be true
});

//Asynchronous with promise
scrypt.verifyKdf(kdfResult, "incorrect password").then(function(result) {
  //result will be false
}, function(err) {
});

hash

The scrypt paper lists four test vectors to test implementation. This example will show how to produce these test vectors from within this module.

Test Vector 1

var scrypt = require("scrypt");
var key = new Buffer("");

//Synchronous
var result = scrypt.hashSync(key,{"N":16,"r":1,"p":1},64,"");
console.log(result.toString("hex"));

//Asynchronous
scrypt.hash(key, {"N":16,"r":1,"p":1},64,"", function(err, res) {
  console.log(result.toString("hex"));
});

//Asynchronous with promise
scrypt.hash(key, {"N":16,"r":1,"p":1},64,"").then(function(result) {
  console.log(result.toString("hex"));
}, function(err){});

Test Vector 2

var scrypt = require("scrypt");
var salt = new Buffer("NaCl");

//Synchronous
var result = scrypt.hashSync("password", {"N":1024,"r":8,"p":16}, 64, salt);
console.log(result.toString("hex"));

scrypt.hash("password", {"N":1024,"r":8,"p":16},64,salt, function(err, result) {
  console.log(result.toString("hex"));
});

Test Vector 3

var scrypt = require("scrypt");
var key = new Buffer("pleaseletmein");
var salt = new Buffer("SodiumChloride");

//Synchronous
var result = scrypt.hashSync(key,{"N":16384,"r":8,"p":1},64,salt);
console.log(result.toString("hex"));

//Asynchronous
scrypt.hash(key, {"N":16384,"r":8,"p":1}, 64, salt, function(err, result) {
  console.log(result.toString("hex"));
});

Test Vector 4

Note: This test vector is very taxing in terms of resources.

var scrypt = require("scrypt");

//Synchronous
var result = scrypt.hashSync("pleaseletmein",{"N":1048576,"r":8,"p":1},64,"SodiumChloride");
console.log(result.toString("hex"));

//Asynchronous
scrypt.hash("pleaseletmein", {"N":1048576,"r":8,"p":1},64,"SodiumChloride", function(err, result) {
  console.log(result.toString("hex"));
});

FAQ

General

What Platforms Are Supported?

This module supports most posix platforms, as well as Microsoft Windows. It has been tested on the following platforms: Linux, MAC OS, SmartOS (so its ready for Joyent Cloud) and Microsoft Windows. It also works on FreeBSD, OpenBSD, SunOS etc.

Scrypt

Why Use Scrypt?

It is probably the most advanced key derivation function available. This is is quote taken from a comment in hacker news:

Passwords hashed with scrypt with sufficiently-high strength values (there are 3 tweakable input numbers) are fundamentally impervious to being cracked. I use the word "fundamental" in the literal sense, here; even if you had the resources of a large country, you would not be able to design any hardware (whether it be GPU hardware, custom-designed hardware, or otherwise) which could crack these hashes. Ever. (For sufficiently-small definitions of "ever". At the very least "within your lifetime"; probably far longer.)

What Are The Pros And Cons For Using Scrypt?

Pros

• The scrypt algorithm has been published by IETF as an [Internet Draft](http://en.wikipedia.org/wiki/Internet_Dra