Shoulder.dev Logo Shoulder.dev

The Big Picture - gothinkster/node-express-realworld-example-app - Bcryptjs

Description

bcryptjs is a popular library used for password hashing and encryption in Node.js applications. It is an optimized version of the bcrypt algorithm with zero dependencies, making it suitable for both server-side and client-side development. The library is compatible with the C++ bcrypt binding on Node.js and the Web Crypto API in the browser. The latest version is 2.4.3, published 7 years ago.

Why Use bcryptjs?

Besides protecting against rainbow table attacks by incorporating a salt, bcrypt is an adaptive function. Over time, the iteration count can be increased to make it slower, ensuring resistance to brute-force search attacks even with increasing computation power. bcrypt.js is slower than the C++ bcrypt binding (about 30%), effectively reducing the number of iterations that can be processed in an equal time span. The maximum input length is 72 bytes, and the length of generated hashes is 60 characters.

Usage

Node.js

Install bcryptjs using npm:

npm install bcryptjs

Require and use bcryptjs:

const bcrypt = require('bcryptjs');

Browser

In the browser, bcrypt.js relies on the 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.

const bcrypt = dcodeIO.bcrypt;

or

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

Usage - Sync

To hash a password:

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

To check a password:

const hash = bcrypt.hashSync('password', 8);
bcrypt.compareSync("password", hash); // true
bcrypt.compareSync("not_password", hash); // false

Usage - Async

To hash a password:

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

To check a password:

const hash = bcrypt.hash('password', 8, function(err, hash) {});
bcrypt.compare("password", hash, function(err, res) { res === true });
bcrypt.compare("not_password", hash, function(err, res) { res === false });

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. It is highly important that the PRNG used is cryptographically secure and that it is seeded 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.

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

References