{"en_US": {"title": "Security authentication", "content": "The platform needs to verify the resource permissions of the API caller, and when using the API, it needs to carry the unified security authentication information in the request header.\n\n## Authentication methods in different scenarios\n\n![](Security Authentication.png.d/Security Authentication-1.drawio.png)\n\n* **The platform supports three authentication methods: user authentication, product authentication, and project authentication**\n\n**Not transferred after adding device**:\n\n1. If the device has not been transferred, but the project is bound, user authentication and project authentication are supported.\n\n2. If the device has not been transferred and no items are bound, user authentication and product authentication are supported.\n\n**Device transfer after adding a device**:\n\n1. When the user tries to \"transfer the device\" on the platform, he or she needs to unbind the project before the transfer can be carried out.\n\n2. After the transfer, when the project is bound again, [User Authentication] and [Project Authentication] are supported.\n\n3. After the transfer, if there is no bound project, only [User Authentication] is supported.\n\n#### Security authentication mechanism\n\nAn authentication authorization consists of multiple parameters, each of which is represented by key = value and delimiter with &. as the delimiter.\n\n```text\nauthorization: version=2022-05-01&res=userid%2F{userId}&et={expireTime}&method=sha1&sign={sign}\n```\n\n#### Token generation tool\n\n* In order to facilitate developers' development, RINGA provides a token generation tool, which can quickly generate security authentication information after filling in the fields. Go to download [Click to jump to document](/doc/v5/fuse/detail/402)\n\n##### Parameter description\n\n| Serial number | Parameter | Type | Description | Example |\n|:- | :- | :- | :- | :- |\n|1 | version | string | Signature Algorithm Version | Currently, only 2022-05-01 |\n|2 | res | string | Access resource information | There are three ways to authenticate: the main user, product, and project:
1) The main user access res is: userid/{userid}, userid is the platform user ID, access_key is the main user access_key, and the parameters are viewed in the personal \"account information\" and \"access permission\".
2) The product access res is: products/{productid}, access_key is the product access_key, enter the \"Product List\" in the \"Product Development\" menu, click the \"Product Development\" link under the \"Operation\" column, and enter the \"Product Information Page\" to view.
3) Project access res is: projects/{projectid}, access_key is the project key, enter the \"My Projects\" list in the \"Application Development\" - \"Project Management\" menu, click the \"Enter Project Management\" link under the \"Operation\" column, enter the \"Project Information Page\", and view it in the \"Project Information\" of \"Project Overview\".

   Note* The different access_key mentioned above are described in detail below|\n|3 | et | string | Access expiration time | The 10-bit second-level timestamp 1537255523 indicates: Beijing time 2018-09-18 15:25:23 |\n|4 | method | string | Signature method | MD5, SHA1, and SHA256 | are supported|\n|5 | sign | string | Signature result string      | version, res, et, and method parameters are calculated and generated with |\n\n#### Obtain the accessKey pair parameter\n\n###### accessKey pair of the primary user\n\n![](Security Authentication.png.d/Security Authentication-2.png)\n\n###### accessKey pair of the product\n\n![](Security Authentication.png.d/Security Authentication-3.png)\n\n![](Security Authentication.png.d/Security Authentication-4.png)\n\n###### Project accessKey pair\n\n![](Security Authentication.png.d/Security Authentication-5.png)\n\n![](Security Authentication.png.d/Security Authentication-6.png)\n\nThe algorithm for generating a sign is:\n\n```c++\nsign = base64(hmac_(base64decode(accessKey), utf8(stringForSignature)))\n```\n\n* accessKey is the access key assigned by the platform (view on the user access rights page), if the access resource is accessed as the master user, the accessKey pair of the master user is used; If the access resource is in the form of a product, the accesskey pair of the product is used and can only be used on devices under the product. If you want to access resources in project mode, you can use the accesskey pair of the project and perform operations only on devices that belong to the project.\n\n* The accessKey pair must be used to perform the base64decode operation before participating in the calculation.\n\n* The string used to calculate the signature stringForSignature is et,method, res, version, and \"\\n\" is arranged as a delimiter as follows:\n\n```js\nstringForSignature = et + \"\\n\" + method + \"\\n\" + res + \"\\n\" + version\n```\n\n##### Parameter encoding\n\nThe value part of the key=value in the authorization needs to be encoded by URL, and the special symbols that need to be encoded are as follows:\n\n|serial number | Symbol | Encoding |\n|:- | :- | :- |\n|1 | + | %2B |\n|2 | Space | %20 |\n|3 | / | %2F |\n|4 | ? | %3F |\n|5 | % | %25 |\n|6 | # | %23 |\n|7 | & | %26 |\n|8 | = | %3D |\n\n##### Authorization generates an example\n\n###### nodejs code samples\n\n```js\n'use strict';\n\nconst crypto = require('crypto');\n\n/**\n * authorization generation function\n*\n * @param {string} method - hash method\n * @param {string} res - resource\n * @param {string} accessKey - access key\n * @param {Number} et - effective time\n * @return {string} - authorization\n */\nfunction generateAuthorization(method, res, accessKey, et) {\n const version = '2022-05-01';\n const et = Math.ceil((Date.now() + et) / 1000); //The validity period of the token\n const base64Key = Buffer.from(accessKey, 'base64'); accessKey base 64 encoded\n const stringForSignature = et + '\\n' + method + '\\n' + res + '\\n' + version;\n const sign = encodeURIComponent(crypto.createHmac(method, base64Key).update(stringForSignature).digest('base64'));\n const encodeRes = encodeURIComponent(res);\n\n return `version=${version}&res=${encodeRes}&et=${et}&method=${method}&sign=${sign}`;\n}\n\nconst method = 'sha1';\nconst accessKey = 'mjgvkTCYTBF6DguxMmm+aV9EkDp2CYfL5jzRTph5Th6KhU8gqZz/cBivPTA7tfY5';\nconst res = 'userid/130037';\nconst et = 3600 * 1000; //Valid time: 1 hour\nconst authorization = generateAuthorization(method, res, accessKey, et);\n\n```\n\n###### Python code examples\n\n```python\n import base64\n import hmac\n import time\n from urllib.parse import quote\n\ndef token(user_id,access_key):\n version = '2022-05-01'\n res = 'userid/%s' % user_id\n # User-defined token expiration time\n et = str(int(time.time()) + 3600)\n # Signature method, MD5, SHA1, SHA256 are supported\n method = 'sha1'\n # Decode the access_key\n key = base64.b64decode(access_key)\n # Calculate the sign\n org = et + '\\n' + method + '\\n' + res + '\\n' + version\n sign_b = hmac.new(key=key, msg=org.encode(), digestmod=method)\n sign = base64.b64encode(sign_b.digest()).decode()\n # The value part is URL encoded, and the method/res/version value is simple and does not need to be encoded\n sign = quote(sign, safe='')\n res = quote(res, safe='')\n # Concatenate token parameters\n token = 'version=%s&res=%s&et=%s&method=%s&sign=%s' % (version, res, et, method, sign)\n\nreturn token\n\nif __name__ == '__main__':\n user_id = '37715'\n access_key = 'mjgvkTCYTBF6DguxMmm+aV9EkDp2CYfL5jzRTph5Th6KhU8gqZz/cBivPTA7tfY5'\n\nprint(token(user_id,access_key))\n```\n\n###### Java code samples\n\n```java\n import javax.crypto.Mac;\n import javax.crypto.spec.SecretKeySpec;\n import java.io.UnsupportedEncodingException;\n import java.net.URLEncoder;\n import java.security.InvalidKeyException;\n import java.security.NoSuchAlgorithmException;\n import java.util.Base64;\n\n public class Token {\n\n public static String assembleToken(String version, String resourceName, String expirationTime, String signatureMethod, String accessKey)\n throws UnsupportedEncodingException, NoSuchAlgorithmException, InvalidKeyException {\n StringBuilder sb = new StringBuilder();\n String res = URLEncoder.encode(resourceName, \"UTF-8\");\n String sig = URLEncoder.encode(generatorSignature(version, resourceName, expirationTime, accessKey, signatureMethod), \"UTF-8\");\n sb.append(\"version=\")\n .append(version)\n .append(\"&res=\")\n .append(res)\n .append(\"&et=\")\n .append(expirationTime)\n .append(\"&method=\")\n .append(signatureMethod)\n .append(\"&sign=\")\n .append(sig);\n return sb.toString();\n }\n\n public static String generatorSignature(String version, String resourceName, String expirationTime, String accessKey, String signatureMethod)\n throws NoSuchAlgorithmException, InvalidKeyException {\n String encryptText = expirationTime + \"\\n\" + signatureMethod + \"\\n\" + resourceName + \"\\n\" + version;\n String signature;\n byte[] bytes = HmacEncrypt(encryptText, accessKey, signatureMethod);\n signature = Base64.getEncoder().encodeToString(bytes);\n return signature;\n }\n\n public static byte[] HmacEncrypt(String data, String key, String signatureMethod)\n throws NoSuchAlgorithmException, InvalidKeyException {\n //A key is constructed from a given byte array, and the second parameter specifies the name of a key algorithm\n SecretKeySpec signinKey = null;\n signinKey = new SecretKeySpec(Base64.getDecoder().decode(key),\n \"Hmac\" + signatureMethod.toUpperCase());\n //Generates a Mac object of designed Mac algorithm\n Mac mac = null;\n mac = Mac.getInstance(\"Hmac\" + signatureMethod.toUpperCase());\n //Initialize the Mac object with the given key\n mac.init(signinKey);\n // finish Mac caculation\n return mac.doFinal(data.getBytes());\n }\n\n public enum SignatureMethod {\n SHA1, MD5, SHA256;\n }\n\n public static void main(String[] args) throws UnsupportedEncodingException, NoSuchAlgorithmException, InvalidKeyException {\n String version = \"2022-05-01\";\n String resourceName = \"userid/12321\";\n //The expiration time of the user-defined token\n String expirationTime = System.currentTimeMillis() / 1000 + 3600 + \"\";\n String signatureMethod = SignatureMethod.SHA1.name().toLowerCase();\n String accessKey = \"KuF3NT/jUBJ62LNBB/A8XZA9CqS3Cu79B/ABmfA1UCw=\";\n String token = assembleToken(version, resourceName, expirationTime, signatureMethod, accessKey);\n System.out.println(\"Authorization:\" + token);\n }\n }\n```\n\n###### go code samples\n\n```go\nfunc (s *SignService) GenerateSign(params_map map[string]string, access_key string) (string, error){\n signature_str := params_map[\"et\"] + \"\\n\" + params_map[\"method\"] + \"\\n\" + params_map[\"res\"] + \"\\n\" + params_map[\"version\"]\n hmac_str := \"\"\n switch strings. ToLower(params_map[\"method\"]) {\n case \"sha1\":\n hmac_str = tools.HmacSha1(signature_str, tools.Base64Decode(access_key))\n case \"sha256\":\n hmac_str = tools.HmacSha256(signature_str, tools.Base64Decode(access_key))\n case \"md5\":\n hmac_str = tools.HmacMd5(signature_str, tools.Base64Decode(access_key))\n default:\n return \"\",errors. New(\"Signature parameter error!\") )\n }\n\n sign:=tools. Base64Encode(hmac_str)\n return sign,nil\n}\n\nfunc Base64Encode(message string) string {\n return base64. StdEncoding.EncodeTostring([]byte(message))\n}\n\nfunc Base64Decode(message string) string {\n decode_str, err := base64.StdEncoding.Decodestring(message)\n if err != nil {\n return \"\"\n }\n return string(decode_str)\n}\n\nfunc HmacSha256(data string, secret string) string {\n h := hmac.New(sha256.New, []byte(secret))\n h.Write([]byte(data))\n return string(h.Sum(nil))\n}\n\nfunc HmacMd5(data string, secret string) string {\n h := hmac.New(md5.New, []byte(secret))\n h.Write([]byte(data))\n return string(h.Sum(nil))\n}\n\nfunc HmacSha1(data string, secret string) string {\n h := hmac.New(sha1.New, []byte(secret))\n h.Write([]byte(data))\n return string(h.Sum(nil))\n}\n```\n\n######\n\nPHP code sample\n\n```php\nclass SafetyAuth\n{\n private  $_version = '2022-05-01'; //version\n private  $_method = 'sha1'; //Encryption methods can also be used with MD5 and SHA256\n private  $_access_key; Access keys\n private $_res ;//resource parameters\n private  $_et; Expiration timestamp\n private  $_expiration; Expiration date, validity period\n\n public function __construct($access_key, $expiration,$res){\n $this->_expiration = $expiration;\n $this->_access_key = $access_key;\n $this->_res = $res;\n }\n\n //Generate sign\n private function _makeSign() {\n date_default_timezone_set('PRC');\n $this->_et =time() + $this->_expiration;\n $string_for_signature = $this->_et . \"\\n\" . $this->_method . \"\\n\" . $this->_res  . \"\\n\" . $this->_version;\n $b64_decode_acckey = base64_decode($this->_access_key);\n $hmac_key = hash_hmac($this->_method, $this->_strToUtf8($string_for_signature), $b64_decode_acckey, true);\n $sign = base64_encode($hmac_key);\n return $sign;\n }\n\n private function _strToUtf8($str) {\n $encode = mb_detect_encoding($str, array(\"ASCII\",'UTF-8',\"GB2312\",\"GBK\",'BIG5'));\n if ($encode == 'UTF-8') {\n return $str;\n } else {\n return mb_convert_encoding($str, 'UTF-8', $encode);\n }\n }\n\n // Generate tokens\n public function makeToken() {\n $sign = $this->_makeSign();\n $token = sprintf(\"version=2022-05-01&res=%s&et=%s&method=sha1&sign=%s\", urlencode($this->_res), $this->_et, urlencode($sign));\n return $token;\n }\n}\n```"}, "zh_CN": {"title": "安全鉴权", "content": "平台需要对API调用方进行资源权限校验，使用API时，需要在请求Header中携带统一的安全鉴权信息。\n\n## 不同情形下的鉴权方式\n\n![](https://upfiles.heclouds.com/portal5-admin/portal5-admin/2024/05/21/26b17278f7106579fc53a0b7efb74dd9.png)\n\n* **平台支持三种鉴权方式：用户鉴权、产品鉴权、项目鉴权**\n\n* **添加设备后未转移**：\n\n1、设备未转移，但绑定了项目时，鉴权支持【用户鉴权】、【项目鉴权】。\n\n2、设备未转移，且没有绑定任何项目时，鉴权支持【用户鉴权】、【产品鉴权】。\n\n* **添加设备后进行设备转移**：\n\n1、用户在平台尝试“设备转移”时，需要先解除项目绑定，才能进行转移操作。\n\n2、转移后，再次绑定项目时，支持【用户鉴权】、【项目鉴权】。\n\n3、转移后，没有绑定项目时，仅支持【用户鉴权】。\n\n#### 安全鉴权机制\n\n安全鉴权authorization由多个参数构成，每个参数均采用key = value的形式表示，并用&作为分隔符：\n\n```text\nauthorization: version=2022-05-01&res=userid%2F{userId}&et={expireTime}&method=sha1&sign={sign}\n```\n\n#### Token生成工具\n\n* 为便于开发者开发，RINGA提供了Token生成工具，填写字段后可以快速生成安全鉴权信息。前往下载[【点击跳转文档】](/doc/v5/fuse/detail/402)\n\n##### 参数说明\n\n| 序号 | 参数 | 类型 | 说明 | 示例 |\n|:- | :- | :- | :- | :- |\n|1 | version | string | 签名算法版本 | 目前仅支持 2022-05-01 |\n|2 | res | string | 访问资源信息 | 支持主用户、产品、项目三种方式：
1）主用户访问res为：userid/{userid}, userid为平台用户id，access_key为主用户access_key，参数在个人「账号信息」、「访问权限」中查看。
2）产品访问res为：products/{productid}，access_key为产品access_key，进入「产品开发」菜单的「产品列表」中，点击「操作」列下的「产品开发」链接，进入「产品信息页面」查看。
3）项目访问res为：projects/{projectid}，access_key为项目key，进入「应用开发」-「项目管理」菜单的「我的项目」列表中，点击「操作」列下的「进入项目管理」链接，进入「项目信息页面」，在「项目概况」的「项目信息」中查看。

   注* 以上提到的不同access_key获取方式在下文中会有详细描述 |\n|3 | et | string | 访问过期时间 | 10位秒级时间戳，1537255523 表示：北京时间 2018-09-18 15:25:23 |\n|4 | method | string | 签名方法 | 目前支持md5、sha1、sha256 |\n|5 | sign | string | 签名结果字符串      | version、res、et、method参数计算生成 |\n\n#### accessKey参数获取\n\n###### 主用户accessKey\n\n![](https://upfiles.heclouds.com/portal5-admin/portal5-admin/2023/05/18/a507874650779a0bc60a53aa5bd43763.png)\n\n###### 产品accessKey\n\n![](https://upfiles.heclouds.com/portal5-admin/portal5-admin/2024/05/13/8b6ec7f43c31d07f7618504d0f882f0b.png)\n\n![](https://upfiles.heclouds.com/portal5-admin/portal5-admin/2024/05/13/503cb1e1cacca7aee2ee8e67b854dc55.png)\n\n###### 项目accessKey\n\n![](https://upfiles.heclouds.com/portal5-admin/portal5-admin/2024/05/13/6d784cfce5f7f12c38687f2aad79be3f.png)\n\n![](https://upfiles.heclouds.com/portal5-admin/portal5-admin/2024/05/13/e8755acbcfabf5b2f12dddf778600081.png)\n\nsign的生成算法为:\n\n```c++\nsign = base64(hmac_(base64decode(accessKey), utf8(stringForSignature)))\n```\n\n* accessKey为平台分配的访问密钥（用户访问权限页面查看），如果访问资源以主用户形式访问, 使用主用户的accessKey；如果访问资源以产品方式访问，使用产品的accessKey，且只能对产品下的设备进行操作；如果访问资源以项目方式访问，使用项目的accessKey，且只能对项目下的设备进行操作。\n\n* accessKey参与计算前应先进行base64decode操作。\n\n* 用于计算签名的字符串 stringForSignature按照et、method、res、version的顺序，以\"\n\n\"作为分隔符进行排列，如下所示：\n\n```c\nstringForSignature = et + \"\\n\" + method + \"\\n\" + res + \"\\n\" + version\n```\n\n##### 参数编码\n\nauthorization中key=value的形式的value部分需要经过URL编码，需要进行编码的特殊符号如下：\n\n|序号 | 符号 | 编码 |\n|:- | :- | :- |\n|1 | + | %2B |\n|2 | 空格 | %20 |\n|3 | / | %2F |\n|4 | ? | %3F |\n|5 | % | %25 |\n|6 | # | %23 |\n|7 | & | %26 |\n|8 | = | %3D |\n\n##### authorization生成示例\n\n###### nodejs代码示例\n\n```js\n'use strict';\n\nconst crypto = require('crypto');\n\n/**\n * authorization生成函数\n *\n * @param {string} method - hash method\n * @param {string} res - resource\n * @param {string} accessKey - access key\n * @param {Number} et - effective time\n * @return {string} - authorization\n */\nfunction generateAuthorization(method, res, accessKey, et) {\n const version = '2022-05-01';\n const et = Math.ceil((Date.now() + et) / 1000); // token有效时间\n const base64Key = Buffer.from(accessKey, 'base64'); // accessKey base64编码\n const stringForSignature = et + '\\n' + method + '\\n' + res + '\\n' + version;\n const sign = encodeURIComponent(crypto.createHmac(method, base64Key).update(stringForSignature).digest('base64'));\n const encodeRes = encodeURIComponent(res);\n\n return `version=${version}&res=${encodeRes}&et=${et}&method=${method}&sign=${sign}`;\n}\n\nconst method = 'sha1';\nconst accessKey = 'mjgvkTCYTBF6DguxMmm+aV9EkDp2CYfL5jzRTph5Th6KhU8gqZz/cBivPTA7tfY5';\nconst res = 'userid/130037';\nconst et = 3600 * 1000; // 有效时间:1小时\nconst authorization = generateAuthorization(method, res, accessKey, et);\n\n```\n\n###### python代码示例\n\n```python\n import base64\n import hmac\n import time\n from urllib.parse import quote\n\n def token(user_id,access_key):\n version = '2022-05-01'\n res = 'userid/%s' % user_id\n # 用户自定义token过期时间\n et = str(int(time.time()) + 3600)\n # 签名方法，支持md5、sha1、sha256\n method = 'sha1'\n # 对access_key进行decode\n key = base64.b64decode(access_key)\n # 计算sign\n org = et + '\n' + method + '\n' + res + '\n' + version\n sign_b = hmac.new(key=key, msg=org.encode(), digestmod=method)\n sign = base64.b64encode(sign_b.digest()).decode()\n # value 部分进行url编码，method/res/version值较为简单无需编码\n sign = quote(sign, safe='')\n res = quote(res, safe='')\n # token参数拼接\n token = 'version=%s&res=%s&et=%s&method=%s&sign=%s' % (version, res, et, method, sign)\n\n return token\n\n if __name__ == '__main__':\n user_id = '37715'\n access_key = 'mjgvkTCYTBF6DguxMmm+aV9EkDp2CYfL5jzRTph5Th6KhU8gqZz/cBivPTA7tfY5'\n\n print(token(user_id,access_key))\n```\n\n###### Java代码示例\n\n```java\n import javax.crypto.Mac;\n import javax.crypto.spec.SecretKeySpec;\n import java.io.UnsupportedEncodingException;\n import java.net.URLEncoder;\n import java.security.InvalidKeyException;\n import java.security.NoSuchAlgorithmException;\n import java.util.Base64;\n\n public class Token {\n\n public static string assembleToken(string version, string resourceName, string expirationTime, string signatureMethod, string accessKey)\n throws UnsupportedEncodingException, NoSuchAlgorithmException, InvalidKeyException {\n stringBuilder sb = new stringBuilder();\n string res = URLEncoder.encode(resourceName, \"UTF-8\");\n string sig = URLEncoder.encode(generatorSignature(version, resourceName, expirationTime, accessKey, signatureMethod), \"UTF-8\");\n sb.append(\"version=\")\n .append(version)\n .append(\"&res=\")\n .append(res)\n .append(\"&et=\")\n .append(expirationTime)\n .append(\"&method=\")\n .append(signatureMethod)\n .append(\"&sign=\")\n .append(sig);\n return sb.tostring();\n }\n\n public static string generatorSignature(string version, string resourceName, string expirationTime, string accessKey, string signatureMethod)\n throws NoSuchAlgorithmException, InvalidKeyException {\n string encryptText = expirationTime + \"\n\" + signatureMethod + \"\n\" + resourceName + \"\n\" + version;\n string signature;\n byte[] bytes = HmacEncrypt(encryptText, accessKey, signatureMethod);\n signature = Base64.getEncoder().encodeTostring(bytes);\n return signature;\n }\n\n public static byte[] HmacEncrypt(string data, string key, string signatureMethod)\n throws NoSuchAlgorithmException, InvalidKeyException {\n //根据给定的字节数组构造一个密钥,第二参数指定一个密钥算法的名称\n SecretKeySpec signinKey = null;\n signinKey = new SecretKeySpec(Base64.getDecoder().decode(key),\n \"Hmac\" + signatureMethod.toUpperCase());\n //生成一个指定 Mac 算法的 Mac 对象\n Mac mac = null;\n mac = Mac.getInstance(\"Hmac\" + signatureMethod.toUpperCase());\n //用给定密钥初始化 Mac 对象\n mac.init(signinKey);\n //完成 Mac 操作\n return mac.doFinal(data.getBytes());\n }\n\n public enum SignatureMethod {\n SHA1, MD5, SHA256;\n }\n\n public static void main(string[] args) throws UnsupportedEncodingException, NoSuchAlgorithmException, InvalidKeyException {\n string version = \"2022-05-01\";\n string resourceName = \"userid/12321\";\n //用户自定义token过期时间\n string expirationTime = System.currentTimeMillis() / 1000 + 3600 + \"\";\n string signatureMethod = SignatureMethod.SHA1.name().toLowerCase();\n string accessKey = \"KuF3NT/jUBJ62LNBB/A8XZA9CqS3Cu79B/ABmfA1UCw=\";\n string token = assembleToken(version, resourceName, expirationTime, signatureMethod, accessKey);\n System.out.println(\"Authorization:\" + token);\n }\n }\n```\n\n###### go代码示例\n\n```go\nfunc (s *SignService) GenerateSign(params_map map[string]string, access_key string) (string, error){\n signature_str := params_map[\"et\"] + \"\n\" + params_map[\"method\"] + \"\n\" + params_map[\"res\"] + \"\n\" + params_map[\"version\"]\n hmac_str := \"\"\n switch strings.ToLower(params_map[\"method\"]) {\n case \"sha1\":\n hmac_str = tools.HmacSha1(signature_str, tools.Base64Decode(access_key))\n case \"sha256\":\n hmac_str = tools.HmacSha256(signature_str, tools.Base64Decode(access_key))\n case \"md5\":\n hmac_str = tools.HmacMd5(signature_str, tools.Base64Decode(access_key))\n default:\n return \"\",errors.New(\"签名参数错误！\")\n }\n\n sign :=tools.Base64Encode(hmac_str)\n return sign,nil\n}\n\nfunc Base64Encode(message string) string {\n return base64.StdEncoding.EncodeTostring([]byte(message))\n}\n\nfunc Base64Decode(message string) string {\n decode_str, err := base64.StdEncoding.Decodestring(message)\n if err != nil {\n return \"\"\n }\n return string(decode_str)\n}\n\nfunc HmacSha256(data string, secret string) string {\n h := hmac.New(sha256.New, []byte(secret))\n h.Write([]byte(data))\n return string(h.Sum(nil))\n}\n\nfunc HmacMd5(data string, secret string) string {\n h := hmac.New(md5.New, []byte(secret))\n h.Write([]byte(data))\n return string(h.Sum(nil))\n}\n\nfunc HmacSha1(data string, secret string) string {\n h := hmac.New(sha1.New, []byte(secret))\n h.Write([]byte(data))\n return string(h.Sum(nil))\n}\n```\n\n###### php代码示例\n\n```php\nclass SafetyAuth\n{\n    private  $_version = '2022-05-01';//版本\n    private  $_method = 'sha1';//加密方法，还可以用md5、sha256\n    private  $_access_key;//访问密钥\n    private  $_res ;//资源参数\n    private  $_et;//到期时间戳\n    private  $_expiration;//有效期，有效时间\n\n    public function __construct($access_key, $expiration,$res){\n        $this->_expiration = $expiration;\n        $this->_access_key = $access_key;\n        $this->_res = $res;\n    }\n\n    //生成sign\n    private function _makeSign() {\n        date_default_timezone_set('PRC');\n        $this->_et =time() + $this->_expiration;\n        $string_for_signature = $this->_et . \"\n\" . $this->_method . \"\n\" . $this->_res  . \"\n\" . $this->_version;\n        $b64_decode_acckey = base64_decode($this->_access_key);\n        $hmac_key = hash_hmac($this->_method, $this->_strToUtf8($string_for_signature), $b64_decode_acckey, true);\n        $sign = base64_encode($hmac_key);\n        return $sign;\n    }\n\n    private function _strToUtf8($str) {\n        $encode = mb_detect_encoding($str, array(\"ASCII\",'UTF-8',\"GB2312\",\"GBK\",'BIG5'));\n        if ($encode == 'UTF-8') {\n            return $str;\n        } else {\n            return mb_convert_encoding($str, 'UTF-8', $encode);\n        }\n    }\n\n //生成token\n    public function makeToken() {\n        $sign = $this->_makeSign();\n        $token = sprintf(\"version=2022-05-01&res=%s&et=%s&method=sha1&sign=%s\", urlencode($this->_res), $this->_et, urlencode($sign));\n        return $token;\n    }\n}\n```"}, "zh_HK": {"title": "安全鑒權", "content": "平台需要對API調用方進行資源權限校驗，使用API時，需要在請求Header中攜帶統一的安全鑒權信息。\n\n## 不同情形下的鑒權方式\n\n![](/fuse/middlelayer/file/download?file=NICG0FcUzuOWrPZIux8n.png)\n\n* **平台支持三種鑒權方式：用戶鑒權、產品鑒權、項目鑒權**\n\n* **添加設備后未轉移**：\n\n1、設備未轉移，但綁定了項目時，鑒權支持【用戶鑒權】、【項目鑒權】。\n\n2、設備未轉移，且沒有綁定任何項目時，鑒權支持【用戶鑒權】、【產品鑒權】。\n\n* **添加設備後進行設備轉移**：\n\n1、用戶在平台嘗試“設備轉移”時，需要先解除項目綁定，才能進行轉移操作。\n\n2、轉移后，再次綁定項目時，支持【用戶鑒權】、【項目鑒權】。\n\n3、轉移后，沒有綁定項目時，僅支持【用戶鑒權】。\n\n#### 安全鑒權機制\n\n安全鑒權authorization由多個參數構成，每個參數均採用key = value的形式表示，並用&作為分隔符：\n\n```text\nauthorization: version=2022-05-01&res=userid%2F{userId}&et={expireTime}&method=sha1&sign={sign}\n```\n\n#### Token生成工具\n\n* 為便於開發者開發，RINGA提供了Token生成工具，填寫字段后可以快速生成安全鑒權信息。前往下載[【點擊跳轉文檔】](/doc/v5/fuse/detail/402)\n\n##### 參數說明\n\n| 序號 | 參數 | 類型 | 說明 | 示例 |\n|:- | :- | :- | :- | :- |\n|1 | version | string | 簽名算法版本 | 目前僅支持 2022-05-01 |\n|2 | res | string | 訪問資源信息 | 支持主用戶、產品、項目三種方式：
1）主用戶訪問res為：userid/{userid}, userid為平台用户id，access_key為主用户access_key，參數在個人「賬號信息」、「訪問權限」中查看。
2）產品访问res為：products/{productid}，access_key為產品access_key，進入「產品开发」菜單的「產品列表」中，點擊「操作」列下的「產品开发」鏈接，進入「產品信息页面」查看。
3）項目訪問res為：projects/{projectid}，access_key為项目key，進入「應用開發」-「項目管理」菜單的「我的項目」列表中，點擊「操作」列下的「進入項目管理」鏈接，進入「項目信息頁面」，在「項目概況」的「項目信息」中查看。

   注* 以上提到的不同access_key獲取方式在下文中會有詳細描述 |\n|3 | et | string | 訪問過期時間 | 10位秒級時間戳，1537255523 表示：北京時間 2018-09-18 15:25:23 |\n|4 | method | string | 簽名方法 | 目前支持md5、sha1、sha256 |\n|5 | sign | string | 簽名結果字符串      | version、res、et、method參數計算生成 |\n\n#### accessKey參數獲取\n\n###### 主用戶accessKey\n\n![](/fuse/middlelayer/file/download?file=tRAgWpoGGm59zvHTlhBe.png)\n\n###### 產品accessKey\n\n![](/fuse/middlelayer/file/download?file=dy7XPJOeXA6ynKJAZkjm.png)\n\n![](/fuse/middlelayer/file/download?file=bXW0Fq3vMqGD3KVMT3QT.png)\n\n###### 項目accessKey\n\n![](/fuse/middlelayer/file/download?file=QDpVmNzTrkyYT4ay2UxK.png)\n\n![](/fuse/middlelayer/file/download?file=xtmUlQhirwY5jc86FW76.png)\n\nsign的生成算法為:\n\n```c++\nsign = base64(hmac_(base64decode(accessKey), utf8(stringForSignature)))\n```\n\n* accessKey為平台分配的訪問密鑰（用戶訪問權限頁面查看），如果訪問資源以主用戶形式訪問, 使用主用戶的accessKey；如果訪問資源以產品方式訪問，使用產品的accessKey，且只能對產品下的設備進行操作；如果訪問資源以項目方式訪問，使用項目的accessKey，且只能對項目下的設備進行操作。\n\n* accessKey參与計算前應先進行base64decode操作。\n\n* 用於計算簽名的字符串 stringForSignature按照et、method、res、version的順序，以\"\n\n\"作為分隔符進行排列，如下所示：\n\n```c\nstringForSignature = et + \"\\n\" + method + \"\\n\" + res + \"\\n\" + version\n```\n\n##### 參數編碼\n\nauthorization中key=value的形式的value部分需要經過URL編碼，需要进行編碼的特殊符号如下：\n\n|序號 | 符號 | 編碼 |\n|:- | :- | :- |\n|1 | + | %2B |\n|2 | 空格 | %20 |\n|3 | / | %2F |\n|4 | ? | %3F |\n|5 | % | %25 |\n|6 | # | %23 |\n|7 | & | %26 |\n|8 | = | %3D |\n\n##### authorization生成示例\n\n###### nodejs代碼示例\n\n```js\n'use strict';\n\nconst crypto = require('crypto');\n\n/**\n * authorization生成函數\n *\n * @param {string} method - hash method\n * @param {string} res - resource\n * @param {string} accessKey - access key\n * @param {Number} et - effective time\n * @return {string} - authorization\n */\nfunction generateAuthorization(method, res, accessKey, et) {\n const version = '2022-05-01';\n const et = Math.ceil((Date.now() + et) / 1000); // token有效時間\n const base64Key = Buffer.from(accessKey, 'base64'); // accessKey base64編碼\n const stringForSignature = et + '\\n' + method + '\\n' + res + '\\n' + version;\n const sign = encodeURIComponent(crypto.createHmac(method, base64Key).update(stringForSignature).digest('base64'));\n const encodeRes = encodeURIComponent(res);\n\n return `version=${version}&res=${encodeRes}&et=${et}&method=${method}&sign=${sign}`;\n}\n\nconst method = 'sha1';\nconst accessKey = 'mjgvkTCYTBF6DguxMmm+aV9EkDp2CYfL5jzRTph5Th6KhU8gqZz/cBivPTA7tfY5';\nconst res = 'userid/130037';\nconst et = 3600 * 1000; // 有效時間:1小時\nconst authorization = generateAuthorization(method, res, accessKey, et);\n\n```\n\n###### python代碼示例\n\n```python\n import base64\n import hmac\n import time\n from urllib.parse import quote\n\n def token(user_id,access_key):\n version = '2022-05-01'\n res = 'userid/%s' % user_id\n # 用戶自定義token過期時間\n et = str(int(time.time()) + 3600)\n # 簽名方法，支持md5、sha1、sha256\n method = 'sha1'\n # 對access_key進行decode\n key = base64.b64decode(access_key)\n # 計算sign\n org = et + '\\n' + method + '\\n' + res + '\\n' + version\n sign_b = hmac.new(key=key, msg=org.encode(), digestmod=method)\n sign = base64.b64encode(sign_b.digest()).decode()\n # value 部分進行url編碼，method/res/version值较为简单无需編碼\n sign = quote(sign, safe='')\n res = quote(res, safe='')\n # token參數拼接\n token = 'version=%s&res=%s&et=%s&method=%s&sign=%s' % (version, res, et, method, sign)\n\n return token\n\n if __name__ == '__main__':\n user_id = '37715'\n access_key = 'mjgvkTCYTBF6DguxMmm+aV9EkDp2CYfL5jzRTph5Th6KhU8gqZz/cBivPTA7tfY5'\n\n print(token(user_id,access_key))\n```\n\n###### Java代碼示例\n\n```java\n import javax.crypto.Mac;\n import javax.crypto.spec.SecretKeySpec;\n import java.io.UnsupportedEncodingException;\n import java.net.URLEncoder;\n import java.security.InvalidKeyException;\n import java.security.NoSuchAlgorithmException;\n import java.util.Base64;\n\n public class Token {\n\n public static string assembleToken(string version, string resourceName, string expirationTime, string signatureMethod, string accessKey)\n throws UnsupportedEncodingException, NoSuchAlgorithmException, InvalidKeyException {\n stringBuilder sb = new stringBuilder();\n string res = URLEncoder.encode(resourceName, \"UTF-8\");\n string sig = URLEncoder.encode(generatorSignature(version, resourceName, expirationTime, accessKey, signatureMethod), \"UTF-8\");\n sb.append(\"version=\")\n .append(version)\n .append(\"&res=\")\n .append(res)\n .append(\"&et=\")\n .append(expirationTime)\n .append(\"&method=\")\n .append(signatureMethod)\n .append(\"&sign=\")\n .append(sig);\n return sb.tostring();\n }\n\n public static string generatorSignature(string version, string resourceName, string expirationTime, string accessKey, string signatureMethod)\n throws NoSuchAlgorithmException, InvalidKeyException {\n string encryptText = expirationTime + \"\\n\" + signatureMethod + \"\\n\" + resourceName + \"\\n\" + version;\n string signature;\n byte[] bytes = HmacEncrypt(encryptText, accessKey, signatureMethod);\n signature = Base64.getEncoder().encodeTostring(bytes);\n return signature;\n }\n\n public static byte[] HmacEncrypt(string data, string key, string signatureMethod)\n throws NoSuchAlgorithmException, InvalidKeyException {\n //根據給定的字節數組構造一個密鑰,第二參數指定一個密鑰算法的名稱\n SecretKeySpec signinKey = null;\n signinKey = new SecretKeySpec(Base64.getDecoder().decode(key),\n \"Hmac\" + signatureMethod.toUpperCase());\n //生成一個指定 Mac 算法的 Mac 對象\n Mac mac = null;\n mac = Mac.getInstance(\"Hmac\" + signatureMethod.toUpperCase());\n //用給定密鑰初始化 Mac 對象\n mac.init(signinKey);\n //完成 Mac 操作\n return mac.doFinal(data.getBytes());\n }\n\n public enum SignatureMethod {\n SHA1, MD5, SHA256;\n }\n\n public static void main(string[] args) throws UnsupportedEncodingException, NoSuchAlgorithmException, InvalidKeyException {\n string version = \"2022-05-01\";\n string resourceName = \"userid/12321\";\n //用戶自定義token過期時間\n string expirationTime = System.currentTimeMillis() / 1000 + 3600 + \"\";\n string signatureMethod = SignatureMethod.SHA1.name().toLowerCase();\n string accessKey = \"KuF3NT/jUBJ62LNBB/A8XZA9CqS3Cu79B/ABmfA1UCw=\";\n string token = assembleToken(version, resourceName, expirationTime, signatureMethod, accessKey);\n System.out.println(\"Authorization:\" + token);\n }\n }\n```\n\n###### go代碼示例\n\n```go\nfunc (s *SignService) GenerateSign(params_map map[string]string, access_key string) (string, error){\n signature_str := params_map[\"et\"] + \"\n\" + params_map[\"method\"] + \"\n\" + params_map[\"res\"] + \"\n\" + params_map[\"version\"]\n hmac_str := \"\"\n switch strings.ToLower(params_map[\"method\"]) {\n case \"sha1\":\n hmac_str = tools.HmacSha1(signature_str, tools.Base64Decode(access_key))\n case \"sha256\":\n hmac_str = tools.HmacSha256(signature_str, tools.Base64Decode(access_key))\n case \"md5\":\n hmac_str = tools.HmacMd5(signature_str, tools.Base64Decode(access_key))\n default:\n return \"\",errors.New(\"簽名參數錯誤！\")\n }\n\n sign :=tools.Base64Encode(hmac_str)\n return sign,nil\n}\n\nfunc Base64Encode(message string) string {\n return base64.StdEncoding.EncodeTostring([]byte(message))\n}\n\nfunc Base64Decode(message string) string {\n decode_str, err := base64.StdEncoding.Decodestring(message)\n if err != nil {\n return \"\"\n }\n return string(decode_str)\n}\n\nfunc HmacSha256(data string, secret string) string {\n h := hmac.New(sha256.New, []byte(secret))\n h.Write([]byte(data))\n return string(h.Sum(nil))\n}\n\nfunc HmacMd5(data string, secret string) string {\n h := hmac.New(md5.New, []byte(secret))\n h.Write([]byte(data))\n return string(h.Sum(nil))\n}\n\nfunc HmacSha1(data string, secret string) string {\n h := hmac.New(sha1.New, []byte(secret))\n h.Write([]byte(data))\n return string(h.Sum(nil))\n}\n```\n\n###### php代碼示例\n\n```php\nclass SafetyAuth\n{\n    private  $_version = '2022-05-01';//版本\n    private  $_method = 'sha1';//加密方法，還可以用md5、sha256\n    private  $_access_key;//訪問密鑰\n    private  $_res ;//資源參數\n    private  $_et;//到期時間戳\n    private  $_expiration;//有效期，有效時間\n\n    public function __construct($access_key, $expiration,$res){\n        $this->_expiration = $expiration;\n        $this->_access_key = $access_key;\n        $this->_res = $res;\n    }\n\n    //生成sign\n    private function _makeSign() {\n        date_default_timezone_set('PRC');\n        $this->_et =time() + $this->_expiration;\n        $string_for_signature = $this->_et . \"\n\" . $this->_method . \"\n\" . $this->_res  . \"\n\" . $this->_version;\n        $b64_decode_acckey = base64_decode($this->_access_key);\n        $hmac_key = hash_hmac($this->_method, $this->_strToUtf8($string_for_signature), $b64_decode_acckey, true);\n        $sign = base64_encode($hmac_key);\n        return $sign;\n    }\n\n    private function _strToUtf8($str) {\n        $encode = mb_detect_encoding($str, array(\"ASCII\",'UTF-8',\"GB2312\",\"GBK\",'BIG5'));\n        if ($encode == 'UTF-8') {\n            return $str;\n        } else {\n            return mb_convert_encoding($str, 'UTF-8', $encode);\n        }\n    }\n\n //生成token\n    public function makeToken() {\n        $sign = $this->_makeSign();\n        $token = sprintf(\"version=2022-05-01&res=%s&et=%s&method=sha1&sign=%s\", urlencode($this->_res), $this->_et, urlencode($sign));\n        return $token;\n    }\n}\n```"}}