You must sign all API requests to ensure security. Alibaba Cloud uses the request signature to verify the identity of the API caller. Alibaba Cloud uses the request signature to verify the identity of the API caller.

Overview

You must add the signature to the Bastionhost API request in the following format:
https://Endpoint/?SignatureVersion=1.0&SignatureMethod=HMAC-SHA1&Signature=CT9X0VtwR86fNWSnsc6v8YGOjuE%3D&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf

The following section describes the two concepts involved in the figure:

  • SignatureMethod: the encryption algorithm used to calculate the signature. Set the value to HMAC-SHA1.
  • SignatureVersion: the version of the signature encryption algorithm. Valid value: 1.0.
  • SignatureNonce: a unique, random number used to prevent replay attacks. You must use different 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 algorithm complies with the HMAC-SHA1 specifications in RFC 2104. It uses an AccessKey secret to calculate the Hash-based Message Authentication Code (HMAC) of an encoded and formatted query string and use the HMAC value as the signature. Request signatures include operation-specific parameters. Therefore, the signature of a request varies depending on the request parameters. To calculate a signature, follow the steps in this topic.
Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(StringToSign)) )

Step 1: build a string to be signed

  1. Use request parameters to construct a canonicalized query string.
    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 (?) and connected by the ampersands (&) in the request uniform resource identifier (URI).
    2. Encode the canonicalized query string in UTF-8. Encoding rules refer to 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, the double quotation mark (") is encoded as % 22.
      Extended UTF-8 characters These characters are encoded in %XY%ZA... format.
      Spaces 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 algorithm (such as the java.net.URLEncoder class provided by the Java standard library). 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. Use the canonicalized query string to construct the string for signature calculation based on the following rules:
    StringToSign=
          HTTPMethod + “&” +
          percentEncode(“/”) + ”&” +
          percentEncode(CanonicalizedQueryString)
    In the preceding string,
    • HTTPMethod indicates the HTTP method used to submit the request, such as GET.
    • percentEncode("/") the value is the value obtained by encoding the character "/" according to the URL encoding rules described in step 1.1, that is % 2F.
    • percentEncode(CanonicalizedQueryString) the encoded string of the canonicalized query string constructed in step 1. Comply with the URL encoding rules described in step 1.2.

Step 2: Calculate the signature

  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. The combination of your AccessKey secret and an ampersand (&) (ASCII code 38) that follows the secret is used as the key for the 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 request parameter value, the value must be URL-encoded like other parameters based on rules defined in RFC 3986.

Examples

To CreateLedger API as an example. The AccessKey ID is testid, AccessKey Secret for testsecret. The request URL to be signed is as follows:
http://ledgerdb.aliyuncs.com/?Action=CreateLedger&Timestamp=2018-12-23T12:46:24Z&Format=XML&AccessKeyId=testid&SignatureMethod=HMAC-SHA1&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&Version=2019-11-22&SignatureVersion=1.0
The signature string calculated by using testsecret& is as follows:
OLeaidS1JvxuMvnyHOwuJ+uX5qY=
Add the Signature string to the request as the Signature parameter. The URL of the signed request is as follows:
http://ledgerdb.aliyuncs.com/?Action=CreateLedger&Timestamp=2018-12-23T12:46:24Z&Format=XML&AccessKeyId=testid&SignatureMethod=HMAC-SHA1&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&Version=2019-11-22&SignatureVersion=1.0&Signature=VyBL52idtt+oImX0NZC+2ngk15Q=