From 570135b1ae052527140efd95517ee1cc8c304d4b Mon Sep 17 00:00:00 2001 From: wesleytong Date: Fri, 25 Feb 2022 14:53:53 +0800 Subject: [PATCH 1/3] =?UTF-8?q?=E4=B8=AD=E6=96=87=E7=BF=BB=E8=AF=91?= =?UTF-8?q?=E4=B8=BA=E8=8B=B1=E6=96=87?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/tls_sig_api_v2.cpp | 10 ++++-- src/tls_sig_api_v2.h | 76 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 84 insertions(+), 2 deletions(-) diff --git a/src/tls_sig_api_v2.cpp b/src/tls_sig_api_v2.cpp index c14b6c0..0daacdc 100644 --- a/src/tls_sig_api_v2.cpp +++ b/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(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) { diff --git a/src/tls_sig_api_v2.h b/src/tls_sig_api_v2.h index 1c29699..fa41aca 100644 --- a/src/tls_sig_api_v2.h +++ b/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 - 计算 usersig 用的加密密钥,控制台可获取。 + * @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 - 计算 usersig 用的加密密钥,控制台可获取。 + * @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 - 计算 usersig 用的加密密钥,控制台可获取。 + * @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); From a09d518b940f6b7977be6a329ba2e5b8a125f626 Mon Sep 17 00:00:00 2001 From: wesleytong Date: Fri, 25 Feb 2022 14:54:14 +0800 Subject: [PATCH 2/3] =?UTF-8?q?=E6=96=B0=E5=A2=9E=E8=8B=B1=E6=96=87?= =?UTF-8?q?=E7=89=88MD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README_EN.md | 98 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 README_EN.md diff --git a/README_EN.md b/README_EN.md new file mode 100644 index 0000000..4c8d64e --- /dev/null +++ b/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 +#include + +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(); +``` + From 99cf44b34564454beafb5f6aa18cd04550314053 Mon Sep 17 00:00:00 2001 From: wesleytong Date: Fri, 25 Feb 2022 15:39:49 +0800 Subject: [PATCH 3/3] =?UTF-8?q?=E4=BF=AE=E6=94=B9=E9=83=A8=E5=88=86?= =?UTF-8?q?=E7=BF=BB=E8=AF=91?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/tls_sig_api_v2.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/tls_sig_api_v2.h b/src/tls_sig_api_v2.h index fa41aca..a99528e 100644 --- a/src/tls_sig_api_v2.h +++ b/src/tls_sig_api_v2.h @@ -50,7 +50,7 @@ enum { * 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 - 计算 usersig 用的加密密钥,控制台可获取。 + * @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. @@ -102,7 +102,7 @@ TLS_API int genUserSig(uint32_t sdkappid, const std::string &userid, const std:: * 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 - 计算 usersig 用的加密密钥,控制台可获取。 + * @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: @@ -166,7 +166,7 @@ TLS_API int genPrivateMapKey(uint32_t sdkappid, const std::string &userid, const * 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 - 计算 usersig 用的加密密钥,控制台可获取。 + * @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: