生成V2认证字符串

1 简介

V2认证字符串是百度智能云最新的API认证协议方式。基于V2协议,服务可提供更高的请求响应性能,用户也可更大程度保证自己的密钥安全。

目前表格服务BTS已经支持v2协议的认证字符串,具体参见BTS API参考

2 V2认证字符串的变化

V2认证字符串在V1版本基础上,主要包含以下变化:

  • 认证字符串的格式调整。与V1版本相比,V2认证字符串中减少了签名时间戳和过期时间,增加了签名日期和生效的服务区域限定。具体格式为:
    bce-auth-v2/{accessKeyId}/{date}/{region}/{service}/{signedHeaders}/{signature}
  • signingKey生成方式,变化为:
    HMAC-SHA256-HEX(sk, "bce-auth-v2/{accessKeyId}/{date}/{region}/{service}")
  • 必须签名的头域/请求参数。认证字符串中减少的签名时间戳,要求必须以x-bce-date请求头或QueryString参数形式,计入签名;请求中如通过x-bce-expiration设置过期时间,则也必须计入签名。请求中未指定过期时间的,则默认请求15分钟过期。

除去以上变化,V2中签名的计算过程,同样包含生成CanonicalRequest、生成SigningKey、生成Signature、生成认证字符串等步骤,与V1版本基本一致。具体过程参见生成V2认证字符串的方法

关于签名认证V1,参见生成字符串的方法

3 生成V2认证字符串的方法

3.1 概述

在生成认证字符串之前,首先需要生成Signature。为了生成Signature,用户需要首先构建CanonicalRequest并计算SigningKey,具体内容如下图所示:

image.png

下表介绍了上图中涉及的函数:

函数名 功能描述
HMAC-SHA256-HEX() 调用HMAC SHA256算法,根据开发者提供的密钥(key)和密文(message)输出密文摘要,并把结果转换为小写形式的十六进制字符串。
Lowercase() 将字符串全部变成小写。
Trim() 去掉字符串开头和结尾的空白字符。
UriEncode() RFC 3986规定,"URI非保留字符"包括以下字符:字母(A-Z,a-z)、数字(0-9)、连字号(-)、点号(.)、下划线(_)、波浪线(~),算法实现如下:
1. 将字符串转换成UTF-8编码的字节流
2. 保留所有“URI非保留字符”原样不变
3. 对其余字节做一次RFC 3986中规定的百分号编码(Percent-encoding),即一个“%”后面跟着两个表示该字节值的十六进制字母,字母一律采用大写形式。
UriEncodeExceptSlash() 与UriEncode() 类似,区别是斜杠(/)不做编码。一个简单的实现方式是先调用UriEncode(),然后把结果中所有的`%2F`都替换为`/`

UriEncode()函数参考代码如下:

public static String uri-encode(CharSequence input, boolean encodeSlash) {
    StringBuilder result = new StringBuilder();
        for (int i = 0; i < input.length(); i++) {
            char ch = input.charAt(i);
            if ((ch >= 'A' && ch <= 'Z') || (ch >= 'a' && ch <= 'z') || (ch >= '0' && ch <= '9') || ch == '_' || ch == '-' || ch == '~' || ch == '.') {
                result.append(ch);
            } else if (ch == '/') {
                result.append(encodeSlash ? "%2F" : ch);
            } else {
                result.append(toHexUTF8(ch));
            }
        }
          return result.toString();
}

3.2 生成CanonicalRequest

CanonicalRequest = HTTP Method + "\n" + CanonicalURI + "\n" + CanonicalQueryString + "\n" + CanonicalHeaders,其中:

  • HTTP Method:指HTTP协议中定义的GET、PUT、POST等请求,必须使用全大写的形式。百度智能云API所涉及的HTTP Method有五种:

    • GET
    • POST
    • PUT
    • DELETE
    • HEAD
  • CanonicalURI:是对URL中的绝对路径进行编码后的结果。要求绝对路径必须以“/”开头,不以“/”开头的需要补充上,空路径为“/”,即CanonicalURI = UriEncodeExceptSlash(Path)

    相关举例:

    若URL为https://bos.cn-n1.baidubce.com/example/测试,则其URL Path为/example/测试,将之规范化得到CanonicalURI = /example/%E6%B5%8B%E8%AF%95

  • CanonicalQueryString:对于URL中的Query String(Query String即URL中“?”后面的“key1 = valve1 & key2 = valve2 ”字符串)进行编码后的结果。

    编码方法为:

    1. 将Query String根据&拆开成若干项,每一项是key=value或者只有key的形式。
    2. 对拆开后的每一项进行如下处理:
      • 对于keyauthorization,直接忽略。
      • 对于只有key的项,转换为UriEncode(key) + "="的形式。
      • 对于key=value的项,转换为 UriEncode(key) + "=" + UriEncode(value) 的形式。这里value可以是空字符串。
    3. 将上面转换后的所有字符串按照字典顺序排序。
    4. 将排序后的字符串按顺序用 & 符号链接起来。
    相关举例:

    若URL为https://bos.cn-n1.baidubce.com/example?text&text1=测试&text10=test,在这个例子中Query String是 text&text1=测试&text10=test

    1. 根据 & 拆开成 texttext1=测试text10=test 三项。
    2. 对每一项进行处理:
      • text => UriEncode("text") + "=" => text=
      • text1=测试 => UriEncode("text1") + "=" + UriEncode("测试") => text1=%E6%B5%8B%E8%AF%95
      • text10=test => UriEncode("text10") + "=" + UriEncode("test")=> text10=test
    3. text=text1=%E6%B5%8B%E8%AF%95text10=test 按照字典序进行排序。它们有共同前缀text,但是=的ASCII码比所有数字的ASCII码都要大,因此 text1=%E6%B5%8B%E8%AF%95text10=test 排在 text= 的前面。同样,text10=test 要排在 text1=%E6%B5%8B%E8%AF%95 之前。最终结果是 text10=testtext1=%E6%B5%8B%E8%AF%95text=
    4. 把排序好的三项 text10=testtext1=%E6%B5%8B%E8%AF%95text=&连接起来得到 text10=test&text1=%E6%B5%8B%E8%AF%95&text=

    说明:

    在这个特殊构造的例子里,我们展示了如何处理只有key的项,非英文的value,以及数字和=进行排序。在实际的BCE API中,因为参数起名是规范的,基本不会遇到这样的排序。正常的排序结果和只按照 key进行排序是完全一致的。算法中有这个约束主要是出于定义严密性的考虑。*

  • CanonicalHeaders:对HTTP请求中的Header部分进行选择性编码的结果。

    您可以自行决定哪些Header 需要编码。百度智能云API的唯一要求是Host域必须被编码。大多数情况下,我们推荐您对以下Header进行编码:

    • Host
    • Content-Length
    • Content-Type
    • Content-MD5
    • 所有以 x-bce- 开头的Header

    如果这些Header没有全部出现在您的HTTP请求里面,那么没有出现的部分无需进行编码。如果发送的请求里包含以上header,出现的header必须签名。

    如果您按照我们的推荐范围进行编码,那么认证字符串中的 {signedHeaders} 可以直接留空,无需填写。如果传signedHeaders则按照客户传的header进行签名。

    您也可以自行选择自己想要编码的Header。如果您选择了不在推荐范围内的Header进行编码,或者您的HTTP请求包含了推荐范围内的Header但是您选择不对它进行编码,那么您必须在认证字符串中填写 {signedHeaders} 。填写方法为,把所有在这一阶段进行了编码的Header名字转换成全小写之后按照字典序排列,然后用分号(;)连接。

    选择哪些Header进行编码不会影响API的功能,但是如果选择太少则可能遭到中间人攻击。

    对于每个要编码的Header进行如下处理:

    1. 将Header的名字变成全小写。
    2. 将Header的值去掉开头和结尾的空白字符。
    3. 经过上一步之后值为空字符串的Header忽略,其余的转换为 UriEncode(name) + ":" + UriEncode(value) 的形式。
    4. 把上面转换后的所有字符串按照字典序进行排序。
    5. 将排序后的字符串按顺序用\n符号连接起来得到最终的CanonicalQueryHeaders

    注意:很多发送HTTP请求的第三方库,会添加或者删除你指定的header(例如:某些库会删除content-length:0这个header),如果签名错误,请检查您真实发出的http请求的header,看看是否与签名时的header一样。

    相关举例1:

    不使用signedHeaders默认值。若希望对 Date 进行编码,但是不希望对 x-bce-date 进行编码,则需要用到signedHeaders

    要编码的Header如下:

    Host: bj.bcebos.com
    Date: Mon, 27 Apr 2015 16:23:49 +0800
    Content-Type: text/plain
    Content-Length: 8
    Content-Md5: NFzcPqhviddjRNnSOGo4rw==
    
    1. 首先把所有名字都改为小写。
      host: bj.bcebos.com
      date: Mon, 27 Apr 2015 16:23:49 +0800
      content-type: text/plain
      content-length: 8
      content-md5: NFzcPqhviddjRNnSOGo4rw==
      
    2. 将Header的值去掉开头和结尾的空白字符。
      host:bj.bcebos.com
      date:Mon, 27 Apr 2015 16:23:49 +0800
      content-type:text/plain
      content-length:8
      content-md5:NFzcPqhviddjRNnSOGo4rw==
      
    3. 做UriEncode。
      host:bj.bcebos.com
      date:Mon%2C%2027%20Apr%202015%2016%3A23%3A49%20%2B0800
      content-type:text%2Fplain
      content-length:8
      content-md5:NFzcPqhviddjRNnSOGo4rw%3D%3D?
      
    4. 把上面转换后的所有字符串按照字典序进行排序。
      content-length:8
      content-md5:NFzcPqhviddjRNnSOGo4rw%3D%3D?
      content-type:text%2Fplain
      date:Mon%2C%2027%20Apr%202015%2016%3A23%3A49%20%2B0800
      host:bj.bcebos.com
      
    5. 将排序后的字符串按顺序用\n符号连接起来得到最终结果。
      content-length:8
      content-md5:NFzcPqhviddjRNnSOGo4rw%3D%3D?
      content-type:text%2Fplain
      date:Mon%2C%2027%20Apr%202015%2016%3A23%3A49%20%2B0800
      host:bj.bcebos.com
      
      这时候认证字符串的signedHeaders内容应该是content-length;content-md5;content-type;date;host
    相关举例2:

    CanonicalHeaders的排序和signedHeaders排序不一致。

    CanonicalQueryString的示例一样,CanonicalHeaders也需要考虑排序的特殊情况。因为BCE API存在允许用户自定义Header的情况,所以这里需要特别注意。

    在BOS的PutObject中允许用户上传自定义meta,为了简明介绍,我们省略大部分Header,假设要编码的Headers如下:

    Host: bj.bcebos.com
    x-bce-meta-data: my meta data
    x-bce-meta-data-tag: description
    

    最终得到的CanonicalHeaders是:

    host:bj.bcebos.com
    x-bce-meta-data-tag:description
    x-bce-meta-data:my%20meta%20data
    

    signedHeadershost;x-bce-meta-data;x-bce-meta-data-tag

    从字符串比较的角度来说 x-bce-meta-data 应该放在 x-bce-meta-data-tag 之前,因此signedHeaders里面遵循了这个排序。但是CanonicalHeaders中因为在namevalue之间还有一个冒号(:),而冒号的ASCII码值要大于连字号(-)的ASCII码值,因此x-bce-meta-data反而放在了x-bce-meta-data-tag之后。

3.3 生成SigningKey

SigningKey = HMAC-SHA256-HEX(sk, authStringPrefix),其中:

  • sk为用户的Secret Access Key,可以通过在控制台中进行查询,关于SK的获取方法,请参看获取AK/SK
  • authStringPrefix代表认证字符串的前缀部分,即:bce-auth-v2/{accessKeyId}/{date}/{region}/{service}

3.4 生成Signature

Signature = HMAC-SHA256-HEX(SigningKey, CanonicalRequest)

3.5 生成认证字符串

认证字符串 = bce-auth-v2/{accessKeyId}/{date}/{region}/{service}/{signedHeaders}/{signature}

  • date:签名的UTC日期,格式为yyyymmdd,例如:20150427。
  • region:所请求服务资源所在的区域,小写格式。例如:bj。
  • service:所请求的服务名称,小写格式。例如:bos。
  • signedHeaders:签名算法中涉及到的HTTP头域列表。HTTP头域名字一律要求小写且头域名字之间用分号(;)分隔,如host;range;x-bce-date。列表按照字典序排列。当signedHeaders为空时表示取默认值。