Media Stream Encryption (Web SDK 4.x)

Introduction

To improve data security, developers can encrypt users' media streams during the real-time engagement. Agora provides the media stream encryption. You can call the API to choose the encryption mode and set the encryption secret and salt.

The following diagram describes the encrypted data transmission process:

Implementation

This section introduces how to use the media stream encryption function of the Web SDK.

Before proceeding, ensure that you refer to the appropriate Quickstart Guide to implement the basic real-time communication functions in your project.

Before joining the channel, call the AgoraRTCClient.setEncryptionConfig method to choose the encryption mode. Agora 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.
• "aes-128-gcm2": 128-bit AES encryption, GCM mode, with salt. Only applicable to the Web SDK v4.5.0 or later.
• "aes-256-gcm2": 256-bit AES encryption, GCM mode, with salt. Only applicable to the Web SDK v4.5.0 or later.

To enhance security, Agora recommends choosing "aes-128-gcm2" or "aes-256-gcm2" and setting the secret and salt.

To generate and set the secret and salt parameters, refer to the following steps.

Generate and set the secret

1. Refer to the following command to generate a 32-byte secret in the string format through OpenSSL on your server.

   // Generate a random secret (32 bytes) in the string format. Pass the string secret in the Agora API directly.
   openssl rand -hex 32
   dba643c8ba6b6dc738df43d9fd624293b4b12d87a60f518253bd10ba98c48453

2. The Web client gets the Hex secret from the server.

3. The Web client converts the secret from Hex to ASCII, and then passes it to the SDK in the setEncryptionConfig method.

Generate and set the salt

1. Refer to the following command to generate a Base64-encoded and 32-byte salt through OpenSSL on the server. You can also refer to the C++ sample code provided by Agora on GitHub to generate a salt in the byte array format and convert it to Base64 on the server.

   // Generate a random salt (32 bytes) in the Base64 format. Decode the Base64 salt to Uint8Array and then pass it in the Agora API.
   openssl rand -base64 32
   X5w9T+50kzxVOnkJKiY/lUk82/bES2kATOt3vBuGEDw=

2. The Web client gets the Base64 salt from the server.

3. The Web client converts the salt from Base64 to Uint8Array, and then passes it to the SDK in the setEncryptionConfig method.

Sample code

The client object in the following sample code is created by calling AgoraRTC.createClient.

// Declare a function to convert Base64 to Uint8Array.
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;
}

// Declare a function to convert Hex to ASCII.
function hex2ascii(hexx) {
    const hex = hexx.toString();//force conversion
    let str = '';
    for (let i = 0; i < hex.length; i += 2)
        str += String.fromCharCode(parseInt(hex.substr(i, 2), 16));
    return str;
}

async function getSecretAndSalt() {
  // Suppose the getSecretAndSaltFromServer method returns the secret key and salt value obtained from the server ["dba643c8ba6b6dc738df43d9fd624293b4b12d87a60f518253bd10ba98c48453", "X5w9T+50kzxVOnkJKiY/lUk82/bES2kATOt3vBuGED="]
  let [secret, salt] = await getSecretAndSaltFromServer();
  salt = base64ToUint8Array(salt);
  secret = hex2ascii(secret);
  return [secret, salt];
}

let [secret, salt] = await getSecretAndSalt();

// Set the encryption mode as aes-256-gcm2, and pass in secret and salt
client.setEncryptionConfig("aes-256-gcm2", secret, salt);

Considerations

• Enable the media stream encryption before calling AgoraRTCClient.join.
• Both the communication and interactive live streaming scenarios support encryption, but Agora does not support pushing encrypted streams to the CDN in the live streaming. However, in the live broadcast scenario, Agora does not support pushing the encrypted media stream to the CDN.
• Ensure that both the receivers and senders use the same encryption mode. Otherwise, undefined behaviors such as no voice and black screen may occur.