You must sign all API requests to ensure security. Alibaba Cloud uses the request signature to verify the identity of the API caller. When you send an HTTP or HTTPS API request, the request must contain the signature information.

Overview

You must add the signature to the RPC 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 request:
  • 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 random numbers for different requests. We recommend that you use universally unique identifiers (UUIDs).
  • Signature: the signature string generated by symmetrically encrypting the request by using the AccessKey secret.
The signature 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 the signature string, you can follow the steps in this topic.
Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(StringToSign) ) )

1 Compose and encode a string-to-sign

  1. Create a canonicalized query string by using the request parameters.
    1. Arrange 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 are the part located after the question mark (?) are placed after the question mark (?) in the URI and are separated with ampersands (&).
    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. For more information about encoding rules, see the following table.
      Character Encoding rule
      A to Z, a to z, 0 to 9, hyphens (-), underscores (_), periods (.), and tildes (~) These characters do not need to be encoded.
      Other characters Other characters must be percent encoded in %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.
      Spaces Spaces must be encoded as %20. Do not encode spaces as plus signs (+).
      This encoding rule is different from the rule for encoding 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 and then replace the plus sign (+) in the encoded string with %20, the asterisk (*) with %2A, and %7E with the tilde (~). To do this, 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. Associate the encoded parameter names with their encoded values separately by using equal signs (=).
    4. Sort the parameter name and value pairs in the order specified in step i and associate the pairs with ampersands (&) to produce the canonicalized query string.
  2. Create a string-to-sign from the encoded canonicalized query string as follows:
    StringToSign=
          HTTPMethod + “&” +
          percentEncode(“/”) + ”&” +
          percentEncode(CanonicalizedQueryString)

    In the preceding rules,

    • HTTPMethod indicates the HTTP method used to send the request, such as GET.
    • percentEncode("/") is the value (namely %2F) obtained by encoding the slash (/) according to the URL encoding rule described in step 1.1.2.
    • percentEncode(CanonicalizedQueryString) is the string obtained by encoding the canonicalized query string in step 1.1 according to the URL encoding rules described in step 1.2.

2 Calculate the signature string

  1. Calculate the HMAC value of the string-to-sign, which is StringToSign, according to RFC 2104.
    Note The HMAC algorithm is HMAC-SHA1. The key of the HMAC algorithm is the combination of your AccessKey secret and an ampersand (&) (ASCII code 38) that follows the secret.
  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 you add the signature string to the request, you must encode the parameter in the same way as other parameters by following the RFC3986 specifications.

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 unsigned request URL is as follows:

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

The signature string calculated by using testsecret& is as follows:

OLeaidS1JvxuMvnyHOwuJ+uX5qY=

Add the Signature parameter to the request and set the value to the signature string. Then the URL of the signed request is as follows:

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