xp-cti-it-api

Hash-based Message Authentication Code (HMAC)

Hash-based Message Authentication Code (HMAC) is a message authentication code that uses a cryptographic key in conjunction with a hash function.

HMAC provides the server and the client each with a private key that is known only to that specific server and that specific client. The client creates a unique HMAC, or hash, per request to the server by hashing the request data with the private keys and sending it as part of a request. What makes HMAC more secure than Message Authentication Code (MAC) is that the key and the message are hashed in separate steps.

This ensures the process is not susceptible to extension attacks that add to the message and can cause elements of the key to be leaked as successive MACs are created.

Once the server receives the request and regenerates its own unique HMAC, it compares the two HMACs.

If they're equal, the client is trusted and the request is executed. This process is often called a secret handshake.

Mule Custom Policy HMAC authentication

In order to provide a way to simultaneously verify both the data integrity and the authentication of the API requests, the Custom Policy additional layer (from now called CPL) creates the HMAC Signature (hash) by combining the request data and matches it with the Authorization request header sent by the API Consumer, which from its side has generated the Authorization token following the same process.

When thew CPL receives the HTTP call which contains the request data and the authorization headers, going through the following steps:

Step1:

The CPL inspects the request timestamp header and checks that it is within a specific time range (CPL configuration property), this prevents request message replication from malicious attack;

Step2:

By using the Client-id (from the X-Client-Id header), the CPL retrieves the Private Secret API Key which is stored in the API Manager component provided by the Mulesoft Anypoint Platform;

Step3:

Once the CPL gets the Private Secret API Key, then it tries to rebuild the string by combining the received request content data along with the extracted data. The parameters order and the encoding format has to be exactly the same followed by the client.

Step4:

Once the string is built, then the CPL generates a hash value by the same Hashing algorithm used by the client i.e. SHA256 and using the Private Secret API Key already retrieved as explained in Step2.

Step5:

Finally the CPL compares the generated hash with the one sent by the client. i

If they match the request is considered valid, else an http status code representing the error is returned to the client (401 unauthorized error).

Mule Custom Policy HMAC authentication

Using HMAC symmetric key algorithm guarantees that the message is not tampered with case of Man in the middle attack. The following headers will be mandatory for every client request:

• X-Requester: Consumer host

type: string

required: true

• X-Request-Date: Current Date in ISO format (2019-07-12T07:07:18.939Z)

type: string

required: true

• X-Client-Id: generated by Anypoint API Manager

type: string

required: true

• Authorization: hmac Token generated by the consumer

type: string

required: true

How generate HMAC token (Authorization header parameter)

First, the client needs to create a string which contains the following parameters:

• Client-Id (provided by Anypoint Platform during the app registration process)
• Requester endpoint (host of the caller)
• The request URI (the entire API path plus query parameters)
• Request datetime (in ISO date format)
• Base64 string representation of the request body (Optional)

Once all the parameters are concatenated in a single string, the client has to encrypt it via SHA256 Algorith, using the Mule Client Secret as key.

Eventually the client has to send the calculated hash in the "Authorization" header parameter.

Note:

Mule Client Secret is provided during the app registration process by the Mule API Manager.