The ZOLOZ gateway protocol provides the capability of message encryption to ensure the data is not tampered during message transmission. If the request sent by the merchant is encrypted, the response returned by the ZOLOZ service is also encrypted; otherwise, the response returned by the ZOLOZ service is not encrypted.

As the data that the ZOLOZ service deals with might contain sensitive information, to enhance the message transmission security, the ZOLOZ service encrypts the response message. The sensitive information includes all the sensitive personally identifiable information, such as name, ID number, birthday, address, face.

Encrypt a message

Encryption process flow

The following diagram shows how to encrypt a request message from the merchant's perspective and how to encrypt a response message from the ZOLOZ service's perspective.

Figure 1. Message encryption activity diagram

Procedure to encrypt a message

1. Get the public key

For the request message, a RSA 2048 key-pair is generated in the ZOLOZ system when the account of the merchant is created. The generated key-pair is unique for each merchant and includes a public key. The merchant needs to acquire the public key beforehand.
For the response message, a RSA 2048 key-pair must be generated on the merchant's side. The generated key-pair includes a public key, which must be registered in the ZOLOZ system before any request is sent. The ZOLOZ service then uses the registered public key for the succeeding response message encryption.

2. Prepare the content to be encrypted

The content to be encrypted is the plain message of the business request/response, typically a JSON string.

3. Generate the AES symmetric key

Randomly generate a 256-bits data as the AES symmetric key.

4. Encrypt the content

Encrypt the content by using the following formula:

ENCYRPTED_CONTENT_STRING=base64urlsafe_encode(aes_encrypt($CONTENT_TO_BE_ENCRYPTED, $AES_KEY))

Methods that are used:

aes_encrypt: the method to encrypt the message by using the AES algorithm.
base64urlsafe_encode: the method to encode the encrypted data.

Input parameters:

CONTENT_TO_BE_ENCRYPTED: the content string that is prepared in Step 2.
AES_KEY: the AES symmetric key that is generated in Step 3.

Output parameter:

ENCRYPTED_CONTENT_STRING: the string of the encrypted content.

5. Encrypt the AES key

Encrypt the AES key by using the following formula:

ENCYRPTED_AES_KEY=base64urlsafe_encode(rsa_encrypt($AES_KEY, $PUBLIC_KEY))

Methods that are used:

rsa_encrypt: the method to encrypt the AES key.
base64urlsafe_encode: the method to encode the encrypted data.

Input parameters:

AES_KEY: the AES symmetric key that is generated in Step 3.
PUBLIC_KEY: the public key that is obtained in Step 1.

Output parameter:

ENCYRPTED_AES_KEY: the string of the encrypted AES key.

6. Configure the header and body

a. Configure the Encrypt header.

Specify the encrypted AES key in the Encrypt field of the HTTP header in the following format:

Encrypt: algorithm=RSA_AES, symmetricKey=<ENCYRPTED_AES_KEY>

b. Configure the Content-Type header.

Set the content type as text/plain :

content-type: text/plain

c. Configure the HTTP body.

Set the encrypted content string (ENCYRPTED_CONTENT_STRING that is obtained from Step 4) as the HTTP body.

Decrypt a message

Decryption process flow

The following diagram shows how to decrypt a request message from the ZOLOZ service's perspective and how to decrypt a response message from the merchant's perspective.

Figure 2. Message decryption activity diagram

Procedure to decrypt a message

1. Get the private key

For the request message, a RSA 2048 key-pair is generated in the ZOLOZ system when the account of the merchant is created. The generated key-pair is unique for each merchant and includes a private key. The ZOLOZ service then uses the private key to decrypt the symmetric key that is carried with the encrypted request.
For the response message, a RSA 2048 key-pair must be generated on the merchant's side. The generated key-pair includes a private key. The merchant then uses the private key to decrypt the symmetric key that is carried with the encrypted response.

2. Get the content to be decrypted

The content to be decrypted is the whole HTTP body that has been encrypted.

3. Extract the encrypted AES symmetric key

Extract the encrypted AES symmetric key that is carried in the Encryptfield of the HTTP request/response header. Encrypt: algorithm=RSA_AES, symmetricKey=<AES_KEY_TO_BE_EXTRACTED>

4. Decrypt the AES key

Decrypt the AES key by using the following formula:

AES_KEY=rsa_decrypt(base64urlsafe_decode($ENCRYPTED_AES_KEY), $PRIVATE_KEY)

Methods that are used:

base64urlsafe_decode: the method to decode the encrypted data.
rsa_decrypt: the method to decrypt the cypher text.

Input parameters:

ENCRYPTED_AES_KEY : the encrypted AES key that is extracted in Step 3.
PRIVATE_KEY: the private key that is obtained in Step 1.

Output parameter:

AES_KEY : the initial AES key that is radomly generated to encrypt the message content.

5. Decrypt the content

Decrypt the content by using the following formular:

PLAIN_CONTENT_STRING=utf8_encode(aes_decrypt(base64urlsafe_decode($Content_To_Be_Decrypted, $AES_KEY))

Methods that are used:

base64urlsafe_decode: the method to decode the encrypted data.
aes_decrypt: the method to decrypt the cypher text.
utf8_encode: the method to encode the binary data to the text string in UTF-8.

Input parameters:

Content_To_Be_Decrypted: the content to be decrypted, which is obtained in Step 2.
AES_KEY: the AES symmetric key that is obtained in Step 4.

Output parameter：

PLAIN_CONTENT_STRING: the plain content string to be consumed, typically it's a JSON string.