Signature mechanism
To ensure secure API calls, Alibaba Cloud uses a signature for identity verification on every API request. All API requests, whether submitted over HTTP or HTTPS, must include signature information.
Overview
For RPC APIs, add the signature to the query parameters of the API request in the following format:
https://Endpoint/?SignatureVersion=1.0&SignatureMethod=HMAC-SHA1&Signature=CT9X0VtwR86fNWSnsc6v8YGOjuE%3D&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf- SignatureMethod: The signature algorithm. The value must be HMAC-SHA1.
- SignatureVersion: The version of the signature algorithm. The value must be 1.0.
- SignatureNonce: A unique random number used to prevent replay attacks. You must use a different random number for each request. We recommend that you use a universally unique identifier (UUID).
- Signature: The signature string that is generated using your AccessKey secret to sign the request.
Calculate a signature
The signature algorithm follows the RFC 2104 HMAC-SHA1 specification. It uses your AccessKey secret to calculate the HMAC value of the string to be signed. This value is the signature. The signature is based on the request parameters. Because the content of each API request is different, the resulting signature is also different.
Signature = Base64( HMAC-SHA1( AccessKeySecret, UTF-8-Encoding-Of(
StringToSign)) )- Create the string to sign
- Create a canonicalized query string from the request parameters:
- Sort all request parameters alphabetically by parameter name. The parameters include common request parameters and operation-specific parameters, but exclude the Signature parameter.
For a GET request, these parameters are the part of the request URL that follows the question mark (?) and are separated by ampersands (&).
- 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
%XYformat, whereXYrepresents 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
%20instead of a plus sign (+).This encoding method is different from the standard
application/x-www-form-urlencodedMultipurpose Internet Mail Extensions (MIME) format. For example, it differs from the implementation ofjava.net.URLEncoderin the Java standard library. You can first encode the string using a standard library. Then, replace the plus signs (+) with%20, asterisks (*) with%2A, and%7Ewith tildes (~) to obtain the required encoded string. You can implement this algorithm using the followingpercentEncodemethod: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; }- Join the encoded parameter name and value with an equal sign (=).
- Join the resulting parameter strings with ampersands (&) in the order established in step a. This creates the canonicalized query string.
- Sort all request parameters alphabetically by parameter name. The parameters include common request parameters and operation-specific parameters, but exclude the Signature parameter.
- Create the string to sign from the canonicalized query string as follows:
StringToSign= HTTPMethod + "&" + percentEncode("/") + "&" + percentEncode(CanonicalizedQueryString)The components are described as follows:
- HTTPMethod is the HTTP method used for the request, such as GET.
- percentEncode("/") is the percent-encoded forward slash (/) character, which is %2F.
- percentEncode(CanonicalizedQueryString) is the percent-encoded canonicalized query string from step 1.a.
- Create a canonicalized query string from the request parameters:
- Calculate the signature
- Calculate the HMAC value of the string to sign (StringToSign) as defined in RFC2104. Note The key used for the calculation is your AccessKey secret appended with an ampersand (&) character (ASCII code 38). The hash algorithm is SHA1.
- Encode the HMAC value into a string using Base64 encoding. The resulting string is the signature value (Signature).
- Add the signature value to the request parameters as the Signature parameter. Note When you submit the signature value as the final request parameter, it must be URL-encoded in the same way as other parameters according to RFC3986.
- Calculate the HMAC value of the string to sign (StringToSign) as defined in RFC2104.
Example
This example shows how to sign a request for the DescribeStores operation. Assume that the AccessKey ID is testid and the AccessKey secret is testsecret. The request URL before signing is as follows:
http://cloudesl.cn-hangzhou.aliyuncs.com/?Timestamp=2016-02-23T12:46:24Z&Format=XML&AccessKeyId=testid&Action=DescribeStores&SignatureMethod=HMAC-SHA1&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&Version=2020-02-01&SignatureVersion=1.0Using testsecret& as the key, the calculated signature is:
OLeaidS1JvxuMvnyHOwuJ+uX5qY=Finally, add the signature to the request URL as the Signature parameter. The final request URL is:
http://cloudesl.cn-hangzhou.aliyuncs.com/?SignatureVersion=1.0&Action=DescribeStores&Format=XML&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&Version=2020-02-01&AccessKeyId=testid&Signature=OLeaidS1JvxuMvnyHOwuJ+uX5qY=&SignatureMethod=HMAC-SHA1&Timestamp=2016-02-23T12%3A46%3A24Z