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 send an HTTP or HTTPS API request, the request must contain the signature information.

Overview

For an RPC API, you must add the signature to the API request in the following format:

https://Endpoint/?SignatureVersion=1.0&SignatureMethod=HMAC-SHA1&Signature=CT9X0VtwR86fNWSnsc6v8YGOjuE%3D&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf
where:
  • SignatureMethod: the encryption algorithm used to calculate the signature. Valid value: HMAC-SHA1.
  • SignatureVersion: the version of the signature encryption algorithm. Valid value: 1.0.
  • SignatureNonce: a unique random number. This parameter is used to prevent replay attacks. You must use different random numbers for multiple requests. We recommend that you use universally unique identifiers (UUIDs).
  • Signature: the signature generated after the request has been symmetrically encrypted by using the AccessKey secret.

Signature calculation

The signature encryption 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. Some parameters in a request are used to calculate the signature. Therefore, the signature of a request varies depending on the API request parameters.

Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(
StringToSign)) )
To calculate a signature, perform the following operations:
  1. Construct the string to be signed
    1. Use the request parameters to construct a canonicalized query string.
      1. Sort all request parameters (including all the common request parameters and operation-specific request parameters except Signature in alphabetical order.

        When you use the GET method to submit a request, the request parameters are placed after the question mark (?) in the URI and are separated by ampersands (&).

      2. Encode in UTF-8 the parameters and their values in the request URL. The encoding rules are as follows:
        Character Encoding method
        A- Z, a- z, 0-9, hyphen (-), underscore (_), and period (.), and tildes (~) These characters do not need to be encoded.
        Other characters These characters are percent encoded in the %XY format. XY represents the ASCII code of the characters in hexadecimal notation. For example, double quotation marks (") are encoded as %22.
        Extended ASCII characters (UTF-8) These characters are encoded in the %XY%ZA... format.
        Space Spaces must be encoded as %20. Do not encode spaces as plus signs (+).
        This encoding method is 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 encoding rules described above. 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. Associate the encoded parameters with their encoded values separately by using equal signs (=).
      4. Sort the parameter name and value pairs in the order specified in Step 1.1.1. and connect the pairs with ampersands (&) to produce the canonicalized query string.
    2. Use the canonicalized query string to construct the string for signature calculation based on the following rules:
      StringToSign=
            HTTPMethod + ''&'' +
            percentEncode("/") + "&" +
             percentEncode(CanonicalizedQueryString)

      where:

      • HTTPMethod indicates the HTTP method used to make the request, for example, GET.
      • percentEncode("/") is the encoded backslashes (/), namely %2F, according to the URL encoding rule described in Step 1.1.2.
      • percentEncode(CanonicalizedQueryString) encodes the canonicalized query string based on the URL encoding rule described in Step 1.1.2.
  2. Obtain the signature.
    1. Calculate the RFC 2104-compliant HMAC value of the string-to-sign.
      Note The key used for signature calculation is the combination of your AccessKey secret and an ampersand (&) (ASCII code 38) that follows the secret. The algorithm used to calculate your signature is HMAC-SHA1.
    2. Encode the HMAC into a string based on the Base64 encoding rules. This encoded string is the signature.
    3. Add the signature string to the request as the Signature parameter.
      Note When the obtained signature value is submitted as the last parameter value, you need to encode the parameter in the same way as other parameters by following the RFC3986 rule.

Example

Take the DescribeRegions API as an example. Suppose the AccessKey Id parameter value is testid and the AccessKey Secret parameter is testsecret. Before the request is signed, its 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 signature string calculated by using testsecret& is as follows:

OLeaidS1JvxuMvnyHOwuJ+uX5qY=

Add the Signature parameter to the request and set the value to the calculated signature string. Then the URL of the signed request 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=OLeaidS1JvxuMvnyHOwuJ+uX5qY=&SignatureMethod=HMAC-SHA1&Timestamp=2016-02-23T12%3A46%3A24Z