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
First, make sure that the version of node you are using is a stable version. You'll know this because it'll have an even major release number. We do not currently support unstable versions and while the module may happen to work on some unstable versions you'll find that we quickly close issues if you're not using a stable version.
If you are on a stable version of node, we can't magically know what you are doing to expose an issue, it is best if you provide a snippet of code or log files if you're having an install issue. 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 that don't help us help you. Thanks.
Version Compatibility
Node Version | Bcrypt Version |
---|
0.4.x | <= 0.4.x |
0.6.x | >= 0.5.x |
0.8.x | >= 0.5.x |
0.10.x | >= 0.5.x |
0.11.x | >= 0.8.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
Per bcrypt implementation, only the first 72 characters of a string are used. Any extra characters are ignored when matching passwords.
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.
Compatibility Note
This library supports $2a$
and $2b$
prefix bcrypt hashes. $2x$
and $2y$
hashes are specific to bcrypt implementation developed for Jon the Ripper. In theory, they should be compatible with $2b$
prefix.
Compatibility with hashes generated by other languages is not 100% guaranteed due to difference in character encodings. However, it should not be an issue for most cases.
Dependencies
- NodeJS
node-gyp
- Please check the dependencies for this tool at: https://github.com/nodejs/node-gyp
- Windows users will need the options for c# and c++ installed with their visual studio instance.
- Python 2.x
OpenSSL
- This is only required to build the bcrypt
project if you are using versions <= 0.7.7. Otherwise, we're using the builtin node crypto bindings for seed data (which use the same OpenSSL code paths we were, but don't have the external dependency).
Install via NPM
Make sure you have the appropriate dependencies installed and configured for your platform. You can find installation instructions for the dependencies for some common platforms in this page.
npm install bcrypt
Note: OS X users using Xcode 4.3.1 or above may need to run the following command in their terminal prior to installing if errors occur regarding xcodebuild: sudo xcode-select -switch /Applications/Xcode.app/Contents/Developer
Usage
async (recommended)
var bcrypt = require('bcrypt');
const saltRounds = 10;
const myPlaintextPassword = 's0/\/\P4$$w0rD';
const someOtherPlaintextPassword = 'not_bacon';
To hash a password:
Technique 1 (generate a salt and hash on separate function calls):
bcrypt.genSalt(saltRounds, function(err, salt) {
bcrypt.hash(myPlaintextPassword, salt, function(err, hash) {
});
});
Technique 2 (auto-gen a salt and hash):
bcrypt.hash(myPlaintextPassword, saltRounds, function(err, hash) {
});
Note that both techniques achieve the same end-result.
To check a password:
bcrypt.compare(myPlaintextPassword, hash, function(err, res) {
});
bcrypt.compare(someOtherPlaintextPassword, hash, function(err, res) {
});
The "compare" function counters timing attacks (using a so-called 'constant-time' algorithm).
In general, don't use the normal JavaScript string comparison functions to compare passwords,
cryptographic keys, or cryptographic hashes if they are relevant to security.
with promises
bcrypt uses whatever Promise implementation is available in global.Promise
. NodeJS >= 0.12 has a native Promise implementation built in. However, this should work in any Promises/A+ compliant implementation.
Async methods that accept a callback, return a Promise
when callback is not specified if Promise support is available.
bcrypt.hash(myPlaintextPassword, saltRounds).then(function(hash) {
});
bcrypt.compare(myPlaintextPassword, hash).then(function(res) {
});
bcrypt.compare(someOtherPlaintextPassword, hash).then(function(res) {
});
sync
var bcrypt = require('bcrypt');
const saltRounds = 10;
const myPlaintextPassword = 's0/\/\P4$$w0rD';
const someOtherPlaintextPassword = 'not_bacon';
To hash a password:
Technique 1 (generate a salt and hash on separate function calls):
var salt = bcrypt.genSaltSync(saltRounds);
var hash = bcrypt.hashSync(myPlaintextPassword, salt);
Technique 2 (auto-gen a salt and hash):
var hash = bcrypt.hashSync(myPlaintextPassword, saltRounds);
As with async, both techniques achieve the same end-result.
To check a password:
bcrypt.compareSync(myPlaintextPassword, hash);
bcrypt.compareSync(someOtherPlaintextPassword, hash);
The "compareSync" function counters timing attacks (using a so-called 'constant-time' algorithm).
In general, don't use the normal JavaScript string comparison functions to compare passwords,
cryptographic keys, or cryptographic hashes if they are relevant to security.
Why is async mode recommended over sync mode?
If you are using bcrypt on a simple script, using the sync mode is perfectly fine. However, if you are using bcrypt on a server, the async mode is recommended. This is because the hashing done by bcrypt is CPU intensive, so the sync version will block the event loop and prevent your application from servicing any other inbound requests or events.
API
BCrypt.
genSaltSync(rounds, minor)
rounds
- [OPTIONAL] - the cost of processing the data. (default - 10)minor
- [OPTIONAL] - minor version of bcrypt to use. (default - b)
genSalt(rounds, minor, cb)
rounds
- [OPTIONAL] - the cost of processing the data. (default - 10)minor
- [OPTIONAL] - minor version of bcrypt to use. (default - b)cb
- [OPTIONAL] - a callback to be fired once the salt has been generated. uses eio making it asynchronous. If cb
is not specified, a Promise
is returned if Promise support is available.
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 to hash the password. if specified as a number then a salt will be generated with the specified number of rounds and used (see example under Usage).
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 with the specified number of rounds and used (see example under Usage).cb
- [OPTIONAL] - a callback to be fired once the data has been encrypted. uses eio making it asynchronous. If cb
is not specified, a Promise
is returned if Promise support is available.
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
- [OPTIONAL] - a callback to be fired once the data has been compared. uses eio making it asynchronous. If cb
is not specified, a Promise
is returned if Promise support is available.
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.
A Note on Rounds
A note about the cost. When you are hashing your data the module will go through a series of rounds to give you a secure hash. The value you submit there is not just the number of rounds that the module will go through to hash your data. The module will use the value you enter and go through 2^rounds
iterations of processing.
From @garthk, on a 2GHz core you can roughly expect:
rounds=8 : ~40 hashes/sec
rounds=9 : ~20 hashes/sec
rounds=10: ~10 hashes/sec
rounds=11: ~5 hashes/sec
rounds=12: 2-3 hashes/sec
rounds=13: ~1 sec/hash
rounds=14: ~1.5 sec/hash
rounds=15: ~3 sec/hash
rounds=25: ~1 hour/hash
rounds=31: 2-3 days/hash
Hash Info
The characters that comprise the resultant hash are ./ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789$
.
Resultant hashes will be 60 characters long.
Testing
If you create a pull request, tests better pass :)
npm install
npm test
Credits
The code for this comes from a few sources:
Contributors
License
Unless stated elsewhere, file headers or otherwise, the license as stated in the LICENSE file.