RESTful API接口认证规则

yunhe

介绍

• yunhe所有API接口都需要通过AccessKeyId / SecretAccessKey来进行身份认证，所以所有接口请务必根据下述规则生成签名（Signature）信息。通过yunhe平台可以获取AccessKeyId / SecretAccessKey；AccessKeyId用于标识用户，SecretAccessKey用于加密认证信息，切勿泄漏。

使用方式

在header中添加头域Yunhe_Autorization，值为认证字符串（生成规则参考下面描述）的Base64结果；

Yunhe_Autorization: Base64(认证字符串)

认证字符串规则

• 认证字符串结构

yunhe-auth/{version}/{client_type}/{auth_id}/{timestamp}/{nonce}/{region}/{service}/{signature}

签名规则

生成方式：HMAC-SHA256-HEX(SecretAccessKey,SignString)

SignString

计算公式为： SignString = HTTP Method + "\n" + CanonicalURI + "\n" + CanonicalQueryString + "\n" + CanonicalHeaders，

HTTP Method

指HTTP协议中定义的GET、PUT、POST等请求，必须使用全大写的形式。yunhe API所涉及的HTTP Method有如下四种：

• GET
• POST
• PUT
• DELETE

CanonicalURI

CanonicalURI是对URL中的绝对路径进行编码后的结果，即CanonicalURI = UriEncodeExceptSlash(Path)。要求绝对路径Path必须以“/”开头和结尾，不以“/”开头和结尾的需要补充上，空路径为“/”，。

说明

• UriEncode
  RFC 3986规定，"URI非保留字符"包括以下字符：字母（A-Z，a-z）、数字（0-9）、连字号（-）、点号（.）、下划线（_)、波浪线（~），算法实现如下：
  
  1. 将字符串转换成UTF-8编码的字节流
  2. 保留所有“URI非保留字符”原样不变
  3. 对其余字节做一次RFC 3986中规定的百分号编码（Percent-encoding），即一个“%”后面跟着两个表示该字节值的十六进制字母，字母一律采用大写形式。
• UriEncodeExceptSlash：与UriEncode() 类似，区别是斜杠（/）不做编码。一个简单的实现方式是先调用UriEncode()，然后把结果中所有的%2F都替换为/

相关举例：
若URL为https://yunhe.com/example/测试/，则其URL Path为/example/测试/，将之规范化得到CanonicalURI ＝ /example/%E6%B5%8B%E8%AF%95/。

CanonicalQueryString

CanonicalQueryString对于URL中的Query String（Query String即URL中“？”后面的“key1 = valve1 & key2 = valve2 ”字符串）进行编码后的结果。

编码步骤如下

1. 提取URL中的Query String项，即URL中“？”后面的“key1 = valve1 & key2 = valve2 ”字符串
2. 将Query String根据&拆开成若干项，每一项是key=value或者只有key的形式。
3. 对拆开后的每一项进行编码处理，分以下两种情况:当该项只有key时，转换公式为UriEncode(key) + "="的形式;当该项是key=value的形式时，转换公式为UriEncode(key) + "=" + UriEncode(value)的形式。这里value可以是空字符串。
4. 将每一项转换后的字符串按照字典顺序（ASCII码由小到大）排序，并使用& 符号连接起来，生成相应的CanonicalQueryString。

编码示例

• 获取URL为https://yunhe.com/example?text&text1=测试&text10=test的CanonicalQueryString

  1. 提取URL中的Query String，得到 text&text1=测试&text10=test。
  2. 根据&对Query String进行拆分，得到text 、text1=测试 、 text10=test三项。
  3. 对拆分的每一项进行编码。
     
     • 对text项进行编码得到 UriEncode("text") + "=" => text=
     • 对text1=测试项进行编码得到 UriEncode("text1") + "=" + UriEncode("测试") => text1=%E6%B5%8B%E8%AF%95
     • 对text10=test项进行编码得到 UriEncode("text10") + "=" + UriEncode("test") => text10=test
  4. 对上面三项编码后的字符串进行（按照ASCII码由小到大）排序，得到结果是text10=test 、text1=%E6%B5%8B%E8%AF%95 、text= ，然后用&连接起来，得到CanonicalQueryString为text10=test&text1=%E6%B5%8B%E8%AF%95&text=。

CanonicalHeaders

1. 选择编码的Header：yunhe仅需对HOST头域进行编码
2. 将认证字符串中除签名外和固定头外的其他部分拆成k-v形式, value均为字符串；如：

    # 认证字符串：
    yunhe-auth/v1/device/123/456/789/all/yunhe/signature
    # 拆分出的编码内容：
    {
        "verison":"v1",
        "client_type":"device",
        "auth_id":"123",
        "timestamp": "456",
        "nonce":"789",
        "region":"all",
        "service":"yunhe"
    }

1. 将头域的key变成小写，并与拆分后认证字符串组合，如下：

{
    "host": "yunhe.com"
    "verison":"v1",
    "client_type":"device",
    "auth_id":"123",
    "nonce":"456",
    "region":"all",
    "service":"yunhe"
}

1. 将上述json中所有的值两端的空白字符去除
2. 将各项转换为UriEncode(name) + ":" + UriEncode(value) 的形式
3. 把上面转换后的所有k-v对按照key的ASCII码由小到大进行排序，并用&将各项拼接，示例将得到如下字符串：

auth_id%3d123&client_type%3ddevice&host%3dyunhe.com&nonce%3d456&region%3dall&service%3dyunhe&verison%3dv1

生成Signature及认证字符串

# signature
signature = HMAC-SHA256-HEX(SecureAccessKey, SignString)
# 认证字符串
sign_str = yunhe-auth/{version}/{client_type}/{auth_id}/{timestamp}/{nonce}/{region}/{service}/{signature}
# 使用时记得对认证字符串进行BASE64编码