Signature mechanism

Request method (HTTPRequestMethod)

The HTTP request method in uppercase letters, such as GET or POST.

Canonicalized URI (CanonicalURI)

The canonicalized URI is the encoded resource path in the URL. The resource path is the part between the endpoint and the query string. The path includes the forward slash (/) that follows the endpoint but excludes the question mark (?) that precedes the query string. You must use a canonicalized URI for signature calculation. To construct a canonicalized URI, encode the strings separated by forward slashes (/) in UTF-8 based on RFC 3986. Encoding rules:

• Letters, digits, hyphens (-), underscores (_), periods (.), and tildes (~) do not need to be encoded.

  Other characters must be percent-encoded in the following format: % + ASCII code of the characters in hexadecimal notation. For example, double quotation marks (") are encoded as %22. The following table describes some special characters before and after encoding. Pay attention to these special characters.

  Before encoding	After encoding
  Space characters ( )	%20
  Asterisks (*)	%2A
  %7E	Titles (~)

If you use java.net.URLEncoder in the Java standard library, encode the strings based on the standard library. In the encoded strings, replace plus signs (+) with %20, asterisks (*) with %2A, and %7E with tildes (~). This way, you can obtain encoded strings that match the preceding encoding rules.

Canonicalized query string (CanonicalQueryString)

In the API metadata, if the request parameters of an API request contain the "in":"query" position information, you need to concatenate the request parameters based on the following method:

1. Sort all request parameters by parameter name in alphabetical order.

2. Encode the parameter names and values in UTF-8 based on RFC 3986. The encoding rules are the same as those used to construct the canonicalized URI.

3. Use an equal sign (=) to concatenate the encoded name and value of each parameter. For a parameter without a value, use an empty string as the parameter value.

4. Use ampersands (&) to concatenate the encoded parameters in the order obtained in the previous step.

Example:

ImageId=win2019_1809_x64_dtc_zh-cn_40G_alibase_20230811.vhd&RegionId=cn-shanghai

HashedRequestPayload

Use the hash function to convert the request body and encode the hash value in Base16 to generate the HashedRequestPayload. Then, change the value of x-acs-content-sha256 in the request header to the value of HashedRequestPayload. Pseudocode:

HashedRequestPayload = HexEncode(Hash(RequestBody))

• In the API metadata, if the request parameters contain the "in": "body" or "in": "formData" position information, specify the parameters in the request body.

  Note

  If the request does not have a body, set the value of RequestBody to an empty string.

  • If the request parameters contain the "in": "formData" position information, concatenate them into a string in the following format: key1=value1&key2=value2&key3=value3, and add the Content-Type header and set it to application/x-www-form-urlencoded. For example, if the request parameters are of the array or object type, convert their values to indexed key-value pairs.

  • If the request parameters contain the "in": "body" position information, add the Content-Type header to the request. The value of the Content-Type header specifies the type of request content. Example:

    • If the request content is a JSON string, set the value of the Content-Type header to application/json.

    • If the request content is a binary file stream, set the value of the Content-Type header to application/octet-stream.

• Hash() specifies a hash function. Only the SHA-256 algorithm is supported.

• HexEncode() encodes the hash value in Base16. This function returns an encoded hash value in the hexadecimal format in lowercase letters.

Sample value when the request body is empty:

e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Canonicalized headers (CanonicalHeaders)

Concatenate the parameters in the request headers based on the following method:

1. Filter out request headers that start with x-acs-, the Host header, and the Content-Type header.

2. Convert the header names to lowercase and sort the headers in alphabetical order.

3. Remove the spaces before and after the value of each header.

4. Concatenate the header name and header value by using a colon (:), and append a line feed (\n) at the end of the name-value pair to form a canonicalized header entry.

5. Concatenate multiple canonicalized header entries into a string.

Pseudocode:

CanonicalHeaderEntry = Lowercase(HeaderName) + ':' + Trim(HeaderValue) + '\n'

CanonicalHeaders = 
    CanonicalHeaderEntry0 + CanonicalHeaderEntry1 + ... + CanonicalHeaderEntryN

Example:

host:ecs.cn-shanghai.aliyuncs.com
x-acs-action:RunInstances
x-acs-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-acs-date:2023-10-26T10:22:32Z
x-acs-signature-nonce:3156853299f313e23d1673dc12e1703d
x-acs-version:2014-05-26

Signed headers (SignedHeaders)

Signed headers provide information about the common request headers used for signature calculation. The name of each signed header corresponds to the name of a canonicalized header. You can perform the following steps to construct signed headers:

• Convert the names of the canonicalized headers to lowercase.

• Sort the headers in alphabetical order and use semicolons (;) to separate the headers.

Pseudocode:

SignedHeaders = Lowercase(HeaderName0) + ';' + Lowercase(HeaderName1) + ... + Lowercase(HeaderNameN) 

Example:

host;x-acs-action;x-acs-content-sha256;x-acs-date;x-acs-signature-nonce;x-acs-version