Signature mechanism

Updated at:

Alibaba Cloud uses a signature to verify the identity of each API request and ensure security. All API requests must include signature information, regardless of whether you use the HTTP or HTTPS protocol.

Overview

For RPC APIs, add a signature to the query 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
Where:
  • SignatureMethod: The signature method. HMAC-SHA1 is supported.
  • SignatureVersion: The version of the signature algorithm. The current version is 1.0.
  • SignatureNonce: A unique random number to prevent replay attacks. A different random value must be used for each request. We recommend that you use a universally unique identifier (UUID).
  • Signature: The signature string generated from the request parameters and your AccessKey secret.
The signature algorithm follows the RFC 2104 HMAC-SHA1 specification. Use your AccessKey secret to calculate the HMAC value of the encoded and sorted request string. This value is the signature. Because the signature is based on the request parameters, it is unique for each API call. Follow the steps in this topic to calculate the signature value.
Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(StringToSign) ) )

Step 1: Construct the string to be signed

  1. Construct a canonicalized query string using the request parameters.
    1. Sort all request parameters alphabetically by name. This includes common and API-specific parameters, but excludes the Signature parameter.
      Note For GET requests, these are the parameters in the URI that follow 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. For information about the encoding rules, see the following table.
      Character Encoding method
      A-Z, a-z, 0-9, and the characters -, _, ., ~ Do not encode.
      Other characters Encode into the %XY format, where XY is the hexadecimal representation of the character's ASCII code. For example, a double quotation mark (") is encoded as %22.
      Extended UTF-8 characters Encode into the %XY%ZA... format.
      A space Encode as %20 instead of a plus sign (+).
      This encoding method differs from the standard application/x-www-form-urlencoded Multipurpose Internet Mail Extensions (MIME) format encoding algorithm, such as the implementation in the java.net.URLEncoder class of the Java standard library. To get the required encoded string, first encode the string using a standard library method. Then, replace plus signs (+) with %20, asterisks (*) with %2A, and %7E with tildes (~). 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;
      }
    3. Join each encoded parameter name and its value with an equal sign (=).
    4. Join the resulting parameter-value pairs with ampersands (&) in the sorted order from step a. This creates the canonicalized query string.
  2. Construct the string to be signed from the canonicalized query string created in step 1 using the following format.
    StringToSign=
          HTTPMethod + "&" +
          percentEncode("/") + "&" +
           percentEncode(CanonicalizedQueryString)

    Where:

    • HTTPMethod is the HTTP method used to submit the request, such as GET.
    • percentEncode("/") is the value that is obtained by encoding the forward slash (/) character according to the URL encoding rules in step 1.b. The encoded value is %2F.
    • percentEncode(CanonicalizedQueryString) is the string that is obtained by encoding the canonicalized query string from step 1 according to the URL encoding rules in step 1.b.

Step 2: Calculate the signature value

  1. Calculate the HMAC value of the string to be signed (StringToSign) as specified in RFC 2104.
    Note The key for the calculation is your AccessKey secret with an ampersand (&) character (ASCII code 38) appended. The hash algorithm is SHA1.
  2. Encode the HMAC value in Base64 to obtain the signature string (Signature).
  3. Add the resulting signature value to the request parameters as the Signature parameter.
    Note Before you add the signature value to the request, URL-encode it as you would any other parameter, according to RFC 3986.

Example

This section uses the CreateIntent API as an example. Assume that the AccessKey ID is testid and the AccessKey secret is testsecret. The request URL before signing is as follows:

http://outboundbot.cn-shanghai.aliyuncs.com/?Timestamp=2016-02-23T12%3A46:24Z&Format=XML&AccessKeyId=testid&Action=CreateIntent&SignatureMethod=HMAC-SHA1&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&Version=2019-12-26&SignatureVersion=1.0

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

OLeaidS1JvxuMvnyHOwuJ+uX5qY=

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

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