How to make a Web Service Request/Response

Setting Up the HTTP Headers

You need to set the following headers in each web service request:

text/xml;charset=utf-8

application/xml;version=1.0

1354699124799

ISVCOde

SCWS 7212140:bWq2s1WEIj+Ydj0vQ697zp+IXMU=

How to Compute the Signature?

Prerequisites

The Message Signing method for authentication uses Secret Key and Secret Key ID. Every software vendor client is assigned a Secret Key and Secret Key ID pair, which is used for authenticating requests. The Secret Key and Secret Key ID are received in Sentinel Order emails from Thales.

NOTE    The Secret Key should not be shared with anyone, and should be kept well-protected inside the application.

Steps for Computing the Signature and Forming the Authorization Header

Step 1

The first step in message signing is to calculate the SHA256 content of a request body, which is in hexadecimal format (lowercase). This value is used as a value for x-sfnt-sha256 in the string to sign.

Step 2

The next step is to concatenate selected elements of the request to form stringToSign.

Following is pseudo-grammar that illustrates the construction of string to sign for a request message:

String stringToSign = httpMethod.toUpperCase() + "\n" + // HTTP-Verb
	  contentLength + "\n" + // Content-Length header value
	  contentType + "\n" + // Content-Type  header value
	  "x-sfnt-sha256:" + contentSHA256Body + "\n" + // SHA256 of HTTP body in hexadecimal format (lowercase)
	  "x-sfnt-date:" + date + "\n" + // x-sfnt-date  header value
	  canonicalizedResource; // CanonicalizedResource

Following is pseudo-grammar that illustrates the construction of string to sign for a response message:

String stringToSign = httpMethod.toUpperCase() + "\n" + // HTTP-Verb
	contentLength + "\n" + // Content-Length of response body
	contentType + "\n" + // Content-Type header value
	"x-sfnt-sha256:" + contentSHA256Body + "\n" + // SHA256 of HTTP response body
	"x-sfnt-date:" + date + "\n" + // value of “DateHeader” in response
	canonicalizedResource;

The parts of the above format are described below:

>HTTP-Verb: Depending upon the Sentinel Cloud Connect web service, the HTTP request type can be POST, DELETE, GET, or PATCH.

>Content-Length: Length of request message.

When the request body is not given, the hash is null (shown below) indicating that the hash value is not set with the header.

>Content-Type: Type of request message, such as XML.

For example, application/xml; charset=utf-8.

When the request body is not given, the hash is null (shown below) indicating that the hash value is not set with the header.

>x-sfnt-sha256: Contains the SHA256 content of a request body. When the request body is not given, the hash is null (shown below) indicating that the hash value is not set with the header.

x-sfnt-sha256:null 

>x-sfnt-date: It is mandatory to set this header for authentication. The value of x-sfnt-date specifies time in milliseconds, since January 1, 1970, 00:00:00 GMT. The value of x-sfnt-date is specified in the UTC time zone.

For request, x-sfnt-date is set to the current date. For response, it is set to the value of DateHeader.

>CanonicalizedResource: This is the string containing the resource and its version as used in the request URI. Example: : /licenseSessions1.0.

In the above format, Content-Type and x-sfnt-date headers should be set in each web service request, with the same value as specified in the string to sign.

Step 3

Calculate HMAC-SHA256 of stringToSign by using secret key. The output of HMAC-SHA256 is a byte string, called the digest.

You need to perform the Base64 encoding of this digest to calculate the signature.

HMAC-SHA256 () is an algorithm defined by RFC 2104 (RFC 2104 - Keyed-Hashing for Message Authentication). The algorithm takes as input two byte-strings: a key and a message. Use your Sentinel Cloud Connect web service Secret Key as the key, and the UTF-8 encoding of the string to sign as the message.

The final output is the signature of request/response which is sent/received in the Authorization header. Following is the pseudo-grammar that illustrates the construction of a signature.

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

Step 4

The last step is to form the authorization header by using the signature computed in the step above. Prefix the “SCWS[SPACE]{SecretKeyId}:” string before the calculated signature.

The Authorization header has the following format:

SCWS[SPACE][SecretKeyId]:[Signature]

Example - Calculating Signature and Setting Headers for a Request

This example explains how to set headers and calculate signature for a web service request. The POST licenseSession web service has been used in this example.

Request URL

https://fra01-he02.trial.sentinelcloud.com/scc/licenseSessions

Request Body

<licenseSession> <user>u1</user> <customer>cloud</customer> <featureNode> <featureVersion>1.0</featureVersion> <featureName>cloud</featureName>
</featureNode> <vendorData>Runtime-1234-1</vendorData> <unitsRequired>2</unitsRequired> <usageCountMultiplier>36</usageCountMultiplier>
</licenseSession>

NOTE   There should not be any white space or newline characters between an XML element and its value.

Step 1 : Calculating the SHA256 Hash of the Body

You need to calculate the SHA256 hash of the above request body, which is in hexadecimal format (lowercase). This value is used as a value for x-sfnt-sha256 in the string to sign.

Let us assume, the SHA256 hash of the above request body is the following:

b19010bb4af8a32075e1997699b535324a1170ac86606c45b26a1406ab3b4135

Step 2: An Example of Constructing the Sample String to Sign

As obtained from the above request, the following are the elements and their values for constructing the string to sign:

Sample String to Sign with the Request Body

POST					// HTTP-Verb
307					// Content-Length header value
text/xml;charset=utf-8			// Content-Type header value
x-sfnt-sha256:4e10563f661b0857d74bb490fc8468f8c4a639214aa612a0e16de2d26a489711	// SHA256 of HTTP body
x-sfnt-date:1483351491859		// x-sfnt-date header value
/licenseSessions1.0			// CanonicalizedResource

Sample String to Sign without the Request Body

GET					// HTTP-Verb
null					// Content-Length header value
null					// Content-Type header value
x-sfnt-sha256:null			// SHA256 of HTTP body
x-sfnt-date:1482481965451		// x-sfnt-date header value
/licenses1.0				// CanonicalizedResource

The x-sfnt-date and x-sfnt-sha256 value (after colon) must not contain any leading spaces.

Step 3: Calculating HMACSHA256 of stringToSign

Calculate HMACSHA256 of stringToSign by using secret key, which is called the digest. You need to perform the Base64 encoding of this digest to calculate the signature.

Step 4: Forming the Authorization Header

The last step is to form the authorization header by using the signature computed in the step above. Prefix the “SCWS[SPACE]{SecretKeyId}:” string before the calculated signature.

For example, let us assume:

>Signature: l49P1O8XSwF89LCUjmV+Sw1P7rKgFTQUueO3Ha2R1UA=

>SecretKeyId: 7212140

The authorization header will look like the following:

SCWS 7212140:l49P1O8XSwF89LCUjmV+Sw1P7rKgFTQUueO3Ha2R1UA=

Setting the Request Headers

The headers to be set in the request are:

Example - Calculating Signature and Retrieving Headers for a Response

The signature calculation and request validation processes for request and response are similar. This example explains how to set headers and calculate signature for a web service response. The POST licenseSession web service has been used in this example.

Request URI

https://fra01-he02.trial.sentinelcloud.com/scc/licenseSessions

Response Body

<licenseSession> <licenseSessionId>YJXgroC%2F7Ng5lYgo2eCrtFaPjv7Gz1X7V2dulSgLgeDXqrfgz7oUz%2B1zZIqt50%2FnS2UYatwdLoVB%0D%0A%2FVFd8hQRjn4O06TM0bf%2FZHm21hZBt2ad2d4M2TzPnXkredifNrFTvGdCP75MyuhOstuFD6492Crk%0D%0AJHzWa0PhOVFjnr7dVYRBC4OTYpC3sXCGAbU%2BE55uqxv3uLF85WV60n4Hr79BbU1ffy%2FeOHMFm1uR%0D%0AChH7yT6X3aBuLQcQ1wAATLUq5ht38v9Ow7MkkBI4Km9ltvHnZ2lhAeI%2BOkSJ </licenseSessionId> </licenseSession>

Response Headers

The headers received in the response are:

Step 1 : Calculating the SHA256 Hash of the Body

You need to calculate the SHA256 hash of the above response body, which is in hexadecimal format (lowercase). This value is used as a value for x-sfnt-sha256 in the string to sign.

Let us assume, the SHA256 hash of the above response body is the following:

51342660b05393aac0d6d34211be70ed59c977b72894160ae32e7095e12dea92

Step 2: Constructing the Sample String to Sign

As obtained from the above response, the following are the elements and their values for constructing the string to sign:

Sample String to Sign with the Response Body

POST							// HTTP-Verb
784							// Content-Length of body
text/xml;charset=utf-8					// Content-Type header value
x-sfnt-sha256:74f07e910fd287fd3d8deec944167ebe6d826a599e479fd35b743e68b9a9cd2b	// SHA256 of HTTP response body
x-sfnt-date:1495691798084				// value of “DateHeader” in response
/licenses1.0						// CanonicalizedResource

The x-sfnt-date and x-sfnt-sha256 value (after colon) must not contain any leading spaces.

Step 3: Calculating HMAC-SHA256 of stringToSign

Calculate HMAC-SHA256 of stringToSign by using secret key, which is called the digest. You need to perform the Base64 encoding of this digest to calculate the signature.

Step 4: Forming the Authorization Header

The last step is to form the authorization header by using the signature computed in the step above. Prefix the “SCWS[SPACE]{SecretKeyId}:” string before the calculated signature.

For example, let us assume:

>Signature: l49P1O8XSwF89LCUjmV+Sw1P7rKgFTQUueO3Ha2R1UA=

>SecretKeyId: 7212140

Then the authorization header will look like the following:

SCWS 7212140:l49P1O8XSwF89LCUjmV+Sw1P7rKgFTQUueO3Ha2R1UA=

Retrieving the Response Headers

The response headers are: