bcryptjs
Version:
Optimized bcrypt in plain JavaScript with zero dependencies. Compatible to 'bcrypt'.
230 lines (184 loc) • 7.19 kB
Markdown
===========
Optimized bcrypt in plain JavaScript with zero dependencies. Compatible to the C++ [bcrypt](https://npmjs.org/package/bcrypt)
binding and also working in the browser.
Features 
--------
* CommonJS/node.js compatible (via [crypto](http://nodejs.org/api/crypto.html)), also available via [npm](https://npmjs.org/package/bcryptjs)
* Shim/browser compatible (via [WebCryptoAPI](http://www.w3.org/TR/WebCryptoAPI))
* RequireJS/AMD compatible
* Zero production dependencies
* Small footprint
* Compiled with Closure Compiler using advanced optimizations, [externs included](https://github.com/dcodeIO/bcrypt.js/blob/master/externs/bcrypt.js)
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](http://en.wikipedia.org/wiki/Bcrypt))
While bcrypt.js is compatible to the C++ bcrypt binding, it is written in pure JavaScript and thus slower, effectively
reducing the number of iterations that can be processed in an equal time span.
Usage
-----
#### node.js
`npm install bcryptjs`
```javascript
var bcrypt = require('bcryptjs');
...
```
```javascript
require.config({
"paths": {
"bcrypt": "/path/to/bcrypt.js"
}
});
require(["bcrypt"], function(bcrypt) {
...
});
```
```html
<script src="//raw.github.com/dcodeIO/bcrypt.js/master/bcrypt.min.js"></script>
```
```javascript
var bcrypt = dcodeIO.bcrypt;
...
```
Usage - Sync
------------
To hash a password:
```javascript
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:
```javascript
// Load hash from your password DB.
bcrypt.compareSync("B4c0/\/", hash); // true
bcrypt.compareSync("not_bacon", hash); // false
```
Auto-gen a salt and hash:
```javascript
var hash = bcrypt.hashSync('bacon', 8);
```
Usage - Async
-------------
To hash a password:
```javascript
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:
```javascript
// 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
});
```
Auto-gen a salt and hash:
```javascript
bcrypt.hash('bacon', 8, function(err, hash) {
});
```
API
---
- [bcrypt](
- [bcrypt.genSaltSync(rounds\*, seed_length\*)](
- [bcrypt.genSalt(rounds\*, seed_length\*, callback\*)](
- [bcrypt.hashSync(s, salt\*)](
- [bcrypt.hash(s, salt, callback)](
- [bcrypt.compareSync(s, hash)](
- [bcrypt.compare(s, hash, callback)](
- [bcrypt.getRounds(hash)](
- [bcrypt.getSalt(hash)](
bcrypt namespace.
Synchronously generates a salt.
| Name | Type | Description |
| ---- | ---- | ----------- |
| rounds\* | number | Number of rounds to use, defaults to 10 if omitted |
| seed_length\* | number | Not supported. |
| |||
| **returns** | string | Resulting salt
Asynchronously generates a salt.
| Name | Type | Description |
| ---- | ---- | ----------- |
| rounds\* | (number &
| seed_length\* | (number &
| callback\* | function(Error, ?string) | Callback receiving the error, if any, and the resulting salt |
Synchronously generates a hash for the given string.
| Name | Type | Description |
| ---- | ---- | ----------- |
| s | string | String to hash |
| salt\* | (number &
| |||
| **returns** | ?string | Resulting hash, actually never null
Asynchronously generates a hash for the given string.
| Name | Type | Description |
| ---- | ---- | ----------- |
| s | string | String to hash |
| salt | number &
| callback | function(Error, ?string) | Callback receiving the error, if any, and the resulting hash |
Synchronously tests a string against a hash.
| Name | Type | Description |
| ---- | ---- | ----------- |
| s | string | String to compare |
| hash | string | Hash to test against |
| |||
| **returns** | boolean | true if matching, otherwise false
| **throws** | Error | If an argument is illegal
Asynchronously compares the given data against the given hash.
| Name | Type | Description |
| ---- | ---- | ----------- |
| s | string | Data to compare |
| hash | string | Data to be compared to |
| callback | function(Error, boolean) | Callback receiving the error, if any, otherwise the result |
| |||
| **throws** | Error | If the callback argument is invalid
Gets the number of rounds used to encrypt the specified hash.
| Name | Type | Description |
| ---- | ---- | ----------- |
| hash | string | Hash to extract the used number of rounds from |
| |||
| **returns** | number | Number of rounds used
| **throws** | Error | If hash is not a string
Gets the salt portion from a hash.
| Name | Type | Description |
| ---- | ---- | ----------- |
| hash | string | Hash to extract the salt from |
| |||
| **returns** | string | Extracted salt part portion
| **throws** | Error | If `hash` is not a string or otherwise invalid
Command line
------------
`Usage: bcrypt <input> [salt]`
If the input has spaces inside, simply surround it with quotes.
Downloads
---------
* [Distributions](https://github.com/dcodeIO/bcrypt.js/tree/master/dist)
* [ZIP-Archive](https://github.com/dcodeIO/bcrypt.js/archive/master.zip)
* [Tarball](https://github.com/dcodeIO/bcrypt.js/tarball/master)
Credits
-------
Based on work started by Shane Girish at [bcrypt-nodejs](https://github.com/shaneGirish/bcrypt-nodejs) (MIT-licensed),
which is itself based on [javascript-bcrypt](http://code.google.com/p/javascript-bcrypt/) (New BSD-licensed).
License
-------
Apache License, Version 2.0 if not stated otherwise