Message encryption and decryption

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.

image.png

Figure 1. Message encryption activity diagram

#Procedure to encrypt a message

#1. Get the public key

  1. 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.
  2. 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 128-bits data as the AES symmetric key.

#4. Encrypt the content

Encrypt the content by using the following formula:

copy
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. For more information, see aes_encrypt.
  • base64urlsafe_encode : the method to encode the encrypted data. For more information, see base64urlsafe_encode.

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:

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

Methods that are used:

  • rsa_encrypt : the method to encrypt the AES key. For more information, see rsa_encrypt.
  • base64urlsafe_encode : the method to encode the encrypted data. For more information, see base64urlsafe_encode.

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:

copy
Encrypt: algorithm=RSA_AES, symmetricKey=<ENCYRPTED_AES_KEY>

b. Configure the Content-Type header.

Set the content type as text/plain :

copy
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.

image.png

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 Encrypt field 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:

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

Methods that are used:

  • base64urlsafe_decode : the method to decode the encrypted data. For more information, see base64urlsafe_decode.
  • rsa_decrypt : the method to decrypt the cypher text. For more information, see rsa_decrypt.

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:

copy
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. For more information, see base64urlsafe_decode
  • aes_decrypt : the method to decrypt the cypher text. For more information, see rsa_decrypt.
  • utf8_encode : the method to encode the binary data to the text string in UTF-8. For more information, see utf8_encode.

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.