Signature mechanism-City Visual Intelligence Engine(CityVisual)-阿里云帮助中心

To ensure the security of API calls, Alibaba Cloud authenticates each API request using a signature. You must include a signature in each request that you send over HTTP or HTTPS.

Overview

For RPC APIs, you must add a signature to the query string of the request in the following format:

https://Endpoint/?SignatureVersion=1.0&SignatureMethod=HMAC-SHA1&Signature=CT9X0VtwR86fNWSnsc6v8YGOjuE%3D&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf

The parameters are described as follows:

SignatureMethod: The method used to generate the signature. Only HMAC-SHA1 is supported.
SignatureVersion: The version of the signature algorithm. The current version is 1.0.
SignatureNonce: A unique random number used to prevent replay attacks. You must use a different random number for each request. We recommend using a universally unique identifier (UUID).
Signature: The signature that is generated using the AccessKey secret to symmetrically encrypt the request.

Calculate a signature

The signature algorithm follows the RFC 2104 HMAC-SHA1 specification. The algorithm uses your AccessKey secret to calculate the HMAC value of the encoded and sorted request string. This value is the signature. Because the content of each API request is different, the resulting signature is also different.

Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(StringToSign)) )

To calculate a signature, follow these steps:

Create the string-to-sign
1. Construct a canonicalized query string from the request parameters.
  1. Sort all request parameters alphabetically by parameter name. This includes common request parameters and custom API parameters, but excludes the Signature parameter.
    If you submit a request using the GET method, these parameters are the part of the request URI that appears after the question mark (?) and are connected by ampersands (&).
  2. URL-encode the names and values of the sorted request parameters using the UTF-8 character set. The encoding rules are as follows:
    - Do not encode uppercase letters (A-Z), lowercase letters (a-z), digits (0-9), hyphens (-), underscores (_), periods (.), or tildes (~).
    - Encode other characters into the %XY format. XY represents the two-digit hexadecimal value of the character's ASCII code. For example, a double quotation mark (") is encoded as %22.
    - Encode extended UTF-8 characters into the %XY%ZA… format.
    - Encode a space as %20, not a plus sign (+).
      
      This encoding method differs from the standard application/x-www-form-urlencoded Multipurpose Internet Mail Extensions (MIME) format. For example, it is different from the implementation of java.net.URLEncoder in the Java standard library. To obtain the correct encoding, you can first encode the string using a standard library method. Then, you must replace plus signs (+) with %20, asterisks (*) with %2A, and %7E with tildes (~). You can use the following percentEncode method to implement this algorithm:
      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 the encoded parameter name and its value with an equal sign (=).
    - Connect the parameter pairs with ampersands (&) in the order from step i to create the canonicalized query string.
2. Use the canonicalized query string from the previous step to create the string-to-sign according to the following rules.
```
StringToSign=
      HTTPMethod + “&” +
      percentEncode(“/”) + ”&” +
      percentEncode(CanonicalizedQueryString)
```
  Where:
  - HTTPMethod is the HTTP method used to submit the request, such as GET.
  - percentEncode("/") is the value that is obtained by URL-encoding the forward slash (/) character according to the previously described URL encoding rules. The value is %2F.
  - percentEncode(CanonicalizedQueryString) is the string that is obtained by URL-encoding the canonicalized query string from step 1.a based on the previously described URL encoding rules.
Calculate the signature
1. Calculate the HMAC value of the string-to-sign (StringToSign) as defined in RFC2104.
  Note The key for the calculation is your AccessKey secret followed by an ampersand (&) character (ASCII code 38). The hash algorithm is SHA1.
2. Encode the HMAC value to a string using Base64 encoding. This string is the signature value (Signature).
3. Add the resulting signature value to the request parameters as the Signature parameter.
  Note When you add the signature value as a request parameter, you must URL-encode it with the other parameters according to RFC3986.

Example

This example uses the DescribeRegions API. Assume that the AccessKey ID is testid and the AccessKey Secret is testsecret. The request URL before signing is:

http://cityvisual.aliyuncs.com/?Timestamp=2019-08-01T12:46:24Z&Format=XML&AccessKeyId=testid&Action=DescribeRegions&SignatureMethod=HMAC-SHA1&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&Version=2018-10-30&SignatureVersion=1.0

Using testsecret& as the key, the calculated signature value is:

OLeaidS1JvxuMvnyHOwuJ+uX5qY=

Finally, add the signature to the request URL as the Signature parameter. The final URL is:

http://cityvisual.aliyuncs.com/?SignatureVersion=1.0&Action=DescribeRegions&Format=XML&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&Version=2018-10-30&AccessKeyId=testid&Signature=OLeaidS1JvxuMvnyHOwuJ+uX5qY=&SignatureMethod=HMAC-SHA1&Timestamp=2019-08-01T12%3A46%3A24Z