Merge pull request #7 from SoapBox/changes/update-documentation

[Changes] Update Documentation

Author: Jaspaul

readme.md

@@ -33,12 +33,24 @@ php artisan vendor:publish
 You will need to set the following details in your environment:
 
 ```sh
+SIGNED_REQUEST_ALGORITHM=
+SIGNED_REQUEST_CACHE_PREFIX=
 SIGNED_REQUEST_SIGNATURE_HEADER=
 SIGNED_REQUEST_ALGORITHM_HEADER=
 SIGNED_REQUEST_KEY=
+SIGNED_REQUEST_ALLOW_REPLAYS=
+SIGNED_REQUEST_TOLERANCE_SECONDS=
 ```
 
-The `SIGNED_REQUEST_SIGNATURE_HEADER` should be the request header that the signature will be included on, something like `X-SIGNATURE`. Similarly the `SIGNED_REQUEST_ALGORITHM_HEADER` should be the request header that the includes the algorithm used to sign the request. Finally the `SIGNED_REQUEST_KEY` should hold the key used to verify the signed requests.
+Each of the settings above allows for a different level of configuration.
+
+  - `SIGNED_REQUEST_ALGORITHM` is the algorithm that will be used to generate / verify the signature. This is defaulted to use `sha256` feel free to change this to anything that `hash_hmac` accepts.
+  - `SIGNED_REQUEST_CACHE_PREFIX` is the prefix to use for all the cache keys that will be generated. Here you can use the default if you're not planning on sharing a cache between multiple applications.
+  - `SIGNED_REQUEST_SIGNATURE_HEADER` should be the request header that the signature will be included on, `X-Signature` will be used by default.
+  - `SIGNED_REQUEST_ALGORITHM_HEADER` should be the request header that the includes the algorithm used to sign the request.
+  - `SIGNED_REQUEST_KEY` is the shared secret key between the application generating the requests, and the application consuming them. This value should not be publically available.
+  - `SIGNED_REQUEST_ALLOW_REPLAYS` allows you to enable or disable replay attacks. By default replays are disabled.
+  - `SIGNED_REQUEST_TOLERANCE_SECONDS` is the number of seconds that a request will be considered for. This setting allows for some time drift between servers and is only used when replays are disabled.
 
 ### Setup the Middleware
 
@@ -57,3 +69,43 @@ Route::get('/fire', function () {
     return "You'll only see this if the signature of the request is valid!";
 })->middleware('verify-signature');
 ```
+
+### Signing Postman Requests
+
+If you, like us, like to use [postman](https://www.getpostman.com/) to share your api internally you can use the following pre-request script to automatically sign your postman requests:
+
+```js
+function guid() {
+  function s4() {
+    return Math.floor((1 + Math.random()) * 0x10000)
+      .toString(16)
+      .substring(1);
+  }
+  return s4() + s4() + '-' + s4() + '-' + s4() + '-' +
+    s4() + '-' + s4() + s4() + s4();
+}
+
+postman.setEnvironmentVariable("x-signed-id", guid());
+postman.setEnvironmentVariable("x-signed-timestamp", (new Date()).toUTCString());
+postman.setEnvironmentVariable("x-algorithm", "sha256");
+
+var payload = {
+    "id": postman.getEnvironmentVariable("x-signed-id"),
+    "method": request.method,
+    "timestamp": postman.getEnvironmentVariable("x-signed-timestamp"),
+    "uri": request.url.replace("{{url}}", postman.getEnvironmentVariable("url")),
+    "content": (Object.keys(request.data).length === 0) ? "" : request.data
+};
+
+var hash = CryptoJS.HmacSHA256(JSON.stringify(payload), postman.getEnvironmentVariable("key"));
+var signature = hash.toString();
+
+postman.setEnvironmentVariable("x-signature", signature);
+```
+
+Note for this to work you'll have to setup your environment to have the following variables:
+
+  - `{{url}}` this is the base url to the api you'll be hitting.
+  - `{{key}}` this is the shared secret key you'll be using in your environment.
+
+All other environment variables that will be needed will be automatically generated by the above script.