Encrypt and decrypt a message
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 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.
- Get the public key for both request and response.
- Prepare the content to be encrypted (
The content to be encrypted is the plain message of a request or response body, typically a JSON string.
- Generate AES symmetric key (
Generate a 256-bits AES symmetrickey randomly.
- 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.
- Obtain the content to be encrypted. The entire HTTP body needs to be encrypted.
- Encrypt the message. Use the one-time symmetric key that you obtained in step 1 to encrypt the message.
- 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
keyVersionto specify the version number. If key version is not specified, the latest version is used by default.
- Encrypt the symmetric key. Use the public key obtained in step 4 to encrypt the one-time symmetric key.
- 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:
#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.
- 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.
- Get the content to be decrypted, which is represented by the
The data to be decrypted is the whole HTTP body that has been encrypted, so the
- Get the AES symmetric key to be decrypted, which is represented by the
AESKey_To_Be_Decryptedis obtained from the
Encryptheader 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>
- 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.
- 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:
- 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.
- Decrypt the message. Use the symmetric key obtained in step2 to decrypt the ciphertext. Sample code:
Content_To_Be_Decrypted: the message you obtained in step 3.
AES_KEY: the key that you obtained in step 2.
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.