bcrypt.js

Optimized bcrypt in JavaScript with zero dependencies. Compatible to the C++ bcrypt binding on node.js and also working in the browser.

Security considerations

Besides incorporating a salt to protect against rainbow table attacks, bcrypt is an adaptive function: over time, the iteration count can be increased to make it slower, so it remains resistant to brute-force search attacks even with increasing computation power. (see)

While bcrypt.js is compatible to the C++ bcrypt binding, it is written in pure JavaScript and thus slower (about 30%), effectively reducing the number of iterations that can be processed in an equal time span.

The maximum input length is 72 bytes (note that UTF8 encoded characters use up to 4 bytes) and the length of generated hashes is 60 characters.

Usage

The library is compatible with CommonJS and AMD loaders and is exposed globally as dcodeIO.bcrypt if neither is available.

node.js

On node.js, the inbuilt crypto module's randomBytes interface is used to obtain secure random numbers.

npm install bcryptjs

var bcrypt = require('bcryptjs');
...

Browser

In the browser, bcrypt.js relies on Web Crypto API's getRandomValues interface to obtain secure random numbers. If no cryptographically secure source of randomness is available, you may specify one through bcrypt.setRandomFallback.

var bcrypt = dcodeIO.bcrypt;
...

or

require.config({
    paths: { "bcrypt": "/path/to/bcrypt.js" }
});
require(["bcrypt"], function(bcrypt) {
    ...
});

Usage - Sync

To hash a password:

var bcrypt = require('bcryptjs');
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('bcryptjs');
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
});
 
// As of bcryptjs 2.4.0, compare returns a promise if callback is omitted:
bcrypt.compare("B4c0/\/", hash).then((res) => {
    // res === true
});

Auto-gen a salt and hash:

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

Note: Under the hood, asynchronisation splits a crypto operation into small chunks. After the completion of a chunk, the execution of the next chunk is placed on the back of JS event loop queue, thus efficiently sharing the computational resources with the other operations in the queue.

API

setRandomFallback(random)

Sets the pseudo random number generator to use as a fallback if neither node's crypto module nor the Web Crypto API is available. Please note: It is highly important that the PRNG used is cryptographically secure and that it is seeded properly!

Hint: You might use isaac.js as a CSPRNG but you still have to make sure to seed it properly.

genSaltSync(rounds=, seed_length=)

Synchronously generates a salt.

genSalt(rounds=, seed_length=, callback)

Asynchronously generates a salt.

hashSync(s, salt=)

Synchronously generates a hash for the given string.

hash(s, salt, callback, progressCallback=)

Asynchronously generates a hash for the given string.

compareSync(s, hash)

Synchronously tests a string against a hash.

compare(s, hash, callback, progressCallback=)

Asynchronously compares the given data against the given hash.

getRounds(hash)

Gets the number of rounds used to encrypt the specified hash.

getSalt(hash)

Gets the salt portion from a hash. Does not validate the hash.

Command line

Usage: bcrypt <input> [salt]

If the input has spaces inside, simply surround it with quotes.

Downloads

• Distributions
• ZIP-Archive
• Tarball

Credits

Based on work started by Shane Girish at bcrypt-nodejs (MIT-licensed), which is itself based on javascript-bcrypt (New BSD-licensed).

License

New-BSD / MIT (see)