{"en_US": {"title": "Token algorithm", "content": "## 1.Composition of Token\n\nDevice key authentication must include product ID + device name + authentication token, where the token consists of multiple parameters.\n\n|Name | Type | Necessary | Parameter description | Example of the parameter |\n| --- | --- | --- | --- | --- |\n| version | string |Yes | The version number and date format of the parameter group are supported only in 2018-10-31 |2018-10-31 |\n| res | string | Yes| Accessing Resources
The product-level format of the resource is products/{product id},
and the device-level format is: products/{product id}/devices/{device name},
see res: Usage Scenarios | products/123123
products/123123/devices/78329710 |\n|et | int |yes | access expiration time. expirationTime, unix time
: If the et time in an access parameter is less than the current time, the platform will consider the access parameter expired and reject the access | 1537255523
(Beijing time: 2018-09-18 15:25:23) |\n|method |string | Yes |signature method signatureMethod
supports md5, sha1, sha256 | sha256 (for hmacsha1 algorithm) |\n|sign | string |Yes | Signature result string signature |rBYeJXTp2q4V3C2aj4DBzjaydcw%3D |\n\n## 2.Special note on token parameters\n\n### Description of the use case of res\n\n| Scene| resParameter Format |Example| Description |\n| --- | --- | --- | --- |\n| Product-level authentication (one type, one password) | products/{productID} | products/123123 | Use the product-level key to burn the same product certificate | on devices under the same product|\n| Device-level authentication (one device, one password) |products/{product ID}/devices/{device name} |products/123123/devices/mydev |Use a device-level key to flash your own device certificate for each device|\n\n### Sign Signature Algorithm\n\nThe algorithm for generating the sign parameter is as follows:\n\n```js\nsign = base64(hmac_(base64decode(key), utf8(stringForSignature)))\n```\n\nThereinto:\n\n* The key is the access key (both product-level and device-level) assigned by OneNET for resources, and it participates in the signature calculation as one of the parameters of the signature algorithm.\n\n* The key must be base64decoded before participating in the calculation.\n\n* The string used to calculate the signature\n\nThe composition order of stringForSignature is sorted by the string by the parameter name, starting with '\n\n'As a parameter separation, the current version is sorted in the following order: et, method, res, version.\n\nThe following is an example of how stringForSignature is composed:\n\n```js\nstringForSignature = et + '\\n' + method + '\\n' + res+ '\\n' + version\n```\n\nNote: Each parameter is composed of key=value format, but only the value in the parameter participates in the calculation of the signature of the string stringForSignature'\n\nIf the token parameters are as follows:\n\n```js\net = 1537255523\nmethod = sha1\nres = products/dafdfadfafdaf/devices/che1\nversion = 2018-10-31\n```\n\nThe string stringForSignature used to calculate the signature is (in the order of et, method, res, and version)\n\n```js\nstringForSignature = \"1537255523\" + \"\\n\" + \"sha1\"+ \"\\n\" + \"products/123123\"+ \"\\n\" + \"2018-10-31\"\n```\n\nAfter the sign is calculated, each parameter is represented in the form of key=value with '&' as the separator, as shown in the following example:\n\n```js\nversion=2018-10-31&res=products/dafdfadfafdaf/devices/che1&et=1537255523&method=sha1&sign=ZjA1NzZlMmMxYzIOTg3MjBzNjYTI2MjA4Yw=\n```\n\n## 3. Parameter encoding\n\nThe value part of the token in the form of key=value needs to be encoded by URL, and the special symbols that need to be encoded are as follows:\n\n|ordinal 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\nAfter encoding, the actual token transferred in the above example is:\n\n```js\nversion=2018-10-31&res=products%2F123123&et=1537255523&method=sha1&sign=ZjA1NzZlMmMxYzIOTg3MjBzNjYTI2MjA4Yw%3D\n```"}, "zh_CN": {"title": "Token算法", "content": "## 1.Token的组成\n\n设备秘钥鉴权需包含产品ID+设备名称+鉴权Token，其中Token由多个参数构成。\n\n|名称 | 类型 | 是否必须| 参数说明 | 参数示例 |\n| --- | --- | --- | --- | --- |\n| version | string |是 | 参数组版本号，日期格式，目前仅支持\"2018-10-31\" |2018-10-31 |\n| res | string | 是| 访问资源 resource
产品级格式为：products/{产品id}
设备级格式为：products/{产品id}/devices/{设备名字}
区别见res使用场景说明 | products/123123
products/123123/devices/78329710 |\n|et | int |是 |访问过期时间 expirationTime，unix时间
当一次访问参数中的et时间小于当前时间时，平台会认为访问参数过期从而拒绝该访问 | 1537255523
（代表北京时间：2018-09-18 15:25:23） |\n|method |string | 是 |签名方法 signatureMethod
支持md5、sha1、sha256 | sha256（代表使用hmacsha1算法） |\n|sign | string |是 | 签名结果字符串 signature |rBYeJXTp2q4V3C2aj4DBzjaydcw%3D |\n\n## 2.关于token参数的特别说明\n\n### res使用场景说明\n\n| 场景| res参数格式 |示例 | 说明 |\n| --- | --- | --- | --- |\n| 产品级鉴权（一型一密） | products/{产品ID} | products/123123 | 使用产品级密钥，同一产品下设备烧录相同产品证书 |\n| 设备级别鉴权（一机一密） |products/{产品ID}/devices/{设备名称} |products/123123/devices/mydev |使用设备级密钥，每台设备烧录自己的设备证书 |\n\n### sign签名算法\n\n参数sign的生成算法为：\n\n```c++\nsign = base64(hmac_(base64decode(key), utf8(stringForSignature)))\n```\n\n其中：\n\n* Key为OneNET为资源分配的访问密钥(产品级、设备级均可)，其作为签名算法参数之一参与签名计算，为保证访问安全，请妥善保管。\n\n* Key参与计算前应先进行base64decode操作。\n\n* 用于计算签名的字符串 stringForSignature的组成顺序按照参数名称进行字符串排序，以'\n\n'作为参数分隔，当前版本中按照如下顺序进行排序：et、method、res、version。\n\nstringForSignature组成示例如下：\n\n```c\nstringForSignature = et + '\\n' + method + '\\n' + res+ '\\n' + version\n```\n\n`注意：每个参数均为key=value格式组成，但是仅参数中的value参与计算签名的字符串 stringForSignature的组成`\n\n若token参数如下\n\n```text\net = 1537255523\nmethod = sha1\nres = products/dafdfadfafdaf/devices/che1\nversion = 2018-10-31\n```\n\n则用于计算签名的字符串stringForSignature为（按照et、method、res、version的顺序）\n\n```c\nstringForSignature = \"1537255523\" + \"\\n\" + \"sha1\"+ \"\\n\" + \"products/123123\"+ \"\\n\" + \"2018-10-31\"\n```\n\n计算出sign后，将每个参数均采用key=value的形式表示，并用'&'作为分隔符，示例如下：\n\n```text\nversion=2018-10-31&res=products/dafdfadfafdaf/devices/che1&et=1537255523&method=sha1&sign=ZjA1NzZlMmMxYzIOTg3MjBzNjYTI2MjA4Yw=\n```\n\n## 3.参数编码\n\ntoken中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编码后，上例中实际传输token为：\n\n```text\nversion=2018-10-31&res=products%2F123123&et=1537255523&method=sha1&sign=ZjA1NzZlMmMxYzIOTg3MjBzNjYTI2MjA4Yw%3D\n```"}, "zh_HK": {"title": "Token算法", "content": "## 1.Token的組成\n\n設備秘鑰鑒權需包含產品ID+設備名稱+鑒權Token，其中Token由多個參數構成。\n\n|名稱 | 類型 | 是否必須| 參數說明 | 參數示例 |\n| --- | --- | --- | --- | --- |\n| version | string |是 | 參數組版本號，日期格式，目前僅支持\"2018-10-31\" |2018-10-31 |\n| res | string | 是| 訪問資源 resource
產品級格式為：products/{產品id}
設備級格式為：products/{產品id}/devices/{設備名字}
區別見res使用場景說明 | products/123123
products/123123/devices/78329710 |\n|et | int |是 |訪問過期時間 expirationTime，unix時間
當一次訪問參數中的et時間小于当前時間时，平台會認為訪問參數過期從而拒絕該訪問 | 1537255523
（代表北京時間：2018-09-18 15:25:23） |\n|method |string | 是 |簽名方法 signatureMethod
支持md5、sha1、sha256 | sha256（代表使用hmacsha1算法） |\n|sign | string |是 | 簽名結果字符串 signature |rBYeJXTp2q4V3C2aj4DBzjaydcw%3D |\n\n## 2.關於token參數的特別說明\n\n### res使用場景說明\n\n| 場景| res參數格式 |示例 | 說明 |\n| --- | --- | --- | --- |\n| 產品級鑒權（一型一密） | products/{產品ID} | products/123123 | 使用產品级密钥，同一產品下设备烧录相同產品证书 |\n| 設備級別鑒權（一機一密） |products/{產品ID}/devices/{設備名稱} |products/123123/devices/mydev |使用設備級密鑰，每台設備燒錄自己的設備證書 |\n\n### sign簽名算法\n\n參數sign的生成算法為：\n\n```c++\nsign = base64(hmac_(base64decode(key), utf8(stringForSignature)))\n```\n\n其中：\n\n* Key為OneNET為资源分配的访问密钥(產品級、設備級均可)，其作為签名算法参数之一参与签名计算，為保证访问安全，請妥善保管。\n\n* Key參与計算前應先進行base64decode操作。\n\n* 用於計算簽名的字符串 stringForSignature的組成順序按照參數名稱進行字符串排序，以'\n\n'作為參數分隔，當前版本中按照如下順序進行排序：et、method、res、version。\n\nstringForSignature組成示例如下：\n\n```c\nstringForSignature = et + '\\n' + method + '\\n' + res+ '\\n' + version\n```\n\n`注意：每個參數均為key=value格式組成，但是僅參數中的value參与計算簽名的字符串 stringForSignature的組成`\n\n若token參數如下\n\n```text\net = 1537255523\nmethod = sha1\nres = products/dafdfadfafdaf/devices/che1\nversion = 2018-10-31\n```\n\n則用於計算簽名的字符串stringForSignature為（按照et、method、res、version的順序）\n\n```c\nstringForSignature = \"1537255523\" + \"\\n\" + \"sha1\"+ \"\\n\" + \"products/123123\"+ \"\\n\" + \"2018-10-31\"\n```\n\n計算出sign后，將每個參數均採用key=value的形式表示，並用'&'作為分隔符，示例如下：\n\n```text\nversion=2018-10-31&res=products/dafdfadfafdaf/devices/che1&et=1537255523&method=sha1&sign=ZjA1NzZlMmMxYzIOTg3MjBzNjYTI2MjA4Yw=\n```\n\n## 3.參數編碼\n\ntoken中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編碼後，上例中實際傳輸token為：\n\n```text\nversion=2018-10-31&res=products%2F123123&et=1537255523&method=sha1&sign=ZjA1NzZlMmMxYzIOTg3MjBzNjYTI2MjA4Yw%3D\n```"}}