Skip to main content

You are viewing Agora Docs forBetaproducts and features. Switch to Docs

  • Core Products
  • Add-Ons
  • Extensions Marketplace
Android
Linux C

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.

Understand the tech​

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:

Encrypt media stream

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.

Prerequisites​

To follow this procedure you must have:

Project setup​

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

  • Set up OpenSSL on your development device.

Implement Agora media stream encryption​

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}}");

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

  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.

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

Reference​

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

vundefined