To ensure the security of your API, you must sign the API request. Alibaba Cloud uses the signature in the request to verify the identity of the person who calls the API. No matter you submit an HTTP request or an HTTPS request, the request must contain a signature.

Note Alibaba Cloud provides multiple SDKs and third-party SDKs to make the manual signature process more efficient. Click here to know more about Alibaba Cloud SDKs.

Signature overview

For RPC APIs, you must add the calculated signature to the 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 hash method used to calculate the signature. HMAC-SHA1 is supported.

  • SignatureVersion: The version of the signature. The current version is 1.0.

  • SignatureNonce: A random number of the signature used to prevent network attacks. You must use different random numbers for different requests. We recommend using a Universally Unique Identifier (UUID).

  • Signature: The signature generated by performing symmetric encryption on the request by using the AccessKey Secret.
    • Level-two content
      • Level-three content
    .

Calculate the signature

The signature algorithm follows the RFC 2014 HMAC-SHA1 specification. Calculate the HMAC value of the encoded and formatted string according to RFC 2104. Different APIs contain different parameters, which results in different HMAC signatures.

Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(
StringToSign)) )
Complete these steps to calculate the signature:
  1. Construct the string to sign
    1. Use the request parameters to create a canonicalized query string to sign.
      1. Sort the parameter names in the lexicographical order, including the common required parameters and the API specific parameters but not including the Signature parameter.

        When using the GET method to call an API, the parameters to sort are any parameters after the question mark (?) that are connected by the ampersands (&).

      2. Use UTF-8 to URL-encode the parameter names and values. The encoding rules are as follows:
        • Do not URL-encode the following characters: A-Z, a-z, 0-9, hyphen (-), underscore (_), period (.), and tilde (~).

        • Encode other characters to the %XY format, where XY is the hexadecimal representation of characters corresponding to the ASCII code. For example, the double quotation marks (“”) must be encoded as % 22.

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

        • Encode space as %20.

          This encoding method is different from the common application/x-www-form-urlencoded MIME encoding such as the implementation of java.net.URLEncoder. However, you can use the java.net.URLEncoder method to encode the parameters, and then replace the plus sign (+) with %20, replace the asterisk (*) with %2A, replace %7E with the tilde (~) in the encoded string. The final result is the same. This algorithm can be achieved by the percentEncode function as follows:

          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;
          }
        • Use the equals sign (=) to append the encoded parameter values to the corresponding encoded parameters.
        • Append the ampersand (&) after each parameter value according to the order in the step i.
    2. Follow these rules to construct the canonicalized query string to sign:
      StringToSign=
            HTTPMethod + “&” +
            percentEncode(“/”) + ”&” +
             percentEncode(CanonicalizedQueryString)

      Where:

      • HTTPMethod is the used HTTP method. For example: Get.

      • percentEncode(“/”) is the encoded value for a forward slash (/), that is, %2F.

      • percentEncode(CanonicalizedQueryString) is the string that is encoded in the way as described in 1.2.

  2. Calculate the signature
    1. Calculate the HMAC value of the string to sign according to RFC 2104.
      Note The key used for calculation is the AccessKey Secret appended with an ampersand (&). The hash algorithm used is SHA1.
    2. Encode the HMAC value as according to the base-64 encoding.
    3. Add the signature to the request parameters as the Signature parameter.
      Note When submitting the signature as the final request parameter, you must also encode it according to RFC 3986.

Examples

The following shows the signing process of the DescribeRegions API. The AccessKey Id is testid, and the AccessKey Secret is testsecret. The original request 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 calculated by using testsecret& is:

CT9X0VtwR86fNWSnsc6v8YGOjuE=

Add this value to the request URL as the Signature parameter to obtain the signed URL:

http://ecs.aliyuncs.com/?SignatureVersion=1.0&Action=DescribeRegions&Format=XML&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&Version=2014-05-26&AccessKeyId=testid&Signature=CT9X0VtwR86fNWSnsc6v8YGOjuE%3D&SignatureMethod=HMAC-SHA1&Timestamp=2016-02-23T12%3A46%3A24Z