Using Dynamic Keys for Increased Security

Each organization using the Agora SDK has a unique Vendor Key for identification. Communications in the Agora Global Network are isolated according to Vendor Keys. People with different Vendor Keys do not interfere with each other, even when the names of the channels they join are the same.

However, if someone dishonestly obtains your static Vendor Key, then they can use it on their own Agora SDK client applications. If they discover the channel names of your organization, they can even interfere with your communication sessions. To increase the security of applications, we recommend that you implement Dynamic Keys in your large-scale production applications.

What Is a Dynamic Key?

A Dynamic Key offers enhanced user authentication for the Agora SDK. Whenever a user tries to enter a channel to access the Agora service, the back-end services of your application use the Vendor Key and a Sign Key provided by Agora to generate a new dynamic key based on keyed-hash message authentication code (HMAC) encryption. The dynamic key is then passed to the client application, which calls the joinChannel API interface function and passes the encoded dynamic key to the Agora server for the user authentication.

Note

Vendor Key：The vendor ID used to identify your organization or product. If dynamic key scheme is not implemented, the Vendor Key is used to access the Agora service.

Sign Key：The “sign” key used to generate the dynamic key (see Table 1 for its usage). The Sign Key is stored on the server and invisible to any users.

How to Use a Dynamic Key

The following sections describe the use of dynamic keys:

Obtaining a Vendor Key and a Sign Key

Implementing the Dynamic Key Scheme

Using a Dynamic Key

Obtaining a Vendor Key and a Sign Key

Each Agora account can create multiple projects, and each project has a unique Vendor Key and Sign Key.

Do the following to create a project to obtain a Vendor Key(API Key) and a Sign Key at the same time:

1. Login https://dashboard.agora.io.
2. Click ADD NEW on the PROJECTS page of the dashboard.
3. Fill the Project Name，select Enable Sign Key and click SAVE.

A project is added.

1. Find the Vendor Key and Sign Key of the created project as follows:

Click the lock icon to show the Sign Key, and re-click it to hide the Sign Key again.

If you did not select Enable Sign Key when creating the project, you can click Enable sign key to view the Sign Key as follows after the project is created:

Notes

If you want to renew the Sign Key for some reason, contact [email protected].

Keep your Sign Key on the server and never on any client machine.

Implementing the Dynamic Key Scheme

Integrate the dynamic key scheme into your organization’s signaling service. Agora.io provides sample server-side code covering the following languages: Java, C++, Python, node.js, and so on, which you can use this code directly in your application. When joining the channel or using the recording function, you use the same Vendor Key and Sign Key, but the method to generate the Dynamic Key is different. Use generateMediaChannelKey to join the channel, and use generateRecordingKey to use the recording function. For the sample code, refer to any of the following sites:

Github: https://github.com/AgoraLab/AgoraDynamicKey

Sign Key Page at dashboard: https://dashboard.agora.io/signkey

Using a Dynamic Key

Before a user joins a channel (that is, has started a call or received a meeting invitation), the following sequence occurs：

1. The client application requests authentication from the signaling server of your organization.
2. The server, upon receiving the request, uses the algorithm provided by Agora.io to generate a dynamic key and then passes the dynamic key back down to the client application.

The dynamic key is based on the Sign Key, Vendor Key, Channel Name, Current Timestamp, Client User ID, Lifespan Timestamp, and so on.

1. The client application calls the joinChannel() method, which requires the dynamic key as the first parameter.
2. The Agora server receives the dynamic key and confirms that the call comes from a legal user, and then allows it to access the Agora Global Network.
3. Note: With the dynamic key scheme implemented, the dynamic key replaces the original Vendor Key when the user joins a channel.

Dynamic keys expire after a certain amount of time and your application must call renewChannelDynamicKey() when a time-out occurs. The onError callback returns ERR_DYNAMIC_KEY_TIMEOUT(109).

Increased Security with Dynamic Keys

If your organization chooses dynamic keys, before a user joins a channel, the client application must provide a new dynamic key to ensure that every call of the user is authorized by the signaling server. The dynamic key uses the HMAC/SHA1 signature schema to increase security for communications within your organization.

Dynamic Key Structure

Connect all fields in the sequence below (103 bytes in total):

Table 1

Service Type

Sign Encryption Algorithm: HMAC/SHA1

The dynamic key encoding uses the industry-standard HMAC/SHA1 approach for which there are libraries on most common server-side development platforms, such as Node.js, Java, Python, C++, and so on. For more information, refer to:

http://en.wikipedia.org/wiki/Hash-based_message_authentication_code

Contact Agora.io for more information or technical support.