Signature mechanism

Updated at:

To ensure secure API calls, Alibaba Cloud uses a signature for identity verification on every API request. All API requests, whether submitted over HTTP or HTTPS, must include signature information.

Overview

For RPC APIs, add the signature to the query parameters of the API request in the following format:

https://Endpoint/?SignatureVersion=1.0&SignatureMethod=HMAC-SHA1&Signature=CT9X0VtwR86fNWSnsc6v8YGOjuE%3D&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf
The parameters are described as follows:
  • SignatureMethod: The signature algorithm. The value must be HMAC-SHA1.
  • SignatureVersion: The version of the signature algorithm. The value must be 1.0.
  • SignatureNonce: A unique random number used to prevent replay attacks. You must use a different random number for each request. We recommend that you use a universally unique identifier (UUID).
  • Signature: The signature string that is generated using your AccessKey secret to sign the request.

Calculate a signature

The signature algorithm follows the RFC 2104 HMAC-SHA1 specification. It uses your AccessKey secret to calculate the HMAC value of the string to be signed. This value is the signature. The signature is based on the request parameters. Because the content of each API request is different, the resulting signature is also different.

Signature = Base64( HMAC-SHA1( AccessKeySecret, UTF-8-Encoding-Of(
StringToSign)) )
To calculate a signature, complete the following steps:
  1. Create the string to sign
    1. Create a canonicalized query string from the request parameters:
      1. Sort all request parameters alphabetically by parameter name. The parameters include common request parameters and operation-specific parameters, but exclude the Signature parameter.

        For a GET request, these parameters are the part of the request URL that follows the question mark (?) and are separated by ampersands (&).

      2. URL-encode the names and values of the sorted request parameters using the UTF-8 character set. The encoding rules are as follows:
        • Do not encode uppercase letters (A-Z), lowercase letters (a-z), digits (0-9), hyphens (-), underscores (_), periods (.), or tildes (~).

        • Encode other characters into the %XY format, where XY represents the two-digit hexadecimal value of the character's ASCII code. For example, a double quotation mark (") is encoded as %22.

        • Encode extended UTF-8 characters into the %XY%ZA… format.

        • Encode a space as %20 instead of a plus sign (+).

          This encoding method is different from the standard application/x-www-form-urlencoded Multipurpose Internet Mail Extensions (MIME) format. For example, it differs from the implementation of java.net.URLEncoder in the Java standard library. You can first encode the string using a standard library. Then, replace the plus signs (+) with %20, asterisks (*) with %2A, and %7E with tildes (~) to obtain the required encoded string. You can implement this algorithm using 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;
          }
        • Join the encoded parameter name and value with an equal sign (=).
        • Join the resulting parameter strings with ampersands (&) in the order established in step a. This creates the canonicalized query string.
    2. Create the string to sign from the canonicalized query string as follows:
      StringToSign=
            HTTPMethod + "&" +
            percentEncode("/") + "&" +
             percentEncode(CanonicalizedQueryString)

      The components are described as follows:

      • HTTPMethod is the HTTP method used for the request, such as GET.
      • percentEncode("/") is the percent-encoded forward slash (/) character, which is %2F.
      • percentEncode(CanonicalizedQueryString) is the percent-encoded canonicalized query string from step 1.a.
  2. Calculate the signature
    1. Calculate the HMAC value of the string to sign (StringToSign) as defined in RFC2104.
      Note The key used for the calculation is your AccessKey secret appended with an ampersand (&) character (ASCII code 38). The hash algorithm is SHA1.
    2. Encode the HMAC value into a string using Base64 encoding. The resulting string is the signature value (Signature).
    3. Add the signature value to the request parameters as the Signature parameter.
      Note When you submit the signature value as the final request parameter, it must be URL-encoded in the same way as other parameters according to RFC3986.

Example

This example shows how to sign a request for the DescribeStores operation. Assume that the AccessKey ID is testid and the AccessKey secret is testsecret. The request URL before signing is as follows:

http://cloudesl.cn-hangzhou.aliyuncs.com/?Timestamp=2016-02-23T12:46:24Z&Format=XML&AccessKeyId=testid&Action=DescribeStores&SignatureMethod=HMAC-SHA1&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&Version=2020-02-01&SignatureVersion=1.0

Using testsecret& as the key, the calculated signature is:

OLeaidS1JvxuMvnyHOwuJ+uX5qY=

Finally, add the signature to the request URL as the Signature parameter. The final request URL is:

http://cloudesl.cn-hangzhou.aliyuncs.com/?SignatureVersion=1.0&Action=DescribeStores&Format=XML&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&Version=2020-02-01&AccessKeyId=testid&Signature=OLeaidS1JvxuMvnyHOwuJ+uX5qY=&SignatureMethod=HMAC-SHA1&Timestamp=2016-02-23T12%3A46%3A24Z