Secure channel encryption

Add variables to hold the encryption key and salt

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

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

Enable encryption

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

channelOptions.enableAutEncryption = true;

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

  // Enable SM4-128-ECB encryption
  agoraEngine.setParams("{\"rtc.encryption\": {\"enable\": true,"
          + "\"mode\":\"SM4-128-ECB\", \"master_key\": \"" + encryptionKey + "\" }}");

• AES-128-GCM encryption

  // Enable AES-128-GCM encryption
  agoraEngine.setParams("{\"rtc.encryption\": {\"enable\": true,"
          + "\"mode\":\"AES-128-GCM\", \"master_key\": \"" + encryptionKey + "\" }}");

• AES-128-GCM2 encryption

  // Enable AES-128-GCM2 encryption
  agoraEngine.setParams("{\"rtc.encryption\": {\"enable\": true,"
          + "\"mode\": \"AES-128-GCM2\", \"master_key\": \"" + encryptionKey
          + "\", \"salt\": \"" + encryptionSaltBase64 + "\", \"salt_type\": \"BASE64\"}}");

Disable encryption

To disable encryption, use the following code:

// Disable built-in encryption
agoraEngine.setParams("{\"rtc.encryption\": {\"enable\": false}}");

Add the 32-byte key to your app:

1. Run the following command in a terminal window:

   openssl rand -hex 32

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

Add the 64-byte salt to your app:

1. Run the following command in your terminal window:

   openssl rand -base64 32

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

Generate a temporary token in Agora Console.

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

Connect a physical Android device to your development machine.

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.

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

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

You see remote videos on the two devices.

Add variables to hold the encryption mode, encryption key, and salt

Open <project-root>/agora_rtsa_sdk/example/hello_rtsa/hello_rtsa.c in your development environment and add the following declarations to main() after char params[512];:

char * encryptionMode; // depends on your choice of an encryption method
const char * encryptionKey = "<32-byte key generated through OpenSSL>";
const char * encryptionSaltBase64 = "<Base64-encoded, salt generated through OpenSSL>";

Enable encryption

Set enable_aut_encryption to true in the channel options. Add the following line in main() after channel_options.auto_subscribe_video = true:

channel_options.enable_aut_encryption = true;

Set encryption parameters

You specify the media stream encryption mode and the related parameters in JSON format by calling agora_rtc_set_params. Depending on your choice of an encryption mode, add one of the following pieces of code before agora_rtc_join_channel function in main():

• SM4-128-ECB encryption

  // set the encryption mode
  encryptionMode = "SM4-128-ECB";
  
  // set encryption parameters
  memset(params, '\0', sizeof(params));
  snprintf(params, sizeof(params), "{\"rtc.encryption\": {\"enable\": true,\"mode\": \"%s\", \"master_key\": \"%s\" }}", encryptionMode, encryptionKey);
  rval = agora_rtc_set_params(params);
  if (rval != 0) {
      LOGE("set encryption key failed, reason: %s", agora_rtc_err_2_str(rval));
      return -1;
  }

• AES-128-GCM encryption

  // set the encryption mode
  encryptionMode = "AES-128-GCM";
  
  // set encryption parameters
  memset(params, '\0', sizeof(params));
  snprintf(params, sizeof(params), "{\"rtc.encryption\": {\"enable\": true,\"mode\": \"%s\", \"master_key\": \"%s\" }}", encryptionMode, encryptionKey);
  rval = agora_rtc_set_params(params);
  if (rval != 0) {
      LOGE("set encryption key failed, reason: %s", agora_rtc_err_2_str(rval));
      return -1;
  }

• AES-128-GCM2 encryption

  // set the encryption mode
  encryptionMode = "AES-128-GCM2";
  
  // set encryption parameters
  memset(params, '\0', sizeof(params));
  snprintf(params, sizeof(params), "{\"rtc.encryption\": {\"enable\": true,\"mode\": \"%s\", \"master_key\": \"%s\", \"salt_type\": \"BASE64\"}}" }}", encryptionMode, encryptionKey, encryptionSaltBase64);
  rval = agora_rtc_set_params(params);
  if (rval != 0) {
      LOGE("set encryption key failed, reason: %s", agora_rtc_err_2_str(rval));
      return -1;
  }

Disable encryption

To disable encryption, use the following code:

// Disable built-in encryption
agora_rtc_set_params("{\"rtc.encryption\": {\"enable\": false}}");

Add the 32-byte key to your app:

1. Run the following command in a terminal window:

   openssl rand -hex 32

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

Add the 64-byte salt to your app:

1. Run the following command in your terminal window:

   openssl rand -base64 32

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

Generate a temporary token in Agora Console.

Compile the sample project by executing the following commands in a terminal window:

cd <project-root>/agora_rtsa_sdk/example

./build-x86_64.sh

Run the sample app by executing the following commands:

cd out/x86_64

./hello_rtsa --app-id <your-app-id> --channel-id <your-channel-name> --token <authentication-token>

Make sure you insert your app ID, channel ID, and token from Agora Console in to the command.

On launch, the app joins a channel and shows output similar to the following:

[INF] Welcome to RTSA SDK v1.9.0
[INF] File parser found: h264
[INF] File parser found: pcm
[INF] [conn-1] Join the channel demo successfully, uid 2645490531 elapsed 602 ms
[INF] [conn-1] Bandwidth change detected. Please adjust encoder bitrate to 499 kbps

Test with an unauthorized user

In your browser, navigate to the Agora web demo and update App ID, Channel, and Token with the values for your temporary token, then click Join. You see the local user video in your browser.

In the terminal, your compiled app shows a decryption error as the web demo does not have the SSL key and salt for stream encryption and decryption.

[INF] [conn-1] Remote user "3674330576" has joined the channel, elapsed 6784 ms
[WRN] Error 120 is captured. Error msg "audio:decrypt error"
[WRN] Error 120 is captured. Error msg "video:not set"

Test with an authorized user

Open two Linux terminals. Navigate to <project-root>/agora_rtsa_sdk/example/out/x86_64 and execute the following command to launch the app from both terminals.

./hello_rtsa --app-id <your-app-id> --channel-id <your-channel-name> --token <authentication-token>

You see that both clients join the same channel and successfully exchange data as they are using the same SSL key and salt.

Terminal output for User 1:

[DBG] [conn-1] on_audio_data, uid 3534962825 sent_ts 28149 data_type 100, len 640
[DBG] [conn-1] on_video_data: uid 3534962825 sent_ts 28150 data_type 2 frame_type 4 stream_type 0 len 618
[DBG] [conn-1] on_audio_data, uid 3534962825 sent_ts 28169 data_type 100, len 640

Terminal output for User 2:

[DBG] [conn-1] on_video_data: uid 2689257578 sent_ts 1494 data_type 2 frame_type 4 stream_type 0 len 160
[DBG] [conn-1] on_video_data: uid 2689257578 sent_ts 1534 data_type 2 frame_type 4 stream_type 0 len 189
[DBG] [conn-1] on_audio_data, uid 2689257578 sent_ts 1541 data_type 100, len 640