Signature v2

TIP

NOTE 1: In sign v2, the Signature algorithm is the same as v1. V2 has adopted a different message construction method for signing.

TIP

NOTE 2: it is advised to include X-LF-Signature-Type:2.0 in the header if signature v2 is used for the api.

Process

All non-empty parameters (including path, query, and body) are to be rearranged in key-value pairs, with keys in lexicographic order as the message to be signed

Data is digested by SHA1 first

Sign using RSA private key

Base64 encode the result

sign= Sign(message, algo=sha1withRSA, key=privateKey)

Construct message to be signed

1. Header

In V2, timestamp and nonce are required to be present in the request header - and they should be included in the message in String format for signing. There is another optional header X-LF-Signature-Type to indicate different Signature version but it's NOT required in signature.

Field	Location	Required	In message to be signed	Remarks
timestamp	Header	Required	Yes	UTC epoch time, in millisecond
nonce	Header	Optional	Yes	Random integer value
X-LF-Signature-Type	Header	Optional	No	Default: 1.0 for apis before 2023 March 01, 2.0 for apis after 2023 March 01

TIP

Timestamp needs to be within 10 minutes from time of request

2. URI and Path

URI is required to be in the message, including the value of path parameters. Key will be x-sign-uri.

3. Query

Query parameters are required to be included in the message, in key (parameter name) & value pair, with all values in String format regardless of its data type in the API definition.

When query parameter's value is of array type, use , (comma) to separate elements.

4. Body

When method is Post, Put, Delete or Patch, the body parameters shall be included in the message, in its original JSON format (do not change the data type of the value).

5. Message construction

Steps:

same as V1

Null and empty parameters are not required to be included in the message

All Key&value pairs are to be first sorted in alphabetic order of the key, in JSON format, then stringify the JSON.

Result should be a standard JSON string without any separators.

TIP

Nested json object needs to sorted according to keys as well.
for example,
before sorting

{
...
  "message": {
    "type":1,
    "content":"xxx"
  }
}

after sorting and stringify

{...,"message":{"content":"xxxx","type":1,...}

WARNING

Array contents do not need to be sorted

Example: GET

//Example
# Header
timestamp: 1674197059220
nonce: 1

# Assume API is: GET https://api.linksfield.net/cube/v4/sims/{sim_id}/usage
# path parameter: sim_id = 89852002021102915651
# query parameters:  begin_from , end_by , category, period_type

GET https://api.linksfield.net/cube/v4/sims/89852002021102915651/usage?begin_from=2023-01&category=data&end_by=2023-01&period_type=2

# Message for signing, after sorting and JSON Stringifying
{"begin_from":"2023-01","category_type":"data","end_by":"2023-01","nonce":"1","period_type":"2","timestamp":"1674197059220","x-sign-uri":"/cube/v4/sims/89852002021102915651/usage"}

Example: POST

# Header
timestamp: 1674197059220
nonce: 1

# Assume API is:  POST https://api.io.linksfield.net/cube/v4/sims/{sim_id}/bundle
POST https://api.linksfield.net/cube/v4/sims/89000100010003125832/bundle
{
    "bundle_id": "LP09823222320",
    "bundle_type": 10,
    "cycles": 3
}

# Message for signing
{"bundle_id":"LP09823222320","bundle_type":10,"cycles":3,"nonce":"1","timestamp":"1674197059220","x-sign-uri":"/cube/v4/sims/89000100010003125832/bundle"}

Process#

Construct message to be signed#

1. Header#

2. URI and Path#

3. Query#

4. Body#

5. Message construction#

Steps:#

Example: GET#

Example: POST#

Process

Construct message to be signed

1. Header

2. URI and Path

3. Query

4. Body

5. Message construction

Steps:

Example: GET

Example: POST