You must sign all API requests to ensure security. Alibaba Cloud uses the request signature to verify the identity of the API caller. When you call an API operation by using HTTP or HTTPS, the request must include the signature information.
Description
Alibaba Cloud authenticates each access request. Therefore, each request must contain
signature information, regardless of whether it is sent through HTTP or HTTPS. Alibaba
Cloud Marketplace implements symmetric encryption with an AccessKey pair to verify
the identity of the request sender. An AccessKey pair is an identity credential issued to Alibaba Cloud accounts and
Resource Access Management (RAM) users. It is similar to a logon username and password.
An AccessKey pair consists of an
AccessKey ID
and an AccessKey secret
. The AccessKey ID
is used to verify the identity of the user, while the AccessKey secret
is used to encrypt and verify the signature string. You must keep your AccessKey
secret strictly confidential.
Signature calculation
The signature algorithm complies with RFC 2104 HMAC-SHA1 specifications. It uses the AccessKey secret to calculate the Hash-based Message Authentication Code (HMAC) of the encoded and formatted request string as the signature. The elements used for calculating a signature are some parameters of the request. Therefore, the signature results vary according to API requests.
Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(
StringToSign)) )
- Compose and encode a string-to-sign.
- Use request parameters to create a canonicalized query string.
- Arrange the request parameters (including all common and operation-specific parameters
except Signature) in alphabetical order.
When you use the GET method to submit a request, the request parameters are included as a part of the URL. The request parameters in the URL are placed after a question mark (?) and separated with ampersands (&).
- Encode the canonicalized query string in UTF-8. The following table describes the
encoding rules.
Character Encoding rule Uppercase letters (A-Z), lowercase letters (a-z), digits (0-9), and some special characters including hyphens (-), underscores (_), periods (.), and tildes (~) Not encoded. Other characters 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 Encoded in %XY%ZA...
format.Space Encoded as %20
. Do not encode spaces as plus signs (+).This encoding method is similar to but different from theapplication/x-www-form-urlencoded
MIME encoding algorithm (such as thejava.net.URLEncoder
class provided by the Java standard library). You can use this encoding method directly by replacing the plus sign (+) in the encoded string with%20
, the asterisk (*) with%2A
, and%7E
with the tilde (~) to conform to the preceding encoding rules. You can use the followingpercentEncode
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 names and their values with equal signs (=).
- Arrange the parameter name and value pairs connected by equal signs in the order specified in step 1.1.1, and connect them with ampersands (&) to produce the canonicalized query string.
- Arrange the request parameters (including all common and operation-specific parameters
except Signature) in alphabetical order.
- Create a string-to-sign from the encoded canonicalized query string.
StringToSign= HTTPMethod + "&" + percentEncode("/") + "&" + percentEncode(CanonicalizedQueryString)
where:
- HTTPMethod: 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.2, which is %2F.
- percentEncode(CanonicalizedQueryString): the string encoded from the canonicalized query string created in step 1 based on the URL encoding rules described in step 1.2.
- Use request parameters to create a canonicalized query string.
- Calculate the signature.
- Calculate the HMAC value of the string-to-sign based on RFC 2104.
Note The key used for calculating the signature is your AccessKey secret followed by an ampersand (&). Use Secure Hash Algorithm 1 (SHA1) for the calculation.
- Encode the HMAC value in Base64 to obtain the signature string.
- Add the signature string to the request as the Signature parameter.
Note When the obtained signature string is submitted as the final request parameter value, the value must be URL-encoded like other parameters based on rules defined in RFC 3986.
- Calculate the HMAC value of the string-to-sign based on RFC 2104.
Example
Take DescribeRegions as an example. Assume that the AccessKey ID
is testid
and the AccessKey secret
is testsecret
. The original request URL is as follows:
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 string-to-sign
is as follows:
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
The AccessKey secret
is testsecret
, so the key used for calculating the HMAC value is testsecret&
. The calculated signature string is as follows:
CT9X0VtwR86fNWSnsc6v8YGOjuE=
Use the signature string as the value of the Signature parameter and add the parameter to the request URL. The final URL is as follows:
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