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 Container Registry 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 and 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 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. Specific parameters in a request are used to calculate the signature. Therefore, the signature of a request varies based 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 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 of the request uniform resource identifier (URI) located after the question mark (?) and connected by the ampersands (&) in the request URI.

      2. Encode the canonicalized query string in the UTF-8 format. The following table describes the encoding rules.
        Character Encoding rule
        Uppercase letters (A-Z), lowercase letters (a-z), digits (0-9), 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 %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 are 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 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 implement this algorithm, 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 their values with equal signs (=) separately.
      4. Sort the parameter name and value pairs in the order specified in Step i. Then, connect 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)

      where:

      • HTTPMethod is the HTTP method used to make the request, such as GET.
      • percentEncode("/"): the encoded value for the forward slash (/) based on the URL encoding rules described in Step 1.i.a, which is %2F.
      • percentEncode(CanonicalizedQueryString): encodes the canonicalized query string based on the URL encoding rule described in Step 1.i.b.
  2. Obtain the signature.
    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 When the obtained signature value is submitted as the final request parameter value, the value must be URL-encoded that is similar to other parameters based on rules defined in RFC 3986.

Signature example

This example shows how to sign an API request for calling the DescribeRegions operation. Assume that the value of the AccessKeyId parameter is testid and the AccessKeySecret parameter is testsecret. The following example shows the request URL 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 calculated signature string is returned by using testsecret&:

OLeaidS1JvxuMvnyHOwuJ+uX5qY=

The following URL is returned after the signature string is added to the request as the Signature parameter:

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