Overview

V2 authentication string is the latest API authentication protocol of Baidu AI Cloud. Based on the V2 protocol, the service can provide higher request response performance, and users can also ensure their key security to a greater extent. Currently, the Forms Service BTS already supports the authentication string of the v2 protocol. For details, see BTS API Reference.

The formula for generating the V2 authentication string is as follows:

bce-auth-v2/{accessKeyId}/{date}/{region}/{service}/{signedHeaders}/{signature}

Among them,

• accessKeyId: For Access Key ID, please see Get AK/SK to get it.

• date: For the signed UTC date, the format is yyyymmdd, for example: 20150427.
• region: region of the requested service resource, lowercase. E.g.: bj.
• service: Requested service name, in lower case. E.g.: bos.
• signedHeaders: A list of HTTP header fields involved in the signature algorithm. HTTP header field names are always lowercase and separated by semicolons (;), such as host; range; x-bce-date. The list is arranged in lexicographic order. When signedHeaders is empty, the default value is used.
• signature: The signature is an important part of the authentication string. The calculation process is more complicated. The signature generation process will be described in detail in the article.

Signature Generation

The calculation formula for the V2 authentication signature is signature = HMAC-SHA256-HEX (SigningKey, CanonicalRequest). From the formula, we can see that in order to get the signature, you need to get the two parameters SigningKey andCanonicalRequest. The following illustrates how to get these two parameters.

Generate CanonicalRequest

The formula for CanonicalRequest is: CanonicalRequest = HTTP Method "\n" CanonicalURI "\n " CanonicalQueryString "\n " CanonicalHeaders,

HTTP Method

It refers to the GET, PUT, and POST requests defined in the HTTP protocol, which must be in all uppercase. There are five HTTP methods involved in Baidu AI Cloud API.

• GET
• POST
• PUT
• DELETE
• HEAD

CanonicalURI

CanonicalURI is the result of encoding the absolute path in the URL, that is,CanonicalURI = UriEncodeExceptSlash (Path). The absolute path Path must start with"/". It is necessary to add those which do not start with"/", and the empty path is"/".

• Related examples:

If the URL is https://bos.cn-n1.baidubce.com/example/test, the URL Path is/example/test, which is normalized to CanonicalURI =/example /% E6% B5% 8B% E8% AF% 95.

CanonicalQueryString

CanonicalQueryString corresponds to the result of Query String in URL (Query String is "key1=valve1&key2=valve2" string after "? "in URL)after encoding.

The encoding steps are as follows:

1. Extract the Query String item in the URL, that is, the "key1 = valve1&key2 = valve2 " string after "?" in the URL
2. Separate Query String into several items according to &, each item is key=value or only key.

3. Encode each item separated, consisting of the following three cases.

   • When the key of the item is authorization, ignore the item.
   • When the item has only key, the conversion formula is in the form ofUriEncode (key)+"=".
   • When the item is in the form of key=value, the conversion formula is in the form ofUriEncode (key)+"="+UriEncode (value). Here value can be an empty string.
4. Sort each converted string in lexicographical order (ASCII code from small to large), and connect with the & symbol to generate the corresponding CanonicalQueryString.

Coding example

Get URL as https://bos.cn-n1.baidubce.com/example? text&text1=Test&text10=test's CanonicalQueryString

1. Extract the Query String in the URL and get text&text1=Test&text10=test.
2. Split Query String according to &, and get three items: text,text1=test, and text10=test.

3. Encode each item of the split.

   • Encode text items to get UriEncode (" text ")+"="= text =
   • Encode the text1=test item to getUriEncode ("text1")+"="+ UriEncode ("test")=text1 =% E6% B5% 8B% E8% AF% 95
   • Encode the item text10=test to get UriEncode ("text10")+ "="+UriEncode ("test")=>text10=test
4. Sort the three encoded strings (from small to large according to the ASCII code), and get the results text10=test,text1 =% E6% B5% 8B% E8% AF% 95, text= , then connect with & t, and get CanonicalQueryString astext10=test&text1 =% E6% B5% 8B% E8% AF% 95&text=.

Note:

1. For the meaning and function of the function UriEncode, please see [Related Explanation](#Related Function Description) .
2. The example shows how to sort items with only keys, non-English values, and numbers and =. In the actual BCE API, since the parameter names are standardized, such sorting does not basically occur. Normal sorting results are exactly the same as sorting by key only. The constraint in the algorithm is mainly due to the strictness of the definition.

CanonicalHeaders

CanonicalHeaders is the result of selectively encoding the header part of the HTTP request.

The encoding steps are as follows:

1. Select the encoded Header. You can decide which headers need encoding. The only requirement for Baidu AI Cloud API is that the Host domain must be encoded. In most cases, we recommend that you encode the following headers:

   • Host
   • Content-Length
   • Content-Type
   • Content-MD5
   • All headers that start with x-bce-

   Note:

   1. If none of the above headers appear in your HTTP request, then the parts that do not appear need not be encoded.If the sent request contains the above headers, the headers that appear must be signed.
   2. If you use the Header in the above recommended range for encoding, the "{signedHeaders}" in the authentication string can be left blank. If you pass in signedHeaders, it will be signed according to the contents of signedHeaders.
   3. You can also choose the header you want to encode yourself. If you choose a header that is not in the recommended range for encoding, or your HTTP request contains a header that is in the recommended range but you choose not to encode it, you must fill in {signedHeaders} in the authentication string. The filling method is to convert all Header names encoded at this stage to all lowercase, arrange them in lexicographic order, and then concatenate them with semicolons (;).
   4. Choosing which headers to encode will not affect the functionality of the API. But too few selection can lead to man-in-the-middle attacks.

2. Encode the Header to get CanonicalHeaders. The encoding steps are as follows.

   1. Change the name of the header to all lowercase. Note that only the name is changed.
   2. Remove the leading and trailing whitespace characters from the value of the header.
   3. After the previous step, headers with empty strings are ignored, and the rest are converted to the form of UriEncode (name)+": "+UriEncode (value).
   4. Sort all the converted strings in lexicographic order.
   5. Concatenate the sorted strings in order with the \ n symbol to get the finalCanonicalHeaders.

Note:

1. For the meaning and function of UriEncode, please see the description of [Related Functions](#Description of Related Functions).
2. Many third-party libraries that send HTTP requests will add or delete headers you specify (for example: Some libraries will delete the header of content-length: 0). If the signature is wrong, please check the header of the http request that you actually sent to see if it is the same as the header when signing.

Coding example 1

This example demonstrates using Header outside the Baidu AI Cloud recommendation range for encoding. At this time, signedHeaders cannot be empty (the default value). In the following example, choose to encode Date and ignorex-bce-date.

Here is the header that sends the request:

Host: bj.bcebos.com
Date: Mon, 27 Apr 2015 16:23:49 +0800
Content-Type: text/plain
Content-Length: 8
Content-Md5: NFzcPqhviddjRNnSOGo4rw==
x-bce-date: 2015-04-27T08:23:49Z

1. Select the Header you want to encode, and change all names to lowercase.

host: bj.bcebos.com
date: Mon, 27 Apr 2015 16:23:49 +0800
content-type: text/plain
content-length: 8
content-md5: NFzcPqhviddjRNnSOGo4rw==

2. Remove the leading and trailing whitespace characters from the value of the 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. Perform UriEncode conversion on each Header.

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. Sort all strings converted in step 3 in lexicographic order.

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. Concatenate the sorted strings in order with the \ n symbol to get the final result.

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

At the same time, the content of the signedHeaders that obtained the authentication string should becontent-length; content-md5; content-type; date; host.

Coding example 2

This example demonstrates the situation that the ordering of CanonicalHeaders and the ordering ofsignedHeaders are inconsistent. Since the BCE API allows users to customize the header, pay special attention to it.

For example, in the PutObject of BOS, users are allowed to upload custom meta. For the sake of concise introduction, we omit most of the Headers, assuming that the headers to be encoded are as follows:

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

Following the coding steps above, the final CanonicalHeaders is:

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

The signedHeaders obtained then ishost; x-bce-meta-data; x-bce-meta-data-tag.

It can be seen that the ordering of CanonicalHeaders andsignedHeaders is different. This is because signedHeaders is sorted according to the name of the header, andx-bce-meta-data is placed before x-bce-meta-data- tag. But in CanonicalHeaders, it is sorted according to the entire string composed of name and value, because there is a colon (:) betweenname and value, and the ASCII value of the colon is greater than the ASCII value of the font size (-), sox-bce-meta-data is placed after x-bce-meta-data-taginstead.

Generate SigningKey

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

• sk is the user's Secret Access Key, which can be queried in the console. For how to get SK, please see Get AK/SK
• authStringPrefix represents the prefix part of the authentication string, that is: bce-auth-v2/{accessKeyId}/{date}/{region}/{service}.

Generate Signature and Authentication String

The SigningKey and CanonicalRequest obtained through the above calculation can get the signature according to the following formula. Signature = HMAC-SHA256-HEX(SigningKey, CanonicalRequest)

Among them,

• HMAC-SHA256-HEX is the HMAC SHA256 algorithm function. For specific functions and descriptions, see [Related Function Descriptions](#Related Function Descriptions).

Finally, get the authentication string according to the formula bce-auth-v2/{accessKeyId}/{date}/{region}/{service}/{signedHeaders}/{signature}.

Description of Related Functions

UriEncode () function reference code is as follows:

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();
}

Comparison between V2 and V1 Authentication Strings

V2 Authentication String Compared with V1 Version Authentication String, there are the following changes:

• Format adjustment of authentication string. Compared with the V1 authentication string, the V2 authentication string reduces the signature timestamp and expiration time, and increases the signature date and effective service area limitation. The specific format is: bce-auth-v2/{accessKeyId}/{date}/{region}/{service}/{signedHeaders}/{signature}
• The signingKey generation method becomes: HMAC-SHA256-HEX(sk, "bce-auth-v2/{accessKeyId}/{date}/{region}/{service}")
• A header field/request parameter that must be signed. The reduced signature timestamp in the authentication string must be included in the signature in the form of the x-bce-date request header or QueryString parameter; if the expiration time is set in the request throughx-bce-expiration, it must be counted into signature. If no expiration time is specified in the request, the request will expire in 15 minutes by default.

Same point: The signature calculation process in V2 also includes the generation process of CanonicalRequest, SigningKey, and Signature, which are basically the same as those in V1.