Last updated: 12/3/2024 11:08:45 AM
LMPI provides a set of integration API interfaces allowing your system to interact
with Trend Micro License Management Portal. The following sections cover some technical
details that are useful when implementing these interfaces for your organization's
system.
LMPI is a REST API implemented via HTTP protocol, and which decomposes complex business
logic of License Management Portal following REST API conventions. Per the API Reference, domain models are collections of resources for developers to operate using HTTP
methods defined by REST API standards.
Authentication
To successfully invoke the LMP API, you must fulfill several requirements for authentication. The following is an example of customized HTTP headers that you should specify for every request made to the API:HTTP header sample:
x-access-token: {Put your access token here} x-posix-time: 1363797148 x-signature: rnBCnS6YWHvR5PnkM2J44IobfTGcQL039xkRbosIMe8= x-traceid: 95b794e7-7f4b-4f20-95b6-a16d4143199e content-type: application/json; charset=utf-8
Header elements are particularly important, as some headers are required for the API
to respond to your request. For more information, see the following table:
Name
|
Type
|
Description
|
Validation
|
||
Required
|
|||||
x-access-token
|
GUID
|
The unique access token that you receive from Trend Micro, which is used to identify
the integrating partner.
Example:
975f9ce9-1234-5678-8c2e-9f0b1f27e1b3 |
GUID
|
||
x-posix-time
|
long
|
The standard UNIX time in seconds, which is the number of seconds elapsed since 00:00:00
UTC on January 1, 1970 (excluding leap seconds). Use this value to generate the x-signature
header.
|
1-10 digits, long integer
|
||
x-signature
|
string
|
A string that verifies that a request comes from a trusted business partner who owns
the Secret Key.
|
1-90 characters
|
||
content-type
|
string
|
The format and encoding of the content in the API call.
Example:
application/json and charset=utf-8
|
1-31 characters
|
||
x-traceid
|
string (GUID recommended)
|
The identifier accompanying the access token, allowing identification of the API caller
and the request logged by the server, which facilitates troubleshooting.
|
1-60 characters
|
||
Date
|
string
|
The date of the authentication request, conforming to HTTP protocol standard.
Example: Tue, 17 Sep 2013 05:54:38 GMT
|
1-30 characters in RFC 822 format
|
x-signature Generation
The
x-signature
verifies that a request comes from a trusted business partner who owns the Secret Key, preventing the request from being hijacked or resent by other parties, even when
all messages are sent via SSL.You must compose the
x-signature
header 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 following table displays the elements that compose the Payload string:
Name
|
Description
|
Example
|
||
x-posix-time
|
The standard UNIX time in seconds, which is the number of seconds elapsed since 00:00:00
UTC on January 1, 1970 (excluding leap seconds). Use this value to generate the x-signature
header.
|
1363370254 |
||
HTTP method
|
The current HTTP method used to request the API, written in all upper case.
|
POST |
||
request_uri
|
The absolute URI of the current request, including the query string.
|
/LMPI/v2/me/plans?keyword=serviceplan%201 |
||
content
|
The content of the request.
Given that the request contains body content such as
POST or UPDATE , the content should be hashed using the following algorithm and appended to the end
of the Payload: Base64(MD5(content as binary)) |
Original content:
{"hello":"json"} |
||
Hashed result:
telHj8YUFXO1IenheVsWkg== |
x-signature
After generating the Payload, you can generate a HMAC-SHA256 hash of the Payload using your Secret Key, then convert the binary into a Base64 string as the x-signature.
The following algorithm generates the x-signature:
Base64 ( HMAC-SHA256(secret_key, Payload) )
NoteYou need to generate a unique x-signature in every request, resulting in a different
signature for each request. The API server verifies the x-signature in every request.
|
Request Content
In addition to the header elements, the HTTP request body should also include any
data you need to send to the API in valid JSON format. The specification for each
API includes the required parameters for the request body content.
For example, after a successful request to invoke the Customers :: Create API, you should receive a response similar to the following:
{ company_id : "17363415-4A9F-4A01-8153-10B8F35B50B1", user : { id : "3CB3C2A5-94C5-4D57-9B97-CF4FCC47FF77", login_name : "staygreen_greenery", password : "93oap1jv0z" } }
C# Sample Code
You can refer to the following code sample when generating the
x-posix-time
.// Verify that if a PosixTime is 15 minutes before or after the server time. // serverTime: Current server time. // posixStr: A posix string of seconds. // timeRangeinMinutes: You may specify a time range in minute. Default value is 15 minutes. // returns: True if the posixStr time is within +-15 minutes range of the given server time. public static bool VerifyPosixTime(string posixStr, int timeRangeinMinutes = 15) { long posixSeconds; if (!Int64.TryParse(posixStr, out posixSeconds)) return false; var from = DateTimeToPosixTimestamp(DateTime.UtcNow.AddMinutes(-timeRangeinMinutes)); var to = DateTimeToPosixTimestamp(DateTime.UtcNow.AddMinutes(timeRangeinMinutes)); return (posixSeconds >= from) && (posixSeconds <= to); } // Methods to convert DateTime to Posix time(seconds) in Unix time stamp. // dateTime: Unix time stamp to convert. // returns: Return Unix time stamp as long type. public static long DateTimeToPosixTimestamp(DateTime dateTime) { TimeSpan unixTimeSpan = (dateTime - new DateTime(1970, 1, 1, 0, 0, 0)); return (long) unixTimeSpan.TotalSeconds; }
You can refer to the following code sample when generating the
x-signature
.// Generate a x-signature header value that's required to invoke LMPI API interface. // secret: The secret key used to hash. // unixTimestamp: Number of seconds after 1970-01-01 til now. // method: HTTP method used to invoke LMPI. // requestUri: The request URI without server host. The request URI should be encoded. // content: HTTP request content in binary. Pass in null if no content is to be sent to server. // hexstring: A hexstring of HMAC-SHA256 hashed value will be assigned to this parameter. // returns: Base64 string encoded x-signature. public static string GenerateSignature(string secret, long unixTimestamp, string method, string requestUri, byte[] content, out string hexstring) { var posix = unixTimestamp.ToString(); var payload = posix + method.ToUpper() + requestUri + ((content == null) ? "" : CalculateMD5Hash(content)); HMAC hash = new HMACSHA256(); hash.Initialize(); hash.Key = Encoding.UTF8.GetBytes(secret); var byteArr = hash.ComputeHash(Encoding.UTF8.GetBytes(payload)); hexstring = ByteArrayToHexString(byteArr); return Convert.ToBase64String(byteArr); } // Calculates MD5 Hash of a binary and return it as a BASE64 string. // input: Binary to be calculated. // returns: MD5 hashed string result in BASE64. public static string CalculateMD5Hash(byte[] input) { // step 1, calculate MD5 hash from input MD5 md5 = MD5.Create(); byte[] hash = md5.ComputeHash(input); return Convert.ToBase64String(hash); } // Converts a byte array into HexString. // ba: Byte array to be converted. // returns: HEX String. public static string ByteArrayToHexString(byte[] ba) { var sb = new StringBuilder(ba.Length*2); foreach (var b in ba) { sb.AppendFormat("{0:x2}", b); } return sb.ToString(); }