Alibaba Cloud SDK:Request syntax and signature method V3

Step 1: Construct a canonicalized request

To use an AccessKey pair to calculate or verify a signature, you must construct a canonicalized request. The client and API gateway must use the same request specifications so that they can obtain the same signature string for an HTTP request to complete identity verification.

Construct a canonicalized request based on the following pseudocode:

CanonicalRequest =
  HTTPRequestMethod + '\n' +    // The HTTP method in uppercase letters.
  CanonicalURI + '\n' +         // The canonicalized URI.
  CanonicalQueryString + '\n' + // The canonicalized query string.
  CanonicalHeaders + '\n' +     // The canonicalized request headers.
  SignedHeaders + '\n' +        // The request headers that are used for signature calculation.
  HashedRequestPayload			

• HTTPRequestMethod: the HTTP method in uppercase letters, such as POST and GET.

• CanonicalURI

  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 (/) following the endpoint but excludes the question mark (?) preceding 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 %XY format. XY indicates the ASCII code of the characters in hexadecimal notation. For example, double quotation marks (") are encoded as %22.

  • Extended UTF-8 characters are encoded in the %XY%ZA… format.

  • Spaces must be encoded as %20 instead of (+). The preceding encoding scheme is similar to but slightly different from the application/x-www-form-urlencoded Multipurpose Internet Mail Extension (MIME) encoding algorithm.

    If you use java.net.URLEncoder in the Java standard library, use percentEncode to encode the strings. In the encoded strings, replace the plus sign (+) with %20, the asterisk (*) with %2A, and %7E with a tilde (~). This way, you can obtain encoded strings that match the preceding encoding scheme.

  Note: If the resource path is empty, use a forward slash (/) as the value of the CanonicalURI parameter.

• CanonicalQueryString: the canonicalized query string. You can perform the following steps to construct the canonicalized query string:

  • Sort the parameters in the query string by the parameter name in alphabetical order. For parameters with the same name, sort the parameters by the parameter value in alphabetical order.

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

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

  • Sort the parameters by the encoded parameter name in alphabetical order. For parameters with the same name, sort the parameters by the encoded parameter value in alphabetical order.

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

  Note: If the query string is empty, use an empty string as the canonicalized query string, which is a blank line.

• CanonicalizedHeaders: the non-standard HTTP headers. Non-standard HTTP headers are headers whose names are prefixed with x-acs- in the request. You can perform the following steps to construct canonicalized headers:

  • Convert the names of all headers that are used for signature calculation to lowercase letters.

  • Remove the spaces before and after the value of a header. If a header has multiple values, remove the spaces before and after each value, sort the values in alphabetical order, and then use commas (,) to concatenate the values.

  • Use a colon (:) to concatenate the name and value of a header obtained in the preceding steps and add a line break at the end to construct a canonicalized header.

  • Concatenate all canonicalized headers by the lowercase header name in alphabetical order.

  • If no headers are used for signature calculation, use an empty string as the canonicalized headers.

Note: All common request headers except the Authorization header must be used for signature calculation.

• SignedHeaders: the names of the headers that are used for signature calculation. This parameter contains the same headers as those in the CanonicalHeaders parameter. You can perform the following steps to construct signed headers:

  • Convert the names of headers in the CanonicalHeaders parameter to lowercase letters.

  • Use semicolons (;) to concatenate all the headers by lowercase header name in alphabetical order. Example: content-type;host;x-acs-date.

  • Pseudocode:

    CanonicalHeaderEntry = Lowercase(HeaderName) + ':' + Trim(HeaderValue) + '\n'
    
    CanonicalHeaders = 
        CanonicalHeaderEntry0 + CanonicalHeaderEntry1 + ... + CanonicalHeaderEntryN

• HashedRequestPayload: the hash value of the request body. The following pseudocode shows how to generate the hash value: HashedRequestPayload = HexEncode(Hash(RequestPayload)). RequestPayload indicates the request body.

  • Hash() indicates the hash algorithm. Only the SHA256 algorithm is supported. For example, if the encryption method of the signature string is ACS3-HMAC-SHA256, you must use SHA256 as the hash algorithm.

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

  • Note: If the request body is empty, such as in a GET request, use an empty string as the value of the RequestPayload parameter.

  Table 1: Mappings among encryption methods of the signature string, signature calculation algorithms, and hash algorithms

  Encryption method of signature string (SignatureAlgorithm)	Hash algorithm used to process RequestPayload and CanonicalRequest (Hash)	Algorithm for signature calculation (SignatureMethod)
  ACS3-HMAC-SHA256	SHA256	HMAC-SHA256