Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solutionDOCS


      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. 


      PGP algorithm is used in file encryption. PGP (Pretty Good Privacy) encryption uses a serial combination of hashing, data compression, symmetric-key cryptography, and finally public-key cryptography. Each step uses one of several supported algorithms. 

      #Encryption process 

      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 

      #Encrypt and decrypt a message 

      When a message contains sensitive information, the entire message needs to be encrypted for transmission. 

      Encrypt a message 

      The following figure illustrates the message encryption process: 


      Figure 2. Message encryption process 

      Complete the following steps to encrypt a message: 

      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

      Decrypt a message

      The following figure illustrates the message decryption process: 


      Figure 3. Message decryption flow 

      Complete the following steps to decrypt a message: 

      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 retrived in step1 to decrypt to get the symmetric key. 

      3. Obtain the ciphertext. The entire body part needs to be decrypted. 

      4. Decrypt the message. Use the symmetric key obtained in step2 to decrypt the ciphertext. 

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

      #Transport layer security 

      To provide privacy and data integrity for communication over network, the following requirements must be met: 

      • Hypertext Transfer Protocol Secure (HTTPS) must be used for secure communication over network 

      • Transport Layer Security (TLS) v1.2 must be used 

      • Use the one-way authentication method