To ensure that API calls are secure, Alibaba Cloud uses signatures to authenticate each API request. Each API request must contain a signature regardless of whether the request is sent over HTTP or HTTPS.

Signature overview

You must add a signature to an HBR 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 that is 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 that is generated after the request is symmetrically encrypted by using the AccessKey secret.
The signature encryption algorithm complies with RFC 2104 HMAC-SHA1 specifications. You can use the AccessKey secret to calculate the hash-based message authentication code (HMAC) value of the encoded and sorted query string. Then, you can use the HMAC value as the signature string. Request signatures include operation-specific parameters. Therefore, the signature of a request varies based on the request parameters. To calculate a signature, perform the following steps:
Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(StringToSign)) )

Step 1: Create a string-to-sign.

  1. Use the request parameters to create a canonicalized query string.
    1. Create a canonicalized query string by arranging the request parameters in alphabetical order. The request parameters include all common request parameters and operation-specific parameters except the Signature parameter.
      Note If you use the GET method to submit a request, the request parameters are included as a part of the URI.The request parameters in the URI are specified after the question mark (?) and separated by ampersands (&).
    2. Encode the canonicalized query string in UTF-8. The following table describes the encoding rules.
      Character Encoding rule
      Uppercase letters, lowercase letters, digits, and the following special characters: 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 specifies 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.
      Space characters Spaces must be encoded as %20. Do not encode spaces as plus signs (+).
      The 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 each plus sign (+) in the encoded string with %20, each asterisk (*) with %2A, and each %7E with a tilde (~). To apply the encoding algorithm, you can use the percentEncode method, as shown in the following code.
      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 by using equal signs (=).
    4. Sort the parameter name and value pairs in the order that is specified in Step 1.1. Then, concatenate the pairs with ampersands (&) to obtain the 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 that is used to submit a request, such as GET.
    • percentEncode("/"): encodes backslashes (/) as %2F based on the URL encoding rule that is described in Step 1.2.
    • percentEncode(CanonicalizedQueryString): encode the canonicalized query string that you created in Step 1 based on the URL encoding rule that is 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 must be the same as other parameters based on the rules that are defined in RFC 3986.

Example

In this example, the DescribeRegions operation is called. The value of the AccessKeyId parameter is testid, and the value of the AccessKeySecret parameter is testsecret. The following example shows the request URL to be signed:

http://hbr.eu-central-1.aliyuncs.com/?Timestamp=2021-09-01T12%3A46:24Z&Format=XML&AccessKeyId=testid&Action=DescribeTask&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&:

OLeaidS1JvxuMvnyHOwuJ+uX5qY=

After the signature string is added to the request as the Signature parameter, the following URL is returned:

http://hbr.eu-central-1.aliyuncs.com/?SignatureVersion=1.0&Action=DescribeTask&Format=XML&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&Version=2014-05-26&AccessKeyId=testid&Signature=OLeaidS1JvxuMvnyHOwuJ+uX5qY=&SignatureMethod=HMAC-SHA1&Timestamp=2021-09-01T12%3A46%3A24Z