You must sign all API requests to ensure security. Alibaba Cloud uses the request signature to verify the identity of the API caller.

Overview

To sign a RESTful API request, you must add the Authorization field to the request header in the following format: 

Authorization:acs:AccessKeyId:Singature
where:
  • acs: the abbreviation for Alibaba Cloud Service. This is a fixed field and cannot be modified.
  • AccessKeyId: the AccessKey ID used to call the API.
  • Signature: the signature generated after the request has been symmetrically encrypted by using the AccessKey secret.

Signature calculation

The signature algorithm complies with the HMAC-SHA1 specifications in RFC 2104. It uses an AccessKey secret to calculate the Hash-based Message Authentication Code (HMAC) of an encoded and formatted query string and use the HMAC value as the signature. The request signature includes operation-specific parameters. Therefore, the signature of each request varies depending on the request parameters. 

Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(
StringToSign)) )
To calculate a signature, perform the following steps:
  1. Compose a string-to-sign (StringToSign).
    The StringToSign is a string assembled by using related elements in an API request. It is used to calculate the signature and contains the following elements:
    • HTTP header
    • Alibaba Cloud protocol headers (CanonicalizedHeaders)
    • Canonicalized resource (CanonicalizedResource)
    • Body

    The string-to-sign must be created in the following format: 

    StringToSign = 
       //HTTP header
        HTTP-Verb + "\n" +
        Accept + "\n" +
        Content-MD5 + "\n" +//Place the request body encrypted by using the MD5 algorithm in this field.
        Content-Type + "\n" +
        Date + "\n" +
       //Alibaba Cloud protocol headers (CanonicalizedHeaders)
        CanonicalizedHeaders +
       //Canonicalized resource (CanonicalizedResource)
        CanonicalizedResource

    Example of an 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 of a canonicalized request:

    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
  2. Add the signature string.

    Add the calculated signature in the following format to the request header:

    Authorization: acs AccessKeyId:Signature

HTTP header

The HTTP header in the StringToSign must contain the values of the following parameters. Parameters must be sorted in alphabetical order. If a parameter has no value, replace it with \n.

  • Accept: the response type required by the client. Valid values: application/json and application/xml.
  • Content-MD5: the 128-bit MD5 hash value of the request body represented as a Base64 string.
  • Content-Type: the type of the HTTP request body defined in RFC 2616.
  • Date: the GMT time specified in HTTP 1.1. Example: Wed, 05 Sep. 2012 23:00:00 GMT.
    Note The HTTP header does not need to contain the AccessKey.
Example of an 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 of a canonicalized header: 
application/json
ChDfdfwC+Tn874znq7Dw7Q==
application/x-www-form-urlencoded;charset=utf-8
Thu, 22 Feb 2018 07:46:12 GMT

Alibaba Cloud protocol headers (CanonicalizedHeaders)

CanonicalizedHeaders are non-standard HTTP headers of Alibaba Cloud. They are parameters prefixed with x-acs- in a request. A request must contain the following parameters:
  • x-acs-signature-nonce: a unique number that is randomly generated to prevent network replay attacks. You must use different numbers for different requests.
  • x-acs-signature-version: the version of the signature encryption algorithm. Set the value to 1.0.
  • x-acs-version: the version number of the API. For more information, see the API documentation of each product.

To construct Alibaba Cloud canonicalized headers, perform the following steps:

  1. Convert the names of all HTTP request headers prefixed with x-acs- to lowercase letters. For example, convert X-acs-OSS-Meta-Name: TaoBao to x-acs-oss-meta-name: TaoBao.
  2. Arrange all HTTP request headers that are obtained from the preceding step in alphabetical order.
  3. Delete all spaces on either side of a delimiter between the request header and its content. For example, convert x-acs-oss-meta-name: TaoBao,Alipay to x-acs-oss-meta-name:TaoBao,Alipay.
  4. Separate all headers and content with delimiters (\n) to form the final CanonicalizedHeaders.

Example of an original 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-02GMT

Example of a canonicalized 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

Canonicalized resource (CanonicalizedResource)

CanonicalizedResource represents the specification description of the resource to be accessed. Sort sub-resources along with query in alphabetical order and separate them with ampersands (&) to generate a sub-resource string. The sub-resource string consists of all parameters following the question mark (?).

Example of an original request: 
/stacks? status=COMPLETE&name=test_alert
Example of a canonicalized request: 
/stacks? name=test_alert&status=COMPLETE

Body

Encrypt the request body by using the MD5 algorithm, encode the request body in Base64, and add the Base64-encoded string to the Content-MD5 parameter.