功能描述

在实时音视频互动过程中，开发者需要对媒体流加密，从而保障用户的数据安全。Agora 提供内置加密方案和自定义加密方案，区别如下：

• 内置加密：加密模式和密钥存在于 app 和 SDK 中。
• 自定义加密：加密模式和密钥仅存在于 app 中。

你可以根据需要选择合适的加密方案。

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

示例项目

Agora 在 GitHub 上提供以下实现了媒体流加密功能的开源示例项目：

• iOS：StreamEncryption
• macOS：StreamEncryption

你可以下载体验并参考源代码。

实现方法

在启用媒体流加密前，请确保已在你的项目中实现基本的实时音视频功能。

使用内置的加密方案

1. 获取加密库（仅 iOS）

自 3.2.0 版本起，Agora iOS SDK 中的 AgoraRtcCryptoLoader.framework 加密库合并入 AgoraRtcKit.framework。如果你使用 3.2.0 及以上版本的 SDK，获取 AgoraRtcKit.framework 后即可使用内置的加密方案。

如果你使用 3.2.0 以下版本的 SDK，除获取 AgoraRtcKit.framework 外，还需参考以下步骤获取 AgoraRtcCryptoLoader.framework 加密库并导入类：

1. 选择以下一种方法集成加密库：

   使用 CocoaPods 获取

   a. 开始前确保你已安装 Cocoapods。参考 Getting Started with CocoaPods 安装说明。
   b. 在 Terminal 里进入项目根目录，并运行 pod init 命令。项目文件夹下会生成一个 Podfile 文本文件。
   c. 打开 Podfile 文件，修改文件为如下内容。注意将 Your App 替换为你的 Target 名称，并将 version 替换为你需集成的 SDK 版本。

    # platform :ios, '9.0'
    target 'Your App' do
      pod 'AgoraRtcEngine_iOS_Crypto', 'version'
    end

   d. 在 Terminal 内运行 pod install 命令安装 Agora SDK。成功安装后，Terminal 中会显示 Pod installation complete!，此时项目文件夹下会生成一个 xcworkspace 文件。
   e. 打开新生成的 xcworkspace 文件。

   手动复制 SDK 文件

   a. 将 SDK 包中的 AgoraRtcCryptoLoader.framework 复制到项目文件夹下。
   b. 打开 Xcode（以 Xcode 11.0 为例），进入 TARGETS > Project Name > General > Frameworks, Libraries, and Embedded Content 菜单，点击 +，再点击 Add Other… 添加 AgoraRtcCryptoLoader.framework，并确保添加的动态库 Embed 属性设置为 Embed & Sign。

   根据 Apple 官方要求，app 的 Extension 不允许包含动态库。如果工程中的 Extension 需要集成 SDK，则集成动态库时需将文件状态改为 Do Not Embed。

2. 在项目中导入 AgoraRtcCryptoLoader 类：

   // Swift 
   import AgoraRtcCryptoLoader

   // Objective-C
   #import <AgoraRtcCryptoLoader/AgoraRtcCryptoLoader.h>

2. 开启内置加密

在加入频道前，调用 enableEncryption 方法开启内置加密，并设置加密模式和密钥。

示例代码

// Swift
// 创建一个 AgoraEncryptionConfig 实例
let config = AgoraEncryptionConfig()
// 设置加密模式为国密 SM4 加密模式
config.encryptionMode = AgoraEncryptionMode.SM4128ECB
// 设置加密密钥
config.encryptionKey = "xxxxxxxxxxxxxxxx"
// 启用内置加密
agoraKit.enableEncryption(true, config)

// Objective-C
// 创建一个 AgoraEncryptionConfig 实例
AgoraEncryptionConfig *config = [[AgoraEncryptionConfig alloc] init];
// 设置加密模式为国密 SM4 加密模式，并设置加密密钥
config.encryptionMode = AgoraEncryptionModeSM4128ECB;
config.encryptionKey = @"xxxxxxxxxxxxxxxx";
// 启用内置加密
[agoraKit enableEncryption: YES encryptionConfig:config];

API 参考

enableEncryption

使用自定义的加密方案

Agora 提供 C++ 的 registerPacketObserver 方法及 IPacketObserver 类，帮助你实现自定义加密功能。

参考步骤如下：

1. 在 .mm 文件中通过 IPacketObserver 类实现你自定义的数据加密算法。

    class AgoraCustomEncryptionObserver : public agora::rtc::IPacketObserver
    {
    public:
        EVP_CIPHER_CTX *ctx_audio_send;
        EVP_CIPHER_CTX *ctx_audio_receive;
        EVP_CIPHER_CTX *ctx_video_send;
        EVP_CIPHER_CTX *ctx_video_receive;
        AgoraCustomEncryptionObserver()
        {
            m_txAudioBuffer.resize(1024);
            m_rxAudioBuffer.resize(1024);
            m_txVideoBuffer.resize(1024);
            m_rxVideoBuffer.resize(1024);
        }
        virtual bool onSendAudioPacket(Packet& packet)
        {
   
            int outlen;
            // 加密数据包
            unsigned char outbuf[1024];
            EVP_EncryptInit_ex(ctx_audio_send, EVP_aes_256_gcm(), NULL, NULL, NULL);
            EVP_CIPHER_CTX_ctrl(ctx_audio_send, EVP_CTRL_GCM_SET_IVLEN, sizeof(gcm_iv), NULL);
            EVP_EncryptInit_ex(ctx_audio_send, NULL, NULL, gcm_key, gcm_iv);
            EVP_EncryptUpdate(ctx_audio_send, outbuf, &outlen, packet.buffer, packet.size);
            // 将加密后数据的缓存地址和缓存大小发回 SDK
            packet.buffer = outbuf;
            packet.size = outlen;
            return true;
        }
   
        virtual bool onSendVideoPacket(Packet& packet)
        {
   
            int outlen;
            // 加密数据包
            unsigned char outbuf[1024];
            EVP_EncryptInit_ex(ctx_video_send, EVP_aes_256_gcm(), NULL, NULL, NULL);
            EVP_CIPHER_CTX_ctrl(ctx_video_send, EVP_CTRL_GCM_SET_IVLEN, sizeof(gcm_iv), NULL);
            EVP_EncryptInit_ex(ctx_video_send, NULL, NULL, gcm_key, gcm_iv);
            EVP_EncryptUpdate(ctx_video_send, outbuf, &outlen, packet.buffer, packet.size);
            // 将加密后数据的缓存地址和缓存大小发回 SDK
            packet.buffer = outbuf;
            packet.size = outlen;
            return true;
        }
   
        virtual bool onReceiveAudioPacket(Packet& packet)
        {
            int outlen;
            // 加密数据包
            unsigned char outbuf[1024];
            EVP_DecryptInit_ex(ctx_audio_receive, EVP_aes_256_gcm(), NULL, NULL, NULL);
            EVP_CIPHER_CTX_ctrl(ctx_audio_receive, EVP_CTRL_GCM_SET_IVLEN, sizeof(gcm_iv), NULL);
            EVP_DecryptInit_ex(ctx_audio_receive, NULL, NULL, gcm_key, gcm_iv);
            EVP_DecryptUpdate(ctx_audio_receive, outbuf, &outlen, packet.buffer, packet.size);
            // 将解密后数据的缓存地址和缓存大小发回 SDK
            packet.buffer = outbuf;
            packet.size = outlen;
            return true;
        }
   
        virtual bool onReceiveVideoPacket(Packet& packet)
        {
            int outlen;
            // 加密数据包
            unsigned char outbuf[1024];
            EVP_DecryptInit_ex(ctx_video_receive, EVP_aes_256_gcm(), NULL, NULL, NULL);
            EVP_CIPHER_CTX_ctrl(ctx_video_receive, EVP_CTRL_GCM_SET_IVLEN, sizeof(gcm_iv), NULL);
            EVP_DecryptInit_ex(ctx_video_receive, NULL, NULL, gcm_key, gcm_iv);
            EVP_DecryptUpdate(ctx_video_receive, outbuf, &outlen, packet.buffer, packet.size);
            // 将解密后数据的缓存地址和缓存大小发回 SDK
            packet.buffer = outbuf;
            packet.size = outlen;
            return true;
        }
   
    private:
        // 发送音频数据 buffer
        std::vector<unsigned char> m_txAudioBuffer;
        // 发送视频数据 buffer
        std::vector<unsigned char> m_txVideoBuffer;
   
        // 接收音频数据 buffer
        std::vector<unsigned char> m_rxAudioBuffer;
        // 接收视频数据 buffer
        std::vector<unsigned char> m_rxVideoBuffer;
    };

2. 在加入频道前，注册数据包观测器，在语音或视频数据包传输时接收事件。

    // Swift
    AgoraCustomEncryption.registerPacketProcessing(agoraKit)

   在 .mm 文件中调用 registerPacketObserver 实现注册数据包观测器。

    + (void)registerPacketProcessing:(AgoraRtcEngineKit *)rtcEngineKit {
        if (!rtcEngineKit) {
            return;
        }
        // 获取 Native SDK 的 C++ 句柄
        agora::rtc::IRtcEngine* rtc_engine = (agora::rtc::IRtcEngine*)rtcEngineKit.getNativeHandle;
        // 注册数据包观测器
        rtc_engine->registerPacketObserver(&s_packetObserver);
        s_packetObserver.ctx_audio_send = EVP_CIPHER_CTX_new();
        s_packetObserver.ctx_video_send = EVP_CIPHER_CTX_new();
        s_packetObserver.ctx_audio_receive = EVP_CIPHER_CTX_new();
        s_packetObserver.ctx_video_receive = EVP_CIPHER_CTX_new();
    }

3. 离开频道后，取消注册数据包观测器。

    // Swift
    AgoraCustomEncryption.deregisterPacketProcessing(agoraKit)

   在 .mm 文件中调用 registerPacketObserver(NULL) 实现取消注册数据包观测器。

    + (void)deregisterPacketProcessing:(AgoraRtcEngineKit *)rtcEngineKit {
        if (!rtcEngineKit) {
            return;
        }
        // 获取 Native SDK 的 C++ 句柄
        agora::rtc::IRtcEngine* rtc_engine = (agora::rtc::IRtcEngine*)rtcEngineKit.getNativeHandle;
        // 取消注册数据包观测器
        rtc_engine->registerPacketObserver(NULL);
        EVP_CIPHER_CTX_free(s_packetObserver.ctx_audio_send);
        EVP_CIPHER_CTX_free(s_packetObserver.ctx_video_send);
        EVP_CIPHER_CTX_free(s_packetObserver.ctx_audio_receive);
        EVP_CIPHER_CTX_free(s_packetObserver.ctx_video_receive);
    }

API 参考

registerPacketObserver