First version of README

Author: tsmx

README.md

@@ -0,0 +1,106 @@
+# [**@tsmx/object-hmac**](https://github.com/tsmx/object-hmac)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+![npm (scoped)](https://img.shields.io/npm/v/@tsmx/object-hmac)
+![node-current (scoped)](https://img.shields.io/node/v/@tsmx/object-hmac)
+[![Build Status](https://img.shields.io/github/workflow/status/tsmx/object-hmac/git-ci-build)](https://img.shields.io/github/workflow/status/tsmx/object-hmac/git-ci-build)
+[![Coverage Status](https://coveralls.io/repos/github/tsmx/object-hmac/badge.svg?branch=master)](https://coveralls.io/github/tsmx/object-hmac?branch=master)
+
+> 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.
+
+## Usage
+
+### Create and add HMAC to a JSON object
+
+```js
+const objectHmac = require('@tsmx/object-hmac');
+const key = 'HmacSecret-0815';
+
+let obj = {
+    name: 'Max',
+    age: 32,
+    hobbies: ['sports', 'travelling']
+};
+
+objectHmac.createHmac(obj, key);
+
+// {"name":"Max","age":32,"hobbies":["sports","travelling"],"__hmac":"37c2e448b6f4a72c9d8abc9a1ab6cada602c3785148caeeed5498ed065ddc69f"}
+```
+
+### Verify HMAC for a JSON object
+
+```js
+// obj = {"name":"Max","age":32,"hobbies":["sports","travelling"],"__hmac":"37c2e448b6f4a72c9d8abc9a1ab6cada602c3785148caeeed5498ed065ddc69f"}
+
+const objectHmac = require('@tsmx/object-hmac');
+const key = 'HmacSecret-0815';
+
+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)
+- Tha HMAC was manipulated
+
+### Only calculate HMAC for an object
+
+```js
+const objectHmac = require('@tsmx/object-hmac');
+const key = 'HmacSecret-0815';
+
+
+let obj = {
+    name: 'Max',
+    age: 32,
+    hobbies: ['sports', 'travelling']
+};
+
+let hmac = objectHmac.calculateHmac(obj, secret);
+
+// 37c2e448b6f4a72c9d8abc9a1ab6cada602c3785148caeeed5498ed065ddc69f
+```
+
+## API
+
+### createHmac(obj, key, hmacAttribute = '__hmac')
+
+#### obj
+
+#### key
+
+#### hmacAttribute
+
+### verifyHmac(obj, key, hmacAttribute = '__hmac')
+
+#### obj
+
+#### key
+
+#### hmacAttribute
+
+### calculateHmac(obj, key)
+
+#### obj
+
+#### key
+
+## 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
+
+
+## Test
+
+```
+npm install
+npm test
+```