Invoking SMPI | Trend Micro Service Central

Views:

The Trend Micro Service Management Programming Interface (SMPI) is a REST API implemented over HTTPS Protocol, provides a set of integrated API interfaces that allows your system to interact with the Trend Micro Remote Manager (TMRM). This section covers some technical detail that you should note when adapting interfaces for your systems.

Authentication

The SMPI implements a simple authentication method for the API to identify integration partners. You could apply a pair of identification credentials along with the SMPI URL from Trend Micro Remote Manager as follow:

First, login to TMRM console, the page of generating SMPI key pair is under Administration tab

After entering Adminitration tab, click into Generate API key link under the section Third-party integration

Here is the page of managing SMPI key pair, partners could genreate a new key pair or revoke an exising one anytime in TMRM console.

After clicking the Geneate button, the corresponding key pair and SMPI URL will be shown.

These credentials help the SMPI recognize the caller as a valid integrating partner of Trend Micro. The Access Token is a GUID represents the caller, while the Secret Key should be safely kept and used to generate signature for every SMPI requests to guarantee the integrity.

To successfully invoke the SMPI, several requirements should be fulfilled. The following is an example of customized HTTP headers that you should specify for every request made to the API:

x-access-token: 8be8f9e2-c82d-454b-90e3-744a6e74f664
x-posix-time: 1363797148
x-signature: rnBCnS6YWHvR5PnkM2J44IobfTGcQL039xkRbosIMe8=
x-traceid: 95b794e7-7f4b-4f20-95b6-a16d4143199e
content-type:application/json; charset=utf-8

Kindly pay attention to the header elements as these are compulsory headers required for the SMPI to respond to your request. The following table explains these elements in detail:

Header Name	Type	Description	Validation
Required
x-access-token	GUID	The unique Access Token generated in TMRM console, that is used to identify the caller. The format will be similar to: 975f9ce9-f509-4842-8c2e-9f0b1f27e1b3.	Format: Must be a valid GUID format Length: 36 characters
x-posix-time	long	This value is the standard UNIX time in seconds, which is the number of seconds that have elapsed since midnight Coordinated Universal Time (UTC), January 1, 1970, not counting leap seconds. Use this value to generate the x-signature header. API also checks this value against its own time. If the differences is more than 15 minutes (plus or minus), the request is denied.	Format: Valid long integer Length: 10 characters
x-signature	String	This value is calculated based on selected headers, as well as a Secret Key, and is a based on 64 encoded string, which is calculated by the following expression. More details on how to generate the x-signature will be presented in the next section.	Value: Validates against the signature generated by the API server Length: 90 characters.
content-type	String	This should specify the application/json and charset=utf-8 for every API call. Note that the content is UTF-8 encoded.	Length: 31 characters
x-traceid	String	This is intend to facilitate troubleshooting. The format of the TraceID is simply a String. It is recommended to be in the format of a GUID string (e.g. 975f9ce9-f509-4842-8c2e-9f0b1f27e1b3), and will not check the format. When the server logs the request, the Trace ID is accompanied with the client's access token for it to identify the caller, as well as the request.	Length: 36 characters
Date	String	The Date is HTTP protocol standard. The format follows RFC 822. It will appear as: Tue, 17 Sep 2013 05:54:38 GMT. Details	Length: 30 characters

x-signature Generation

The x-signature proves that the message is composed by a trusted Business Partner who owns the Secret Key. It also prevents the message from been hijacked or resent by other parties when sent via the Internet, even when all transactions are forced to be sent over SSL. The x-signature header should be composed using the following matrix:

Payload = [x-posix-time] + [http method] + [request_uri] + [body content]

x-signature = HMAC-SHA256(secret_key, UTF-8 Encoding(Payload))

Payload

The table explains the elements of the Payload string:

Name	Description	Example
x-posix-time	This value is the standard UNIX time in seconds, which is the number of seconds that have elapsed since midnight Coordinated Universal Time (UTC), January 1, 1970, not counting leap seconds.	1363370254
HTTP method	The current HTTP method that is used to request the API. This value should be in upper case.	POST
request_uri	This should be the absolute URI of the current request, including the query string. Please note to percent encode query string parameter values.	/my/plans?keyword=serviceplan%201
content	Given that the request contains body content, such as POST or UPDATE, this content should be hashed and appended to the end of the Payload. Hashing algorithm is: Base64(MD5(content as binary))	Hashed result	Original content
content		telHj8YUFXO1IenheVsWkg==	{"hello":"json"}

x-signature

Once the Payload is generated, it is ready to be hashed using the Secret Key that was provided to generate the signature. The following algorithm explains how the signature is generated.

Base64 ( HMAC-SHA256(secret_key, Payload) )

The first step is to generate a HMAC-SHA256 hash of the Payload using your Secret Key, and then convert the binary into Base64 string.

As for this design, you need to generate a unique x-signature in every request, resulting in a different signature for each request. The x-signature will be verified by the API server in every request.

Request Content

Apart from the header elements. The HTTP request body should also include a valid JSON data structure of the data that you need to send to the LMPI API, if required. The details of the body content is included in each API Specification.

Example

SMPI Examples