Extensible hashes (breaking change)

Extensible hashes allow you to keep up with Moore's law by changing the work units required to hash passwords over time, or swapping out the hashing algorithm when security flaws are discovered.

Now, each password hash contains a JSON-encoded record of:

* salt
* hash
* hashMethod (algorithm)
* iterations (or work units)
* keylength

This allows the verifier to verify the password, even if the format changes over time, and allows the system administrator to scan the user database for vulnerable users who need to change their passwords and upgrade to the latest password hashing standard.

Author: Eric Elliott

credential.js

@@ -36,16 +36,20 @@ var crypto = require('crypto'),
    * @param  {[type]}   salt
    * @param  {Function} callback err, buffer
    */
-  pbkdf2 = function pbkdf2(password, salt, callback) {
+  pbkdf2 = function pbkdf2(password, salt, iterations, keylength, callback) {
     crypto.pbkdf2(password, salt,
-      this.iterations, this.keylength, function (err, buff) {
+      iterations, keylength, function (err, hash) {
         if (err) {
           return callback(err);
         }
-        callback(null, buff.toString('base64'));
+        callback(null, new Buffer(hash).toString('base64'));
       });
   },
 
+  hashMethods = {
+    pbkdf2: pbkdf2
+  },
+
   /**
    * createSalt(callback)
    *
@@ -56,8 +60,8 @@ var crypto = require('crypto'),
    * @param  {Function} callback [description]
    * @return {[type]}            [description]
    */
-  createSalt = function createSalt(callback) {
-    crypto.randomBytes(this.keylength, function (err, buff) {
+  createSalt = function createSalt(keylength, callback) {
+    crypto.randomBytes(keylength, function (err, buff) {
       if (err) {
         return callback(err);
       }
@@ -77,22 +81,33 @@ var crypto = require('crypto'),
    */
   toHash = function toHash(password,
       callback) {
+    var hashMethod = this.hashMethod,
+      keylength = this.keylength,
+      iterations = this.iterations;
 
     // Create the salt
-    createSalt.call(this, function (err, salt) {
+    createSalt(keylength, function (err, salt) {
       if (err) {
         return callback(err);
       }
 
-      salt = salt.toString('base64');
-
       // Then create the hash
-      pbkdf2.call(this, password, salt, function (err, hash) {
+      hashMethods[hashMethod](password, salt,
+          iterations, keylength,
+          function (err, hash) {
+
         if (err) {
           return callback(err);
         }
 
-        callback(null, salt + '$' + hash.toString('base64'));
+        callback(null, JSON.stringify({
+          salt: salt,
+          hash: hash,
+          hashMethod: hashMethod,
+          iterations: iterations,
+          keylength: keylength
+        }));
+
       });
     }.bind(this));
   },
@@ -117,6 +132,14 @@ var crypto = require('crypto'),
     return result;
   },
 
+  parseHash = function parseHash(encodedHash) {
+    try {
+      return JSON.parse(encodedHash);
+    } catch (err) {
+      return err;
+    }
+  },
+
   /**
    * verify(hash, input, callback)
    *
@@ -129,15 +152,21 @@ var crypto = require('crypto'),
    * @param  {Function} callback callback(err, isValid)
    */
   verify = function verify(hash, input, callback) {
-    var oldHash = hash,
-      salt = hash.slice(0, 88);
+    var storedHash = parseHash(hash);
+
+    if (!hashMethods[storedHash.hashMethod]) {
+      return callback(new Error('Couldn\'t parse stored ' +
+        'hash.'));
+    }
+
+    hashMethods[storedHash.hashMethod](input, storedHash.salt, storedHash.iterations,
+        storedHash.keylength, function (err, newHash) {
 
-    pbkdf2.call(this, input, salt, function (err, newHash) {
       var result;
       if (err) {
         return callback(err);
       }
-      callback(null, constantEquals(salt + '$' + newHash, oldHash));
+      callback(null, constantEquals(newHash, storedHash.hash));
     });
   },
 
@@ -154,15 +183,18 @@ var crypto = require('crypto'),
    * @return {Object}         credential object
    */
   configure = function configure(options) {
-    var overrides = pick(options, ['keylength', 'iterations']);
-    mixIn(this, overrides);
+    mixIn(this, this.defaults, options);
     return this;
+  },
+
+  defaults = {
+    keylength: 66,
+    iterations: 80000,
+    hashMethod: 'pbkdf2'
   };
 
-module.exports = {
+module.exports = mixIn({}, defaults, {
   hash: toHash,
   verify: verify,
-  configure: configure,
-  keylength: 66,
-  iterations: 80000
-};
+  configure: configure
+});

package.json

@@ -1,6 +1,6 @@
 {
   "name": "credential",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Easy password hashing and verification in Node. Protects against brute force, rainbow tables, and timing attacks.",
   "main": "credential.js",
   "directories": {

test/credential-test.js

@@ -8,8 +8,8 @@ test('hash', function (t) {
     t.equal(typeof hash, 'string',
       'should produce a hash string.');
 
-    t.equal(hash.length, 177,
-      'should produce an 177 character hash string.');
+    t.ok(JSON.parse(hash).hash,
+      'should a json object representing the hash.');
 
     t.end();
   });
@@ -50,6 +50,9 @@ test('verify with right pw', function (t) {
 
   pw.hash(pass, function (err, storedHash) {
     pw.verify(storedHash, pass, function (err, isValid) {
+      t.error(err,
+        'should not cause error.');
+
       t.ok(isValid,
         'should return true for matching password.');
       t.end();
@@ -58,6 +61,21 @@ test('verify with right pw', function (t) {
 
 });
 
+test('verify with broken stored hash', function (t) {
+  var pass = 'foo',
+    storedHash = 'aoeuntkh;kbanotehudil,.prcgidax$aoesnitd,riouxbx;qjkwmoeuicgr';
+
+  pw.verify(storedHash, pass, function (err, isValid) {
+
+    t.ok(err,
+      'should cause error.');
+
+    t.end();
+  });
+
+});
+
+
 test('verify with wrong pw', function (t) {
   var pass = 'foo';
 
@@ -73,17 +91,19 @@ test('verify with wrong pw', function (t) {
 
 
 test('overrides', function (t) {
+  var iterations = 1;
+  var keylength = 12;
   pw.configure({
-    iterations: 1,
-    keylength: 12
+    iterations: iterations,
+    keylength: keylength
   });
 
   pw.hash('foo', function (err, hash) {
 
-    t.equal(pw.iterations, 1,
+    t.equal(pw.iterations, iterations,
       'should allow iterations override');
 
-    t.equal(hash.length, 33,
+    t.equal(JSON.parse(hash).keylength, keylength,
       'should allow keylength override');
     t.end();
   });