You must sign all API requests to ensure security. Alibaba Cloud uses the request signature to verify the identity of the API caller. Each API request must contain the signature, regardless of whether the request is sent over HTTP or HTTPS.

Overview

To call a remote procedure call (RPC) API operation, 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
In the preceding format:
  • SignatureMethod: the encryption algorithm used to calculate the signature. Set the value to HMAC-SHA1.
  • SignatureVersion: the version of the signature encryption algorithm. Set the value to 1.0.
  • SignatureNonce: a unique, random number used to prevent replay attacks. You must use different numbers for different requests. We recommend that you use universally unique identifiers (UUIDs).
  • Signature: the signature of the request. The signature is generated by using a symmetric encryption algorithm with the AccessKey secret as the key.

Signature calculation

The signature algorithm complies with the HMAC-SHA1 specifications in RFC 2104. The AccessKey secret is used to calculate the Hash-based Message Authentication Code (HMAC) value of an encoded and formatted query string. The HMAC value is then used as the signature. Some parameters in a request are used to calculate the signature. Therefore, the signature of a request varies based on the API request parameters.

Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(
StringToSign)) )
To calculate a signature, perform the following steps:
  1. Compose and encode a string-to-sign.
    1. Use the request parameters to construct a canonicalized query string:
      1. Create a canonicalized query string by arranging the request parameters in alphabetical order. Include all common and operation-specific parameters except Signature.

        If you use the GET method to submit the request, these parameters are the part of the request uniform resource identifier (URI) located after the question mark (?) and connected by the ampersands (&) in the request URI.

      2. Encode the canonicalized query string in the UTF-8 format. The following table describes the encoding rules.
        Character Encoding rule
        Uppercase letters (A-Z), lowercase letters (a-z), digits (0-9), and the following special characters: hyphens (-), underscores (_), periods (.), 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 UTF-8 characters These characters are encoded in the %XY%ZA... format.
        Space characters 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. To convert such texts to the percent encoded format, replace plus signs (+) in the encoded string with %20, asterisks (*) with %2A, and %7E with tildes (~). To implement this algorithm, you can use the following percentEncode method:
        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. Separately associate the encoded parameter names with their encoded values by using equal signs (=).
      4. Sort the parameter name and value pairs in the order specified in Step i. Then, 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)

      In the preceding rules:

      • HTTPMethod: the HTTP method used to submit a request, such as GET.
      • percentEncode("/"): encodes backslashes (/) as %2F based on the URL encoding rule described in Step i.
      • percentEncode(CanonicalizedQueryString) encodes the canonicalized query string based on the URL encoding rule described in Step ii.
  2. Calculate signatures
    1. Calculate the RFC 2104-compliant HMAC value of the string-to-sign.
      Note Use the SHA1 algorithm to calculate the HMAC value of the string-to-sign. Your AccessKey secret followed by an ampersand (&) (ASCII code 38) is used as the key for HMAC 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 value is submitted as the final request parameter value, the value must be URL-encoded that is similar to other parameters based on rules defined in RFC 3986.

Examples

This example shows how to sign an API request for calling the DescribeRegions operation. If the value of the AccessKeyId parameter is testid, the AccessKeySecret parameter is testsecret. The following example shows the request URL to be signed:

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 following calculated signature string is returned by using testsecret&:

OLeaidS1JvxuMvnyHOwuJ+uX5qY=

The following URL is returned after the signature string is added to the request as the Signature parameter:

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