Secure channel encryption

Media stream encryption encrypts audio and video streams with a unique key and salt controlled by your app server. Encryption ensures that only authorized users in a channel can see and hear each other. RTC SDK provides built-in encryption methods that you can use to guarantee data confidentiality during transmission.

This article describes how to integrate Agora built-in media stream encryption into your app.

Understand the tech

The following figure illustrates data transfer with media stream encryption enabled.

Data transfer process

Prerequisites

Ensure that you have implemented the SDK quickstart in your project.

Implement media stream encryption

To add built-in media stream encryption to your app, refer to the following steps.

Generate a key and salt on your server.

To generate a random 32-byte hexadecimal key on your server as a string, run:
```
openssl rand -hex 32
```
To generate a random Base64-encoded, 32-byte salt on your server, run:
```
openssl rand -base64 32
```
Implement client-side logic.

All users in a channel must use the same encryption mode, key, and salt. Discrepancies may lead to unexpected behavior, such as black screens or audio loss.

To ensure security, use a new key and salt each time you enable media stream encryption.

Obtain the string key and Base64-encoded salt from your server, convert the salt from Base64 to uint8_t, and call enableEncryption before joining a channel. Set the encryption mode to AES_128_GCM2 or AES_256_GCM2 and pass the key and salt to the SDK.

// Noise-free sample values must come from your server.
String encryptionKey = getEncryptionKeyFromServer();
byte[] encryptionKdfSalt = getEncryptionSaltFromServer();

EncryptionConfig config = new EncryptionConfig();
config.encryptionMode = EncryptionConfig.EncryptionMode.AES_128_GCM2;
config.encryptionKey = encryptionKey;
config.encryptionKdfSalt = encryptionKdfSalt;

int result = rtcEngine.enableEncryption(true, config);

// Noise-free sample values must come from your server.
val encryptionKey = getEncryptionKeyFromServer()
val encryptionKdfSalt = getEncryptionSaltFromServer()

val config = EncryptionConfig().apply {
  encryptionMode = EncryptionConfig.EncryptionMode.AES_128_GCM2
  this.encryptionKey = encryptionKey
  this.encryptionKdfSalt = encryptionKdfSalt
}

val result = rtcEngine.enableEncryption(true, config)

Reference

Sample project

ChannelEncryption

API reference

To add built-in media stream encryption to your app, refer to the following steps.

Generate a key and salt on your server.

To generate a random 32-byte hexadecimal key on your server as a string, run:
```
openssl rand -hex 32
```
To generate a random Base64-encoded, 32-byte salt on your server, run:
```
openssl rand -base64 32
```
Implement client-side logic.

All users in a channel must use the same encryption mode, key, and salt. Discrepancies may lead to unexpected behavior, such as black screens or audio loss.

To ensure security, use a new key and salt each time you enable media stream encryption.

Manually add the encryption library to your project or integrate it with CocoaPods, then call enableEncryption before joining a channel. Set the encryption mode to AgoraEncryptionModeAES128GCM2 or AgoraEncryptionModeAES256GCM2 and pass the key and salt to the SDK.

import AgoraRtcCryptoLoader

func getEncryptionSaltFromServer() -> Data {
  let base64Salt = "EncryptionKdfSaltInBase64Strings"
  return Data(base64Encoded: base64Salt)!
}

let config = AgoraEncryptionConfig()
config.encryptionMode = .AES128GCM2
config.encryptionKdfSalt = getEncryptionSaltFromServer()
config.encryptionKey = getEncryptionKeyFromServer()

let result = agoraKit.enableEncryption(true, encryptionConfig: config)
if result != 0 {
  print("enableEncryption failed: \(result)")
}

Reference

Sample project

API reference

To add built-in media stream encryption to your app, refer to the following steps.

Generate a key and salt on your server.

To generate a random 32-byte hexadecimal key on your server as a string, run:
```
openssl rand -hex 32
```
To generate a random Base64-encoded, 32-byte salt on your server, run:
```
openssl rand -base64 32
```
Implement client-side logic.

All users in a channel must use the same encryption mode, key, and salt. Discrepancies may lead to unexpected behavior, such as black screens or audio loss.

To ensure security, use a new key and salt each time you enable media stream encryption.

import AgoraRtcCryptoLoader

func getEncryptionSaltFromServer() -> Data {
  let base64Salt = "EncryptionKdfSaltInBase64Strings"
  return Data(base64Encoded: base64Salt)!
}

let config = AgoraEncryptionConfig()
config.encryptionMode = .AES128GCM2
config.encryptionKdfSalt = getEncryptionSaltFromServer()
config.encryptionKey = getEncryptionKeyFromServer()

let result = agoraKit.enableEncryption(true, encryptionConfig: config)
if result != 0 {
  print("enableEncryption failed: \(result)")
}

Reference

Sample project

API reference

RTC SDK for Web supports the following encryption modes:

"aes-128-xts": 128-bit AES encryption, XTS mode.
"aes-256-xts": 256-bit AES encryption, XTS mode.
"aes-128-gcm": 128-bit AES encryption, GCM mode.
"aes-256-gcm": 256-bit AES encryption, GCM mode.
"aes-128-ecb": 128-bit AES encryption, ECB mode.
"sm4-128-ecb": 128-bit SM4 encryption, ECB mode.

Available only in Web SDK v4.5.0 and higher:

"aes-128-gcm2": 128-bit AES encryption, GCM mode, salted.
"aes-256-gcm2": 256-bit AES encryption, GCM mode, salted.

For maximum security, set the encryption mode to "aes-128-gcm2" or "aes-256-gcm2" and specify an encryption key and salt. If you choose another encryption mode, you only need to specify the encryption key.

Generate a key and salt on your server.

openssl rand -hex 32

openssl rand -base64 32

Before joining a channel, call AgoraRTCClient.setEncryptionConfig to select the encryption mode and specify the encryption key and salt.

function base64ToUint8Array(base64Str: string): Uint8Array {
  const raw = window.atob(base64Str);
  const result = new Uint8Array(new ArrayBuffer(raw.length));

  for (let i = 0; i < raw.length; i += 1) {
    result[i] = raw.charCodeAt(i);
  }

  return result;
}

function hexToAscii(hexValue: string) {
  let result = '';
  for (let i = 0; i < hexValue.length; i += 2) {
    result += String.fromCharCode(parseInt(hexValue.slice(i, i + 2), 16));
  }
  return result;
}

const [secretFromServer, saltFromServer] = await getSecretAndSaltFromServer();
const secret = hexToAscii(secretFromServer);
const salt = base64ToUint8Array(saltFromServer);

client.setEncryptionConfig('aes-256-gcm2', secret, salt);

All users in a channel must use the same encryption mode, key, and salt. Discrepancies may lead to unexpected behavior, such as black screens or audio loss.

To ensure security, use a new key and salt each time you enable media stream encryption.

Reference

Development considerations

The media stream encryption feature is supported in both communication and live broadcasting use cases. However, Agora does not support pushing encrypted media streams to CDN.

API reference

To add built-in media stream encryption to your app, refer to the following steps.

Generate a key and salt on your server.

To generate a random 32-byte hexadecimal key on your server as a string, run:
```
openssl rand -hex 32
```
To generate a random Base64-encoded, 32-byte salt on your server, run:
```
openssl rand -base64 32
```
Implement client-side logic.

All users in a channel must use the same encryption mode, key, and salt. Discrepancies may lead to unexpected behavior, such as black screens or audio loss.

To ensure security, use a new key and salt each time you enable media stream encryption.

int enableEncryption() {
  std::string secret = getEncryptionKeyFromServer();
  std::vector<uint8_t> kdfSalt = getEncryptionSaltFromServer();

  agora::rtc::EncryptionConfig config;
  config.encryptionMode = AES_128_GCM2;
  config.encryptionKey = secret.c_str();
  memcpy(config.encryptionKdfSalt, kdfSalt.data(), sizeof(config.encryptionKdfSalt));

  return rtcEngine->enableEncryption(true, config);
}

Reference

Sample project

AgoraMediaEncryption

API reference

To add built-in media stream encryption to your app, refer to the following steps.

Generate a key and salt on your server.

To generate a random 32-byte hexadecimal key on your server as a string, run:
```
openssl rand -hex 32
```
To generate a random Base64-encoded, 32-byte salt on your server, run:
```
openssl rand -base64 32
```
Implement client-side logic.

All users in a channel must use the same encryption mode, key, and salt. Discrepancies may lead to unexpected behavior, such as black screens or audio loss.

To ensure security, use a new key and salt each time you enable media stream encryption.

Obtain the string key and Base64-encoded salt from your server, convert the salt to a 32-byte array, and call enableEncryption before joining a channel. Set the encryption mode to Aes128Gcm2 or Aes256Gcm2 and pass the key and salt to the SDK.

const encryptionMode = EncryptionMode.Aes128Gcm2;
const encryptionKey = await getEncryptionKeyFromServer();
const encryptionKdfSalt = await getEncryptionSaltBytesFromServer();

if (!encryptionKey) {
  throw new Error('encryptionKey is invalid');
}

rtcEngine.enableEncryption(true, {
  encryptionMode,
  encryptionKey,
  encryptionKdfSalt,
});

Reference

Sample projects

API reference

To add built-in media stream encryption to your app, refer to the following steps.

Generate a key and salt on your server.

To generate a random 32-byte hexadecimal key on your server as a string, run:
```
openssl rand -hex 32
```
To generate a random Base64-encoded, 32-byte salt on your server, run:
```
openssl rand -base64 32
```
Implement client-side logic.

All users in a channel must use the same encryption mode, key, and salt. Discrepancies may lead to unexpected behavior, such as black screens or audio loss.

To ensure security, use a new key and salt each time you enable media stream encryption.

Obtain the string key and Base64-encoded salt from your server, convert the salt from Base64 to Uint8List, and call enableEncryption before joining a channel. Set the encryption mode to aes128Gcm2 or aes256Gcm2 and pass the key and salt to the SDK.

import 'dart:convert';
import 'dart:typed_data';
import 'package:agora_rtc_engine/agora_rtc_engine.dart';

Future<void> enableEncryption(RtcEngine rtcEngine) async {
  final String encryptionKdfSaltBase64 =
      await Server.getEncryptionKdfSaltBase64();
  final String encryptionSecret = await Server.getEncryptionSecret();
  final Uint8List encryptionKdfSalt = base64Decode(encryptionKdfSaltBase64);

  final config = EncryptionConfig(
    encryptionMode: EncryptionMode.aes128Gcm2,
    encryptionKey: encryptionSecret,
    encryptionKdfSalt: encryptionKdfSalt,
  );

  await rtcEngine.enableEncryption(enabled: true, config: config);
}

Reference

API reference

To add built-in media stream encryption to your app, refer to the following steps.

Generate a key and salt on your server.

To generate a random 32-byte hexadecimal key on your server as a string, run:
```
openssl rand -hex 32
```
To generate a random Base64-encoded, 32-byte salt on your server, run:
```
openssl rand -base64 32
```
Implement client-side logic.

All users in a channel must use the same encryption mode, key, and salt. Discrepancies may lead to unexpected behavior, such as black screens or audio loss.

To ensure security, use a new key and salt each time you enable media stream encryption.

const encryptionMode = EncryptionMode.Aes128Gcm2;
const encryptionKey = await getEncryptionKeyFromServer();
const encryptionKdfSalt = await getEncryptionSaltBytesFromServer();

if (!encryptionKey) {
  throw new Error('encryptionKey is invalid');
}

rtcEngine.enableEncryption(true, {
  encryptionMode,
  encryptionKey,
  encryptionKdfSalt,
});

Reference

Sample projects

API reference

To add built-in media stream encryption to your app, refer to the following steps.

Generate a key and salt on your server.

To generate a random 32-byte hexadecimal key on your server as a string, run:
```
openssl rand -hex 32
```
To generate a random Base64-encoded, 32-byte salt on your server, run:
```
openssl rand -base64 32
```
Implement client-side logic.

All users in a channel must use the same encryption mode, key, and salt. Discrepancies may lead to unexpected behavior, such as black screens or audio loss.

To ensure security, use a new key and salt each time you enable media stream encryption.

Obtain the string key and 32-byte salt from your server, and call EnableEncryption before joining a channel. Set the encryption mode to AES_128_GCM2 or AES_256_GCM2 and pass the key and salt to the SDK.

string secret = GetEncryptionKeyFromServer();
byte[] kdfSalt = GetEncryptionSaltFromServer();

var config = new EncryptionConfig
{
  encryptionMode = ENCRYPTION_MODE.AES_128_GCM2,
  encryptionKey = secret,
  encryptionKdfSalt = kdfSalt
};

var result = RtcEngine.EnableEncryption(true, config);
Debug.Log("EnableEncryption: " + result);

Reference

Sample project

EncryptionSample

Secure channel encryption

Understand the tech

Prerequisites

Implement media stream encryption

Reference

Sample project

API reference

Reference

Sample project

API reference

Reference

Sample project

API reference

Reference

Development considerations

API reference

Reference

Sample project

API reference

Reference

Sample projects

API reference

Reference

API reference

Reference

Sample projects

API reference

Reference

Sample project

API reference

Contact Us

Contact Us