bcrypt.js
Optimized bcrypt in JavaScript with zero dependencies, with TypeScript support. 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 UTF-8 encoded characters use up to 4 bytes) and the length of generated
hashes is 60 characters. Note that maximum input length is not implicitly checked by the library for compatibility with
the C++ binding on Node.js, but should be checked with bcrypt.truncates(password) where necessary.
Usage
The package exports an ECMAScript module with an UMD fallback.
$> npm install bcryptjs
import bcrypt from "bcryptjs";
Usage with a CDN
- From GitHub via jsDelivr:
https://cdn.jsdelivr.net/gh/dcodeIO/bcrypt.js@TAG/index.js (ESM)
- From npm via jsDelivr:
https://cdn.jsdelivr.net/npm/bcryptjs@VERSION/index.js (ESM)
https://cdn.jsdelivr.net/npm/bcryptjs@VERSION/umd/index.js (UMD)
- From npm via unpkg:
https://unpkg.com/bcryptjs@VERSION/index.js (ESM)
https://unpkg.com/bcryptjs@VERSION/umd/index.js (UMD)
Replace TAG respectively VERSION with a specific version or omit it (not recommended in production) to use latest.
When using the ESM variant in a browser, the crypto import needs to be stubbed out, for example using an import map. Bundlers should omit it automatically.
Usage - Sync
To hash a password:
const salt = bcrypt.genSaltSync(10);
const 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:
const hash = bcrypt.hashSync("bacon", 10);
Usage - Async
To hash a password:
const salt = await bcrypt.genSalt(10);
const hash = await bcrypt.hash("B4c0/\/", salt);
// Store hash in your password DB
bcrypt.genSalt(10, (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
await bcrypt.compare("B4c0/\/", hash); // true
await bcrypt.compare("not_bacon", hash); // false
// Load hash from your password DB
bcrypt.compare("B4c0/\/", hash, (err, res) => {
// res === true
});
bcrypt.compare("not_bacon", hash, (err, res) => {
// res === false
});
Auto-gen a salt and hash:
await bcrypt.hash("B4c0/\/", 10);
// Store hash in your password DB
bcrypt.hash("B4c0/\/", 10, (err, hash) => {
// Store hash in your password DB
});
Note: Under the hood, asynchronous APIs split an operation into small chunks. After the completion of a chunk, the execution of the next chunk is placed on the back of the JS event queue, efficiently yielding for other computation to execute.
Usage - Command Line
Usage: bcrypt <input> [rounds|salt]
API
Callback types
-
Callback<T>: (err: Error | null, result?: T) => void
Called with an error on failure or a value of type T upon success.
-
ProgressCallback: (percentage: number) => void
Called with the percentage of rounds completed (0.0 - 1.0), maximally once per MAX_EXECUTION_TIME = 100 ms.
-
RandomFallback: (length: number) => number[]
Called to obtain random bytes when both Web Crypto API and Node.js
crypto are not available.
Functions
-
bcrypt.genSaltSync(rounds?: number): string
Synchronously generates a salt. Number of rounds defaults to 10 when omitted.
-
bcrypt.genSalt(rounds?: number): Promise<string>
Asynchronously generates a salt. Number of rounds defaults to 10 when omitted.
-
bcrypt.genSalt([rounds: number, ]callback: Callback<string>): void
Asynchronously generates a salt. Number of rounds defaults to 10 when omitted.
-
bcrypt.truncates(password: string): boolean
Tests if a password will be truncated when hashed, that is its length is greater than 72 bytes when converted to UTF-8.
-
bcrypt.hashSync(password: string, salt?: number | string): string
Synchronously generates a hash for the given password. Number of rounds defaults to 10 when omitted.
-
bcrypt.hash(password: string, salt: number | string): Promise<string>
Asynchronously generates a hash for the given password.
-
bcrypt.hash(password: string, salt: number | string, callback: Callback<string>, progressCallback?: ProgressCallback): void
Asynchronously generates a hash for the given password.
-
bcrypt.compareSync(password: string, hash: string): boolean
Synchronously tests a password against a hash.
-
bcrypt.compare(password: string, hash: string): Promise<boolean>
Asynchronously compares a password against a hash.
-
bcrypt.compare(password: string, hash: string, callback: Callback<boolean>, progressCallback?: ProgressCallback)
Asynchronously compares a password against a hash.
-
bcrypt.getRounds(hash: string): number
Gets the number of rounds used to encrypt the specified hash.
-
bcrypt.getSalt(hash: string): string
Gets the salt portion from a hash. Does not validate the hash.
-
bcrypt.setRandomFallback(random: RandomFallback): void
Sets the pseudo random number generator to use as a fallback if neither Web Crypto API nor Node.js crypto are available. Please note: It is highly important that the PRNG used is cryptographically secure and that it is seeded properly!
Building
Building the UMD fallback:
$> npm run build
Running the tests:
$> npm test
Credits
Based on work started by Shane Girish at bcrypt-nodejs, which is itself
based on javascript-bcrypt (New BSD-licensed).
