You must sign all API requests to ensure security. Alibaba Cloud uses the request signature to verify the identity of the API caller. Therefore, each API request must contain signature information, regardless of whether it is sent by using HTTP or HTTPS.
Overview
You must add the signature to the Message Queue for MQTT API request in the following format:
https://Endpoint/?SignatureVersion=1.0&SignatureMethod=HMAC-SHA1&Signature=CT9X0VtwR86fNWSnsc6v8YGOju****&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82f****
- Endpoint: the endpoint of the ApsaraMQ for MQTT API is onsmqtt.[regionId].aliyuncs.com. For more information about [regionId], see Endpoints.
- 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, random number used to prevent replay attacks. You must use different random numbers for different requests. We recommend that you use universally unique identifiers (UUIDs).
- Signature: the signature generated after the request is symmetrically encrypted by using the AccessKey secret.
Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(
StringToSign)) )
Step 1: Compose and encode a string-to-sign
- Create a canonicalized query string by using request parameters.
- Arrange the request parameters (including all common and operation-specific parameters except Signature) in alphabetical order. Note When you use the GET method to submit requests, these parameters constitute the parameter field of the request URI. They are placed after the question mark (?) in the request URI and connected by ampersands (&).
- URL encode the name and value of each request parameter in UTF-8. For more information about encoding rules, see the following table.
Character Encoding rule Uppercase letters, lowercase letters, digits, and some special characters such as hyphens (-), underscores (_), periods (.), and tildes (~) These characters do not need to be encoded. Other characters Other 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 Extended UTF-8 characters are encoded in %XY%ZA...
format.Spaces 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. You can encode spaces based on the encoding rule for the standard library, and then replace the plus sign (+) in the encoded string with%20
, the asterisk (*) with%2A
, and%7E
with the tilde (~). To do this, 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; }
- Connect the encoded parameter names and values by using equal signs (=).
- Sort the parameter name and value pairs in the order specified in Step 1.1.1 and connect the pairs by using 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 method used to encode backslashes (/) as %2F based on the URL encoding rules described in Step 1.1.2.
- percentEncode(CanonicalizedQueryString): the method used to encode the query string created in Step 1.1 based on the URL encoding rules described in Step 1.1.2.
Step 2: Calculate the signature string
- Calculate the HMAC value of the string-to-sign as defined in RFC 2104. Note The key used to calculate the signature string is your AccessKey secret followed by an ampersand (&) (ASCII:38). The SHA1 algorithm is used 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 you add the signature string to the request as the Signature parameter, the parameter must be URL encoded like other parameters based on rules defined in RFC 3986.
Examples
This example shows how to sign an API request to call the DescribeRegions operation. Assume that the value of the AccessKeyId
parameter is testid
and the value of the AccessKey Secret
parameter is testsecret
. The following URL is the request URL to be signed:
http://ecs.aliyuncs.com/?Timestamp=2016-02-23T12%3A46:24Z&Format=XML&AccessKeyId=testid&Action=DescribeRegions&SignatureMethod=HMAC-SHA1&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82f****&Version=2014-05-26&SignatureVersion=1.0
The following value is the signature string calculated by using testsecret&
:
OLeaidS1JvxuMvnyHOwuJ+u****
Add the signature string to the request as the Signature parameter. The following URL is the URL of the signed request:
http://ecs.aliyuncs.com/?SignatureVersion=1.0&Action=DescribeRegions&Format=XML&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82f****&Version=2014-05-26&AccessKeyId=testid&Signature=OLeaidS1JvxuMvnyHOwuJ+u****=&SignatureMethod=HMAC-SHA1&Timestamp=2016-02-23T12%3A46%3A24Z