You must sign all API requests to ensure security. Alibaba Cloud uses the request signature to verify the identity of the API caller. Each API request must contain the signature, regardless of whether it is sent over HTTP or HTTPS.

Overview

You must add the signature to the PolarDB-X 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 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 a different random number for each request. We recommend that you use universally unique identifiers (UUIDs).
  • Signature: the signature of the request. The signature is generated by using a symmetric encryption algorithm with the AccessKey secret as the key.

Signature calculation

The signature algorithm complies with the HMAC-SHA1 specifications in RFC 2104. The AccessKey secret is used to calculate the Hash-based Message Authentication Code (HMAC) value of an encoded and formatted query string. The HMAC value is then used as the signature. Some parameters in a request are used to calculate the signature. Therefore, the signature of a request varies depending on the API request parameters.

Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(
StringToSign)) )
To calculate a signature, perform the following steps:
  1. Compose and encode a string-to-sign.
    1. Use request parameters to construct a canonicalized query string.
      1. Create a canonicalized query string by arranging the request parameters in alphabetical order. Include all common and operation-specific parameters except Signature.

        If you use the GET method to submit the request, these parameters are the part of the request URI located after the question mark (?) and connected by ampersands (&).

      2. Encode the canonicalized query string in UTF-8. The following list describes the rules of percent encoding:
        • Letters, digits, hyphens (-), underscores (_), periods (.), and tildes (~) do not need to be encoded.

        • Other characters must be encoded in %XY format, where XY represents the ASCII code of the characters in hexadecimal notation. For example, double quotation marks (") are encoded as %22.

        • Extended UTF-8 characters are encoded in %XY%ZA... format.

        • Spaces must be encoded as %20. Do not encode spaces as plus signs (+).

          This encoding method is different from the application/x-www-form-urlencoded MIME encoding method, which is used by the java.net.URLEncoder class in the Java standard library. To convert such texts to percent encoded format, replace plus signs (+) in the encoded string with %20, asterisks (*) with %2A, and %7E with tildes (~). The following percentEncode method performs this conversion:

          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;
          }
        • Connect each encoded parameter name with its encoded value by using an equal sign (=).
        • Sort the parameter name and value pairs in the order specified in Step i. Then connect the pairs with ampersands (&) to produce the canonicalized query string.
    2. Use the canonicalized query string to construct the string for signature calculation in the following way:
      StringToSign=
            HTTPMethod + "&" +
            percentEncode("/") + "&" +
             percentEncode(CanonicalizedQueryString)

      where:

      • HTTPMethod is the HTTP method used to make the request, such as GET.
      • percentEncode("/") encodes the backslashes (/) in the URL as %2F.
      • percentEncode(CanonicalizedQueryString) encodes the canonicalized query string based on the URL encoding rules described in Step 1.2.
  2. Calculate the HMAC value of the string-to-sign.
    1. Calculate the RFC 2104-compliant HMAC value of the string-to-sign.
      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 The value of the signature parameter must also be percent encoded based on the rules defined in RFC 3986.

Examples

This example generates a signed request URL for the DescribeInstanceIds operation. In this example, the AccessKey ID is testid and the AccessKey secret is testsecret. The following example shows the request URL to be signed:

AccessKeyId=testid&Action=DescribeDrdsInstances&Format=XML&RegionId=cn-hangzhou&SignatureMethod=HMAC-SHA1&SignatureNonce=ae5bdbeb-9b44-40a1-8bb4-b40784bff686&SignatureVersion=1.0&Timestamp=2016-01-20T14%3A26%3A15Z&Version=2015-04-13

The following signature string is calculated by using testsecret&:

h/ka/jNO+WZv8Tqgo4a75sp6eTs=

After the Signature parameter and its value are added to the request, the following URL is generated:

http://drds.aliyuncs.com/?AccessKeyId=testid&Action=DescribeDrdsInstances&Format=XML&RegionId=cn-hangzhou&SignatureMethod=HMAC-SHA1&SignatureNonce=ae5bdbeb-9b44-40a1-8bb4-b40784bff686&SignatureVersion=1.0&Timestamp=2016-01-20T14%3A26%3A15Z&Version=2015-04-13&Signature=h%2Fka%2FjNO%2BWZv8Tqgo4a75sp6eTs%3D