To ensure the security of your API security, you must sign the API request. Alibaba Cloud uses the signature in the request to verify the identity of the person who calls the API.
Alibaba Cloud provides multiple SDKs and third-party SDKs to make the manual signature process more efficient. Click here to know more about Alibaba Cloud SDKs.
Signature overview
For REST APIs, you must add an Authorization
header to the API request header according to the following format:
Authorization:acs:AccessKeyId:Signature
where:
acs
: The abbreviation for Alibaba Cloud Service, a fixed value that cannot be changed.AccessKeyId
: The AccessKey ID used to call the API.Signature
: The signature generated by performing symmetric encryption on the request by using the AccessKey Secret.
Calculate signatures
According to RFC 2104, calculate the HMAC value of the encoded and formatted string. The calculated HMAC value is the signature.
Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(
StringToSign) ) )
The signature algorithm follows the RFC 2014 HMAC-SHA1 specification. Different APIs contain different request parameters, which result in different HMAC signatures.
1. Construct the string to sign
The string to sign is composed of the following components:
Construct the string to sign in the required order as follows:
StringToSign =
//HTTP header
HTTP-Verb + "\n" +
Accept + "\n" +
Content-MD5 + "\n" +//The MD5 value of the body is put here
Content-Type + "\n" +
Date + "\n" +
//Alibaba Cloud header
CanonicalizedHeaders +
//Canonicalized resource
CanonicalizedResource
Example: original request
POST /stacks?name=test_alert&status=COMPLETE HTTP/1.1
Host: ***.aliyuncs.com
Accept: application/json
Content-MD5: ChDfdfwC+Tn874znq7Dw7Q==
Content-Type: application/x-www-form-urlencoded;charset=utf-8
Date: Thu, 22 Feb 2018 07:46:12 GMT
x-acs-signature-nonce: 550e8400-e29b-41d4-a716-446655440000
x-acs-signature-method: HMAC-SHA1
x-acs-signature-version: 1.0
x-acs-version: 2016-01-02
Example: constructed string to sign
POST
application/json
ChDfdfwC+Tn874znq7Dw7Q==
application/x-www-form-urlencoded;charset=utf-8
Thu, 22 Feb 2018 07:46:12 GMT
x-acs-signature-nonce: 550e8400-e29b-41d4-a716-446655440000
x-acs-signature-method:HMAC-SHA1
x-acs-signature-version:1.0
x-acs-version:2016-01-02
/stacks?name=test_alert&status=COMPLETE
HTTP header
The values of the Accept
, Content-MD5
, Content-Type
, and Date
parameters must be included when calculating the signature, but the AccessKey is not included. Sort the parameter values in the lexicographical order. Use \n
to fill up the empty values.
Parameter | Description |
---|---|
Accept | The type of the response to return. Valid values: application/json | application/xml |
Content-MD5 | The base-64 encoded 128-bit MD5 digest. |
Content-Type | The content type of the request defined in RFC 2616. |
Date | The time at which the request is created in the GMT format. Example: Wed, 05 Sep. 2012 23:00:00 GMT |
Example: original header
Accept: application/json
Content-MD5: ChDfdfwC+Tn874znq7Dw7Q==
Content-Type: application/x-www-form-urlencoded;charset=utf-8
Date: Thu, 22 Feb 2018 07:46:12 GMT
Example: canonical header
application/json
ChDfdfwC+Tn874znq7Dw7Q==
application/x-www-form-urlencoded;charset=utf-8
Thu, 22 Feb 2018 07:46:12 GMT
Alibaba Cloud header
The Alibaba Cloud header, not a standard header, are the parameters with the x-acs-
prefix in the request. It includes the following:
Parameter | Description |
---|---|
x-acs-signature-nonce | A random number of the signature to prevent from network attacks. You must use different random numbers for different requests. |
x-acs-signature-method | The hash method used to calculate the signature. Valid value: HMAC-SHA1 |
x-acs-signature-version | The version of the signature. Valid value: 1.0 |
x-acs-version | The version of the API to use. Go to the API documentation of the specific product to get the API version. |
Follow these steps to construct the Alibaba Cloud header:
Change all the parameters starting with
x-acs-
to lowercase. For example, changeX-acs-OSS-Meta-Name: TaoBao
tox-acs-oss-meta-name: TaoBao
.Sort the Alibaba Cloud header in the ascending lexicographical order.
Delete any space in the delimiter between the header and the content. For example, change
x-acs-oss-meta-name: TaoBao,Alipay
tox-acs-oss-meta-name:TaoBao,Alipay
.Use
\n
to separate the headers and the contents.
Example: original Alibaba Cloud header
x-acs-signature-nonce: 550e8400-e29b-41d4-a716-446655440000
x-acs-signature-method: HMAC-SHA1
x-acs-signature-version: 1.0
x-acs-version: 2016-01-02
Example: canonical Alibaba Cloud header
x-acs-signature-nonce:550e8400-e29b-41d4-a716-446655440000
x-acs-signature-method:HMAC-SHA1
x-acs-signature-version:1.0
x-acs-version:2016-01-02
Canonical resource
CanonicalizedResource
is the canonical description for the resource to access. Sort the sub resources together with the query parameters (all the parameters after the question mark) in the descending lexicographical order and use the ampersand (&) to separate parameters.
Example: original request
/stacks?status=COMPLETE&name=test_alert
Example: canonical request
/stacks?name=test_alert&status=COMPLETE
Body
Use MD5 to encrypt the body, and then use base-64 to encode it. Add the final content to Content-MD5
.
2. Add the signature to the request
Add the calculated signature to the request header as follows:
Authorization: acs AccessKeyId:Signature