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

Signature overview

You must add the signature to the Server Load Balancer API request in the following format:

https://Endpoint/?SignatureVersion=1.0&SignatureMethod=HMAC-SHA1&Signature=CT9X0VtwR86fNWSnsc6v8YGOjuE%3D&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf
A signature contains the following parameters:
  • SignatureMethod: the encryption method of the signature string. 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 random numbers for different 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.
The signature encryption algorithm complies with RFC 2104 HMAC-SHA1 specifications. The AccessKey secret is used to calculate the hash-based message authentication code (HMAC) value of the encoded and sorted query string, and the HMAC value is used as the signature string. The elements of the signature string are some parameters in the request. Therefore, the signature results vary with API requests. To calculate a signature, perform the following steps.
Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(
StringToSign)) )

Step 1: Compose and encode a string-to-sign

  1. Create a canonicalized query string by using the request parameters.
    1. Create a canonicalized query string by arranging the request parameters (including all common and operation-specific parameters except Signature) in alphabetical order.
      Note If you use the GET method to submit the request, these parameters follow question mark (?)and are connected by the ampersands (&) in the request URI.
    2. Encode the names and values of the arranged request parameters in the request URL by using the unicode transformation format (UTF)-8 character set. The following table describes the encoding rules.
      Character Encoding rule
      Uppercase letters, lowercase letters, digits, and some special characters such as ampersands (&), hyphens (-), underscores (_), periods (.),and tildes (~) These characters do not need to be encoded
      Other characters These characters must be 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 must be percent encoded in the %XY%ZA…format.
      Spaces Spaces must be encoded as %20. Do not encode spaces as plus signs (+).
      This encoding rule is different from the rule that is used to encode data in the common Multi-purpose Internet Mail Extensions (MIME) format application/x-www-form-urlencoded. For example, java.net.URLEncoder in the standard Java library is in this MIME format. However, you can apply the encoding algorithm. Then, replace the plus sign (+) in the encoded string with %20, the asterisk (*) with %2A, and %7E with the tilde (~). 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. Connect the encoded parameter names and values with equal signs (=).
    4. Sort the parameter name and value pairs in the order specified in Step i. Then, connect the pairs with ampersands (&) to obtain a canonicalized query string.
  2. Create a string-to-sign from the encoded canonicalized query string based on the following rules:
    StringToSign=
          HTTPMethod + "&" +
          percentEncode("/") + "&" +
           percentEncode(CanonicalizedQueryString)

    A string-to-sign contains the following parameters:

    • 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 1.1.
    • percentEncode(CanonicalizedQueryString) is the string obtained by encoding the canonicalized query string in Step 1 according to the URL encoding rules described in Step 1.2.

Step 2: Calculate the signature string

  1. Calculate the HMAC value of the string-to-sign based on RFC 2104.
    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 value of a request parameter, the value must be URL-encoded. The URL-encoded value is similar to other parameters based on the rules defined in RFC 3986.

Signature example

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

http://ecs.aliyuncs.com/?Timestamp=2016-02-23T12%3A46: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 signature string is calculated by using testsecret&:

OLeaidS1JvxuMvnyH****+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=OLeaidS1JvxuMvnyH****+uX5qY=&SignatureMethod=HMAC-SHA1&Timestamp=2016-02-23T12%3A46%3A24Z