forked from joepie91/scrypt-for-humans
You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
140 lines
5.3 KiB
Markdown
140 lines
5.3 KiB
Markdown
# scrypt-for-humans
|
|
|
|
A human-friendly API wrapper for the Node.js Scrypt bindings, because the default bindings kind of suck.
|
|
|
|
This module will change and do the following things for you:
|
|
|
|
* Input values (passwords, usually) are expected in utf-8.
|
|
* Output/hash values are base64-encoded, and can be stored directly in your data store of choice.
|
|
* Scrypt parameters are set to `scrypt.params(0.1)`, this can be overridden on a per-hash basis (see API documentation below).
|
|
* Scrypt errors, which are not proper Error types in the original library, are caught and rethrown as one of three correctly-inheriting Error types (see API documentation below). This means you can handle them like any other kind of Error.
|
|
|
|
The API supports both Promises and nodebacks.
|
|
|
|
## License
|
|
|
|
[WTFPL](http://www.wtfpl.net/txt/copying/) or [CC0](https://creativecommons.org/publicdomain/zero/1.0/), whichever you prefer.
|
|
|
|
## Donate
|
|
|
|
My income consists entirely of donations for my projects. If this module is useful to you, consider [making a donation](http://cryto.net/~joepie91/donate.html)!
|
|
|
|
You can donate using Bitcoin, PayPal, Gratipay, Flattr, cash-in-mail, SEPA transfers, and pretty much anything else.
|
|
|
|
## Contributing
|
|
|
|
Pull requests welcome. Please make sure your modifications are in line with the overall code style, and ensure that you're editing the `.coffee` files, not the `.js` files.
|
|
|
|
As this module could potentially deal with authentication, tests are needed; a pull request for those would be especially welcome.
|
|
|
|
Build tool of choice is `gulp`; simply run `gulp` while developing, and it will watch for changes.
|
|
|
|
Be aware that by making a pull request, you agree to release your modifications under the licenses stated above.
|
|
|
|
## Usage
|
|
|
|
```javascript
|
|
scrypt = require("scrypt-for-humans");
|
|
Promise = require("bluebird");
|
|
|
|
/* Using Promises */
|
|
|
|
var theHash;
|
|
|
|
Promise.try(function(){
|
|
return scrypt.hash("secretpassword");
|
|
}).then(function(hash){
|
|
console.log("The hash is " + hash);
|
|
theHash = hash;
|
|
|
|
/* Now let's see if it verifies - number 1 is correct. */
|
|
return scrypt.verifyHash("secretpassword", theHash);
|
|
}).then(function(){
|
|
console.log("Number 1 was correct!");
|
|
}).catch(scrypt.PasswordError, function(err){
|
|
console.log("Number 1 was wrong!");
|
|
}).then(function(){
|
|
/* And let's see if it fails correctly - number 2 is wrong. */
|
|
return scrypt.verifyHash("wrongpassword", theHash);
|
|
}).then(function(){
|
|
console.log("Number 2 was correct!");
|
|
}).catch(scrypt.PasswordError, function(err){
|
|
console.log("Number 2 was wrong!");
|
|
});
|
|
|
|
/* Using nodebacks */
|
|
|
|
scrypt.hash("secretpassword", {}, function(err, hash){
|
|
console.log("The hash is " + hash);
|
|
|
|
/* Now let's see if it verifies - number 1 is correct. */
|
|
scrypt.verifyHash("secretpassword", hash, function(err, result){
|
|
if(err) {
|
|
console.log("Number 1 was wrong!", err);
|
|
} else {
|
|
console.log("Number 1 was correct!");
|
|
}
|
|
|
|
/* And let's see if it fails correctly - number 2 is wrong. */
|
|
scrypt.verifyHash("wrongpassword", hash, function(err, result){
|
|
if(err) {
|
|
console.log("Number 2 was wrong!", err);
|
|
} else {
|
|
console.log("Number 2 was correct!");
|
|
}
|
|
});
|
|
});
|
|
});
|
|
```
|
|
|
|
## API
|
|
|
|
### scrypt.hash(input, [options, [callback]])
|
|
|
|
Creates a hash.
|
|
|
|
* __input__: The input to hash, usually a password.
|
|
* __options__: *Optional.* Custom options.
|
|
* __options.params__: Sets the Scrypt parameters to use. Defaults to `scrypt.params(0.1)`. If you want to change these, you'll probably need scrypt.scryptLib (documented below).
|
|
* __callback__: *Optional.* A nodeback to call upon completion. If omitted, the function will return a Promise.
|
|
|
|
If this is successful, the hash is returned as either the resolved Promise value or the second callback parameter, depending on the API you use.
|
|
|
|
If an error occurs, either the Promise will reject with it, or it will be passed as the first callback parameter, depending on the API you use. All errors correctly inherit from `Error`, and are documented below.
|
|
|
|
### scrypt.verifyHash(input, hash, [callback])
|
|
|
|
Creates a hash.
|
|
|
|
* __input__: The input to hash, usually a password.
|
|
* __hash__: The hash to verify against, in base64 encoding (the default output format of `scrypt.hash`).
|
|
* __callback__: *Optional.* A nodeback to call upon completion. If omitted, the function will return a Promise.
|
|
|
|
If the input is correct and matches the hash, the Promise will resolve or the callback will be called with `true` as the value.
|
|
|
|
__If the input does *not* match the hash, this is considered a PasswordError, *not* a `false` value!__
|
|
|
|
If an error occurs, either the Promise will reject with it, or it will be passed as the first callback parameter, depending on the API you use. All errors correctly inherit from `Error`, and are documented below.
|
|
|
|
### scrypt.PasswordError
|
|
|
|
This error is thrown if the input did not match the specified hash. The original error message is retained.
|
|
|
|
### scrypt.InputError
|
|
|
|
This error is thrown if there is a different problem with the input (either the to-be-hashed value, or the hash), such as a malformed hash. The original error message is retained.
|
|
|
|
### scrypt.OperationalError
|
|
|
|
This error is thrown when an internal error of some other kind occurs in the `scrypt` library. The original error message is retained.
|
|
|
|
### scrypt.scryptLib
|
|
|
|
Provides access to the underlying `scrypt` library that is used. Useful if you want to eg. specify custom Scrypt parameters.
|
|
|
|
## Changelog
|
|
|
|
### v1.0.0
|
|
|
|
Initial release.
|