媒体流加密 | 声网文档中心

媒体流加密是指通过由 App 开发者控制的唯一的密钥和盐为 App 中的音视频流加密。声网提供媒体流加密功能以确保传输过程中数据的保密性，建议你根据实际的业务场景合理应用。

本文介绍如何在你的 App 中添加声网内置媒体流加密。

技术原理

下图描述了启用媒体流加密后的数据传输流程。声网推荐使用 AES_128_GCM2 或 AES_256_GCM2 加密模式，并设置密钥和盐。

前提条件

在进行操作之前，请确保你已经在项目中实现了基本的实时音视频功能。详见实现音视频互动。

实现方法

参考如下步骤，为你的 App 添加内置媒体流加密功能：

在你的服务端生成一个密钥和盐。
- 在你的服务端，参考以下命令，通过 OpenSSL 随机生成一个 16 字节的随机值，并以 16 进制 (hex) 字符串形式输出，作为密钥使用：
  Shell
```
# 随机生成一个密钥
openssl rand -hex 16
# 示例输出
9f3c7a1e5b8d4c2a6e0f91b7d4a2c8e5
```
- 在你的服务端，参考以下命令，通过 OpenSSL 随机生成 Base64 编码、32 字节的盐：
  Shell
```
# 随机生成一个 Base64 编码、32 字节的盐
openssl rand -base64 32
# 示例输出
X5w9T+50kzxVOnkJKiY/lUk82/bES2kATOt3vBuGEDw=
```
实现客户端逻辑：
1. 从服务端获取 String 型的密钥和 Base64 编码的盐。
2. 将盐从 Base64 转换成 uint8_t。
3. 加入频道前，调用 enableEncryption 设置 AES_128_GCM2 或 AES_256_GCM2 加密模式，并将密钥和盐传入 SDK。

注意

同一频道内所有用户必须使用相同的加密模式、密钥和盐。否则，可能会出现黑屏或音频丢失等未定义行为。
为确保安全性，声网建议在每次启用媒体流加密前使用新的密钥和盐。

以下示例代码展示了该逻辑的实现过程：

Java

import java.util.Base64;
import io.agora.rtc2.RtcEngine;
import io.agora.rtc2.internal.EncryptionConfig;

class Example
{
    public bool enableEncryption(RtcEngine engine) {
        if(engine == null)
            return false;
        // 从服务端获取 Base64 编码的盐
        String encryptionKdfSaltBase64 = Server.getEncryptionKdfSaltBase64();
        // 从服务端获取 String 型的密钥
        String encryptionSecret = Server.getEncryptionSecret();
        if(encryptionKdfSaltBase64 == null || encryptionSecret == null)
            return false;

        // 将 Base64 编码的盐转换成 uint8_t
        byte[] encryptionKdfSalt = Base64.getDecoder().decode(encryptionKdfSaltBase64);
        // 创建一个 EncryptionConfig 实例
        EncryptionConfig config = new EncryptionConfig();
        // 将加密模式设置为 AES_128_GCM2
        config.encryptionMode = EncryptionConfig.EncryptionMode.AES_128_GCM2;
        config.encryptionKey = encryptionSecret;
        System.arraycopy(encryptionKdfSalt, 0, config.encryptionKdfSalt, 0, config.encryptionKdfSalt.length);
        int result = engine.enableEncryption(true, config);
        return (result == 0);
    }
}

参考信息

示例项目

声网提供了开源的媒体流加密示例项目供你参考，你可以前往下载或查看其中的源代码。

ChannelEncryption（Gitee）

ChannelEncryption（GitHub）

注意事项

如需与 Web 平台的音视频 SDK 互通，你还需要将本文提到的 String 型密钥从 Hex 编码格式转换成 ASCII 编码格式。

本文介绍如何在你的 App 中添加声网内置媒体流加密。

技术原理

下图描述了启用媒体流加密后的数据传输流程。声网推荐使用 AgoraEncryptionModeAES128GCM2 或 AgoraEncryptionModeAES256GCM2 加密模式，并设置密钥和盐。

前提条件

在进行操作之前，请确保你已经在项目中实现了基本的实时音视频功能。详见实现音视频互动。

实现方法

参考如下步骤，为你的 App 添加内置媒体流加密功能：

在你的服务端生成一个密钥和盐。
- 在你的服务端，参考以下命令，通过 OpenSSL 随机生成一个 16 字节的随机值，并以 16 进制 (hex) 字符串形式输出，作为密钥使用：
  Shell
```
# 随机生成一个密钥
openssl rand -hex 16
# 示例输出
9f3c7a1e5b8d4c2a6e0f91b7d4a2c8e5
```
- 在你的服务端，参考以下命令，通过 OpenSSL 随机生成 Base64 编码、32 字节的盐：
  Shell
```
# 随机生成一个 Base64 编码、32 字节的盐
openssl rand -base64 32
# 示例输出
X5w9T+50kzxVOnkJKiY/lUk82/bES2kATOt3vBuGEDw=
```
实现客户端逻辑：
1. 根据以下步骤，手动为你的项目添加加密库：
  1. 将 SDK 包中的 AgoraRtcCryptoLoader.framework 复制到你的项目文件夹中。
  2. 打开 Xcode（此处以 Xcode 11.0 为例），进入 TARGETS > Project Name > General > Frameworks, Libraries, and Embedded Content 菜单。
  3. 点击 + 和 Add Other...，添加 AgoraRtcCryptoLoader.framework。
  4. 为确保动态库的签名和 App 的签名一致，将动态库的 Embed 属性设置为 Embed & Sign。
  注意
  根据 Apple 的要求，App 的 Extension 不包含动态库。如果要将 SDK 集成到 Extension 里的动态库中，需要将文件状态改为 Do Not Embed。
  
  信息
  更多集成方式，详见其他集成方式。
2. 在 ViewController.swift 文件中添加以下代码，导入 AgoraRtcCryptoLoader 库：
  Swift
```
import AgoraRtcCryptoLoader
```
3. 从服务端获取 String 型的密钥和 Base64 编码的盐。
4. 将盐从 Base64 转换成 uint8_t。
5. 加入频道前，调用 enableEncryption，设置 AgoraEncryptionModeAES128GCM2 或 AgoraEncryptionModeAES256GCM2 加密模式，并将密钥和盐传入 SDK。
注意
- 同一频道内所有用户必须使用相同的加密模式、密钥和盐。否则，可能会出现黑屏或音频丢失等未定义行为。
- 为确保安全性，声网建议在每次启用媒体流加密前使用新的密钥和盐。
以下示例代码展示了该逻辑的实现过程：
Swift
```
func getEncryptionSaltFromServer() -> Data {
   // 将 Base64 编码的盐转换成 uint8_t
   return "EncryptionKdfSaltInBase64Strings".data(using: .utf8)!
}

// 创建一个 AgoraEncryptionConfig 实例
let config = AgoraEncryptionConfig()
// 将加密模式设置为 AgoraEncryptionModeAES128GCM2
config.encryptionMode = .AES128GCM2
// 从服务端获取 Base64 编码的盐
config.encryptionKdfSalt = getEncryptionKdfSaltBase64FromServer()
// 从服务端获取 String 型的密钥
config.encryptionKey = getEncryptionKeyFromServer()
let ret = agoraKit.enableEncryption(true, encryptionConfig: config)
if ret != 0 {
   self.showAlert(title: "Error", message: "enableEncryption call failed: \(ret), please check your params")
}
```

参考信息

示例项目

声网提供了开源的媒体流加密示例项目供你参考，你可以前往下载或查看其中的源代码。

StreamEncryption（Gitee）

StreamEncryption（GitHub）

通过 CocoaPods 集成加密库

根据以下步骤，通过 CocoaPods 集成加密库：

安装 CocoaPods。安装指南请参考 Getting Started with CocoaPods。
在终端，打开项目路径，运行 pod init 命令，在项目文件夹中创建 Podfile。
打开 Podfile，删除所有内容后，输入以下内容。注意将 Your App 替换为你的 Target 名称，并将 version 替换成你需要集成的 SDK 版本。
Ruby
```
# platform :ios, '9.0'
target 'Your App' do
  pod 'AgoraRtcEngine_iOS_Crypto', '~> version
end
```
回到终端，运行 pod install 命令，安装声网 SDK。SDK 安装成功后，终端会显示 Pod installation complete!，你可以在项目文件夹中看到 xcworkspace 文件。
打开 Xcode 中生成的 xcworkspace 文件。

注意事项

如需与 Web 平台的音视频 SDK 互通，你还需要将本文提到的 String 型密钥从 Hex 编码格式转换成 ASCII 编码格式。

本文介绍如何在你的 App 中添加声网内置媒体流加密。

技术原理

下图描述了启用媒体流加密后的数据传输流程。声网推荐使用 AgoraEncryptionModeAES128GCM2 或 AgoraEncryptionModeAES256GCM2 加密模式，并设置密钥和盐。

前提条件

在进行操作之前，请确保你已经在项目中实现了基本的实时音视频功能。详见实现音视频互动。

实现方法

参考如下步骤，为你的 App 添加内置媒体流加密功能：

在你的服务端生成一个密钥和盐。
- 在你的服务端，参考以下命令，通过 OpenSSL 随机生成一个 16 字节的随机值，并以 16 进制 (hex) 字符串形式输出，作为密钥使用：
  Shell
```
# 随机生成一个密钥
openssl rand -hex 16
# 示例输出
9f3c7a1e5b8d4c2a6e0f91b7d4a2c8e5
```
- 在你的服务端，参考以下命令，通过 OpenSSL 随机生成 Base64 编码、32 字节的盐：
  Shell
```
# 随机生成一个 Base64 编码、32 字节的盐
openssl rand -base64 32
# 示例输出
X5w9T+50kzxVOnkJKiY/lUk82/bES2kATOt3vBuGEDw=
```
实现客户端逻辑：
1. 根据以下步骤，手动为你的项目添加加密库：
  1. 将 SDK 包中的 AgoraRtcCryptoLoader.framework 复制到你的项目文件夹中。
  2. 打开 Xcode（此处以 Xcode 11.0 为例），进入 TARGETS > Project Name > General > Frameworks, Libraries, and Embedded Content 菜单。
  3. 点击 + 和 Add Other...，添加 AgoraRtcCryptoLoader.framework。
  4. 为确保动态库的签名和 App 的签名一致，将动态库的 Embed 属性设置为 Embed & Sign。
  注意
  根据 Apple 的要求，App 的 Extension 不包含动态库。如果要将 SDK 集成到 Extension 里的动态库中，需要将文件状态改为 Do Not Embed。
  
  信息
  更多集成方式，详见其他集成方式。
2. 在 ViewController.swift 文件中添加以下代码，导入 AgoraRtcCryptoLoader 库：
  Swift
```
import AgoraRtcCryptoLoader
```
3. 从服务端获取 String 型的密钥和 Base64 编码的盐。
4. 将盐从 Base64 转换成 uint8_t。
5. 加入频道前，调用 enableEncryption，设置 AgoraEncryptionModeAES128GCM2 或 AgoraEncryptionModeAES256GCM2 加密模式，并将密钥和盐传入 SDK。
注意
- 同一频道内所有用户必须使用相同的加密模式、密钥和盐。否则，可能会出现黑屏或音频丢失等未定义行为。
- 为确保安全性，声网建议在每次启用媒体流加密前使用新的密钥和盐。
以下示例代码展示了该逻辑的实现过程：
Swift
```
func getEncryptionSaltFromServer() -> Data {
   // 将 Base64 编码的盐转换成 uint8_t
   return "EncryptionKdfSaltInBase64Strings".data(using: .utf8)!
}

// 创建一个 AgoraEncryptionConfig 实例
let config = AgoraEncryptionConfig()
// 将加密模式设置为 AgoraEncryptionModeAES128GCM2
config.encryptionMode = .AES128GCM2
// 从服务端获取 Base64 编码的盐
config.encryptionKdfSalt = getEncryptionKdfSaltBase64FromServer()
// 从服务端获取 String 型的密钥
config.encryptionKey = getEncryptionKeyFromServer()
let ret = agoraKit.enableEncryption(true, encryptionConfig: config)
if ret != 0 {
   self.showAlert(title: "Error", message: "enableEncryption call failed: \(ret), please check your params")
}
```

参考信息

示例项目

声网提供了开源的媒体流加密示例项目供你参考，你可以前往下载或查看其中的源代码。

StreamEncryption（Gitee）

StreamEncryption（GitHub）

通过 CocoaPods 集成加密库

根据以下步骤，通过 CocoaPods 集成加密库：

安装 CocoaPods。安装指南请参考 Getting Started with CocoaPods。
在终端，打开项目路径，运行 pod init 命令，在项目文件夹中创建 Podfile。
打开 Podfile，删除所有内容后，输入以下内容。注意将 Your App 替换为你的 Target 名称，并将 version 替换成你需要集成的 SDK 版本。
Ruby
```
# platform :ios, '9.0'
target 'Your App' do
  pod 'AgoraRtcEngine_iOS_Crypto', '~> version
end
```
回到终端，运行 pod install 命令，安装声网 SDK。SDK 安装成功后，终端会显示 Pod installation complete!，你可以在项目文件夹中看到 xcworkspace 文件。
打开 Xcode 中生成的 xcworkspace 文件。

注意事项

如需与 Web 平台的音视频 SDK 互通，你还需要将本文提到的 String 型密钥从 Hex 编码格式转换成 ASCII 编码格式。

在实时音视频互动过程中，开发者需要对媒体流加密，从而保障用户的数据安全。声网提供媒体流加密功能，你可以调用 API 选择加密模式并设置密钥和盐。

下图描述了启用媒体流加密功能后的数据传输流程：

实现方法

本节介绍如何使用 Web SDK 的媒体流加密功能。

开始前，请确保你已参考快速开始文档在你的项目中实现基本的实时音视频互动功能。

在加入频道前，调用 AgoraRTCClient.setEncryptionConfig 方法选择加密模式。声网支持以下加密模式：

"aes-128-xts": 128 位 AES 加密，XTS 模式。
"aes-256-xts": 256 位 AES 加密，XTS 模式。
"aes-128-gcm": 128 位 AES 加密，GCM 模式。
"aes-256-gcm": 256 位 AES 加密，GCM 模式。
"aes-128-ecb": 128 位 AES 加密，ECB 模式。
"sm4-128-ecb": 128 位 SM4 加密，ECB 模式。
"aes-128-gcm2": 128 位 AES 加密，GCM 模式，加盐。仅适用于 Web SDK v4.5.0 及之后版本。
"aes-256-gcm2": 256 位 AES 加密，GCM 模式，加盐。仅适用于 Web SDK v4.5.0 及之后版本。

如果你选择除 "aes-128-gcm2" 和 "aes-256-gcm2" 之外的加密模式，只需设置密钥。为加强安全性，声网建议将加密模式设为 "aes-128-gcm2" 或 "aes-256-gcm2"，并设置密钥和盐。

参考以下步骤分别生成并设置密钥和盐。

注意

同一频道内所有用户必须使用相同的加密模式、密钥和盐值。

生成并设置密钥

参考以下命令在服务端通过 OpenSSL 随机生成一个 16 字节的随机值，并以 16 进制 (hex) 字符串形式输出，作为密钥使用：
Shell
```
# 随机生成一个密钥
openssl rand -hex 16
# 示例输出
9f3c7a1e5b8d4c2a6e0f91b7d4a2c8e5
```
Web 客户端从服务端获取 Hex 编码的密钥，并在调用 setEncryptionConfig 时传入 SDK。

生成并设置盐

参考以下命令在服务端通过 OpenSSL 生成 Base64 编码、32 字节的盐。你也可以参考声网在 GitHub 上提供的 C++ 示例代码在服务端生成 byte array 型的盐，然后转换成 Base64 编码。
Shell
```
# Generate a random salt (32 bytes) in the Base64 format
openssl rand -base64 32
X5w9T+50kzxVOnkJKiY/lUk82/bES2kATOt3vBuGEDw=
```
Web 客户端从服务端获取 Base64 编码的盐。
Web 客户端将盐从 Base64 转换成 Uint8Array，并在调用 setEncryptionConfig 时传入 SDK。

示例代码

以下示例代码中的 client 是指通过 AgoraRTC.createClient 创建的本地客户端对象。

JavaScript

// 声明一个工具函数，用于将 Base64 转换成 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;
}

// 声明一个工具函数，用于将 Hex 转换成 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() {
// 假设 getSecretAndSaltFromServer 返回从服务器拿到的密钥和盐值 ["dba643c8ba6b6dc738df43d9fd624293b4b12d87a60f518253bd10ba98c48453", "X5w9T+50kzxVOnkJKiY/lUk82/bES2kATOt3vBuGEDw="]
  let [secret, salt] = await getSecretAndSaltFromServer();
  salt = base64ToUint8Array(salt);
  secret = hex2ascii(secret);
  return [secret, salt];
}

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

// 设置加密方案为 aes-256-gcm2，并传入 secret 和 salt
client.setEncryptionConfig("aes-256-gcm2", secret, salt);

开发注意事项

请确保在调用 AgoraRTCClient.join 加入频道之前设置加密。
通信和直播场景均支持媒体流加密功能。但是在直播场景下，声网不支持将加密后的媒体流推到 CDN 上。
如需使用媒体流加密功能，请确保接收端和发送端使用相同的加密模式，否则会出现未定义行为，例如音频无声或视频黑屏。

本文介绍如何在你的 App 中添加声网内置媒体流加密。

在你的服务端生成一个密钥和盐。
- 在你的服务端，参考以下命令，通过 OpenSSL 随机生成一个 16 字节的随机值，并以 16 进制（hex）字符串形式输出，作为密钥使用：
  Shell
```
# 随机生成一个密钥
openssl rand -hex 16
# 示例输出
9f3c7a1e5b8d4c2a6e0f91b7d4a2c8e5
```
- 在你的服务端，参考以下命令，通过 OpenSSL 随机生成 Base64 编码、32 字节的盐：
  Shell
```
# 随机生成一个 Base64 编码、32 字节的盐
openssl rand -base64 32
# 示例输出
X5w9T+50kzxVOnkJKiY/lUk82/bES2kATOt3vBuGEDw=
```

实现客户端逻辑：

从服务端获取 String 型的密钥和 Base64 编码的盐。
将盐从 Base64 转换成 uint8_t。
加入频道前，调用 enableEncryption 设置 AES_128_GCM2 或 AES_256_GCM2 加密模式，并将密钥和盐传入 SDK。

注意

同一频道内所有用户必须使用相同的加密模式、密钥和盐。否则，可能会出现黑屏或音频丢失等未定义行为。
为确保安全性，声网建议在每次启用媒体流加密前使用新的密钥和盐。

以下示例代码展示了该逻辑的实现过程：

C++

#include <boost/algorithm/string/trim.hpp>
#include <boost/archive/iterators/base64_from_binary.hpp>
#include <boost/archive/iterators/binary_from_base64.hpp>
#include <boost/archive/iterators/transform_width.hpp>
#include <boost/range/algorithm/copy.hpp>

namespace detail {
using Base64FromBinary = boost::archive::iterators::base64_from_binary<
    boost::archive::iterators::transform_width<const char*, 6, 8>>;

using BinaryFromBase64 = boost::archive::iterators::transform_width<
    boost::archive::iterators::binary_from_base64<std::string::const_iterator>,
    8, 6>;
}

void decodeBase64(const std::string& encoded, std::vector<uint8_t>& out) {
    auto unpadded = encoded;

    const auto num_padded = std::count(begin(encoded), end(encoded), '=');
    std::replace(begin(unpadded), end(unpadded), '=', 'A');  // A_64 == \0

    std::string decoded{
        detail::BinaryFromBase64{begin(unpadded)},
        detail::BinaryFromBase64{begin(unpadded) + unpadded.length()}};

    decoded.erase(end(decoded) - num_padded, end(decoded));
    std::copy(begin(decoded), end(decoded), out.begin());
}
// 请在调用 initialize 初始化 rtcEngine 后再调用该方法
int enableEncryption() {
    std::string secret;
    std::string kdfSaltBase64;
    std::vector<uint8_t> kdfSalt;
    for (int i = 0; i < 32; ++i) {
        kdfSalt.push_back(0);
    }
    if (!getSecretAndSaltFromSever(secret, kdfSaltBase64)) return -1;
    if (rtcEngine && decodeBase64(kdfSaltBase64, kdfSalt)) {
        // 创建一个 EncryptionConfig 实例
        agora::rtc::EncryptionConfig config;
        // 将加密模式设置为 AES_128_GCM2
        config.encryptionMode = AES_128_GCM2;
        // 设置密钥
        config.encryptionKey = secret.c_str();
        // 设置盐
        memcpy(config.encryptionKdfSalt, kdfSalt.data(),
            sizeof(config.encryptionKdfSalt));
        // 开启内置加密
        return rtcEngine->enableEncryption(true, config);
    }
    return -1;
}

上述示例代码中使用到了第三方库 Boost，你可以前往 boostorg 官网下载。

在你的服务端生成一个密钥和盐。
- 在你的服务端，参考以下命令，通过 OpenSSL 随机生成一个 16 字节的随机值，并以 16 进制 (hex) 字符串形式输出，作为密钥使用：
  Shell
```
# 随机生成一个密钥
openssl rand -hex 16
# 示例输出
9f3c7a1e5b8d4c2a6e0f91b7d4a2c8e5
```
- 在你的服务端，参考以下命令，通过 OpenSSL 随机生成 Base64 编码、32 字节的盐：
  Shell
```
# 随机生成一个 Base64 编码、32 字节的盐
openssl rand -base64 32
# 示例输出
X5w9T+50kzxVOnkJKiY/lUk82/bES2kATOt3vBuGEDw=
```
实现客户端逻辑：
1. 从服务端获取 String 型的密钥和 Base64 编码的盐。
2. 将盐从 Base64 转换成 uint8_t。
3. 加入频道前，调用 enableEncryption 设置 AES_128_GCM2 或 AES_256_GCM2 加密模式，并将密钥和盐传入 SDK。

注意

同一频道内所有用户必须使用相同的加密模式、密钥和盐。否则，可能会出现黑屏或音频丢失等未定义行为。
为确保安全性，声网建议在每次启用媒体流加密前使用新的密钥和盐。

以下示例代码展示了该逻辑的实现过程：

TypeScript

// 开启内置加密
enableEncryption = () => {
  // 内置加密模式为 Aes128Xts
  const encryptionMode = EncryptionMode.Aes128Xts;
  // 内置加密密钥
  const encryptionKey = '';
  // 盐
  const encryptionKdfSalt = new Array(32).fill(1, 0, 32);
  if (!encryptionKey) {
    this.error("encryptionKey is invalid");
    return;
  }
  rtcEngine.enableEncryption(true, {
    encryptionMode,
    encryptionKey,
    encryptionKdfSalt,
  });
};

// 关闭内置加密
disableEncryption = () => {
  rtcEngine.enableEncryption(false, {});
};

在你的服务端生成一个密钥和盐。
- 在你的服务端，参考以下命令，通过 OpenSSL 随机生成一个 16 字节的随机值，并以 16 进制 (hex) 字符串形式输出，作为密钥使用：
  Shell
```
# 随机生成一个密钥
openssl rand -hex 16
# 示例输出
9f3c7a1e5b8d4c2a6e0f91b7d4a2c8e5
```
- 在你的服务端，参考以下命令，通过 OpenSSL 随机生成 Base64 编码、32 字节的盐：
  Shell
```
# 随机生成一个 Base64 编码、32 字节的盐
openssl rand -base64 32
# 示例输出
X5w9T+50kzxVOnkJKiY/lUk82/bES2kATOt3vBuGEDw=
```
实现客户端逻辑：
1. 从服务端获取 String 型的密钥和 Base64 编码的盐。
2. 将盐从 Base64 转换成 uint8_t。
3. 加入频道前，调用 EnableEncryption 设置 AES_128_GCM2 或 AES_256_GCM2 加密模式，并将密钥和盐传入 SDK。
注意
- 同一频道内所有用户必须使用相同的加密模式、密钥和盐。否则，可能会出现黑屏或音频丢失等未定义行为。
- 为确保安全性，声网建议在每次启用媒体流加密前使用新的密钥和盐。
以下示例代码展示了该逻辑的实现过程：
C#
```
// 从服务器传输得到的密钥
string secret;
//从服务传输得到的 32 位的盐
byte[] kdfSal;
// 设置加密模式
ENCRYPTION_MODE EncrytionMode = ENCRYPTION_MODE.AES_128_GCM2;
var config = new EncryptionConfig
{
    encryptionMode = EncrytionMode,
    encryptionKey = secret,
    encryptionKdfSalt = kdfSal
};
// 开启加密。请在初始化引擎后再调用该方法
var nRet= RtcEngine.EnableEncryption(true, config);
Debug.Log("EnableEncryption: " + nRet);
```

在你的服务端生成一个密钥和盐。
- 在你的服务端，参考以下命令，通过 OpenSSL 随机生成一个 16 字节的随机值，并以 16 进制 (hex) 字符串形式输出，作为密钥使用：
  Shell
```
# 随机生成一个密钥
openssl rand -hex 16
# 示例输出
9f3c7a1e5b8d4c2a6e0f91b7d4a2c8e5
```
- 在你的服务端，参考以下命令，通过 OpenSSL 随机生成 Base64 编码、32 字节的盐：
  Shell
```
# 随机生成一个 Base64 编码、32 字节的盐
openssl rand -base64 32
# 示例输出
X5w9T+50kzxVOnkJKiY/lUk82/bES2kATOt3vBuGEDw=
```
实现客户端逻辑：
1. 从服务端获取 String 型的密钥和 Base64 编码的盐。
2. 将盐从 Base64 转换成 uint8_t。
3. 加入频道前，调用 enableEncryption 设置 AES_128_GCM2 或 AES_256_GCM2 加密模式，并将密钥和盐传入 SDK。

注意

同一频道内所有用户必须使用相同的加密模式、密钥和盐。否则，可能会出现黑屏或音频丢失等未定义行为。
为确保安全性，声网建议在每次启用媒体流加密前使用新的密钥和盐。

以下示例代码展示了该逻辑的实现过程：

TypeScript

// 开启内置加密
enableEncryption = () => {
  // 内置加密模式为 Aes128Xts
  const encryptionMode = EncryptionMode.Aes128Xts;
  // 内置加密密钥
  const encryptionKey = '';
  // 盐
  const encryptionKdfSalt = new Array(32).fill(1, 0, 32);
  if (!encryptionKey) {
    this.error("encryptionKey is invalid");
    return;
  }
  rtcEngine.enableEncryption(true, {
    encryptionMode,
    encryptionKey,
    encryptionKdfSalt,
  });
};

// 关闭内置加密
disableEncryption = () => {
  rtcEngine.enableEncryption(false, {});
};

encryptionKey 为字符串类型。
encryptionKdfSalt 为 32 字节的 ArrayBuffer。
不要在客户端代码中硬编码生产环境的密钥和盐。

单连接场景

在加入频道前创建 EncryptionConfig，设置加密模式、密钥和盐，然后调用 enableEncryption：

TypeScript

import { EncryptionConfig, EncryptionMode } from "AgoraRtcSdk";

const encryptionKey = "your-key-from-server";
// 示例仅用于展示类型。生产环境应替换为服务端下发的 32 字节盐。
const encryptionKdfSalt = new Uint8Array(32).fill(1).buffer;

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

// 在加入频道前调用
const result = this.rtcEngine?.enableEncryption(true, encryptionConfig);
if (result !== undefined && result !== 0) {
    Logger.error(TAG, `enableEncryption failed: ${result}`);
}

关闭加密时，将 enabled 设置为 false。用户离开频道后，SDK 会自动关闭该频道的加密；再次加入前需要重新调用 enableEncryption。

多连接场景

如果同一个 RtcEngine 实例通过多个 RtcConnection 加入频道，需要针对每个连接调用 enableEncryptionEx，并传入对应的 RtcConnection：

TypeScript

import { EncryptionConfig, EncryptionMode, RtcConnection } from "AgoraRtcSdk";

const connection = new RtcConnection("your-channel", 0);
const encryptionConfig = new EncryptionConfig();
encryptionConfig.encryptionMode = EncryptionMode.AES_128_GCM2;
encryptionConfig.encryptionKey = "your-key-from-server";
// 生产环境应替换为该连接对应的服务端下发盐。
encryptionConfig.encryptionKdfSalt = new Uint8Array(32).fill(1).buffer;

// 在该连接加入频道前调用
const result = this.rtcEngine?.enableEncryptionEx(
    true,
    encryptionConfig,
    connection
);
if (result !== undefined && result !== 0) {
    Logger.error(TAG, `enableEncryptionEx failed: ${result}`);
}

enableEncryptionEx 的加密配置作用于传入的连接。多个连接不能依赖一个全局配置；你需要为每个连接明确配置，并确保同一频道内的所有用户使用一致的加密模式和密钥。

注意事项

必须在加入频道前调用 enableEncryption 或 enableEncryptionEx。
AES_128_GCM2 和 AES_256_GCM2 需要设置有效的 32 字节盐，盐不能全部为 0。
开启内置加密后，不能使用旁路推流功能。
如果密钥为空或加密参数无效，SDK 会返回错误码。请检查服务端下发的数据和 EncryptionConfig 字段。
需要关闭加密时，使用与开启时相同的连接粒度调用对应方法。

技术原理Copy Anchor Link

前提条件Copy Anchor Link

实现方法Copy Anchor Link

参考信息Copy Anchor Link

示例项目Copy Anchor Link

CAgoraMediaEncryptDlg（Gitee）

CAgoraMediaEncryptDlg（GitHub）

注意事项Copy Anchor Link

咨询电话

咨询电话

技术原理

前提条件

实现方法

参考信息

示例项目

注意事项