You must sign all API requests to ensure security. Alibaba Cloud uses the request signature to verify the identity of the API caller. When you call an API operation by using HTTP or HTTPS, the request must include the signature information.

Description

Alibaba Cloud authenticates each access request. Therefore, each request must contain signature information, regardless of whether it is sent through HTTP or HTTPS. Alibaba Cloud Marketplace implements symmetric encryption with an AccessKey pair to verify the identity of the request sender. An AccessKey pair is an identity credential issued to Alibaba Cloud accounts and Resource Access Management (RAM) users. It is similar to a logon username and password. An AccessKey pair consists of an AccessKey ID and an AccessKey secret. The AccessKey ID is used to verify the identity of the user, while the AccessKey secret is used to encrypt and verify the signature string. You must keep your AccessKey secret strictly confidential.

Signature calculation

The signature algorithm complies with RFC 2104 HMAC-SHA1 specifications. It uses the AccessKey secret to calculate the Hash-based Message Authentication Code (HMAC) of the encoded and formatted request string as the signature. The elements used for calculating a signature are some parameters of the request. Therefore, the signature results vary according to API requests.

Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(
StringToSign)) )
To calculate the signature, follow these steps:
  1. Compose and encode a string-to-sign.
    1. Use request parameters to create a canonicalized query string.
      1. Arrange the request parameters (including all common and operation-specific parameters except Signature) in alphabetical order.

        When you use the GET method to submit a request, the request parameters are included as a part of the URL. The request parameters in the URL are placed after a question mark (?) and separated with ampersands (&).

      2. Encode the canonicalized query string in UTF-8. The following table describes the encoding rules.
        Character Encoding rule
        Uppercase letters (A-Z), lowercase letters (a-z), digits (0-9), and some special characters including hyphens (-), underscores (_), periods (.), and tildes (~) Not encoded.
        Other characters Percent encoded in %XY format. XY represents the ASCII code of the characters in hexadecimal notation. For example, double quotation marks (") are encoded as %22.
        Extended UTF-8 characters Encoded in %XY%ZA... format.
        Space Encoded as %20. Do not encode spaces as plus signs (+).
        This encoding method is similar to but different from the application/x-www-form-urlencoded MIME encoding algorithm (such as the java.net.URLEncoder class provided by the Java standard library). You can use this encoding method directly by replacing the plus sign (+) in the encoded string with %20, the asterisk (*) with %2A, and %7E with the tilde (~) to conform to the preceding encoding rules. You can use the following percentEncode method to implement this algorithm.
        private static final String ENCODING = "UTF-8";
        private static String percentEncode(String value) throws UnsupportedEncodingException 
        {
        return value ! = null ? URLEncoder.encode(value, ENCODING).replace("+", "%20").replace("*", "%2A").replace("%7E", "~") : null;
        }
      3. Connect the encoded parameter names and their values with equal signs (=).
      4. Arrange the parameter name and value pairs connected by equal signs in the order specified in step 1.1.1, and connect them with ampersands (&) to produce the canonicalized query string.
    2. Create a string-to-sign from the encoded canonicalized query string.
      StringToSign=
            HTTPMethod + "&" +
            percentEncode("/") + "&" +
             percentEncode(CanonicalizedQueryString)

      where:

      • HTTPMethod: the HTTP method used to make the request, such as GET.
      • percentEncode("/"): the encoded value for the forward slash (/) based on the URL encoding rules described in step 1.2, which is %2F.
      • percentEncode(CanonicalizedQueryString): the string encoded from the canonicalized query string created in step 1 based on the URL encoding rules described in step 1.2.
  2. Calculate the signature.
    1. Calculate the HMAC value of the string-to-sign based on RFC 2104.
      Note The key used for calculating the signature is your AccessKey secret followed by an ampersand (&). Use Secure Hash Algorithm 1 (SHA1) for the calculation.
    2. Encode the HMAC value in Base64 to obtain the signature string.
    3. Add the signature string to the request as the Signature parameter.
      Note When the obtained signature string is submitted as the final request parameter value, the value must be URL-encoded like other parameters based on rules defined in RFC 3986.

Example

Take DescribeRegions as an example. Assume that the AccessKey ID is testid and the AccessKey secret is testsecret. The original request URL is as follows:

http://ecs.aliyuncs.com/?TimeStamp=2016-02-23T12:46:24Z&Format=XML&AccessKeyId=testid&Action=DescribeRegions&SignatureMethod=HMAC-SHA1&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&Version=2014-05-26&SignatureVersion=1.0

The string-to-sign is as follows:

GET&%2F&AccessKeyId%3Dtestid&Action%3DDescribeRegions&Format%3DXML&SignatureMethod%3DHMAC-SHA1&SignatureNonce%3D3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&SignatureVersion%3D1.0&TimeStamp%3D2016-02-23T12%253A46%253A24Z&Version%3D2014-05-26

The AccessKey secret is testsecret, so the key used for calculating the HMAC value is testsecret&. The calculated signature string is as follows:

CT9X0VtwR86fNWSnsc6v8YGOjuE=

Use the signature string as the value of the Signature parameter and add the parameter to the request URL. The final URL is as follows:

http://ecs.aliyuncs.com/?SignatureVersion=1.0&Action=DescribeRegions&Format=XML&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&Version=2014-05-26&AccessKeyId=testid&Signature=CT9X0VtwR86fNWSnsc6v8YGOjuE%3D&SignatureMethod=HMAC-SHA1&TimeStamp=2016-02-23T12%3A46%3A24Z