Secure channel encryption

Media stream encryption ensures that only the authorized users in a channel can see and hear each other. This ensures that potential eavesdroppers cannot access sensitive and private information shared in a channel. While not every use case requires media stream encryption, Voice Calling provides built-in encryption methods that guarantee data confidentiality during transmission.

This page shows you how to integrate built-in media stream encryption into your app using Voice Calling.

To ensure secure communication, your app uses the same SSL key and salt to encrypt and decrypt data in the channel. You use the key and salt to create an encryption configuration. Agora SD-RTN™ uses the encryption configuration to encrypt a stream and sends it to remote users. When the remote user receives the encrypted media stream, the remote app decrypts the media stream using the same salt and key.

The following figure shows the call flow for the media stream encryption:

All users in a channel must use the same encryption configuration to initiate agoraEngine and enable encryption before joining a channel. If you don’t have the correct configuration, you cannot decrypt channel content. Best practice is that your authentication system generates a new key and salt regularly.

To follow this procedure you must have:

• Implemented the SDK quickstart project for Voice Calling.

• OpenSSL latest version

To encrypt the media streams in your app, you need to:

• Open the SDK quickstart Voice Calling project you created previously.

• Set up OpenSSL in your development device.

To implement media stream encryption, do the following:

1. Add the required variables

   In AgoraImplementationDlg.h, add the following declarations to CAgoraImplementationDlg:

   // In a production environment, you retrieve the key and salt from
   

   // an authentication server. For this code example you generate them locally.
   

   
   

   // A 32-byte string for encryption.
   

   std::string encryptionKey = "";
   

   // A 32-byte string in Base64 format for encryption.
   

   std::string encryptionSaltBase64 = "";
   

2. Add the media stream encryption method

   To enable media stream encryption in your app, create an EncryptionConfig object and specify a key, salt, and encryption mode. Call enableEncryption and pass the EncryptionConfig object as a parameter. To implement this logic, take the following steps:

   1. In AgoraImplementationDlg.cpp, add the following method before OnInitDialog:

      void CAgoraImplementationDlg::enableEncryption()
      

      {
      

      if (encryptionSaltBase64 == "" || encryptionKey == "")
      

      return;
      

      //set encrypt mode and encrypt secret
      

      EncryptionConfig config;
      

      config.encryptionMode = AES_256_GCM2;
      

      config.encryptionKey = encryptionKey.c_str();
      

      memcpy(config.encryptionKdfSalt, encryptionSaltBase64.c_str(), 32);
      

      // Call the method to enable media encryption.
      

      if (agoraEngine->enableEncryption(true, config) == 0)
      

      {
      

      AfxMessageBox(L"Encryption Enabled");
      

      }
      

      }
      

   2. In AgoraImplementationDlg.h, add the following method declaration to CAgoraImplementationDlg:

      void enableEncryption();
      

3. Start media encryption before joining a channel

   In AgoraImplementationDlg.cpp, add the following code at the end of SetupVoiceSDKEngine:

   enableEncryption();
   

To ensure that you have implemented Agora media stream encryption in your app:

1. Add the 32-byte key to your app

   1. Run the following command in a terminal window:

      openssl rand -hex 32
      

   2. Paste the key returned into the encryptionKey variable.

2. Add the 64-byte salt to your app

   1. Run the following command in a terminal window:

      openssl rand -base64 32
      

   2. Paste the salt returned into the encryptionSaltBase64 variable.

3. Generate a token in Agora Console.

4. In AgoraImplementationDlg.h, update appId, channelName and token with the values for your temporary token.

5. In Visual Studio, click Local Window Debugger. A moment later you see the project running on your development device.

6. Click Join to start Voice Calling.

   If this is the first time you run the project, you need to grant microphone access to your app.

7. Open another instance of your app on a test device and update appId, channelName and token with your values, then click Join.

Communication between your test devices is end-to-end encrypted. This prevents data from being read or secretly modified by anyone other than the true sender and recipient.

This section contains information that completes the information in this page, or points you to documentation that explains other aspects to this product.

• enableEncryption
• EncryptionConfig