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.
On this page
- HMAC Authentication