You must sign all API requests to ensure security. Alibaba Cloud uses the request signature to verify the identity of the API caller. The following items describe the parameters in the syntax:

Overview

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

Authorization:acs AccessKeyId:Signature
In the preceding example:
  • acs: indicates  Alibaba Cloud service. The fixed identifier cannot be modified.
  • AccessKeyId: indicates the AccessKey ID that is used to call the API operation.
  • Signature: indicates the signature that is generated by using the AccessKey secret to perform symmetric encryption on the request.

Calculate signatures

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 of a request are used to calculate a signature. Therefore, a signature varies based on the specified request. 

Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(
StringToSign)) )
To calculate a signature, perform the following steps:
  1. Create a string-to-sign.
    Each string-to-sign is a string that is formed by splicing the required parameters of an API request. The string is used to calculate a signature and contains the following parameters:

    The following example shows the structure of a string-to-sign.

    StringToSign = 
       // The HTTP header.
        HTTP-Verb + "\n" +
        Accept + "\n" +
        Content-MD5 + "\n" + // The request body that is encrypted by using the MD5 algorithm.
        Content-Type + "\n" +
        Date + "\n" +
       // Alibaba Cloud protocol headers (CanonicalizedHeaders).
        CanonicalizedHeaders +
       // Specifies how to add the CanonicalizedResource parameter to the signature.
        CanonicalizedResource

    The following example shows an original request:

    POST /stacks? name=test_alert&status=COMPLETE HTTP/1.1
Host: ***.aliyuncs.com
Accept: application/json
Content-MD5: ChDfdfwC+Tn87******w7Q==
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-44665544****
x-acs-signature-method: HMAC-SHA1
x-acs-signature-version: 1.0
x-eventbridge-version: 2020-04-01

    The following example shows a canonical request:

    POST
application/json
ChDfdfwC+Tn87******w7Q==
application/x-www-form-urlencoded;charset=utf-8
Thu, 22 Feb 2018 07:46:12 GMT
x-acs-signature-nonce:550e8400-e29b-41d4-a716-44665544****
x-acs-signature-method:HMAC-SHA1
x-acs-signature-version:1.0
x-eventbridge-version:2020-04-01
/stacks? name=test_alert&status=COMPLETE
  2. Add the signature.

    Add the calculated signature to the request header:

    Authorization:acs AccessKeyId:Signature

HTTP header

The signature calculation must include the values of the following parameters that are 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 Base64-encoded 128-bit MD5 hash value of the HTTP request body.
  • Content-Type: the type of the HTTP request body. The type is defined in RFC 2616.
  • Date: the GMT time specified in HTTP 1.1. For example, the value is Wed, 05 Sep. 2012 23:00:00 GMT.
    Note The keys of the parameters are not converted during signature calculation.
The following sample shows an original header:
Accept: application/json
Content-MD5: ChDfdfwC+Tn87******w7Q==
Content-Type: application/x-www-form-urlencoded;charset=utf-8
Date: Thu, 22 Feb 2018 07:46:12 GMT
The following sample shows a canonical header:
application/json
ChDfdfwC+Tn87******w7Q==
application/x-www-form-urlencoded;charset=utf-8
Thu, 22 Feb 2018 07:46:12 GMT

Canonicalized headers of Alibaba Cloud (CanonicalizedHeaders)

Alibaba Cloud canonicalized headers are non-standard HTTP headers. These headers are parameters that are prefixed with x-acs- in a request. A request must contain the following parameters:
  • x-acs-signature-nonce: a unique, random number used to prevent replay attacks. A different random number is required for each request.
  • x-acs-signature-method: the signature algorithm. Set the value to HMAC-SHA1.
  • x-acs-signature-version: the version of the signature algorithm. Set the value to 1.0.
  • x-eventbridge-version: the version number of the API. For more information, see the API documentation for each service.

To construct canonicalized headers of Alibaba Cloud, 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 spaces from each 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.

The following sample shows an original header:

x-acs-signature-nonce: 550e8400-e29b-41d4-a716-44665544****
x-acs-signature-method: HMAC-SHA1
x-acs-signature-version: 1.0
x-eventbridge-version: 2020-04-01GMT

The following sample shows a canonical header:

x-acs-signature-nonce: 550e8400-e29b-41d4-a716-44665544****
x-acs-signature-method: HMAC-SHA1
x-acs-signature-version: 1.0
x-eventbridge-version: 2020-04-01

Canonicalized resource (CanonicalizedResource)

CanonicalizedResource specifies the canonical description of the resource that you want to access. Sort sub-resources and query parameters in alphabetical order and separate them with ampersands (&) to generate a sub-resource string. The sub-resource string consists of all parameters that follow the question mark (?).

The following sample shows an original request:
/stacks? status=COMPLETE&name=test_alert
The following sample shows a canonical request:
/stacks? name=test_alert&status=COMPLETE

Body

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