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 the request is sent over HTTP or HTTPS.

Overview

To call a remote procedure call (RPC) API operation, 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
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 different numbers for different requests. We recommend that you use universally unique identifiers (UUIDs).
  • Signature: the signature generated after the request is symmetrically encrypted by using the AccessKey secret.

Procedure

The HMAC-SHA1 algorithm specified in RFC 2104 is used for encryption. 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. Request signatures include operation-specific parameters. Therefore, the signature of a request varies depending on the 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 the request parameters to construct a canonicalized query string.
      1. Create a canonicalized query string by arranging the request parameters (including all common and operation-specific parameters except Signature) in alphabetical order.

        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 URI.

      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 some special characters such as 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 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 must be percent 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 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 MIME 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. Connect the encoded parameter names and values by using equal signs (=).
      4. Sort the parameter name and value pairs in the order 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.
      StringToSign=
            HTTPMethod + "&" +
            percentEncode("/") + "&" +
             percentEncode(CanonicalizedQueryString)

      where:

      • HTTPMethod: specifies the HTTP method used to make the request, such as GET.
      • percentEncode(“/”) : encodes forward slashes (/) as %2F based on the URL encoding rule described in Step 1.1.
      • percentEncode(CanonicalizedQueryString): encodes the canonicalized query string based on the URL encoding rule described in Step 1.2.
  2. Obtain the signature.
    1. Calculate the HMAC value of the string-to-sign as defined in 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) 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 If the obtained signature string is submitted as the final value of a request parameter, the value must be URL-encoded based on the rules defined in RFC 3986. Other parameters are also encoded based on the same rules.

Signature example

Take the DescribeRegions operation as an example. Assume that AccessKeyId is testid and AccessKey Secret is testsecret. The following URL needs to be signed:

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 following signature string calculated by using testsecret& is returned:

OLeaidS1JvxuMvnyHOwuJ+uX5qY=

Add the signature string to the request as the Signature parameter. The following signed URL is obtained:

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