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:
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.
"aes-128-gcm2"
and "aes-256-gcm2"
, you only need to set the secret.To generate and set the secret
and salt
parameters, refer to the following steps.
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
The Web client gets the Hex secret from the server.
The Web client converts the secret from Hex to ASCII, and then passes it to the SDK in the setEncryptionConfig
method.
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=
The Web client gets the Base64 salt from the server.
The Web client converts the salt from Base64 to Uint8Array, and then passes it to the SDK in the setEncryptionConfig
method.
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);
AgoraRTCClient.join
.