Signature mechanism

Last Updated: Mar 28, 2017

Each time the ECS service is accessed by a request, it performs authentication. Therefore, either HTTP or HTTPS protocol is used to submit a request, the request must contain signature information. By using the Access Key ID and Access Key Secret, the ECS performs symmetric encryption to authenticate the request sender. The Access Key ID and Access Key Secret are officially issued to visitors by Alibaba Cloud (visitors can apply for and manage them on Alibaba Cloud official website). The Access Key ID indicates the identity of the visitor. The Access Key Secret is the secret key used to encrypt the signature string and to verify the signature string on the server. It must be kept strictly confidential and should only be known to Alibaba Cloud and the authenticated visitors.

Service address

Follow the steps below to implement signatures on the requests during your access:

  1. The Canonicalized Request String is constructed using the request parameters.

    1. Parameter ordering. Order the request parameters (including the “public request parameters” and custom parameters for the interfaces, but not the Signature parameter mentioned in “Public Request Parameters”) alphabetically by parameter names.

      Note: When a request is submitted using the GET method, these parameters are the parameter section of the request URI (that is, the section in the URI following “?” and connected by “&”).

    2. Parameter encoding. Perform URL-encoding for the names and values of ordered request parameters with UTF-8 character sets. The encoding rules are as follows:

      • The characters A-Z, a-z, 0-9, “-“, “_”, “.”, and “~” are not encoded;

      • Other characters are encoded in “%XY” format, with XY representing the characters’ ASCII code in hexadecimal notation. For example, the English double quotes (“) are encoded as %22.

      • Extended UTF-8 characters are encoded in “%XY%ZA…” format;

      • Note that the space ( ) is encoded as “%20”, rather than the plus sign “+”.

      Note: This encoding method is similar to the generally-adopted “application/x-www-form-urlencoded” MIME encoding algorithm (such as the implementation of java.net.URLEncoder in Java standard library), but with slight differences. To implement it, you can encode the names and values following the method for the standard library, and then replace the plus signs (+) in the encoded strings with %20, the asterisks (*) with %2A, and change %7E back to the tilde (~) to conform to the encoding rules described above. The algorithm can be implemented through the following percentEncode method:

      1. private static final String ENCODING = "UTF-8";
      2. private static String percentEncode(String value) throws UnsupportedEncodingException {
      3. return value != null ? URLEncoder.encode(value, ENCODING).replace("+", "%20").replace("*", "%2A").replace("%7E", "~") : null;
      4. }
    3. Connect the encoded parameter names and values with the English equals sign (=).

    4. Order the parameter name and value pairs connected by equals signs in the order in Step (a) and connect them with the “&” symbol to produce the Canonicalized Request String.

  2. Follow the rules below to construct the string for signature by using the Canonicalized Request String constructed in Step 1:

    1. StringToSign=
    2. HTTPMethod + "&" +
    3. percentEncode("/") + "&" +
    4. percentEncode(CanonicalizedRequestString)

    Here, HTTPMethod is the HTTP method used for request submission, for example, GET. PercentEncode (“/“) is the encoded value for the character “/“ according to the URL encoding rules described in 1.ii, that is, “%2F”. PercentEncode(CanonicalizedRequestString) is the encoded string of the Canonicalized Request String constructed in Step 1, produced by following the URL encoding rules described in 1.ii.

  3. According to RFC2104 definition, calculate the HMAC value of the character string StringToSign for signature.

    NOTE: When the signature is calculated, the Key is the Access Key Secret held by the user adding the “&” character (ASCII:38), and the SHA1 hashing algorithm is used.

  4. Encode the above HMAC value into a string based on Base64 encoding rules, and you can obtain the signature value.

  5. Add the obtained signature value to the request parameters as the Signature parameter. Thus the request signing process is completed.

    Note: When the obtained signature value is submitted to the ECS server as the final request parameter value, the value will be URL encoded like other parameters according to RFC3986 rules.

    Take DescribeRegions as an example. If the Access Key Id is “testid”, and the Access Key Secret is “testsecret”, the request URL before signature is:

    1. 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 character string StringToSign for signature after calculation is:

    1. GET&%2F&AccessKeyId%3Dtestid&Action%3DDescribeRegions&Format%3DXML&SignatureMethod%3DHMAC-SHA1&SignatureNonce%3D3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&SignatureVersion%3D1.0&TimeStamp%3D2016-02-23T12%253A46%253A24Z&Version%3D2014-05-26

    If we assume the Access Key Secret is “testsecret”, and the Key used for HMAC calculation is “testsecret&”, and the calculated signature value is:

    1. CT9X0VtwR86fNWSnsc6v8YGOjuE=

    Add the signature as the Signature parameter to the URL request and the final URL will be:

    1. http://ecs.aliyuncs.com/?SignatureVersion=1.0&Action=DescribeRegions&Format=XML&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&Version=2014-05-26&AccessKeyId=testid&Signature=CT9X0VtwR86fNWSnsc6v8YGOjuE%3D&SignatureMethod=HMAC-SHA1&TimeStamp=2016-02-23T12%3A46%3A24Z
Thank you! We've received your feedback.