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.
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. For more information, see aes_encrypt.base64urlsafe_encode: the method to encode the encrypted data. For more information, see base64urlsafe_encode.
Input parameters:
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. For more information, see rsa_encrypt.base64urlsafe_encode: the method to encode the encrypted data. For more information, see base64urlsafe_encode.
Input parameters:
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/plainc. 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 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:
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：
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. For more information, see base64urlsafe_decodeaes_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：
Output parameter：
PLAIN_CONTENT_STRING: the plain content string to be consumed, typically it's a JSON string.