Dev wesleytong

README_EN.md

@@ -0,0 +1,98 @@
+## Note
+This project is the C++ implementation of tls-sig-api-v2. Previous asymmetric keys cannot use APIs of this version. To enable them to use APIs of this version, [see here](https://github.com/tencentyun/tls-sig-api)。
+
+## Download code and sync dependencies
+```shell
+git clone https://github.com/tencentyun/tls-sig-api-v2-cpp.git
+cd tls-sig-api-v2-cpp
+git submodule update --init --recursive
+```
+
+If the above code sync fails, download the source code [here](https://github.com/tencentyun/tls-sig-api-v2-cpp/releases).
+
+## Build
+
+### Unix-like system
+`CMake` 、 `Make` and `GCC` are required for project building. Ensure that they have been installed.
+```shell
+cmake CMakeLists.txt
+cmake --build .
+```
+
+If you need to manually specify the OpenSSL path, add the following commands when running the `cmake CMakeLists.txt`  command:
+```shell
+cmake  -DOPENSSL_ROOT_DIR=your_openssl_root_dir CMakeLists.txt
+cmake --build .
+```
+
+The header file path is as follows:
+```
+src/tls_sig_api_v2.h
+```
+
+The library file path is as follows:
+```
+
+./libtlssigapi_v2.a
+```
+
+In addition to linking `libtlssigapi_v2.a`, you need to introduce `zlib`  and `openssl` when building a project. They usually come with Unix-like systems, and you only need to add the following command:
+```
+-lz -lcrypto
+```
+
+### Windows
+Project building in Windows depends on `CMake` and `Visual Studio`. Ensure that they have been installed.
+
+```
+.\build.bat
+```
+
+The header file path is as follows:
+
+```
+src/tls_sig_api_v2.h
+```
+
+The library file paths are as follows (including Win32 and x64 as well as Debug and Release versions):
+```
+tls-sig-api_xx/xxxx/tlssigapi_v2.lib
+tls-sig-api_xx/xxxx/zlibstatic.lib
+tls-sig-api_xx/xxxx/mbedcrypto.lib
+```
+zlib of the Debug version is named zlibstaticd.lib.
+
+When building a project, you only need to reference the header file `src/tls_sig_api_v2.h` and the three library files above.
+
+## Usage
+
+### API usage
+
+```C
+#include "tls_sig_api_v2.h"
+#include <string>
+#include <iostream>
+
+std::string key = "5bd2850fff3ecb11d7c805251c51ee463a25727bddc2385f3fa8bfee1bb93b5e";
+
+std::string sig;
+std::sgring errmsg;
+int ret = genUserSig(140000000, "xiaojun", key, 180*86400, sig, errmsg);
+if (0 != ret) {
+	std::cout << "genUserSig failed " << ret << " " << errmsg << std::endl;
+} else {
+	std::cout << "genUserSig " << sig << std::endl;
+}
+
+```
+
+### Multi-thread support
+Because Unix-like systems use OpenSSL by default, you need to call the following function during multi-thread program initialization. This issue does not exist in the Windows version.
+```C
+thread_setup();
+```
+Call the following function when the program ends:
+```C
+thread_cleanup();
+```
+

src/tls_sig_api_v2.cpp

@@ -43,7 +43,8 @@ static std::string hmacsha256(uint32_t sdkappid, const std::string &identifier,
 static std::string hmacsha256(uint32_t sdkappid, const std::string &identifier, uint64_t init_time, uint64_t expire,
                               const std::string &key, const std::string &userbuf);
 
-//去掉某些 base64 中生成的 \r\n space
+// 去掉某些 base64 中生成的 \r\n space
+// Remove some generated \r\n spaces in base64
 static std::string base64_strip(const void *data, size_t data_len) {
   const char *d = static_cast<const char *>(data);
   std::string s;
@@ -195,29 +196,34 @@ static std::string __hmacsha256(uint32_t sdkappid, const std::string &identifier
 }
 
 // 使用 hmac sha256 生成 sig
+// Generate sig using hmac sha256
 static std::string hmacsha256(uint32_t sdkappid, const std::string &identifier, uint64_t init_time, uint64_t expire,
                               const std::string &key) {
   return __hmacsha256(sdkappid, identifier, init_time, expire, key, "", false);
 }
 
 // 使用 hmac sha256 生成带 userbuf 的 sig
+// Generate sig with userbuf using hmac sha256
 static std::string hmacsha256(uint32_t sdkappid, const std::string &identifier, uint64_t init_time, uint64_t expire,
                               const std::string &key, const std::string &base64_userbuf) {
   return __hmacsha256(sdkappid, identifier, init_time, expire, key, base64_userbuf, true);
 }
 // 生成签名
+// Generate signature
 TLS_API int genUserSig(uint32_t sdkappid, const std::string &userid, const std::string &key, int expire,
                        std::string &usersig, std::string &errmsg) {
   return genSig(sdkappid, userid, key, "", expire, usersig, errmsg);
 }
 
-// 生成带 userbuf 的签名
+// 生成带 userbuf 的签名 
+// Signature with userbuf generated
 TLS_API int genPrivateMapKey(uint32_t sdkappid, const std::string &userid, const std::string &key, uint32_t roomid,
                              int expire, int privilegeMap, std::string &usersig, std::string &errmsg) {
   std::string userbuf = gen_userbuf(userid, sdkappid, roomid, expire, privilegeMap, 0, "");
   return genSig(sdkappid, userid, key, userbuf, expire, usersig, errmsg);
 }
 // 生成带 userbuf 的签名,字符串房间号
+// Signature with userbuf generated, String-type room ID
 TLS_API int genPrivateMapKeyWithStringRoomID(uint32_t sdkappid, const std::string &userid, const std::string &key,
                                              const std::string &roomstr, int expire, int privilegeMap,
                                              std::string &usersig, std::string &errmsg) {

src/tls_sig_api_v2.h

@@ -43,6 +43,20 @@ enum {
  * @param errmsg - 错误信息。
  * @return 0 为成功，非 0 为失败
  */
+
+/**
+ * Function: Used to issue UserSig that is required by the TRTC and IM services.
+ *
+ * Parameter description:
+ * @param sdkappid - Application ID
+ * @param userid - User ID. The value can be up to 32 bytes in length and contain letters (a-z and A-Z), digits (0-9), underscores (_), and hyphens (-).
+ * @param key - The encryption key used to calculate usersig can be obtained from the console.
+ * @param expire - UserSig expiration time, in seconds. For example, 86400 indicates that the generated UserSig will expire one day after being generated.
+ * @param usersig - Generated signature.
+ * @param errmsg - error message.
+ * @return 0 for success, non-0 for failure
+ */
+
 TLS_API int genUserSig(uint32_t sdkappid, const std::string &userid, const std::string &key, int expire,
                        std::string &usersig, std::string &errmsg);
 
@@ -76,6 +90,37 @@ TLS_API int genUserSig(uint32_t sdkappid, const std::string &userid, const std::
  * @param errmsg - 错误信息。
  * @return 0 为成功，非 0 为失败
  */
+
+/**
+ * Function:
+ * Used to issue PrivateMapKey that is optional for room entry.
+ * PrivateMapKey must be used together with UserSig but with more powerful permission control capabilities.
+ *  - UserSig can only control whether a UserID has permission to use the TRTC service. As long as the UserSig is correct, the user with the corresponding UserID can enter or leave any room.
+ *  - PrivateMapKey specifies more stringent permissions for a UserID, including whether the UserID can be used to enter a specific room and perform audio/video upstreaming in the room.
+ * To enable stringent PrivateMapKey permission bit verification, you need to enable permission key in TRTC console > Application Management > Application Info.
+ *
+ * Parameter description:
+ * @param sdkappid - Application ID
+ * @param userid - User ID. The value can be up to 32 bytes in length and contain letters (a-z and A-Z), digits (0-9), underscores (_), and hyphens (-).
+ * @param key - The encryption key used to calculate usersig can be obtained from the console.
+ * @param roomid - ID of the room to which the specified UserID can enter.
+ * @param expire - PrivateMapKey expiration time, in seconds. For example, 86400 indicates that the generated PrivateMapKey will expire one day after being generated.
+ * @param privilegeMap - Permission bits. Eight bits in the same byte are used as the permission switches of eight specific features:
+ *  - Bit 1: 0000 0001 = 1, permission for room creation
+ *  - Bit 2: 0000 0010 = 2, permission for room entry
+ *  - Bit 3: 0000 0100 = 4, permission for audio sending
+ *  - Bit 4: 0000 1000 = 8, permission for audio receiving
+ *  - Bit 5: 0001 0000 = 16, permission for video sending
+ *  - Bit 6: 0010 0000 = 32, permission for video receiving
+ *  - Bit 7: 0100 0000 = 64, permission for substream video sending (screen sharing)
+ *  - Bit 8: 1000 0000 = 200, permission for substream video receiving (screen sharing)
+ *  - privilegeMap == 1111 1111 == 255: Indicates that the UserID has all feature permissions of the room specified by roomid.
+ *  - privilegeMap == 0010 1010 == 42: Indicates that the UserID has only the permissions to enter the room and receive audio/video data.
+ * @param usersig -Generated signature
+ * @param errmsg - error message.
+ * @return 0 for success, non-0 for failure
+ */
+
 TLS_API int genPrivateMapKey(uint32_t sdkappid, const std::string &userid, const std::string &key, uint32_t roomid,
                              int expire, int privilegeMap, std::string &usersig, std::string &errmsg);
 
@@ -109,6 +154,37 @@ TLS_API int genPrivateMapKey(uint32_t sdkappid, const std::string &userid, const
  * @param errmsg - 错误信息。
  * @return 0 为成功，非 0 为失败
  */
+
+/**
+ * Function:
+ * Used to issue PrivateMapKey that is optional for room entry.
+ * PrivateMapKey must be used together with UserSig but with more powerful permission control capabilities.
+ *  - UserSig can only control whether a UserID has permission to use the TRTC service. As long as the UserSig is correct, the user with the corresponding UserID can enter or leave any room.
+ *  - PrivateMapKey specifies more stringent permissions for a UserID, including whether the UserID can be used to enter a specific room and perform audio/video upstreaming in the room.
+ * To enable stringent PrivateMapKey permission bit verification, you need to enable permission key in TRTC console > Application Management > Application Info.
+ *
+ * Parameter description:
+ * @param sdkappid - Application ID
+ * @param userid - User ID. The value can be up to 32 bytes in length and contain letters (a-z and A-Z), digits (0-9), underscores (_), and hyphens (-).
+ * @param key - The encryption key used to calculate usersig can be obtained from the console.
+ * @param roomstr - ID of the room to which the specified UserID can enter.
+ * @param expire - PrivateMapKey expiration time, in seconds. For example, 86400 indicates that the generated PrivateMapKey will expire one day after being generated.
+ * @param privilegeMap - Permission bits. Eight bits in the same byte are used as the permission switches of eight specific features:
+ *  - Bit 1: 0000 0001 = 1, permission for room creation
+ *  - Bit 2: 0000 0010 = 2, permission for room entry
+ *  - Bit 3: 0000 0100 = 4, permission for audio sending
+ *  - Bit 4: 0000 1000 = 8, permission for audio receiving
+ *  - Bit 5: 0001 0000 = 16, permission for video sending
+ *  - Bit 6: 0010 0000 = 32, permission for video receiving
+ *  - Bit 7: 0100 0000 = 64, permission for substream video sending (screen sharing)
+ *  - Bit 8: 1000 0000 = 200, permission for substream video receiving (screen sharing)
+ *  - privilegeMap == 1111 1111 == 255: Indicates that the UserID has all feature permissions of the room specified by roomid.
+ *  - privilegeMap == 0010 1010 == 42: Indicates that the UserID has only the permissions to enter the room and receive audio/video data.
+ * @param usersig - Generated signature
+ * @param errmsg - error message.
+ * @return 0 for success, non-0 for failure
+ */
+
 TLS_API int genPrivateMapKeyWithStringRoomID(uint32_t sdkappid, const std::string &userid, const std::string &key,
                                              const std::string &roomstr, int expire, int privilegeMap,
                                              std::string &usersig, std::string &errmsg);