Before calling an API, if a request contains sensitive information, data encryption is required to guarantee that data is not tampered during transmission.

Sensitive information includes all the sensitive personally identifiable information, such as security code, access code, password or certificate, and biometric records.

The encryption algorithm RSA or PGP can be used for data transmission. Data encryption is required if sensitive information is enclosed in the message.

RSA_AES 

RSA_AES stands for AES symmetric encryption and RSA asymmetric encryption algorithm. RSA_AES is used in message encryption. Encrypt the message with AES symmetric encryption algorithm, and then encrypt the symmetric key with RSA asymmetric encryption algorithm. 

• Recommended AES key size: 256 bits.
• Recommended RSA key size: 2048 bits.

Encrypt a message

To guarantee that data have not been altered in transmission, digital signature and encryption mechanism can be adopted. For all messages, the digital signature is mandatory. In addition, data encryption is required if sensitive information is enclosed in the message. Sensitive information includes all the sensitive personally identifiable information, such as security code, access code, password or certificate, and biometric records.

When both digital signature and data encryption are required, encrypt the message first before adding a digital signature. The following graphic illustrates the data encryption and digital signature workflow: 

Figure 1. Message transmission workflow 

Encryption process flow

The following figure illustrates the message encryption process: 

Figure 2. Message encryption process 

Procedure to encrypt a message

Complete the following steps to encrypt a message.

Prerequisites

1. Get the public key for both request and response.
2. Prepare the content to be encrypted (CONTENT_TO_BE_ENCRYPTED).
   The content to be encrypted is the plain message of a request or response body, typically a JSON string.
3. Generate AES symmetric key (AES_KEY)
   Generate a 256-bits AES symmetrickey randomly.

Steps

1. Generate a one-time symmetric key. The symmetric key format is selected according to the symmetric algorithm. If AES algorithm is used, it is recommended to use a 256-bit length key. For a single request and response, the symmetric key can be reused.
2. Obtain the content to be encrypted. The entire HTTP body needs to be encrypted. 
3. Encrypt the message. Use the one-time symmetric key that you obtained in step 1 to encrypt the message. 
4. Obtain the public key of the message receiver. The public key is associated with Client-Id. Key rotation is supported, therefore, different key versions might exist. You can use keyVersion to specify the version number. If key version is not specified, the latest version is used by default.
5. Encrypt the symmetric key. Use the public key obtained in step 4 to encrypt the one-time symmetric key. 
6. Add algorithm, key version, and encrypted symmetric key to encrypt header, and add the encrypted message to http body. 

The following example shows a finished Encrypt header: 

key: Encrypt

value：algorithm=<encryption-algorithm>，keyVersion=<key-version>,

symmetricKey=bqS8HSmdaRrpKSuPy7CqUlyd8lJurG93

Decrypt a message

Decryption process flow

The following figure illustrates the message decryption process: 

Figure 3. Message decryption flow 

Procedure to decrypt a message

Complete the following steps to decrypt a message.

Prerequisites

1. Get the private key
   The private key is used to decrypt the symmetric key carried with the encrypted request or response. You can obtain Client-Id, keyVersion, and algorithm from the message header. Then with Client-Id and keyVersion, you can then retrieve the private key for decryption.
2. Get the content to be decrypted, which is represented by the Content_To_Be_Decrypted variable.
   The data to be decrypted is the whole HTTP body that has been encrypted, so the Content_To_Be_Decrypted is ciphertext.
3. Get the AES symmetric key to be decrypted, which is represented by the AESKey_To_Be_Decrypted  variable.The AESKey_To_Be_Decrypted is obtained from the Encrypt  header that has been encrypted. See the header format. For details about the header, see the Message instructure chapter.
   Encrypt: algorithm=RSA_AES, symmetricKey=<AESKey_To_Be_Decrypted>

Steps

1. Retrieve the private key. Obtain Client-Id, keyVersion, and algorithm from header. With Client-Id and keyVersion, you can then retrieve the private key for decryption. If key version is not specified, the latest version is used by default.
2. Retrieve the symmetric key. Obtain the encrypted symmetric key from header, and then use the private key you retrieved in step1 to decrypt to get the symmetric key. The following sample assumes that an AES symmetric key was used:

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

3. Obtain the content to be decrypted, which is represented by the Content_To_Be_Decrypted variable. The data to be decrypted is the whole HTTP body that has been encrypted, so the Content_To_Be_Decrypted is ciphertext.
4. Decrypt the message. Use the symmetric key obtained in step2 to decrypt the ciphertext. Sample code:

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

• Content_To_Be_Decrypted : the message you obtained in step 3.
• AES_KEY : the key that you obtained in step 2.

One-way encryption 

A one-way encryption, or the hash function, is used when the transmitted information is sensitive and the receiver is not expected to learn the clear text information. The recommended hashing algorithm is sha256, and the encrypted byte array must be base64 encoded before transmission. 

For example, in the blockchain remittance scenario, the user information can not be directly stored on blockchain. Instead, hash the user information first by using the sha256 algorithm and then send it to Blockchain.