Media Stream Encryption

Last updated 2022/09/27 02:05:45

Media encryption encrypts your app’s audio and video streams with a unique key and salt controlled by the app developer. While not every use case requires media encryption, Agora provides the option to guarantee data confidentiality during transmission.

This page shows you how to add Agora's built-in media stream encryption to your app.

Understand the tech

The following figure shows the encrypted data transmission process after you enable the built-in encryption. Agora recommends using the AgoraEncryptionModeAES128GCM2 or AgoraEncryptionModeAES256GCM2 encryption mode and setting the key and salt.

Prerequisites

Before implementing media stream encryption, ensure that you have implemented the basic real-time communication functions in your project. For details, see the following quickstart guides:

iOS: Start a Video Call or Start Interactive Live Streaming.
macOS: Start a Video Call or Start Interactive Live Streaming.

Implement the built-in encryption

Add the built-in media stream encryption to your app, as follows:

Generate a key and salt on your server:

To generate a random 32-byte key in the string format through OpenSSL on your server, run the following command:

// Generate a random 32-byte key in the string format
openssl rand -hex 32
dba643c8ba6b6dc738df43d9fd624293b4b12d87a60f518253bd10ba98c48453

To generate a random Base64-encoded, 32-byte salt through OpenSSL on your server, run the following command:

// Generate a random 32-byte salt in the Base64 format
openssl rand -base64 32
X5w9T+50kzxVOnkJKiY/lUk82/bES2kATOt3vBuGEDw=

The client logic you need to implement is:
1. Manually add the encryption library to your project, as follows:
  1. Copy AgoraRtcCryptoLoader.framework from the SDK package to your project folder.
  2. Open Xcode (take the Xcode 11.0 as an example) and go to the TARGETS > Project Name > General > Frameworks, Libraries, and Embedded Content menu.
  3. Click + and Add Other... to add AgoraRtcCryptoLoader.framework.
  4. To ensure that the signature of the dynamic library is the same as the signature of the app, set the Embed attribute of the dynamic library to Embed & Sign.
    
    According to the requirement of Apple, the Extension of app cannot contain the dynamic library. If you need to integrate the SDK with the dynamic library in the Extension, change the file status as Do Not Embed.
    
    For more integration methods, see Other approaches to integrate the encryption library
2. Import the AgoraRtcCryptoLoader library. To do this, add the following code to the ViewController.swift file:
```
import AgoraRtcCryptoLoader
```
3. Get the key in the string format and the salt in the Base64 format from your server.
4. Convert the salt from Base64 to uint8_t.
5. Before joining a channel, call enableEncryption to choose the AgoraEncryptionModeAES128GCM2 or AgoraEncryptionModeAES256GCM2 encryption mode and pass the key and salt to the SDK.
  - All users in a channel must use the same encryption mode, key, and salt; otherwise, undefined behaviors such as a black screen or audio loss occur.
  - To enhance security, Agora recommends using a new key and salt every time you enable media stream encryption.
The following sample code shows this logic:
```
func getEncryptionSaltFromServer() -> Data {
// Converts the salt from Base64 to uint8_t
return "EncryptionKdfSaltInBase64Strings".data(using: .utf8)!
}

// Creates an AgoraEncryptionConfig instance
let config = AgoraEncryptionConfig()
// Sets the encryption mode as AgoraEncryptionModeAES128GCM2
config.encryptionMode = .AES128GCM2
// Gets the salt in the Base64 format from the server
config.encryptionKdfSalt = getEncryptionKdfSaltBase64FromServer()
// Gets the key in the string format from your server
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")
}
```

Reference

This section provides reference information you may need when implementing the built-in encryption.

Sample project

Agora provides an open-source sample project that implements the built-in media encryption on GitHub. You can try the demo and view the source code.

Integrate the encryption library through Cocoapods

Integrate the encryption library through Cocoapods, as follows:

Install CocoaPods. See the installation guide in Getting Started with CocoaPods.
In Terminal, go to the project path and run the pod init command to create a Podfile in the project folder.
Open the Podfile, delete all contents and input the following contents. Remember to change Your App to the target name of your project, and change version to the version of the SDK which you want to integrate.
```
# platform :ios, '9.0'
target 'Your App' do
  pod 'AgoraRtcEngine_iOS_Crypto', '~> version'
end
```
Go back to Terminal, and run the pod install command to install the Agora SDK. Once you successfully install the SDK, it shows Pod installation complete! in Terminal, and you can see an xcworkspace file in the project folder.
Open the generated xcworkspace file in Xcode.

Is this page helpful?

Yes