README updated, null object captured for verification

Author: tsmx

README.md

@@ -8,7 +8,7 @@
 
 > Create and verify HMAC's for JSON objects.
 
-Easily create and verify [HMAC's](https://en.wikipedia.org/wiki/HMAC) for your JSON objects to ensure data integrity and authenticity.
+Easily create and verify [HMAC's](https://en.wikipedia.org/wiki/HMAC) for your JSON objects to ensure data integrity and authenticity. 
 
 ## Usage
 
@@ -26,7 +26,7 @@ let obj = {
 
 objectHmac.createHmac(obj, key);
 
-// {"name":"Max","age":32,"hobbies":["sports","travelling"],"__hmac":"37c2e448b6f4a72c9d8abc9a1ab6cada602c3785148caeeed5498ed065ddc69f"}
+// obj = {"name":"Max","age":32,"hobbies":["sports","travelling"],"__hmac":"37c2e448b6f4a72c9d8abc9a1ab6cada602c3785148caeeed5498ed065ddc69f"}
 ```
 
 ### Verify HMAC for a JSON object
@@ -42,11 +42,6 @@ let verification = objectHmac.verifyHmac(obj, key);
 // true
 ```
 
-The verification would fail and return `false`, if...
-- The object to be verified doesn't provide a HMAC to check against
-- The object was manipulated: attributes were changed, added or deleted (deep-inspection including all nested objects/arrays)
-- The HMAC was manipulated
-
 ### Only calculate HMAC for an object
 
 ```js
@@ -65,37 +60,85 @@ let hmac = objectHmac.calculateHmac(obj, key);
 // 37c2e448b6f4a72c9d8abc9a1ab6cada602c3785148caeeed5498ed065ddc69f
 ```
 
-## API - *under construction*
+## API
 
 ### createHmac(obj, key, hmacAttribute = '__hmac')
 
+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 overkapping with other attributes already in use.
+
 ### verifyHmac(obj, key, hmacAttribute = '__hmac')
 
+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
+
 #### 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.
+
 #### 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.
+
 #### 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](https://nodejs.org/docs/latest-v12.x/api/crypto.html#crypto_class_hmac) are used.
 
 The HMAC is generated by using the following parameters:
 - Hash function: SHA-256
-- Digest output encoding: Hexadecimal
+- Digest output encoding: Hexadecimal String
 
 
 ## Test

object-hmac.js

@@ -12,6 +12,7 @@ function calculateHmac(obj, key) {
 }
 
 function verifyHmac(obj, key, hmacAttribute = '__hmac') {
+    if (!obj) return false;
     const providedHmac = obj[hmacAttribute];
     let hmacObj = { ...obj };
     delete hmacObj[hmacAttribute];

test/object-hmac.test.js

@@ -54,4 +54,9 @@ describe('object-hmac test suite', () => {
         done();
     });
 
+    it('test a failed HMAC verification - obj is null', async (done) => {
+        expect(objectHmac.verifyHmac(null, testKey)).toBeFalsy();
+        done();
+    });
+
 });