Signature mechanism

Last Updated: Feb 14, 2018

Introduction

The accessKeyId and accessKeySecret are officially issued to you by Alibaba Cloud (you can apply for and manage them on the Alibaba Cloud official website). The accessKeyId is used to identify your identity. The accessKeySecret is the key used to encrypt the signature string and verify the signature string on the server side. You must keep the accessKeySecret confidential. Only you and Alibaba Cloud can know it.

Container Service verifies each access request it receives. Therefore, all requests sent to Container Service must contain signature information. Container Service performs symmetric encryption by using the accessKeyId and accessKeySecret to verify the identity of request senders. If the calculated verification code is the same as the one provided, the request is considered as valid. Otherwise, Container Service rejects the request and returns the HTTP 403 error.

You can add the authorization header in the HTTP request to contain the signature information, indicating that the message has been authorized.

Container Service requires to contain the signature in the HTTP header in the format of Authorization: acs [accessKeyId]:[Signature].

The signature calculation method is as follows:

  1. Signature = base64(hmac-sha1(VERB + "\n"
  2. + ACCEPT + "\n" +
  3. + Content-MD5 + "\n"
  4. + Content-Type + "\n"
  5. + Date + "\n"
  6. + CanonicalizedHeaders + "\n"
  7. + CanonicalizedResource))
  • VERB indicates the HTTP method, for example, PUT.
  • Accept indicates the return type required by the client, which can be application/json or application/xml.
  • Content-MD5 indicates the MD5 value of the requested content.
  • Content-Type indicates the type of the requested content.
  • Date indicates the operation time, which cannot be null. For example, Thu, 17 Mar 2012 18:49:58 GMT. Currently, only the GMT format is supported. If the difference between the request time and the CAS server time exceeds 15 minutes, CAS considers the request as invalid and returns error 400.
  • CanonicalizedHeaders indicates a combination of fields started with x-acs- in the HTTP request.
  • CanonicalizedResource indicates the uniform resource identifier (URI) of the resource in the HTTP request. For example, /clusters?name=my-clusters&resource=new.

Note:
Conform to the following specifications for CanonicalizedHeaders (headers started with x-acs-) before signature verification:

  1. Convert the names of all HTTP request headers started with x-acs- to lowercase letters. For example, convert X-ACS-Meta-Name: TaoBao to x-acs-meta-name: TaoBao. The names of request headers are case-insensitive according to Alibaba Cloud specifications. However, we recommend that you use the lowercase letters.
  2. If the value part of a public request header is too long, replace the \t, \n, \r, and \f separators with spaces.
  3. Sort all HTTP request headers that are obtained from the preceding step and compliant with Alibaba Cloud specifications in the lexicographically ascending order.
  4. Delete any space at either side of a separator between request header and content. For example, convert x-acs-meta-name: TaoBao,Alipay to x-acs-meta-name:TaoBao,Alipay.
  5. Separate all headers and contents with the \n separator to form the final CanonicalizedHeaders.

Note:
The format specification for CanonicalizedResource: CanonicalizedResource indicates the standard description of the resource you want to access. Sort sub-resources and query in the lexicographically ascending order and separate them by using the & separator to generate a sub-resource string (all parameters after ?).

  1. http://cs.aliyuncs.com/clusters?name=my-clusters&resource=new

The CanonicalizedResource format is:

  1. /clusters?name=my-clusters&resource=new

Signature example

Overview

The following example shows the signature process.

In the example, the accessKeyId and accessKeySecret are access_key_id and access_key_secret respectively. We recommend that you use your own API call program to calculate the signature string in the following example. Then, compare your signature string with the example result.

The request example is as follows:

  1. POST http://cs.aliyuncs.com/clusters?param1=value1&param2=value2 HTTP/1.1
  2. Accept-Encoding: identity
  3. Content-Length: 210
  4. Content-MD5: 6U4ALMkKSj0PYbeQSHqgmA==
  5. x-acs-version: 2015-12-15
  6. Accept: application/json
  7. User-Agent: cs-sdk-python/0.0.1 (Darwin/15.2.0/x86_64;2.7.10)
  8. x-acs-signature-nonce: fbf6909a-93a5-45d3-8b1c-3e03a7916799
  9. x-acs-signature-version: 1.0
  10. Date: Wed, 16 Dec 2015 12:20:18 GMT
  11. x-acs-signature-method: HMAC-SHA1
  12. Content-Type: application/json;charset=utf-8
  13. X-Acs-Region-Id: cn-beijing
  14. Authorization: acs access_key_id:/uA9QF5CHrr1FK3siBA4xLMTWE0=
  15. {"password": "Just$test","instance_type": "ecs.m2.medium","name": "my-test-cluster-97082734","size": 1,"network_mode": "classic","data_disk_category": "cloud","data_disk_size": 10,"ecs_image_id": "m-253llee3l"}

Request construction process

Calculate Content-Length and Content-MD5

Content-Length: The length of the body content.

Note: No space or line break is at the beginning of the example body.

  1. body: {"password": "Just$test","instance_type": "ecs.m2.medium","name": "my-test-cluster-97082734","size": 1,"network_mode": "classic","data_disk_category": "cloud","data_disk_size": 10,"ecs_image_id": "m-253llee3l"}
  2. Content-Length: 210

Content-MD5: The MD5 calculation process.

  1. body: {"password": "Just$test","instance_type": "ecs.m2.medium","name": "my-test-cluster-97082734","size": 1,"network_mode": "classic","data_disk_category": "cloud","data_disk_size": 10,"ecs_image_id": "m-253llee3l"}
  2. # Calculate the MD5 value of the body.
  3. md5(body): e94e002cc90a4a3d0f61b790487aa098
  4. # Convert the MD5 value to a byte array. Convert every two hexadecimal symbols of the MD5 value to a byte.
  5. # For example, e9 -> 11111111111111111111111111101001 -> -23
  6. bytes(md5(body)): {[-23], [78], [0], [44], [-55], [10], [74], [61], [15], [97], [-73], [-112], [72], [122], [-96], [-104]}
  7. # Convert the obtained byte array to a Base64 string.
  8. base64(bytes(md5(body))): 6U4ALMkKSj0PYbeQSHqgmA==
  9. Content-MD5: 6U4ALMkKSj0PYbeQSHqgmA==

Process CanonicalizedHeaders

  1. # List all headers started with 'x-acs-'.
  2. x-acs-version: 2015-12-15
  3. x-acs-signature-nonce: ca480402-7689-43ba-acc4-4d2013d9d8d4
  4. x-acs-signature-version: 1.0
  5. x-acs-signature-method: HMAC-SHA1
  6. X-Acs-Region-Id: cn-beijing
  7. # Convert the request name to lowercase letters, delete the spaces at the beginning and end of each line, and sort in the lexicographical order. Delete any space at either side of a separator between request header and content.
  8. # Note: No line break is in the last line.
  9. x-acs-region-id:cn-beijing
  10. x-acs-signature-method:HMAC-SHA1
  11. x-acs-signature-nonce:fbf6909a-93a5-45d3-8b1c-3e03a7916799
  12. x-acs-signature-version:1.0
  13. x-acs-version:2015-12-15

Calculate CanonicalizedResource

In the example, the length of CanonicalizedResource is 27.

Note: An \n line break is at the end of the first line.

  1. /clusters?param1=value1&param2=value2

Calculate Signature

Assemble SignatureString. In the example, the length of the signature string is 307. An \n line break is at the end of all lines except the last line.

  1. POST
  2. application/json
  3. 6U4ALMkKSj0PYbeQSHqgmA==
  4. application/json;charset=utf-8
  5. Wed, 16 Dec 2015 12:20:18 GMT
  6. x-acs-region-id:cn-beijing
  7. x-acs-signature-method:HMAC-SHA1
  8. x-acs-signature-nonce:fbf6909a-93a5-45d3-8b1c-3e03a7916799
  9. x-acs-signature-version:1.0
  10. x-acs-version:2015-12-15
  11. /clusters?param1=value1&param2=value2

Calculate Signature

  1. # Use accessKeySecret to encrypt the signature string. In the example, the accessKeySecret is access_key_secret.
  2. hmac-sha1(SignatureString): fee03d405e421ebaf514adec881038c4b313584d
  3. # Convert the encrypted string to a byte array, similar to the Content-MD5 calculation method.
  4. # Convert the byte array to a Base64 string to get the final signature string.
  5. base64(bytes(hmac-sha1(SignatureString))): ZmVlMDNkNDA1ZTQyMWViYWY1MTRhZGVjODgxMDM4YzRiMzEzNTg0ZA==
  6. Signature: ZmVlMDNkNDA1ZTQyMWViYWY1MTRhZGVjODgxMDM4YzRiMzEzNTg0ZA==

Finish

After the preceding processing, add some other header information to construct the final HTTP request as follows:

  1. POST http://cs.aliyuncs.com/clusters?param1=value1&param2=value2 HTTP/1.1
  2. Accept-Encoding: identity
  3. Content-Length: 210
  4. Content-MD5: 6U4ALMkKSj0PYbeQSHqgmA==
  5. x-acs-version: 2015-12-15
  6. Accept: application/json
  7. User-Agent: cs-sdk-python/0.0.1 (Darwin/15.2.0/x86_64;2.7.10)
  8. x-acs-signature-nonce: fbf6909a-93a5-45d3-8b1c-3e03a7916799
  9. x-acs-signature-version: 1.0
  10. Date: Wed, 16 Dec 2015 12:20:18 GMT
  11. x-acs-signature-method: HMAC-SHA1
  12. Content-Type: application/json;charset=utf-8
  13. X-Acs-Region-Id: cn-beijing
  14. Authorization: acs access_key_id:/uA9QF5CHrr1FK3siBA4xLMTWE0=
  15. {"password": "Just$test","instance_type": "ecs.m2.medium","name": "my-test-cluster-97082734","size": 1,"network_mode": "classic","data_disk_category": "cloud","data_disk_size": 10,"ecs_image_id": "m-253llee3l"}
Thank you! We've received your feedback.