tencent cloud

What is UserSig?

UserSig is a security signature designed by Tencent Cloud to prevent attackers from accessing your Tencent Cloud account.
Currently, Tencent Cloud services including TRTC, IM, and MLVB all use this security mechanism. Whenever you want to use these services, you must provide three key pieces of information, i.e. SDKAppID, UserID, and UserSig in the initialization or login function of the corresponding SDK.
SDKAppID is used to identify your application, and UserID your user. UserSig is a security signature calculated based on the two parameters using the HMAC SHA256 encryption algorithm. Attackers cannot use your Tencent Cloud traffic without authorization as long as they cannot forge a UserSig.
See the figure below for how UserSig is calculated. Basically, it involves hashing crucial information such as SDKAppID, UserID, and ExpireTime.

// UserSig formula, in which `secretkey` is the key used to calculate UserSig
usersig = hmacsha256(secretkey, (userid + sdkappid + currtime + expire + 
                                base64(userid + sdkappid + currtime + expire)))

Note：

• currtime is the current system time and expire the expiration time of the signature.
• The above figure only shows how to calculate UserSig. For more information on how to implement the UserSig concatenation code, please see Calculating UserSig through client sample code and How do I calculate UserSig during formal operations?.

How do I calculate UserSig during debugging and running?

If you want to quickly run the demo to try out TRTC SDK features, you can calculate and get UserSig either through the client sample code or console as follows:

Note：

• The above methods for calculating and getting UserSig are only applicable for debugging. They are not recommended for official launch because SECRETKEY of the client code (especially on the web) may be easily decompiled and reversed. If your key is leaked, attackers can steal your Tencent Cloud traffic.
• The correct method is to deploy the UserSig calculation code on your project server so that your application can request from your server a UserSig that is calculated whenever one is needed.

Calculating UserSig through client sample code

1. Get the SDKAppID and key:
   1. Log in to the TRTC console and select Application Management.
   2. Click Application Info of the target SDKAppID and click the Quick Start tab.
   3. View the secret key used to calculate UserSig in Step 2: obtain the secret key to issue UserSig.
   4. Click Copy Secret Key to copy the key to the clipboard.
      

Note：

If you can get only the public and private key information when you try to view the secret key, see Only public and private key can be obtained when I try to view the secret key. How do I get the secret key?.

2. Calculate UserSig:
   For the convenience of the client, TRTC provides the source code file for calculating UserSig for various platforms, which you can directly download for calculation:

   Applicable Platform	File Source Code	Relative File Path
   iOS	Github	TRTC-API-Example-OC/Debug/GenerateTestUserSig.h
   macOS	Github	OCDemo/TRTCDemo/TRTC/GenerateTestUserSig.h
   Android	Github	TRTC-API-Example/Debug/src/main/java/com/tencent/trtc/debug/GenerateTestUserSig.java
   Windows£¨C++£©	Github	TRTC-API-Example-C++/TRTC-API-Example-Qt/src/Util/defs.h
   Windows£¨C#£©	Github	TRTC-API-Example-CSharp/TRTC-API-Example-CSharp/GenerateTestUserSig.cs
   Web	Github	base-js/js/debug/GenerateTestUserSig.js
   Flutter	Github	TRTC-API-Example/lib/Debug/GenerateTestUserSig.dart

We provide an open-source module called GenerateTestUserSig in the TRTC SDK sample code. Set the three member variables of SDKAPPID, EXPIRETIME, and SECRETKEY, and you will be able to call the genTestUserSig() function to obtain the UserSig and get started quickly with the SDK.

Only public and private key can be obtained when I try to view the secret key. How do I get the secret key?

TRTC SDK 6.6 (August 2019) and later versions use the new signature algorithm HMAC-SHA256. If your application was created before August 2019, you need to upgrade the signature algorithm to get a new key. Without upgrading, you can continue to use the old algorithm ECDSA-SHA256. After upgrading, you can switch between the new and old algorithms as needed.

Upgrade/Switch:

1. Log in to the TRTC console.
2. Click Application Management on the left sidebar, find your application, and click Application Info.
3. Select the Quick Start tab and click Upgrade, asymmetric encryption, or HMAC-SHA256 in Step 2: obtain the secret key to issue UserSig.

• Upgrade
• Switch to the old algorithm ECDSA-SHA256:
  
• Switch to the new algorithm HMAC-SHA256:
  

Getting UserSig in console

1. Log in to the TRTC console and select Development Assistance > UserSig Generation & Verification.
2. Select the corresponding SDKAppID and UserID under the UserSig generation tool.
3. Click Generate Signature (UserSig) to calculate the corresponding UserSig.

How do I calculate UserSig during production?

During production, TRTC provides a more secure scheme of using the server to calculate UserSig. It offers the utmost protection against key leakage, for it is more difficult to hack a server than it is to reverse engineer an application. See below for the specific implementation process:

1. Before your application calls the SDK initialization function, request UserSig from your server.
2. Your server will calculate a UserSig based on the SDKAppID and UserID. The calculation source code is provided above.
3. The sever returns the UserSig to your application.
4. Your application sends the UserSig to the SDK through a specific API.
5. The SDK submits the SDKAppID + UserID + UserSig to the Tencent Cloud server for verification.
6. Tencent Cloud verifies the validity of the UserSig.
7. If the UserSig is valid, real time audio/video services will be provided to the TRTC SDK.

To simplify your implementation process, we provide UserSig calculation source code in multiple languages (new signature algorithm):

Programming Language	Signature Algorithm	Key Function	Download Link
Java	HMAC-SHA256	genSig	Github
Go	HMAC-SHA256	GenSig	GitHub
PHP	HMAC-SHA256	genSig	Github
Node.js	HMAC-SHA256	genSig	GitHub
Python	HMAC-SHA256	genSig	Github
C#	HMAC-SHA256	GenSig	Github

Legacy signature algorithm for calculating UserSig

To simplify the signature calculation process and facilitate your use of Tencent Cloud services, on July 19, 2019, TRTC switched from ECDSA-SHA256 to the new signature algorithm HMAC-SHA256. This means that all applications (SDKAppID) created on and after July 19, 2019 will use the new HMAC-SHA256 algorithm.

If your application (SDKAppID) was created before July 19, 2019, you can continue to use the old signature algorithm, whose source code can be downloaded in the below links.

Programing Language	Signature Algorithm	Download Link
Java	ECDSA-SHA256	GitHub
C++	ECDSA-SHA256	GitHub
Go	ECDSA-SHA256	GitHub
PHP	ECDSA-SHA256	GitHub
Node.js	ECDSA-SHA256	GitHub
C#	ECDSA-SHA256	GitHub
Python	ECDSA-SHA256	GitHub