@tsmx/object-hmac

Create and verify HMAC's for JSON objects.

Easily create and verify keyed-hash message authentication codes (HMAC's) for your JSON objects to ensure data integrity and authenticity.

The generated HMAC is independent of the JSON's attribute order and therefore stable for content-identical objects. See calculateHmac.

Users of an older version prior to v1.1.0 please see the important note.

Usage

Create and add HMAC to a JSON object

1const oh = require('@tsmx/object-hmac');
2const key = 'HmacSecret-0815';
3
4let person = {
5    name: 'Max',
6    age: 32,
7    hobbies: ['sports', 'travelling']
8};
9
10oh.createHmac(person, key);
11
12// person = {
13//   name: 'Max',
14//   age: 32,
15//   hobbies: ['sports','travelling'],
16//   __hmac:'37c2e448b6f4a72c9d8abc9a1ab6cada602c3785148caeeed5498ed065ddc69f'
17// }

Verify HMAC for a JSON object

1// person = {
2//   name: 'Max',
3//   age: 32,
4//   hobbies: ['sports','travelling'],
5//   __hmac:'37c2e448b6f4a72c9d8abc9a1ab6cada602c3785148caeeed5498ed065ddc69f'
6// }
7
8const oh = require('@tsmx/object-hmac');
9const key = 'HmacSecret-0815';
10
11let verification = oh.verifyHmac(person, key);
12// true
13
14person.age = 33;
15
16let verificationAfterChange = oh.verifyHmac(person, key);
17// false

Only calculate HMAC for a JSON object

1const oh = require('@tsmx/object-hmac');
2const key = 'HmacSecret-0815';
3
4let person = {
5    name: 'Max',
6    age: 32,
7    hobbies: ['sports', 'travelling']
8};
9
10let hmac = oh.calculateHmac(person, key);
11// 37c2e448b6f4a72c9d8abc9a1ab6cada602c3785148caeeed5498ed065ddc69f

API

createHmac(obj, key, hmacAttribute)

Calculates the HMAC of obj and attaches it as value of attribute obj[hmacAttribute].

obj

Type: Object

The object to calculate and store the HMAC for.

key

Type: String

The key to calculate the objects HMAC.

hmacAttribute

Type: String Default: __hmac

The name of the attribute to store the HMAC value in obj. Make sure that the name of the attribute is not overlapping with other attributes already in use.

verifyHmac(obj, key, hmacAttribute)

Verifies the HMAC attached to obj. Returns true if the validation was successful, otherwise false false.

The verification would fail and return false, if...

• obj is null
• obj doesn't provide a HMAC to check against
• obj was manipulated: at least one attribute was changed, added or deleted (deep-inspection including all nested objects/arrays)
• the HMAC of obj was manipulated
• key is deviating from the one the HMAC was created with

The verification would not fail, just because the JSON's attributes order has changed. For more details see calculateHmac.

obj

Type: Object

The object of which the HMAC should be verified. The given HMAC to be verified is assumed to exist as an attribute in the object itself: obj[hmacAttribute].

key

Type: String

The key to calculate the objects HMAC and validate against the given one. Must be identical to the key that was used to create the original HMAC for the object for a successful verification.

hmacAttribute

Type: String Default: __hmac

The name of the attribute for the HMAC value in obj to be verified against.

calculateHmac(obj, key)

Calculates and returns the HMAC of obj.

Takes all of obj attributes into account for calculating the HMAC. So make sure that there isn't already a HMAC attribute created in the object. Otherwise this would also being used as an input for the calculation.

The calculation of the HMAC is independent of the order of your JSON's attributes. This means that the HMAC of content-identical objects with just another order of attributes will always by the same.

1let person = {
2    name: 'Max',
3    age: 32,
4    hobbies: ['sports', 'travelling']
5};
6
7let hmac = oh.calculateHmac(person, key);
8
9let person2 = {
10    age: 32,
11    hobbies: ['sports', 'travelling'],
12    name: 'Max'
13};
14
15let hmac2 = oh.calculateHmac(person2, key);
16
17/// (hmac === hmac2) is true

Please not that this order-independency does not apply to array elements. Arrays containing the same values in another order are not content-identical for obvious reasons. So the HMAC's of { hobbies: ['sports', 'travelling'] } and { hobbies: ['travelling', 'sports'] } are different.

obj

Type: Object

The object to calculate the HMAC for.

key

Type: String

The key to calculate the objects HMAC.

Under the hood

To create and verify the HMAC, standard NodeJS crypto functions are used.

The HMAC is generated by using the following parameters:

• Hash function: SHA-256
• Digest output encoding: Hexadecimal String

To provide a stable (attribute-order independent) representation of the JSON object, a sorted traversal using the library @tsmx/json-traverse is applied.

Note for users of older versions prior to v1.1.0

Prior to v1.1.0 the algorithm used to generate the JSON's representation for the HMAC generation didn't to 100% guarantee a deterministic behaviour which could in some cases result in a failing verification although it should succeed.

Therefore it is strongly recommended to update to version 1.1.0 or higher. If you have any HMAC's persistently stored which where generated with a 1.0.x version you must re-calculate them with v1.1.0 or higher when upgrading.

Test

npm install
npm test