Views:
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.
Note
Note
The API checks this value against its own time. If the UNIX time and API time differ by more than 15 minutes, the request is denied.
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.
Note
Note
This value is a Base64 encoded string calculated based on selected headers.
1-90 characters
content-type
string
The format and encoding of the content in the API call.
Example: application/json and charset=utf-8
Note
Note
The content must be encoded using the UTF-8 character set.
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.
Note
Note
Make sure to encode query string parameter values with percentage signs (%).
/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) )
Note
Note
You 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();
}