HMAC-SHA256 Signature Verification of Request-Response

The RMS Cloud LM (server) uses HMAC-SHA256-based message signing to authenticate client requests (users/devices consuming licenses) while using the login, refresh, and logout calls. Only these REST APIs require message signing, as they facilitate license authorization.

For clients using the REST APIs, it is the software vendor's responsibility to compute a message signature and send it in the x-sntl-signature HTTP header. If a correct signature is not passed in the header for the login, refresh, and logout calls, these APIs will fail. Similarly, messages from the server should be validated on the client end using the value in the x-sntl-signature header sent by the server.

TIP   The SCP-integrated library automatically handles the end-to-end process of message signing. Refer to the table below for detailed workflow.

Message Signing Workflow

The workflow for message signing between the client and server is as follows:

Workflow	Entity Responsible
	For SCP-integrated Library	For RMS Cloud LM REST API
Client computes the signature of request data using the steps described below.	SCP-integrated Library	To be done by the software vendor
Client sends the computed signature in the x-sntl-signature request header to the server.	SCP-integrated Library	To be done by the software vendor
Server authorizes the client request upon successful signature verification.	Server	Server
The server computes the signature of response data using the steps described below.	Server	Server
Server sends the computed signature in the x-sntl-signature response header to the client.	Server	Server
Client verifies the signature received from the server.	SCP-integrated Library	To be done by the software vendor

Steps for Computing a Message Signature

Step 1: Calculate x-sntl-content-sha256

Calculate the SHA256 content of a request body, which is used as a value for x-sntl-content-sha256 in the stringToSign.

Step 2: Create stringToSign

Concatenate the selected elements of the request to form stringToSign.

Rules to Construct stringToSign

Follow the rules below to construct stringToSign:

>All participating elements must be separated by a newline character.

>The first element is the HTTP verb in uppercase.

NOTE   Message signing is only needed for POST methods (such as login, refresh, and logout), so the value is always POST.

>The last element is the canonicalized resource. This is the string containing the resource as used in the request URI. For example: /rmslm/licenseSessions

>Between the first and the last elements are the participating headers listed below (also described here) and their values in the format <header-name>:<header-value>:

•Content-Length

•Content-Type

•x-sntl-content-sha256

•x-sntl-epoch

•x-sntl-message-id

NOTE   The headers and their values must be concatenated in the order listed above.

>For all the header values, all the leading and trailing spaces must be trimmed before adding to the stringToSign

>All the header names should be converted to lower case before adding to the stringToSign.

An example of stringToSign:

POST\n                                                                                      // HTTP-Verb
content-length:400\n                                                                        // Content-Length header value
content-type:application/json\n                                                             // Content-Type header value
x-sntl-content-sha256:7ba7bf9d4819f6f9892edc7aab6432566265cb69ef3acd2fc1f35fbf8758a2c6\n    // SHA256 of HTTP body
x-sntl-epoch:1540054530\n                                                                   // epoch header value
x-sntl-message-id:C1EC68F7-9661-4580-94A8-8F0E0CC67D84\n                                    // message-id header value
/rmslm/licenseSessions                                                                      // canonicalized resource

Step 3: Calculate HMAC-SHA256 of stringToSign

Compute the HMAC-SHA256 of stringToSign using the Secret Key.

NOTE   Both the Secret Key and Secret Key ID (used in step 4) are provided in the Sentinel order email.

HMAC-SHA256 is an algorithm defined by RFC 2104 (RFC 2104—Keyed-Hashing for Message Authentication). The algorithm takes two byte-strings as input: a key and a message. The output of HMAC-SHA256 is a byte string, called the digest. You must perform the Base64 encoding of this digest to calculate the signature.

The pseudo-grammar that illustrates the construction of a signature is shown below:

Signature = Base64( HMAC-SHA256( YourSecretKey,  StringToSign  ) )

Step 4: Form the x-sntl-signature Header

Form the x-sntl-signature header by using the signature computed in the step above.

The x-sntl-signature header has the following format:

[YourSecretKeyId]:[Signature]

For response verification, the signature calculated in Step 3 is verified against the value received from the server in the x-sntl-signature header.