Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Modularize project #87

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Modularize project #87

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 58 additions & 71 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@ binding on node.js and also working in the browser.

<a href="https://travis-ci.org/dcodeIO/bcrypt.js"><img alt="build static" src="https://travis-ci.org/dcodeIO/bcrypt.js.svg?branch=master" /></a> <a href="https://npmjs.org/package/bcryptjs"><img src="https://img.shields.io/npm/v/bcryptjs.svg" alt=""></a> <a href="https://npmjs.org/package/bcryptjs"><img src="https://img.shields.io/npm/dm/bcryptjs.svg" alt=""></a> <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=dcode%40dcode.io&item_name=Open%20Source%20Software%20Donation&item_number=dcodeIO%2Fbcrypt.js"><img alt="donate ❤" src="https://img.shields.io/badge/donate-❤-ff2244.svg"></a>

Version 3.0.0
-----------------------
There are some breaking changes in version 3.0.0. In this version, bcrypt.js has removed supports for prebuilt dists and global entry `dcodeIO.bcrypt`. bcrypt.js can now be bundled with build tools like `webpack`, `rollup` or `browserify`.

Security considerations
-----------------------
Expand All @@ -18,48 +21,19 @@ 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
Installation
-----
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](http://nodejs.org/api/crypto.html)'s randomBytes interface is used to obtain
secure random numbers.

`npm install bcryptjs`

```js
var bcrypt = require('bcryptjs');
...
```bash
npm install bcryptjs
```

### Browser

In the browser, bcrypt.js relies on [Web Crypto API](http://www.w3.org/TR/WebCryptoAPI)'s getRandomValues
interface to obtain secure random numbers. If no cryptographically secure source of randomness is available, you may
specify one through [bcrypt.setRandomFallback](https://github.com/dcodeIO/bcrypt.js#setrandomfallbackrandom).

```js
var bcrypt = dcodeIO.bcrypt;
...
```bash
yarn add bcryptjs
```

or

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

Usage - Sync
Usage
------------
To hash a password:
### Sync
To hash a password:

```javascript
var bcrypt = require('bcryptjs');
Expand All @@ -68,7 +42,7 @@ var hash = bcrypt.hashSync("B4c0/\/", salt);
// Store hash in your password DB.
```

To check a password:
To check a password:

```javascript
// Load hash from your password DB.
Expand All @@ -82,9 +56,8 @@ Auto-gen a salt and hash:
var hash = bcrypt.hashSync('bacon', 8);
```

Usage - Async
-------------
To hash a password:
### Async
To hash a password:

```javascript
var bcrypt = require('bcryptjs');
Expand All @@ -95,7 +68,7 @@ bcrypt.genSalt(10, function(err, salt) {
});
```

To check a password:
To check a password:

```javascript
// Load hash from your password DB.
Expand All @@ -121,6 +94,20 @@ 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](https://developer.mozilla.org/en/docs/Web/JavaScript/EventLoop), thus efficiently sharing the computational resources with the other operations in the queue.

Secure Random Numbers
-----

### node.js

On node.js, the inbuilt [crypto module](http://nodejs.org/api/crypto.html)'s randomBytes interface is used to obtain
secure random numbers.

### Browser

In the browser, bcrypt.js relies on [Web Crypto API](http://www.w3.org/TR/WebCryptoAPI)'s getRandomValues
interface to obtain secure random numbers. If no cryptographically secure source of randomness is available, you may
specify one through [bcrypt.setRandomFallback](https://github.com/dcodeIO/bcrypt.js#setrandomfallbackrandom).

API
---
### setRandomFallback(random)
Expand All @@ -131,8 +118,8 @@ seeded properly!

| Parameter | Type | Description
|-----------------|-----------------|---------------
| random | *function(number):!Array.&lt;number&gt;* | Function taking the number of bytes to generate as its sole argument, returning the corresponding array of cryptographically secure random byte values.
| **@see** | | http://nodejs.org/api/crypto.html
| random | *function(number):!Array.&lt;number&gt;* | Function taking the number of bytes to generate as its sole argument, returning the corresponding array of cryptographically secure random byte values.
| **@see** | | http://nodejs.org/api/crypto.html
| **@see** | | http://www.w3.org/TR/WebCryptoAPI/

**Hint:** You might use [isaac.js](https://github.com/rubycon/isaac.js) as a CSPRNG but you still have to make sure to
Expand All @@ -144,20 +131,20 @@ Synchronously generates a salt.

| Parameter | Type | Description
|-----------------|-----------------|---------------
| rounds | *number* | Number of rounds to use, defaults to 10 if omitted
| seed_length | *number* | Not supported.
| **@returns** | *string* | Resulting salt
| **@throws** | *Error* | If a random fallback is required but not set
| rounds | *number* | Number of rounds to use, defaults to 10 if omitted
| seed_length | *number* | Not supported.
| **@returns** | *string* | Resulting salt
| **@throws** | *Error* | If a random fallback is required but not set

### genSalt(rounds=, seed_length=, callback)

Asynchronously generates a salt.

| Parameter | Type | Description
|-----------------|-----------------|---------------
| rounds | *number &#124; function(Error, string=)* | Number of rounds to use, defaults to 10 if omitted
| seed_length | *number &#124; function(Error, string=)* | Not supported.
| callback | *function(Error, string=)* | Callback receiving the error, if any, and the resulting salt
| rounds | *number &#124; function(Error, string=)* | Number of rounds to use, defaults to 10 if omitted
| seed_length | *number &#124; function(Error, string=)* | Not supported.
| callback | *function(Error, string=)* | Callback receiving the error, if any, and the resulting salt
| **@returns** | *Promise* | If `callback` has been omitted
| **@throws** | *Error* | If `callback` is present but not a function

Expand All @@ -167,19 +154,19 @@ Synchronously generates a hash for the given string.

| Parameter | Type | Description
|-----------------|-----------------|---------------
| s | *string* | String to hash
| salt | *number &#124; string* | Salt length to generate or salt to use, default to 10
| **@returns** | *string* | Resulting hash
| s | *string* | String to hash
| salt | *number &#124; string* | Salt length to generate or salt to use, default to 10
| **@returns** | *string* | Resulting hash

### hash(s, salt, callback, progressCallback=)

Asynchronously generates a hash for the given string.

| Parameter | Type | Description
|-----------------|-----------------|---------------
| s | *string* | String to hash
| salt | *number &#124; string* | Salt length to generate or salt to use
| callback | *function(Error, string=)* | Callback receiving the error, if any, and the resulting hash
| s | *string* | String to hash
| salt | *number &#124; string* | Salt length to generate or salt to use
| callback | *function(Error, string=)* | Callback receiving the error, if any, and the resulting hash
| progressCallback | *function(number)* | Callback successively called with the percentage of rounds completed (0.0 - 1.0), maximally once per `MAX_EXECUTION_TIME = 100` ms.
| **@returns** | *Promise* | If `callback` has been omitted
| **@throws** | *Error* | If `callback` is present but not a function
Expand All @@ -190,22 +177,22 @@ Synchronously tests a string against a hash.

| Parameter | 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
| 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

### compare(s, hash, callback, progressCallback=)

Asynchronously compares the given data against the given hash.

| Parameter | 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
| 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
| progressCallback | *function(number)* | Callback successively called with the percentage of rounds completed (0.0 - 1.0), maximally once per `MAX_EXECUTION_TIME = 100` ms.
| **@returns** | *Promise* | If `callback` has been omitted
| **@returns** | *Promise* | If `callback` has been omitted
| **@throws** | *Error* | If `callback` is present but not a function

### getRounds(hash)
Expand All @@ -214,19 +201,19 @@ Gets the number of rounds used to encrypt the specified hash.

| Parameter | 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
| 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

### getSalt(hash)

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

| Parameter | Type | Description
|-----------------|-----------------|---------------
| hash | *string* | Hash to extract the salt from
| **@returns** | *string* | Extracted salt part
| **@throws** | *Error* | If `hash` is not a string or otherwise invalid
| hash | *string* | Hash to extract the salt from
| **@returns** | *string* | Extracted salt part
| **@throws** | *Error* | If `hash` is not a string or otherwise invalid


Command line
Expand Down
22 changes: 0 additions & 22 deletions bower.json
View file
Open in desktop

This file was deleted.

15 changes: 0 additions & 15 deletions dist/README.md
View file
Open in desktop

This file was deleted.

Loading