Tuned Global Services aAPIs

HMAC Authentication

Hash-based message authentication code (HMAC) is a mechanism for calculating a message authentication code involving a hash function in combination with a secret key. This can be used to verify the integrity and authenticity of a message (sent from a client to a server or server to server).

If an intermediate party attempts to intercept and alter an API call for malicious reasons, or where a fault in an intermediary proxy drops key header information, the signature will not match and the API call will be denied.

Generate HMAC

Tuned Global will provide the client with a public (Access Key) and a private secret (Secret Key). Both of the keys are base-64 encoded strings, which means they should never contain any non-base-64 characters and the length of each key is always a multiple of 4.

It’s the client’s responsibility is to store the Secret Key securely and never share it with other parties. HMAC tokens are one time use only i.e. client needs to generate a new HMAC for every request to the server even if it’s for the same resource.

The client must Hash the request content using MD5 hashing algorithm. This typically applies to HTTP GET, PUT and POST requests in which the data is sent to the server in the request body or in query string parameters.

Following fields are required to create HMAC signature:

Access key (provided by Tuned Global)
Secret Key (provided by Tuned Global)
Http method (e.g. Get, Post, Put)
UTF-8 encoded request-URI (e.g https://api-delivery-connect.tunedglobal.com/v5/assets encoded using UTF-8
Encoded payload (if applicable)
Nonce
Timestamp

Steps

1

Generate Nonce and Timestamp

Generate a new GUID (to be used as nonce) and a Unix timestamp.

2

Encode URI

Encode the full URI using UTF-8 encoding. Note: Ensure the encoded string is all in lowercase. Note: Steps 3 - 5 are only applicable for POST requests with a JSON object in the payload. Skip to step 6 for http GETAsset requests or requests where there is no Payload to be sent.

3

Serialize JSON Payload

Serialize the Json object / payload that needs to be sent (Only for POST requests).

4

Convert Payload to Bytes

Convert the serialized Json object / payload to bytes using UTF-8 encoding table (Only for POST requests).

5

Hash Payload with MD5

Hash the above byte array using the standard MD5 hashing algorithm and convert the hashed output back to base64 string (Only for POST requests).

6

Build Raw Signature String

Construct a string by concatenating all the fields above to create raw signatures.The expected format is: ``.

7

Convert Raw Signature to Bytes

Convert formatted raw signature string from above to bytes array using UTF 8 encoding.

8

Convert Secret Key to Bytes

Convert the secret key provided by Tuned Global, into a byte array.

9

Generate HMAC-SHA256 Signature

Hash this full concatenated raw signature string using standard HMAC SHA256 hashing algorithm using the secret key byte array.

10

Convert HMAC to Base64 String

Convert the hashed result array from above to the Base64 string. This is the final string which will be used as the unique signature for the request.

11

Construct Authorization Header Value

Build Authorization Header value.This value should contain access key, request signature from the step above, nonce and timestamp separated by colon “:”. The expected format is: {access-key}:{request-signature}:{nonce}:{timestamp}.

12

Add Authorization Header to Request

Add an http Header called Authorization to the request. And the value should be Tuned-HMAC e.g Authorization: Tuned-HMAC {access-key}:{request-signature}:{nonce}:{timestamp}

Resources:

HAMC Generator

Generates HMAC instantly for a request.

Sections