Overview

In the API authentication mode, the formula for generating the authentication string is as follows:

bce-auth-v1/{accessKeyId}/{timestamp}/{expirationPeriondInSeconds }/{signedHeaders}/{signature}

Among them,

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

• timestamp: The time when the signature takes effect in UTC, the format is yyyy-mm-ddThh: mm: ssZ, for example: 2015-04-27T08:23:49Z, the default value is the current time, please note that the signature effective time and the sending request time must be the same.
• expirationPeriodInSeconds: The signature validity period is calculated from the time specified by timestamp, in seconds, and the default value is 1800 seconds (30) minutes.
• 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. Prepare in reference to [example](#authentication string example).
• signature: Signature. The calculation process is more complicated and will be described in detail below.

Generation Method

You can use online signature tools, Postman scripts, or offline programming to generate v1 authentication strings.

Online Signature Tool Generation

Baidu AI Cloud provides online generation of Signature Tool. Users only need to fill in the necessary header fields and AKSK fields to quickly generate authentication strings.

Postman Script Generated Directly

Baidu AI Cloud also provides a method based on Postman script. Users only need to follow the steps in the manual for simple configuration, and then automatically calculate the signature and authentication strings of Baidu AI Cloud.

Offline Programming

You can also understand the specific generation process of authentication strings through the following text, and then write the code to generate the corresponding authentication strings.

Description of Steps to Generate Authentication String

As shown in the authentication string generation formula, all parameters are known except the parameter signature. The following describes the generation process of the signature in detail, and then gets the authentication string.

The signature calculation formula is signature = HMAC-SHA256-HEX (SigningKey, CanonicalRequest). It can be seen from the formula that in order to get the signature, you need to get the two parameters SigningKey andCanonicalRequest. First of all, how to get these two parameters.

Generate CanonicalRequest

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

It can be seen from the formula that CanonicalRequest is composed ofHTTP Method, CanonicalURI,CanonicalQueryString, and CanonicalHeaders, and their specific meanings and methods of obtaining are as follows.

1. 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

2. CanonicalURI

CanonicalURI is the result of encoding the absolute path in the URL, i.e. CanonicalURI = UriEncodeExceptSlash (Path). It is required that the absolute path must start with "/". The path that does not start with "/" needs to be added. The empty path is "/". For the specific meaning and function of the function UriEncodeExceptSlash, please see [Related Function](#Related Function Description).

• Example:

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

3. CanonicalQueryString

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

The encoding steps are as follows

1. Extract the Query String item in the URL, after "?" in URL
2. Separate Query String into several items according to &, each item is key=value or onlykey.

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.

4. 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 function of API, but if you choose too few, you may suffer from man-in-the-middle attack. Baidu AI Cloud requires that you include at least the Host domain.

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 Function](#Related Function Description).
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, signed Headers 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:

• HMAC-SHA256-HEX is the HMAC SHA256 algorithm function. For specific functions and descriptions, see [Related Function Descriptions](#Related Function Descriptions).
• 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-v1/{accessKeyId}/{timestamp}/{expirationPeriodInSeconds}。

Generate Signature and Authentication Strings

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, the authentication string is obtained by the formula bce-auth-v1/{accessKeyId}/{timestamp}/{expirationPeriondInSeconds}/{signedHeaders}/{signature}.

Example of Authentication String

After the above description on how to generate a string, each step of the generation is demonstrated in detail in the following example. The example assumes that the user uploads the last part of a file to the BOS cluster in Beijing using the UploadPart interface, whose content is Example. User information is as follows

Bucket name:test
Object key:myfolder/readme.txt
uploadId:a44cc9bab11cbd156984767aad637851
partNumber:9
Access Key ID:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Secret Access Key:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
Time: Beijing time at 16:23:49 on April 27, 2015 (translated to UTC time: 8:23:49 on April 27, 2015) 

The HTTP request sent by the user is:

PUT /v1/test/myfolder/readme.txt?partNumber=9&uploadId=a44cc9bab11cbd156984767aad637851 HTTP/1.1
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

Example

1. Generate CanonicalRequest.

   CanonicalRequest consists of four parts: HTTP Method, CanonicalURI, CanonicalQueryString, and CanonicalHeaders.

   HTTP Method ="PUT" 
   CanonicalURI= UriEncodeExceptSlash(/v1/test/myfolder/readme.txt)="/v1/test/myfolder/readme.txt"
   CanonicalQueryString="partNumber=9&uploadId=a44cc9bab11cbd156984767aad637851"
   CanonicalHeaders="content-length:8
    content-md5:NFzcPqhviddjRNnSOGo4rw%3D%3D
    content-type:text%2Fplain
    host:bj.bcebos.com
    x-bce-date:2015-04-27T08%3A23%3A49Z"

   Finally, CanonicalRequest is obtained by the formula CanonicalRequest= HTTP Method + "\ n" + CanonicalURI + "\ n" + CanonicalQueryString + "\ n" + CanonicalHeaders.

   PUT
   /v1/test/myfolder/readme.txt
   partNumber=9&uploadId=a44cc9bab11cbd156984767aad637851
   content-length:8
   content-md5:NFzcPqhviddjRNnSOGo4rw%3D%3D
   content-type:text%2Fplain
   host:bj.bcebos.com
   x-bce-date:2015-04-27T08%3A23%3A49Z

2. Generate SigningKey

   The SigningKey is calculated by the formula SigningKey= HMAC-SHA256-HEX (sk, authStringPrefix).
   SigningKey= HMAC-SHA256-HEX("bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "bce-auth-v1/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/2015-04-27T08:23:49Z/1800")=1d5ce5f464064cbee060330d973218821825ac6952368a482a592e6615aef479

3. Generate Signature

   Get by the formula Signature = HMAC-SHA256-HEX (SigningKey, CanonicalRequest) Signature= d74a04362e6a848f5b39b15421cb449427f419c95a480fd6b8cf9fc783e2999e

4. Generate authentication string

   Authorization = bce-auth-v1/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/2015-04-27T08:23:49Z/1800//d74a04362e6a848f5b39b15421cb449427f419c95a480fd6b8cf9fc783e2999e

5. The final HTTP request sent by the user contains authentication information

   PUT /v1/test/myfolder/readme.txt?partNumber=9&uploadId=a44cc9bab11cbd156984767aad637851 HTTP/1.1
   Authorization:bce-auth-v1/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/2015-04-27T08:23:49Z/1800//d74a04362e6a848f5b39b15421cb449427f419c95a480fd6b8cf9fc783e2999e
   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
   
   
   Example

Note:

There are two "/" between the timeout 1800 and the signature result, which means that the default signature method is used and the content of signedHeaders is left blank.

Related Function Description

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