Skip to main content

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.

Understand the tech

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:

Encrypt media stream

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.

Prerequisites

To follow this procedure you must have:

Project setup

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

Implement Agora media stream encryption

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();

Test your implementation

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.

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

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

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

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

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

Reference

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

Page Content

Video Calling