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.
>Thefirst 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<![CDATA[]]>
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-Verbcontent-length:400\n // Content-Length header valuecontent-type:application/json\n // Content-Type header valuex-sntl-content-sha256:7ba7bf9d4819f6f9892edc7aab6432566265cb69ef3acd2fc1f35fbf8758a2c6\n // SHA256 of HTTP bodyx-sntl-epoch:1540054530\n // epoch header valuex-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.
