edit-icon download-icon

Signature

Last Updated: Sep 11, 2018

Detailed description

The API Gateway service performs authentication on each access request. Therefore, whether submitted through HTTP or HTTPS, a request must contain signature information.

The API Gateway service performs symmetric encryption using the AccessKey ID and AccessKey Secret to verify the identities of request senders. Alibaba Cloud issues the AccessKey ID and AccessKey Secret to visitors (obtain and manage them on the Alibaba Cloud website).

The AccessKey ID indicates the identity of a visitor.

The AccessKey Secret is the key used to encrypt the signature string and verify the signature string on the server. It must be kept strictly confidential, only known to Alibaba Cloud and the user.

Follow these steps to sign access requests:

a. Construct the Canonicalized Query String using the request parameters.

  • Sort the request parameters alphabetically by parameter name. (The request parameters include the “public request parameters” and the custom parameters for the given request interface described in this document, but do not include the Signature parameter mentioned in “Public request parameters”.)

NOTE: When a request is submitted using the GET method, these parameters constitute the parameter section of the request URI (that is, the section in the URI following the “?” and connected by “&”).

  • Encode the name and value of each request parameter. Perform URL encoding of parameter names and values using the UTF-8 character set. The URL encoding rules are as follows:
  1. The characters A-Z, a-z, 0-9, “-“, “_”, “.”, and “~” are not encoded.
  2. Other characters are encoded in “%XY” format, with XY representing the characters’ ASCII code in hexadecimal notation. For example, the double quotes (“) are encoded as %22.
  3. Extended UTF-8 characters are encoded in “%XY%ZA…” format.
  4. It must be noted that the space ( ) is encoded as %20, rather than the plus sign (+).
  1. NOTE: Generally, libraries that support URL encoding (for example, java.net.URLEncoder of Java) are all encoded according to the rules for the "application/x-www-form-urlencoded" MIME-type.
  2. You can use this encoding method directly by replacing the plus sign (+) with %20 and the asterisk (*) with %2A in the encoded string, and change %7E back to the tilde (~) to conform to the preceding encoding rules.
  • Connect the encoded parameter names and values with the equal sign (=).
  • Then, sort the parameter name and value pairs connected by equal signs in alphabetical order and connect them with the & symbol to produce the Canonicalized Query String.

b. Use the canonicalized query string to construct the string for signature calculation according to the following rules:

  1. StringToSign=
  2. HTTPMethod + “&” +
  3. percentEncode(“/”) + ”&” +
  4. percentEncode(CanonicalizedQueryString)

Here, HTTPMethod indicates an HTTP method used to submit requests, such as GET.

percentEncode(“/“) is the encoded value (namely, “%2F”) for the character “/“ according to the URL encoding rules described in 1.b.

percentEncode(CanonicalizedQueryString) is the encoded string of the Canonicalized Query String constructed in Step 1, produced by following the URL encoding rules described in 1.b.

c. According to RFC2104 definitions, use the preceding signature sting to calculate the signature’s HMAC value. NOTE: When calculating the signature, the Key is your AccessKey Secret appended with the “&” character (ASCII:38). The SHA1 hashing algorithm is used.

d. According to Base64 encoding rules, encode the preceding HMAC value into a string to obtain the signature value.

e. Add the obtained signature value as the “Signature” parameter to the request parameters to complete the request signing process.

NOTE: The obtained signature value requires URL encoding based on the RFC3986 rule like other parameters before it is submitted as the final request parameter value to the API Gateway server.

Using DescribeRegions as an example, the request URL before signature is:

  1. http://apigateway.cn-qingdao.aliyuncs.com?Format=json&AccessKeyId=testid&Action=DescribeRegions&SignatureMethod=Hmac-SHA1&SignatureNonce=d48e931b-90c9-49c7-ac86-a70dd3607c88&SignatureVersion=1.0&Version=2016-07-14&Timestamp=2016-09-27T09%3A08%3A30Z

Thus, the StringToSign is:

  1. GET&%2F&AccessKeyId%3Dtestid&Action%3DDescribeRegions&Format%3Djson&SignatureMethod%3DHmac-SHA1&SignatureNonce%3Dd48e931b-90c9-49c7-ac86-a70dd3607c88&SignatureVersion%3D1.0&Timestamp%3D2016-09-27T09%253A08%253A30Z&Version%3D2016-07-14

Assume that the AccessKey Id is “testid”, the AccessKey Secret is “testsecret”, and the Key used for HMAC calculation is “testsecret&”, the calculated signature value is:

lG8YeSKohaw568TaNdgRQH3yPCo=

The signed request URL is (with the Signature parameter added):

  1. http://apigateway.cn-qingdao.aliyuncs.com?Signature=DRdMb%2F1m7PeToGRBApTl3wThyOg%3D&Format=json&AccessKeyId=testid&Action=DescribeRegions&SignatureMethod=Hmac-SHA1&SignatureNonce=d48e931b-90c9-49c7-ac86-a70dd3607c88&SignatureVersion=1.0&Version=2016-07-14&Timestamp=2016-09-27T09%3A08%3A30Z
Thank you! We've received your feedback.