Easy PBKDF2 for node.js
Easy PBKDF2 makes it easier to create secure, individually salted, password hashes using PBKDF2.
This implementation is based on StackExchange's own Open Sourced PBKDF2 methods.
Installation:
via cmd line:
$ npm install easy-pbkdf2 --save
or in your package.json
:
"dependencies":
Usage:
var easyPbkdf2 = ;var salt = easyPbkdf2; // `salt` should be treated as opaque, as it captures iterationsvar password = "RandomDigits";easyPbkdf2; // ... // sometime later: { // make sure the user-entered password is equal to the previously // created hash when hashed with the same salt. easyPbkdf2;}
You can also use EasyPbkdf2 to generate the salt for you by omitting the salt
parameter:
easyPbkdf2;
To create a new instance of EasyPbkdf2
:
var easyPbkdf2 = ;
You can also use the following methods of instantiation:
// the EasyPbkdf2 constructorvar EasyPbkdf2 = easyPbkdf2; easyPbkdf2 = ;easyPbkdf2 = options;easyPbkdf2 = EasyPbkdf2;easyPbkdf2 = options;
of which all will return an EasyPbkdf2
instance with options
set.
Options
var options = // default DEFAULT_HASH_ITERATIONS is 512 "DEFAULT_HASH_ITERATIONS": 256 // default SALT_SIZE is 32 "SALT_SIZE": 16 // default KEY_LENGTH is 256 "KEY_LENGTH": 128; var easyPbkdf2 = options;console // 256console; // 16console; // 128 // options are applied to each instance individually.console; // 512
Methods
weakHash( value )
Cranks out a collision resistant hash, relatively quickly. Not suitable for passwords, or sensitive information. Synchronous only
Params:
- value: String or Object. Base64 encoded SHA-1 hash of
value
Returns:
- A string; Base64 encoded SHA-1 hash of
value
random( bytes, callback )
Universal random provider. Generates cryptographically strong pseudo-random data. Syncronous or Asyncronous
Params:
- bytes: Number. The number of bytes to return.
- callback: Function. The callback to call for async operation (optional)
Returns:
- A SlowBuffer; A buffer containing therandom bytes. (optional)
generateSalt( explicitIterations, callback )
Convenience wrapper around
.random
to grab a new salt value. Treat this value as opaque, as it captures iterations.Salt length varies based on SALT_SIZE and iterations. The default SALT_SIZE of 32 produces a value that is: (hashIterations.toString(16).length) + 1 + base64EncodedSalt.length) characters long (42 characters).
Synchronous or Asynchronous
Params:
- explicitIterations: Number. An integer (optional)
- callback: Function. (optional)
Returns:
- A String. Return iterations and salt together as one string ({hex-iterations}.{base64-salt}) (optional)
secureHash( value, salt, callback )
Alias for
hash
.
hash( value, salt, callback )
Backs Secure hashes. Uses PBKDF2 internally, as implemented by node's native crypto library. See http://en.wikipedia.org/wiki/PBKDF2 and http://code.google.com/p/crypto-js/ for more information. Asynchronous only
Params:
- value: String. The plaintext value/password you want to hash.
- salt: String. salt (should include iterations). Automatically created if omitted. (optional)
- callback: Function. fn( {Error} err, {String} A secure hash (base64 encoded), {String} the original or newly created salt ).
verify( salt, priorHash, value, callback )
Verifies that the supplied plaintext
value
hashes to the same base64 encoded string as thepriorHash
, when hashed with the same salt. This method uses a constant-time string equality check to ensure information is not leaked via timing-attack. Asynchronous only
Params:
- salt: String. salt (should include iterations).
- priorHash: String. A secure hash (base64 encoded).
- value: String. The plaintext value/password you want to verify.
- callback: Function. fn( {Error} err, {Boolean} True if the
value
matches thepriorHash
, false if not. ).
Issues
Please file them here: https://github.com/davidmurdoch/easy-pbkdf2/issues.
And remember: pull requests are very welcome. :-)