menu

API 签名算法

更新时间: 2019-12-24 18:10:38 · 编辑者:宇链科技

宇链可信云中部分接口需要向宇链申请 AppID、AppSecret 后才可合法使用。每次执行敏感操作时,必须在接口中签名才可以使用。

我们提供多种语言的代码示例或 SDK 来避免你手工计算签名。如果你仍需要了解签名算法的细节,本页面进行了详细的说明。

签名算法

在请求的 URI 的 Query 字符串中加入三个新值,分别是 _appid_t(当前以毫秒计算的 UNIX 时间戳)、_s(以 16 进制编码的签名结果)。

签名 = HMAC-SHA256(待签名字符串, AppSecret)

也就是说,使用 AppSecret 作为密钥,对待签名字符串进行 HMAC-SHA256 运算,即得到最终结果。

下面将介绍待签名字符串的生成方法。

待签名字符串

待签名字符串由 2 - 3 行文本组成。具体内容如下:

[HTTP METHOD] [PATH]
[排序后的 Query 字符串]
[Body 内容]

其中, HTTP METHOD 可能是 GET / POST / OPTIONS 等,必须是大写。

PATH 为请求的 API 的路径,不包括协议、域名和 Query字符串,举例如:/membership-card

排序后的 Query 字符串是根据每个参数的 Key 的字典序来排列的,且必须包含 _appid_t

例如,有下面的 Query:

_t=1556511605295&_s=7f52c91f720595cf4523cf52fc4fd094a189df728ac357dc92c45df3873b0bc9&_appid=AzE5my7

则根据 _appid_t_s 来排列,结果如下:

_appid=AzE5my7&_s=7f52c91f720595cf4523cf52fc4fd094a189df728ac357dc92c45df3873b0bc9&_t=1556511605295&

注意:在签名字符串中,不进行任何转义操作,使用原文。

Body 内容 指的是 POST 等请求中 Body 中传递的 JSON 串原文。

签名实例

我们先以 GET 请求为例。如果你调用的是 POST 请求,请注意留意本小节最后的说明。

GET 请求

例如你想调用如下 API (GET 请求):

https://v1.api.tc.vastchain.ltd/submerchant-pay/prePay/PP5217839266?someQuery=1

假如你的 AppID 是 AzE5my7,AppSecret 是 u4VcwCrZ0tD$ozhE

首先,我们可以根据前面的“待签名字符串”的定义来进行拼接。

在这个例子中,HTTP METHODGET, PATH 为 /submerchant-pay/prePay/PP5217839266。请求本身的 Query 字符串为 someQuery=1

我们需要将自己的 AppID 和当前 UNIX 世界戳(毫秒)_t 追加到 Query 列表,得到的完整 Query 列表如下 (请勿转义):

someQuery=1&_appid=AzE5my7&_t=1556511605295

然后进行字典序排序,如下:

_appid=AzE5my7&_t=1556511605295&someQuery=1

注意:Query 中不能包含 _s(签名结果)。

因此最终的待签名字符串如下(请注意换行符使用 \n 而不是 \r\n):

GET /submerchant-pay/prePay/PP5217839266
_appid=AzE5my7&_t=1556511605295&someQuery=1

请不要有多余的空格和换行。

使用 AppSecret 作为密钥,对待签名字符串进行 HMAC-SHA256 运算,即得到最终结果:

cb0cf6a6f5db14af74ae0da0fa3f8019d0a794a5f84d1fbe03fe24ef5dd1bf3f

于是我们得到了最终请求的 URI:

https://v1.api.tc.vastchain.ltd/submerchant-pay/prePay/PP5217839266?someQuery=1&_appid=AzE5my7&_t=1556511605295&_s=cb0cf6a6f5db14af74ae0da0fa3f8019d0a794a5f84d1fbe03fe24ef5dd1bf3f

非 GET 请求

如果你的请求不是 GET 方法(例如 POSTPUT),需要把 Body 里的 JSON 也放进去,也就是在上述的签名字符串后加一个换行(\n),然后写入 body 内容。例如,如果上面的例子是 POST,且提交的 body 参数为 {"msg":"ok"},则待签名字符串如下:

POST /submerchant-pay/prePay/PP5217839266
_appid=AzE5my7&_t=1556511605295&someQuery=1
{"msg":"ok"}

注意:虽然在计算签名的过程中不进行参数转义,但是在提交请求的时候,最终字符串务必正常使用 URI Encode 进行参数转义。