Implementation of HMAC Based Token pattern

API.md

@@ -63,7 +63,8 @@ The following options are available when registering the plugin.
   * `skip` - a function with the signature of `function (request, h) {}`, which when provided, is called for every request. If the provided function returns true, validation and generation of crumb is skipped. Defaults to `false`.
   * `enforce` - defaults to true, using enforce with false will set the CSRF header cookie but won't execute the validation
   * `logUnauthorized` - whether to add to the request log with tag 'crumb' and data 'validation failed' (defaults to false)
-
+  * `method` - The token generation method (and therefore how to validate), could take values `random` or `hmac`. Defaults to `random`, if set to `hmac` crumb will use the `Hmac Based Token pattern` [as described by OWASP here](https://github.com/OWASP/CheatSheetSeries/blob/083b4791c44ef28b105f66c82ffd83a86bf9fa16/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.md).    
+  * `sessionKey` - Define which key of `auth.credentials` should be used during token creation if specified method is `hmac`
 ### Routes configuration
 
 Additionally, some configuration can be passed on a per-route basis. Disable Crumb for a particular route by passing `false` instead of a configuration object.

lib/hmac.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const Crypto = require('crypto');
+
+const ALGO = 'sha256';
+/**
+ * Returns base64-encoded ciphertext
+ * @param {string}userId The string to encrypt
+ * @param {string}key The secret
+ * @returns {string}token
+ */
+const encrypt = (userId, key) => {
+
+    const timestamp = Date.now().toString();
+    const digest = Crypto.createHmac(ALGO, key)
+        .update(userId, 'utf8')
+        .update(timestamp, 'utf8')
+        .digest('hex');
+
+    return `${digest}_${timestamp}`;
+};
+
+/**
+ * Validate a CSRF token generated with HMAC method. based on OWASP cheatsheet
+ * https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#hmac-based-token-pattern
+ * @param {string}enc
+ * @param {string}userId
+ * @param {string}key
+ */
+const validate = (enc, userId, key) => {
+
+    if (!enc || !userId || !key) {
+        // Validation fails is one of the params is null or undefined
+        return false;
+    }
+
+    const timestamp = Date.now().toString();
+    const [token_digest, token_timestamp] = enc.split('_'); //Split the encrypted string to retrieve the hmac digest and the timestamp
+
+    if (!token_digest || !token_timestamp) {
+        // Validation fails is one of the params is null or undefined
+        return false;
+    }
+
+    const digest = Crypto.createHmac(ALGO, key)
+        .update(userId, 'utf8')
+        .update(token_timestamp, 'utf8') // Timestamp used at token generation
+        .digest('hex');
+
+    return (digest === token_digest && token_timestamp <= timestamp);
+};
+
+module.exports = {
+    encrypt,
+    validate
+};

lib/index.js

@@ -7,6 +7,7 @@ const Cryptiles = require('@hapi/cryptiles');
 const Hoek = require('@hapi/hoek');
 const Validate = require('@hapi/validate');
 
+const Hmac = require('./hmac');
 
 const internals = {
     restfulValidatedMethods: ['post', 'put', 'patch', 'delete']
@@ -23,7 +24,16 @@ internals.schema = Validate.object().keys({
     restful: Validate.boolean().optional(),
     skip: Validate.func().optional(),
     enforce: Validate.boolean().optional(),
-    logUnauthorized: Validate.boolean().optional()
+    logUnauthorized: Validate.boolean().optional(),
+    method: Validate.string().optional().valid('random', 'hmac'),
+    secret: Validate.string().when(
+        'method',
+        { is: Validate.exist(), then: Validate.required(), otherwise: Validate.optional() }
+    ),
+    sessionKey: Validate.string().when(
+        'method',
+        { is: Validate.exist(), then: Validate.required(), otherwise: Validate.optional() }
+    )
 });
 
 
@@ -39,7 +49,9 @@ internals.defaults = {
     restful: false,                 // Set to true for custom header crumb validation. Disables payload/query validation
     skip: false,                    // Set to a function which returns true when to skip crumb generation and validation,
     enforce: true,                  // Set to true for setting the CSRF cookie while not performing validation
-    logUnauthorized: false          // Set to true for crumb to write an event to the request log
+    logUnauthorized: false,         // Set to true for crumb to write an event to the request log
+    method: 'random',               // Define the token generation method (and therefore how to validate)
+    sessionKey: 'userId'            // Define which key of auth.credentials should be used during token creation if method = hmac
 };
 
 
@@ -68,7 +80,8 @@ exports.plugin = {
             const unauthorizedLogger = () => {
 
                 if (settings.logUnauthorized) {
-                    request.log(['crumb', 'unauthorized'], 'validation failed');
+                    const tags = ['crumb', 'unauthorized'];
+                    request.log(tags, 'validation failed');
                 }
             };
 
@@ -130,7 +143,6 @@ exports.plugin = {
             }
 
             // Validate crumb
-
             const restful = request.route.settings.plugins._crumb ? request.route.settings.plugins._crumb.restful : settings.restful;
             if (restful) {
                 if (!internals.restfulValidatedMethods.includes(request.method) || !request.route.settings.plugins._crumb) {
@@ -144,7 +156,13 @@ exports.plugin = {
                     throw Boom.forbidden();
                 }
 
-                if (header !== getCrumbValue()) {
+                if (settings.method !== 'hmac' && header !== getCrumbValue()) {
+                    unauthorizedLogger();
+                    throw Boom.forbidden();
+                }
+
+                if (settings.method === 'hmac' &&
+                    !Hmac.validate(header, request.auth.credentials[settings.sessionKey], settings.secret)) {
                     unauthorizedLogger();
                     throw Boom.forbidden();
                 }
@@ -168,11 +186,17 @@ exports.plugin = {
                 throw Boom.forbidden();
             }
 
-            if (content[request.route.settings.plugins._crumb.key] !== getCrumbValue()) {
+            if (settings.method !== 'hmac' && content[request.route.settings.plugins._crumb.key] !== getCrumbValue()) {
                 unauthorizedLogger();
                 throw Boom.forbidden();
             }
 
+            if (settings.method === 'hmac' &&
+                !Hmac.validate(content[request.route.settings.plugins._crumb.key], request.auth.credentials[settings.sessionKey], settings.secret)
+            ) {
+                unauthorizedLogger();
+                throw Boom.forbidden();
+            }
             // Remove crumb
 
             delete request[request.route.settings.plugins._crumb.source][request.route.settings.plugins._crumb.key];
@@ -210,7 +234,16 @@ exports.plugin = {
         const generate = function (request, h) {
 
             if (!request.plugins.crumb) {
-                const crumb = Cryptiles.randomString(settings.size);
+                let crumb = null;
+
+                if (settings.method === 'random') {
+                    crumb = Cryptiles.randomString(settings.size);
+                }
+
+                if (settings.method === 'hmac' && (request.auth.isAuthenticated)) {
+                    crumb = Hmac.encrypt(request.auth.credentials[settings.sessionKey], settings.secret);
+                }
+
                 h.state(settings.key, crumb, settings.cookieOptions);
                 request.plugins.crumb = crumb;
             }

test/hmac.js

@@ -0,0 +1,66 @@
+'use strict';
+
+const Code = require('@hapi/code');
+const Lab = require('@hapi/lab');
+const Hmac = require('../lib/hmac');
+
+const { describe, it } = exports.lab = Lab.script();
+const { expect } = Code;
+
+describe('Hmac', () => {
+
+    const mySecret = 'super secret!!! Do not share';
+    const userId = 'myUserId';
+
+    it('should export two methods', () => {
+
+        expect(Hmac).to.include('encrypt')
+            .and
+            .to.include('validate');
+
+        expect(Hmac.encrypt).to.be.a.function();
+        expect(Hmac.validate).to.be.a.function();
+    });
+
+    describe('encrypt', () => {
+
+        it('should return a digest and a timestamp concatenate with _', () => {
+
+            const result = Hmac.encrypt(userId, mySecret);
+            expect(result).to.be.a.string().and.to.include('_');
+        });
+    });
+
+    describe('validate', () => {
+
+        it('should return FALSE if the token is not in the right format', () => {
+
+            let encryptedStr = 'thisIsNotaGoodformat';
+            expect(Hmac.validate(encryptedStr, userId, mySecret)).to.be.a.false();
+
+            encryptedStr = '_thisIsNotaGoodformat';
+            expect(Hmac.validate(encryptedStr, userId, mySecret)).to.be.a.false();
+        });
+
+        it('should return FALSE if one of the parameters is null', () => {
+
+            const encryptedStr = 'thisIsNotaGoodformat';
+
+            expect(Hmac.validate(null, userId, mySecret)).to.be.a.false();
+            expect(Hmac.validate(encryptedStr, null, mySecret)).to.be.a.false();
+            expect(Hmac.validate(encryptedStr, userId, null)).to.be.a.false();
+        });
+
+        it('should return TRUE if the token is valid', () => {
+
+            const encryptedStr = Hmac.encrypt(userId, mySecret);
+            expect(Hmac.validate(encryptedStr, userId, mySecret)).to.be.a.true();
+        });
+
+        it('should return FALSE if digest do not match', () => {
+
+            const encryptedStr = `123456ABCD_${Date.now().toString()}`;
+            expect(Hmac.validate(encryptedStr, userId, mySecret)).to.be.a.false();
+        });
+    });
+});