Sign REST APIs - Signature| Alibaba Cloud Documentation Center

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:

HTTP header
Alibaba Cloud header
Canonical resource
Body

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, change X-acs-OSS-Meta-Name: TaoBao to x-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 to x-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