bcrypt-deterministic

Core from primary NodeJS implementation: https://github.com/kelektiv/node.bcrypt.js/, credit for bindigs/bcrypt_node.cc, as well as most of this README.md

What is this?

This is an implementation of the bcrypt algorithm, with the capability to provide a string salt (which will be turned to a 16 byte hash), and produce a deterministic/consistent/stable output hash. If none is provided, the default/initial bcrypt strategy of generating a random 16 byte hash is used.

Usage

$ npm install --save bcrypt-deterministic

Hash with stable output

const { hash } = require('bcrypt-deterministic');

const salt = 'I am a salt.';
const data = 'Hello there, I am data.';

// Assume top-level await or inside an async function

// hash1 and hash2 will be the same
const hash1 = await hash(data, { salt, rounds: 10 });
const hash2 = await hash(data, { salt, rounds: 10 });

Hash with dynamic output due to dynamic salt

const { hash } = require('bcrypt-deterministic');

const data = 'Hello there, I am data.';

// Assume top-level await or inside an async function

// hash1 and hash2 will be different, because a random salt is generated
// if not provided.
const hash1 = await hash(data, { rounds: 10 });
const hash2 = await hash(data, { rounds: 10 });

Compare with dynamic or fixed salt

const { hash, compare } = require('bcrypt-deterministic');

const password = 'BCryptIsCool';

// Assume top-level await or inside an async function

const hashedWithFixedSalt = await hash(data, { salt: 'salty', rounds: 10 });
const hashedWithDynamicSalt = await hash(data, { rounds: 10 });

await compare(password, hashedWithFixedSalt); // true
await compare(password, hashedWithDynamicSalt); // true

Version Compatibility

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 And Concerns

Per bcrypt implementation, only the first 72 bytes of a string are used. Any extra bytes are ignored when matching passwords. Note that this is not the first 72 characters. It is possible for a string to contain less than 72 characters, while taking up more than 72 bytes (e.g. a UTF-8 encoded string containing emojis).

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][jtr] 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][zooko].

Compatibility Note

This library supports $2a$ and $2b$ prefix bcrypt hashes. $2x$ and $2y$ hashes are specific to bcrypt implementation developed for John 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

$ npm install bcrypt-deterministic

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

Pre-built binaries for various NodeJS versions are made available on a best-effort basis.

Only the current stable and supported LTS releases are actively tested against. Please note that there may be an interval between the release of the module and the availabilty of the compiled modules.

Currently, we have pre-built binaries that support the following platforms:

1. Windows x32 and x64
2. Linux x64 (GlibC targets only). Pre-built binaries for MUSL targets such as Apline Linux are not available.
3. macOS

If you face an error like this:

node-pre-gyp ERR! Tried to download(404): https://github.com/kelektiv/node.bcrypt.js/releases/download/v1.0.2/bcrypt_lib-v1.0.2-node-v48-linux-x64.tar.gz

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][depsinstall].

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

A Note on Timing Attacks

Because it's come up multiple times in this project, and other bcrypt projects, it needs to be said. The bcrypt comparison function is not susceptible to timing attacks. From codahale/bcrypt-ruby#42:

One of the desired properties of a cryptographic hash function is preimage attack resistance, which means there is no shortcut for generating a message which, when hashed, produces a specific digest.

A great thread on this, in much more detail can be found @ codahale/bcrypt-ruby#43

If you're unfamiliar with timing attacks and want to learn more you can find a great writeup @ [A Lesson In Timing Attacks][timingatk]

However, timing attacks are real. And, the comparison function is not time safe. What that means is that it may exit the function early in the comparison process. This happens because of the above. We don't need to be careful that an attacker is going to learn anything, and our comparison function serves to provide a comparison of hashes, it is a utility to the overall purpose of the library. If you end up using it for something else we cannot guarantee the security of the comparator. Keep that in mind as you use the library.

Hash Info

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

Resultant hashes will be 60 characters long.

Credits

The code for this comes from a few sources:

• blowfish.cc - OpenBSD
• bcrypt.cc - OpenBSD
• bcrypt::gen_salt - [gen_salt inclusion to bcrypt][bcryptgs]
• bcrypt_node.cc - kelektiv