node.bcrypt.js

Lib to help you hash passwords. bcrypt on wikipedia

Catalyst for this module: How To Safely Store A Password

If You Are Submitting Bugs/Issues

Because we can't magically know what you are doing to expose an issue, it is best if you provide a snippet of code. This snippet need not include your secret sauce, but it must replicate the issue you are describing. The issues that get closed without resolution tend to be the ones without code examples. Thanks.

Version Compatability

Node Ver	Bcrypt Version
<= 0.4.x	<= 0.4.x
>= 0.6.x	>= 0.5.x

Windows users should make sure to have at least node 0.8.5 installed and version >= 0.7.1 of this module.
node-gyp only works with stable/released versions of node. Since the bcrypt module uses node-gyp to build and install you'll need a stable version of node to use bcrypt. If you do not you'll likely see an error that starts with:

gyp ERR! stack Error: "pre" versions of node cannot be installed, use the --nodedir flag instead

Security Issues/Concerns

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.

To make it easier for people using this tool to analyze what has been surveyed, here is a list of BCrypt related security issues/concerns as they've come up.

An issue with passwords was found with a version of the Blowfish algorithm developed for John the Ripper. This is not present in the OpenBSD version and is thus not a problem for this module. HT zooko.

Dependencies

NodeJS
OpenSSL (Development Libraries (header files) for compilation)
For Windows you'll need http://slproweb.com/products/Win32OpenSSL.html installed to the default location of C:\OpenSSL-Win32
Please note that for this to build properly you'll need the Normal version of OpenSSL-Win, not the Light version. The reason for this is that we need to be able to compile the code using the header files that exist in the Normal version.
For 64 bit use the 64 bit version and install to C:\OpenSSL-Win64
node-gyp
Please check the dependencies for this tool at: https://github.com/TooTallNate/node-gyp/
Windows users will need the options for c# and c++ installed with their visual studio instance.
Python 2.x

From NPM

npm install bcrypt

From Source

Assuming you've already built node, you can compile the module with node-gyp:

git clone git://github.com/ncb000gt/node.bcrypt.js.git
cd node.bcrypt.js
node-gyp configure
node-gyp build

Note: if you do not have node-gyp installed, install it using: npm install -g node-gyp

Usage - Sync

To hash a password:

var bcrypt = require('bcrypt');
var salt = bcrypt.genSaltSync(10);
var hash = bcrypt.hashSync("B4c0/\/", salt);
// Store hash in your password DB.

To check a password:

// Load hash from your password DB.
bcrypt.compareSync("B4c0/\/", hash); // true
bcrypt.compareSync("not_bacon", hash); // false

Auto-gen a salt and hash:

var hash = bcrypt.hashSync('bacon', 8);

Usage - Async

To hash a password:

var bcrypt = require('bcrypt');
bcrypt.genSalt(10, function(err, salt) {
    bcrypt.hash("B4c0/\/", salt, function(err, hash) {
        // Store hash in your password DB.
    });
});

To check a password:

// Load hash from your password DB.
bcrypt.compare("B4c0/\/", hash, function(err, res) {
    // res == true
});
bcrypt.compare("not_bacon", hash, function(err, res) {
    // res = false
});

Auto-gen a salt and hash:

bcrypt.hash('bacon', 8, function(err, hash) {
});

API

BCrypt.

genSaltSync(rounds, seed_length)
- rounds - [OPTIONAL] - the number of rounds to process the data for. (default - 10)
- seed_length - [OPTIONAL] - RAND_bytes wants a length. to make that a bit flexible, you can specify a seed_length. (default - 20)
genSalt(rounds, seed_length, cb)
- rounds - [OPTIONAL] - the number of rounds to process the data for. (default - 10)
- seed_length - [OPTIONAL] - RAND_bytes wants a length. to make that a bit flexible, you can specify a seed_length. (default - 20)
- cb - [REQUIRED] - a callback to be fired once the salt has been generated. uses eio making it asynchronous.
  - err - First parameter to the callback detailing any errors.
  - salt - Second parameter to the callback providing the generated salt.
hashSync(data, salt)
- data - [REQUIRED] - the data to be encrypted.
- salt - [REQUIRED] - the salt to be used in encryption.
hash(data, salt, cb)
- data - [REQUIRED] - the data to be encrypted.
- salt - [REQUIRED] - the salt to be used to hash the password. if specified as a number then a salt will be generated and used (see examples).
- cb - [REQUIRED] - a callback to be fired once the data has been encrypted. uses eio making it asynchronous.
  - err - First parameter to the callback detailing any errors.
  - encrypted - Second parameter to the callback providing the encrypted form.
compareSync(data, encrypted)
- data - [REQUIRED] - data to compare.
- encrypted - [REQUIRED] - data to be compared to.
compare(data, encrypted, cb)
- data - [REQUIRED] - data to compare.
- encrypted - [REQUIRED] - data to be compared to.
- cb - [REQUIRED] - a callback to be fired once the data has been compared. uses eio making it asynchronous.
  - err - First parameter to the callback detailing any errors.
  - same - Second parameter to the callback providing whether the data and encrypted forms match [true | false].
getRounds(encrypted) - return the number of rounds used to encrypt a given hash
- encrypted - [REQUIRED] - hash from which the number of rounds used should be extracted.

Hash Info

The characters that comprise the resultant hash are ./ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789$.

Testing

If you create a pull request, tests better pass :)

npm install
npm test

Credits

The code for this comes from a few sources:

blowfish.cc - OpenBSD
bcrypt.cc - OpenBSD
bcrypt::gen_salt - gen_salt inclusion to bcrypt
bcrypt_node.cc - me

Contributors

Antonio Salazar Cardozo - Early MacOS X support (when we used libbsd)
Ben Glow - Fixes for thread safety with async calls
Van Nguyen - Found a timing attack in the comparator
NewITFarmer - Initial Cygwin support
David Trejo - packaging fixes
Alfred Westerveld - packaging fixes
Vincent Côté-Roy - Testing around concurrency issues
Lloyd Hilaiel - Documentation fixes
Roman Shtylman - Code refactoring, general rot reduction, compile options, better memory management with delete and new, and an upgrade to libuv over eio/ev.
Vadim Graboys - Code changes to support 0.5.5+
Ben Noordhuis - Fixed a thread safety issue in nodejs that was perfectly mappable to this module.
Nate Rajlich - Bindings and build process.
Sean McArthur - Windows Support
Fanie Oosthuysen - Windows Support

License

Unless stated elsewhere, file headers or otherwise, the license as stated in the LICENSE file.

jcruz2us / node.bcrypt.js