Media Stream Encryption (Web SDK 3.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 setEncryptionMode 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 v3.6.0 or later.
• "aes-256-gcm2": 256-bit AES encryption, GCM mode, with salt. Only applicable to the Web SDK v3.6.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 secret in string format 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 by calling the setEncryptionSecret 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 format 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-encoded salt from the server.

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

Sample code

// 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 the salt
client.setEncryptionMode("aes-256-gcm2", salt);

// Pass in the secret
client.setEncryptionSecret(secret);