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 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 encryption algorithm used to calculate the signature. Set the value to HMAC-SHA1.
- SignatureVersion: the version of the signature encryption algorithm. Set the value to 1.0.
- SignatureNonce: a unique, 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. Some 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)) )
- Compose and encode a string-to-sign.
- Use the request parameters to construct a canonicalized query string:
- Create a canonicalized query string by arranging the request parameters in alphabetical
order. Include all common and operation-specific parameters except Signature.
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.
- 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 are percent encoded in the %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.Space characters Spaces must be encoded as %20
. Do not encode spaces as plus signs (+).This encoding method is different from theapplication/x-www-form-urlencoded
MIME encoding algorithm, such as thejava.net.URLEncoder
class provided by the Java standard library. To convert such texts to the percent encoded format, replace plus signs (+) in the encoded string with%20
, asterisks (*) with%2A
, and%7E
with tildes (~). To implement this algorithm, you can use the followingpercentEncode
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; }
- Separately associate the encoded parameter names with their encoded values by using equal signs (=).
- Sort the parameter name and value pairs in the order specified in Step i. Then, connect the pairs with ampersands (&) to produce the canonicalized query string.
- Create a canonicalized query string by arranging the request parameters in alphabetical
order. Include all common and operation-specific parameters except Signature.
- Use the canonicalized query string to construct the string for signature calculation
based on the following rules:
StringToSign= HTTPMethod + "&" + percentEncode("/") + "&" + percentEncode(CanonicalizedQueryString)
In the preceding rules:
- HTTPMethod: the HTTP method used to submit a request, such as GET.
- percentEncode("/"): encodes backslashes (/) as %2F based on the URL encoding rule described in Step i.
- percentEncode(CanonicalizedQueryString) encodes the canonicalized query string based on the URL encoding rule described in Step ii.
- Use the request parameters to construct a canonicalized query string:
- Calculate signatures
- 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.
- 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 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.
- Calculate the RFC 2104-compliant HMAC value of the string-to-sign.
Examples
This example shows how to sign an API request for calling the DescribeRegions operation. If the value of the AccessKeyId
parameter is testid
, 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