To prevent the man-in-the-middle attack, both the request and response message must be signed by the sender and the signature must be validated by the recipient.

Message Signing and Signature Verification Method: Use the Secret-Key corresponding to the Access-Key in the request header to sign and verify the signature.

Sign a message

ZOLOZ services require the validation of the signature for each request message. Therefore, merchants must correctly sign the request message when sending requests.

Constructing the content to be signed

The content to be signed is a string composed of multiple elements. Below is the format for constructing the string of content to be signed by the merchant:

<Request Method> <Request URI>
<Client ID>.<Request Time>.<Request Body>

Thus construct the content string to be signed by sequentially concatenating the following strings:

1. The request method
2. A white space character (" ")
3. The requested URI
4. A new-line character ("\n")
5. The client ID
6. A dot character (".")
7. The request time that is set in the Request-Time header field.
8. A dot character (".")
9. The request body

The following example shows a content string to be signed by the merchant:

POST /api/v1/zoloz/authentication/test
2089012345678900.2020-01-01T08:00:00+0800.{
  "title": "hello",
  "description": "just for demonstration."
}

Calculate the signature

1. Decode the Base64 key
   Use a standard Base64 decoding function that supports URL-safe character sets (i.e., replace + with - and / with _) to convert the secretKey from Base64 encoding into raw byte data.
   Note: Some languages' default Base64 decoders may not support URL-safe characters, in which case manual replacement or the use of a specialized library may be required.
2. Initialize HMAC-SHA256

1. Create an HMAC-SHA256 instance.
2. Pass the decoded byte array as the key to initialize the HMAC-SHA256 algorithm.

Note: The key should be in byte stream format (byte[]), not a string.

3. Calculate the Signature

1. Convert the string to be signed into a byte array using UTF-8 encoding.
2. Use the HMAC-SHA256 algorithm to compute the signature on the byte array to generate the signature result.

4. Encode the Signature Result
   Use the Base64 encoding function to encode the signature result, converting it into a URL-safe Base64 string. Ensure the output conforms to URL-safe format:

• Replace + in Base64 characters with -, and / with _.
• Remove the trailing padding character =.

The following is the pseudocode for calculating the signature:

// Step 1: Decode the key
keyBytes = base64UrlDecode(secretKey)

// Step 2: Initialize HMAC-SHA256
hmac = HMAC_SHA256(keyBytes)

// Step 3: Calculate the Signature
signatureBytes = hmac.sign(data.encode("UTF-8"))

// Step 4: Encode the Signature Result
signature = base64UrlEncode(signatureBytes).rstrip('=')

• HMAC-SHA256 is a widely used cryptographic hash algorithm that follows the RFC 2104 standard.
• Base64 URL encoding should adhere to the RFC 4648 standard.

Verify the signature

Construct content to be verified

The content to be verified is a string composed of multiple elements. Below is the format for constructing the merchant's content string to be verified:

<Request Method> <Request URI>
<Client ID>.<Response Time>.<Response Body>

Thus construct the content string to be verified by sequentially concatenating the following strings:

1. The request method
2. A white space character (" ")
3. The requested URI
4. A new-line character ("\n")
5. The client ID
6. A dot character (".")
7. The response time that is set in the Response-Time header field
8. A dot character (".")
9. The response body

The following example shows a content string to be verified:

POST /api/v1/zoloz/authentication/test
2089012345678900.2020-01-01T08:00:01+0800.{
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "{\"title\":\"hello\",\"description\":\"just for demonstration.\"}",
    "resultStatus": "S"
 }
}

Verify signature

Check if the extracted signature matches the content string to be verified.

1. Generate the string to be signed from the returned content, and create the signature using the Secret-Key and HMAC-SHA256 algorithm.
2. Compare the generated signature with the signature returned in the Header to verify consistency.