Secure channel encryption

Media stream encryption ensures that only the authorized users in a channel can see and hear each other. This ensures that potential eavesdroppers cannot access sensitive and private information shared in a channel. While not every use case requires media stream encryption, Video Calling provides built-in encryption methods that guarantee data confidentiality during transmission.

This page shows you how to integrate built-in media stream encryption into your app using Video Calling.

To ensure secure communication, your app uses the same SSL key and 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 the remote user receives the encrypted media stream, the remote app decrypts the media stream using the same salt and key.

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

All users in a channel must use the same encryption configuration to initiate agoraEngine and enable encryption before joining a channel. If you don’t have the correct configuration, you cannot decrypt channel content. Best practice is that your authentication system generates a new key and salt regularly.

To follow this procedure you must have:

• Implemented the SDK quickstart project for Video Calling.

• OpenSSL latest version

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

• Open the SDK quickstart Video Calling project you created previously.

• Set up OpenSSL in your development device.

To implement media stream encryption, do the following:

1. Add the required imports

   In /app/java/com.example.<projectname>/MainActivity, add the following imports after the last import statement:

   
   

   _2

   import io.agora.rtc2.internal.EncryptionConfig;

   _2

   import java.util.Base64;

   
   

   Base64 requires that you set the Min SDK Version property in your project to 26 or higher.

2. Add the required variables

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

   
   

   _7

   // In a production environment, you retrieve the key and salt from

   _7

   // an authentication server. For this code example you generate them locally.

   _7

   _7

   // A 32-byte string for encryption.

   _7

   private String encryptionKey = "";

   _7

   // A 32-byte string in Base64 format for encryption.

   _7

   private String encryptionSaltBase64 = "";

   
   

3. Add the media stream encryption method

   To enable media stream encryption in your app, create an EncryptionConfig object and specify a key, salt, and encryption mode. Call enableEncryption and pass the EncryptionConfig object as a parameter.

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

   
   

   _19

   public void enableEncryption()

   _19

   {

   _19

   if(encryptionSaltBase64 == null || encryptionKey == null)

   _19

   return;

   _19

   // Convert the salt string into bytes

   _19

   byte[] encryptionSalt = Base64.getDecoder().decode(encryptionSaltBase64);

   _19

   // An object to specify encryption configuration.

   _19

   EncryptionConfig config = new EncryptionConfig();

   _19

   // Specify an encryption mode.

   _19

   config.encryptionMode = EncryptionConfig.EncryptionMode.AES_128_GCM2;

   _19

   // Set secret key and salt.

   _19

   config.encryptionKey = encryptionKey;

   _19

   System.arraycopy(encryptionSalt, 0, config.encryptionKdfSalt, 0, config.encryptionKdfSalt.length);

   _19

   // Call the method to enable media encryption.

   _19

   if(agoraEngine.enableEncryption(true, config) == 0)

   _19

   {

   _19

   Toast.makeText(getApplicationContext(), "Media encryption enabled", Toast.LENGTH_SHORT).show();

   _19

   }

   _19

   }

   
   

4. Start encryption before joining a channel

   In /app/java/com.example.<projectname>/MainActivity, add the following code at the end of SetupVideoSDKEngine:

   
   

   _1

   enableEncryption();

   
   

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 returned into the encryptionKey variable.

2. Add the 64-byte salt to your app

   1. Run the following command in a terminal window:

      
      

      _1

      openssl rand -base64 32

      
      

   2. Paste the salt returned into the encryptionSaltBase64 variable.

3. Generate a 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 the local and remote videos on the two devices.

Communication between your test devices is 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.

• enableEncryption
• EncryptionConfig