媒体流加密
功能描述
在实时音视频互动过程中，你需要对媒体流加密，从而保障用户的数据安全。Agora 提供内置加密和自定义加密方案，你可以根据需要选择合适的加密方案。
- 内置加密：使用 SDK 预置的加密模式给媒体流加密。
- 自定义加密：通过 SDK 提供的数据包观测器来自定义媒体流的加密模式。
下图描述了启用媒体流加密后的数据传输流程：
示例项目
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 加密库并导入类：
选择以下一种方法集成加密库：
使用 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' endd. 在 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。在项目中导入
AgoraRtcCryptoLoader类：// Swift import AgoraRtcCryptoLoader// Objective-C #import <AgoraRtcCryptoLoader/AgoraRtcCryptoLoader.h>
2. 生成密钥
在你的服务端，参考以下命令通过 OpenSSL 随机生成 String 型、32 字节的密钥。
// 随机生成一个 string 型、32 字节的密钥，并将该密钥传入 enableEncryption 的 encryptionKey 参数。 openssl rand -hex 32 dba643c8ba6b6dc738df43d9fd624293b4b12d87a60f518253bd10ba98c48453客户端从服务端获取 String 型密钥，并在调用
enableEncryption时传入 SDK。
3. 生成盐
在你的服务端，参考以下命令通过 OpenSSL 随机生成 Base64 编码、32 字节的盐。你也可以参考 Agora 在 GitHub 上提供的 C++ 示例代码，在服务端随机生成 byte array 型的盐，然后转换成 Base64 编码。
// 随机生成一个 Base64 编码、32 字节的盐，并将该盐传入 enableEncryption 的 encryptionKdfSalt 参数。 openssl rand -base64 32 X5w9T+50kzxVOnkJKiY/lUk82/bES2kATOt3vBuGEDw=客户端从服务端获取 Base64 编码的盐。
客户端将盐值从 Base64 编码解码为长度为 32 的 NSData，然后在调用
enableEncryption时传入 SDK。
4. 开启内置加密
在加入频道前，调用 enableEncryption 方法启用内置加密。
自 v3.4.5 起，Agora 推荐使用 AgoraEncryptionModeAES128GCM2 或 AgoraEncryptionModeAES256GCM2 加密模式，并设置密钥和盐。
GCM2 加密模式使用了安全性更高的密钥派生函数且支持盐。如果你选择其他加密模式，则只需设置加密模式和密钥。示例代码
@interface Server
+ (NSString*) getEncryptionKdfSaltBase64;
+ (NSString*) getEncryptionSecret;
@end
@interface Example
- (BOOL) enableEncryption:(AgoraRtcEngineKit* _Nonnull)engine;
@end
@implementation Example
- (BOOL) enableEncryption:(AgoraRtcEngineKit*)agoraKit
{
if(!agoraKit) return NO;
NSString* encryptionKdfSaltBase64 = [Server getEncryptionKdfSaltBase64];
NSString* encryptionSecret = [Server getEncryptionSecret];
if(!encryptionKdfSaltBase64 || !encryptionSecret)
return NO;
NSData* encryptionKdfSalt = [[NSData alloc] initWithBase64EncodedString:encryptionKdfSaltBase64 options:0];
AgoraEncryptionConfig* config = [[AgoraEncryptionConfig alloc] init];
config.encryptionMode = AgoraEncryptionModeAES128GCM2;
config.encryptionKey = encryptionSecret;
config.encryptionKdfSalt = encryptionKdfSalt;
int result = [agoraKit enableEncryption:YES encryptionConfig:config];
return (0 == result);
}
@endAPI 参考
使用自定义的加密方案
Agora 提供 C++ 的 registerPacketObserver 方法及 IPacketObserver 类，帮助你实现自定义加密功能。
.mm 文件中实现。.mm 文件的开头需要引入 C++ 头文件: #include <AgoraRtcKit/IAgoraRtcEngine.h>。参考步骤如下：
在
.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; };在加入频道前，注册数据包观测器，在语音或视频数据包传输时接收事件。
// 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(); }离开频道后，取消注册数据包观测器。
// 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 参考
开发注意事项
- 通信和直播场景均支持媒体流加密功能。但是在直播场景下，Agora 不支持将加密后的媒体流推到 CDN 上。
- 如需使用媒体流加密功能，你需要在加入频道前设置加密并让接收端和发送端使用相同的加密模式，否则会出现未定义行为，例如音频无声或视频黑屏。
- 为提高安全性，Agora 建议每次启用媒体流加密时都更换新的密钥和盐。
