Secure channel encryption

Media stream encryption ensures that only authorized users in a channel see and hear each other. Encryption prevents potential eavesdroppers from accessing sensitive and private information shared in a channel. IoT SDK provides built-in encryption methods that you can use to guarantee data confidentiality during transmission, when required.

This page shows you how to integrate media stream encryption into your app using IoT SDK.

To ensure secure communication, your app uses an SSL key and a salt to encrypt and decrypt data in the channel. You use the key and salt to create an encryption configuration. Agora SD-RTN™ uses the encryption configuration to encrypt a stream and sends it to remote users. When a remote user receives an encrypted media stream, the remote app decrypts it using the same salt and key.

The following figure shows the call flow for media stream encryption:

All users in a channel must use the same encryption configuration. You set this up when you initiate the Agora Engine and enable encryption before joining a channel. If you don’t have the correct configuration, you cannot decrypt channel content. Best practice is to have your authentication system generate a new key and salt regularly.

IoT SDK supports the following encryption modes:

• SM4-128-ECB
• AES_128_ECB
• AES_128_XTS
• AES_256_XTS
• AES-128-GCM
• AES-256-GCM
• AES-128-GCM2 (recommended)
• AES-256-GCM2 (recommended)

Compared to other encryption modes, GCM2 encryption uses a more secure key derivation function and supports salt. If you choose another encryption mode, you only need to set the encryption mode and key.

To follow this procedure you must have:

• Implemented the SDK quickstart project for IoT SDK.

• OpenSSL v3.0.0 or above.

To encrypt media streams in your app, you need to:

• Open the SDK quickstart IoT SDK project you created previously.

• Set up OpenSSL on your development device.

To implement media stream encryption, do the following:

1. Add variables to hold the encryption key and salt

   In /app/java/com.example.<projectname>/MainActivity, add the following declarations to the MainActivity class:

   
   

   _2

   private String encryptionKey = "<32-byte key generated through OpenSSL>";

   _2

   private String encryptionSaltBase64 = "<Base64-encoded, salt generated through OpenSSL>";

   
   

2. Enable encryption

   To enable encryption, you set enableAutEncryption to true in channelOptions. Add the following line after channelOptions.autoSubscribeVideo = true; in joinChannel:

   
   

   _1

   channelOptions.enableAutEncryption = true;

   
   

3. Set encryption parameters

   You specify the media stream encryption mode and the related parameters in JSON format by calling setParams. Depending on your choice of an encryption method, add one of the following pieces of code to joinChannel before agoraEngine.joinChannel(...):

   • SM4-128-ECB encryption

     
     

     _3

     // Enable SM4-128-ECB encryption

     _3

     agoraEngine.setParams("{\"rtc.encryption\": {\"enable\": true,"

     _3

     + "\"mode\":\"SM4-128-ECB\", \"master_key\": \"" + encryptionKey + "\" }}");

     
     

   • AES-128-GCM encryption

     
     

     _3

     // Enable AES-128-GCM encryption

     _3

     agoraEngine.setParams("{\"rtc.encryption\": {\"enable\": true,"

     _3

     + "\"mode\":\"AES-128-GCM\", \"master_key\": \"" + encryptionKey + "\" }}");

     
     

   • AES-128-GCM2 encryption

     
     

     _4

     // Enable AES-128-GCM2 encryption

     _4

     agoraEngine.setParams("{\"rtc.encryption\": {\"enable\": true,"

     _4

     + "\"mode\": \"AES-128-GCM2\", \"master_key\": \"" + encryptionKey

     _4

     + "\", \"salt\": \"" + encryptionSaltBase64 + "\", \"salt_type\": \"BASE64\"}}");

     
     

4. Disable encryption

   To disable encryption, use the following code:

   
   

   _2

   // Disable built-in encryption

   _2

   agoraEngine.setParams("{\"rtc.encryption\": {\"enable\": false}}");

   
   

To ensure that you have implemented Agora media stream encryption in your app:

1. Add the 32-byte key to your app:

   1. Run the following command in a terminal window:

      
      

      _1

      openssl rand -hex 32

      
      

   2. Paste the key string returned into the encryptionKey variable.

2. Add the 64-byte salt to your app:

   1. Run the following command in your terminal window:

      
      

      _1

      openssl rand -base64 32

      
      

   2. Paste the salt string returned into the encryptionSaltBase64 variable.

3. Generate a temporary token in Agora Console.

4. In Android Studio, in app/java/com.example.\<projectname>/MainActivity, update appId, channelName and token with the values for your temporary token.

5. Connect a physical Android device to your development machine.

6. In Android Studio, click Run app. You see the app running on your device.

   If this is the first time you run your app, grant microphone and camera access.

7. Copy and install the apk for your app on a second Android test device.

8. Press Join on both Android devices to join the same channel.

   You see remote videos on the two devices.

Communication between your test devices is now end-to-end encrypted. This prevents data from being read or secretly modified by anyone other than the true sender and recipient.

This section contains information that completes the information in this page, or points you to documentation that explains other aspects to this product.

• setParams
• ChannelOptions