Implementation of HMAC Based Token pattern #155

gdelpu · 2021-05-20T09:35:07Z

Hello,

In the frame of one of my project, I had to modify the Crumb plugin to implement an HMAC based token pattern to be used in a stateless server. I think it could valuable for the community to have it officially embedded in Crumb. The implementation follows the pattern described in the OWSAP cheatsheet. I have included a new option to specify the token generation to use: random (the method used by crumb as of now) or hmac (my current contribution)

Unit tests have been updated to test 100% of the code base with both generation method. API markdown documentation has also been updated accordingly.

devinivy · 2021-06-03T03:29:50Z

I can tell this was a major effort— the contribution offer is appreciated. There's a lot to dig into and consider here, but I wanted to followup to let you know that this has been seen 👍

gdelpu · 2021-06-04T07:26:43Z

@devinivy Thanks for your update. I'm looking into implementing the double submit pattern as described in the OWASP cheat sheet. Is it something the CRUMB community could be interested in?

nlf

first off, let me say thank you for implementing this. i love that the hapi community cares about security, and this is a fantastic example of that. your contribution is hugely appreciated!

i requested some changes, largely a lot of nit picking, but the sessionKey option is definitely worth discussing (see my code comments)

nlf · 2021-06-04T17:56:41Z

test/index_hmac.js

+            method: (req, h) => {
+                // This extension method fakes an authentication
+                req.auth.credentials = { userId: 'john' };
+                req.auth.isAuthenticated = true;


given the condition that isAuthenticated needs to be true for us to generate a valid crumb in hmac mode, but it is also possible for isAuthenticated to be false, i would very much like to see a test here that demonstrates and documents that behavior

nlf · 2021-06-04T17:57:44Z

lib/index.js

+                    crumb = Cryptiles.randomString(settings.size);
+                }
+
+                if (settings.method === 'hmac' && (request.auth.isAuthenticated)) {


nit: extra parens

Suggested change

if (settings.method === 'hmac' && (request.auth.isAuthenticated)) {

if (settings.method === 'hmac' && request.auth.isAuthenticated) {

nlf · 2021-06-04T17:58:30Z

lib/index.js

+                if (settings.method === 'hmac' && (request.auth.isAuthenticated)) {
+                    crumb = Hmac.encrypt(request.auth.credentials[settings.sessionKey], settings.secret);
+                }
+
                h.state(settings.key, crumb, settings.cookieOptions);


as mentioned in another comment, it's possible at this point for crumb to be null. we need a test that shows what happens in this scenario

nlf · 2021-06-04T18:00:13Z

lib/index.js

                unauthorizedLogger();
                throw Boom.forbidden();
            }

+            if (settings.method === 'hmac' &&
+                !Hmac.validate(content[request.route.settings.plugins._crumb.key], request.auth.credentials[settings.sessionKey], settings.secret)


nit: this line is super long, making it kind of hard to comprehend quickly. it might be best if we assigned the value of request.route.settings.plugins._crumb.key to a named variable and used that instead of the full reference.

nlf · 2021-06-04T18:00:56Z

lib/index.js

@@ -144,7 +156,13 @@ exports.plugin = {
                    throw Boom.forbidden();
                }

-                if (header !== getCrumbValue()) {
+                if (settings.method !== 'hmac' && header !== getCrumbValue()) {


if we're setting a default of random to settings.method, why not make this condition if (settings.method === 'random' to be more explicit?

nlf · 2021-06-04T18:20:39Z

lib/hmac.js

+
+const Crypto = require('crypto');
+
+const ALGO = 'sha256';


this should be configurable. sha256 is a reasonable default, but there's no good reason to not allow users to override it with their own choice

nlf · 2021-06-04T18:21:59Z

lib/hmac.js

+ * @param {string}key The secret
+ * @returns {string}token
+ */
+const encrypt = (userId, key) => {


nit: all instances of the variable userId should be sessionId since that more clearly indicates what the parameter is since it's not necessarily a user's id

nlf · 2021-06-04T18:23:39Z

lib/hmac.js

+ * @param {string}key The secret
+ * @returns {string}token
+ */
+const encrypt = (userId, key) => {


second nit: key variables should be renamed to secret, again to more clearly indicate what it's used for

nlf · 2021-06-04T18:27:38Z

lib/hmac.js

+        .update(token_timestamp, 'utf8') // Timestamp used at token generation
+        .digest('hex');
+
+    return (digest === token_digest && token_timestamp <= timestamp);


given the comparison of token_timestamp and timestamp, i think it's more appropriate to convert the token_timestamp to a number after splitting the value out than it is to convert the timestamp to a string

nlf · 2021-06-04T18:29:54Z

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).    


nit:

Suggested change

* `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).

* `method` - The token generation and validation method, can be `'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).

nlf · 2021-06-04T18:39:10Z

@devinivy Thanks for your update. I'm looking into implementing the double submit pattern as described in the OWASP cheat sheet. Is it something the CRUMB community could be interested in?

if this is something you're interested in implementing we would be happy to review and merge!

gdelpu added 5 commits May 19, 2021 17:24

feat: Hmac first implementation

eb51ece

test: cover hmac module

7c3dc3d

Fix issue discovered in unit testing

5fbd8c1

test: fix unit tests issues

ce64f6b

doc: update API.md

0e65a2f

gdelpu mentioned this pull request May 21, 2021

HMAC based token pattern #156

Open

do: fixe typos in API doc

c145f6e

nlf requested changes Jun 4, 2021

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Implementation of HMAC Based Token pattern #155

Implementation of HMAC Based Token pattern #155

gdelpu commented May 20, 2021

devinivy commented Jun 3, 2021 •

edited

Loading

gdelpu commented Jun 4, 2021

nlf left a comment

nlf Jun 4, 2021

nlf Jun 4, 2021

nlf Jun 4, 2021

nlf Jun 4, 2021

nlf Jun 4, 2021

nlf Jun 4, 2021

nlf Jun 4, 2021

nlf Jun 4, 2021

nlf Jun 4, 2021

nlf Jun 4, 2021

nlf commented Jun 4, 2021

	if (settings.method === 'hmac' && (request.auth.isAuthenticated)) {
	if (settings.method === 'hmac' && request.auth.isAuthenticated) {

	* `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).
	* `method` - The token generation and validation method, can be `'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).

Implementation of HMAC Based Token pattern #155

Are you sure you want to change the base?

Implementation of HMAC Based Token pattern #155

Conversation

gdelpu commented May 20, 2021

devinivy commented Jun 3, 2021 • edited Loading

gdelpu commented Jun 4, 2021

nlf left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nlf commented Jun 4, 2021

devinivy commented Jun 3, 2021 •

edited

Loading