To ensure secure calls to an API, Alibaba Cloud authenticates each API request through the signature. When you call an API by using HTTP or HTTPS, the request must contain the signature information.

Overview

To call a RESTful API, you must add the Authorization parameter in the following format to the API request header to provide a signature:

Authorization:acs:AccessKeyId:Signature
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 RFC 2104 HMAC-SHA1 specifications. It uses the AccessKey secret to calculate the Hash-based Message Authentication Code (HMAC) of the encoded and formatted request string as the signature. The elements used for calculating a signature are some parameters of the request. Therefore, the signature results vary according to API requests.

Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(
StringToSign)) )
To calculate a signature, perform the following steps:
  1. Construct a complete string to be signed (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 StringToSign must be constructed 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. Calculate a signature.

    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 following parameters. Sort the parameters in ascending lexicographic order. If a parameter has no value, pad it with \n.

  • Accept: the return value 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 stipulated in the HTTP 1.1 protocol, for 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. A different random number is required for each request.
  • x-acs-signature-version: the signature version. Valid value: 1.0.
  • x-acs-version: the API version. 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. Sort all HTTP request headers that are obtained from the preceding step in ascending lexicographic order.
  3. Delete any space on either side of the delimiter between each 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 separators (\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-02 GMT

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 is the canonical description of the resource you want to access. Sort sub-resources along with the query parameters in ascending lexicographic 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

Use the MD5 algorithm to encrypt the request body, and encode it in Base64. Then write the Base64-encoded string in the Content-MD5 parameter.