Add crypto.timingSafeEqual().

doc/api/crypto.md

@@ -681,6 +681,13 @@ Calculates the HMAC digest of all of the data passed using [`hmac.update()`][].
 The `encoding` can be `'hex'`, `'binary'` or `'base64'`. If `encoding` is
 provided a string is returned; otherwise a [`Buffer`][] is returned;
 
+Caution: Code that uses `digest()` directly for comparison with an input value
+is very likely to introduce a
+[timing attack](http://codahale.com/a-lesson-in-timing-attacks/).
+Such a timing attack would allow someone to construct an
+HMAC value for a message of their choosing without posessing the key.
+Use `timingSafeEqual(a, b)` to compare digest values.
+
 The `Hmac` object can not be used again after `hmac.digest()` has been
 called. Multiple calls to `hmac.digest()` will result in an error being thrown.
 
@@ -1211,6 +1218,15 @@ keys:
 
 All paddings are defined in the `constants` module.
 
+### crypto.timingSafeEqual(a, b)
+
+Returns true if `a` is equal to `b`, without leaking timing information that would
+help an attacker guess one of the values. This is suitable for comparing HMAC
+digests or secret values like authentication cookies or
+[capability urls](http://www.w3.org/TR/capability-urls/).
+
+A `TypeError` will be thrown if either `a` or `b` is not a [`Buffer`][] instance.
+
 ### crypto.privateEncrypt(private_key, buffer)
 
 Encrypts `buffer` with `private_key`.

lib/crypto.js

@@ -661,6 +661,33 @@ function filterDuplicates(names) {
   }).sort();
 }
 
+// This implements Brad Hill's Double HMAC pattern from
+// https://www.nccgroup.trust/us/about-us/
+//   newsroom-and-events/blog/2011/february/double-hmac-verification/.
+// In short, it's near-impossible to write a reliable constant-time compare in a
+// high level language like JS, because of the many layers that can optimize
+// away attempts at being constant time.
+//
+// Double HMAC avoids that problem by blinding the timing channel instead. After
+// running the inputs through a second round of HMAC, we are free to
+// short-circuit comparison, because the time it takes to reach the
+// short-circuit has no relation to the similarity between the guessed digest
+// and the correct one.
+exports.timingSafeEqual = timingSafeEqual;
+function timingSafeEqual(a, b) {
+  if (!(a instanceof Buffer))
+    throw new TypeError('First argument must be a Buffer');
+  if (!(b instanceof Buffer))
+    throw new TypeError('Second argument must be a Buffer');
+  var key = randomBytes(32);
+  var ah = new Hmac('sha256', key).update(a).digest();
+  var bh = new Hmac('sha256', key).update(b).digest();
+  // The second test, for a.equals(b), is just in case of the vanishingly small
+  // chance of a collision. It only fires if the digest comparison passes and so
+  // doesn't leak timing information.
+  return ah.equals(bh) && a.equals(b);
+}
+
 // Legacy API
 exports.__defineGetter__('createCredentials',
   internalUtil.deprecate(function() {

test/parallel/test-crypto-hmac.js

@@ -9,11 +9,26 @@ if (!common.hasCrypto) {
 var crypto = require('crypto');
 
 // Test HMAC
-var h1 = crypto.createHmac('sha1', 'Node')
+const h1 = crypto.createHmac('sha1', 'Node')
                .update('some data')
-               .update('to hmac')
-               .digest('hex');
-assert.equal(h1, '19fd6e1ba73d9ed2224dd5094a71babe85d9a892', 'test HMAC');
+               .update('to hmac');
+assert.equal(h1.digest('hex'),
+             '19fd6e1ba73d9ed2224dd5094a71babe85d9a892',
+             'test HMAC');
+
+const h2 = crypto.createHmac('sha1', 'Node')
+               .update('some data')
+               .update('to hmac');
+assert.ok(h2.validate(
+  Buffer.from('19fd6e1ba73d9ed2224dd5094a71babe85d9a892', 'hex'),
+  'test HMAC valid'));
+
+const h3 = crypto.createHmac('sha1', 'Node')
+               .update('some data')
+               .update('to hmac');
+assert.ok(!h3.validate(
+  Buffer.from('6bdee6ee47fb42c53a4f44c3e4bb97591c0c3635', 'hex'),
+  'test HMAC not valid'));
 
 // Test HMAC (Wikipedia Test Cases)
 var wikipedia = [

test/parallel/test-crypto-timing-safe-equal.js

@@ -0,0 +1,14 @@
+'use strict';
+const common = require('../common');
+const assert = require('assert');
+
+if (!common.hasCrypto) {
+  console.log('1..0 # Skipped: missing crypto');
+  return;
+}
+const crypto = require('crypto');
+
+assert.ok(crypto.timingSafeEqual(Buffer.from('alpha'), Buffer.from('alpha')),
+          'equal strings not equal');
+assert.ok(!crypto.timingSafeEqual(Buffer.from('alpha'), Buffer.from('beta')),
+          'inequal strings considered equal');