Common HTTP parameters

Last Updated: Mar 14, 2017

Communication protocol

In the KMS, requests can be sent only through the HTTPS channel.

KMS does not support SSLv2 or SSLv3 but TLS1.0 and above.

Request method

HTTP POST and GET requests are supported.

Signature mechanism

KMS performs authentication on the sender of each access request. Therefore, a request must contain signature information. By using Access Key ID and Access Key Secret, KMS performs Message Authentication Code (MAC) calculation to authenticate the request sender. Access Key ID and Access Key Secret are officially issued to visitors by Alibaba Cloud (visitors can apply for and manage them on the official website of Alibaba Cloud). Access Key ID indicates the identity of the visitor. Access Key Secret is the secret key used to encrypt signature string and to verify the signature string on the server. Access Key Secret must be kept strictly confidential and known only by Alibaba Cloud and authenticated visitors.

When you access KMS, use the following method to sign the request:

  • Use request parameters to construct a canonicalized request string.

    • (a) Order all request parameters (including the “public request parameters” and custom parameters for the given request interfaces described in this document, but excluding Signature parameter itself mentioned in “Public Request Parameters”) of the request alphabetically by parameter names.NOTE: When a request is submitted using the GET method, these parameters are the parameter section of the request URI (that is, the section in the URI following “?” and connected by “&”).

    • (b) Encode the name and value of each request parameter. The names and values must undergo URL encoding using UTF-8 character set. URL encoding rules are as follows:

      • i. Do not encode characters A-Z, a-z, 0-9, “-“, “_”, “.” or “~”.
      • ii. Encode other characters to “%XY” format, in which XY represents the characters’ ASCII code in hexadecimal notation. For example, the English double quotes (“) are encoded as %22.
      • iii. Encode extended UTF-8 characters to “%XY%ZA…” format.
      • iv. Note: Encode the English space ( ) as %20 instead of plus sign (+).
      • NOTE: Generally, libraries that support URL encoding (for example, Java’s java.net.URLEncoder) are all encoded according to the rules for “application/x-www-form-urlencoded” MIME-type. If this encoding method is used, replace the plus signs (+) in the encoded strings with %20, the asterisks (*) with %2A, and change %7E back to the tilde (~) to obtain encoded character string described in the rules above.```
    • (c) Connect encoded parameter names and values with the equal sign (=).

    • (d) Connect the character string, which is connected by English equal signs, alphabetically by parameter name with the ampersand “&” to produce canonicalized request string.

  • Use the canonicalized request string to construct the string for signature calculation according to the following rules:

    1. StringToSign=
    2. HTTPMethod + “&” +
    3. percentEncode(“/”) + ”&” +
    4. percentEncode(CanonicalizedRequestString)
    5. Here, HTTPMethod is the HTTP method used for request submission, for example, GET.
    6. percentEncode ("/") is the encoded value for the character "/" according to URL encoding rules described in 1.b, that is, "%2F".
    7. percentEncode(CanonicalizedQueryString) is the string encoded from the canonicalized request string constructed in Step 1, according to the URL encoding rules described in 1.b.
  • Based on the RFC2104 definition, use the string for signature mentioned above to calculate HMAC value of the signature. NOTE: The Key used when calculating the signature is the Access Key Secret held by the user with an extra character “&” (ASCII:38), and SHA1 hashing algorithm is used.

-Encode above HMAC value to a string according to Base64 encoding rules to obtain the signature value.

  • Add the obtained signature value to the request parameters as Signature parameter to sign the request.

NOTE: Like other parameters, the obtained signature value is required to undergo URL encoding based on RFC3986 rules when submitted to KMS server as final request parameter value.

Take CreateKey as an example: the request URL before signature is:

  1. https://kms.cn-hangzhou.aliyuncs.com/?Action=CreateKey
  2. &SignatureVersion=1.0
  3. &Format=json
  4. &Version=2016-01-20
  5. &AccessKeyId=testid
  6. &SignatureMethod=HMAC-SHA1
  7. &Timestamp=2016-03-28T03:13:08Z

And then the canonicalized request string is:

  1. AccessKeyId=testid&Action=CreateKey&Format=json&SignatureMethod=HMAC-SHA1&SignatureVersion=1.0&Timestamp=2016-03-28T03%3A13%3A08Z&Version=2016-01-20
  2. Thus, the StringToSign is:

AccessKeyId=testid&Action=CreateKey&Format=json&SignatureMethod=HMAC-SHA1&SignatureVersion=1.0&Timestamp=2016-03-28T03%3A13%3A08Z&Version=2016-01-20

  1. Assume that the "Access Key ID" parameter value is "testid", the "Access Key Secret" parameter value is "testsecret" and the key used for HMAC calculation is "testsecret&", and then the calculated signature value would be:

41wk2SSX1GJh7fwnc5eqOfiJPFg= //It would be 41wk2SSX1GJh7fwnc5eqOfiJPFg%3D after URL encoding.

  1. The signed request URL is (with Signature parameter added):

https://kms.cn-hangzhou.aliyuncs.com/?Action=CreateKey&SignatureVersion=1.0&Format=json&Version=2016-01-20&AccessKeyId=F5856RW8kXMuAPMU&SignatureMethod=HMAC-SHA1&Timestamp=2016-03-28T03:13:08Z&Signature=41wk2SSX1GJh7fwnc5eqOfiJPFg%3D

  1. ##Public parameters
  2. Public request parameters refer to the request parameters that every interface must use.
  3. | Name | Type | Required? | Description |
  4. | :-- | :-- | :-- | :-- |
  5. | Format | String | No | Type of the value returned. JSON and XML are supported. Default value is XML. |
  6. | Action| String | Yes | API name. Currently, the following APIs are provided: CreateKey, GenerayeDataKey, Encrypt, Decrypt, ListKeys, and DescribeKey.
  7. | Version | String | Yes | API version number. The format is YYYY-MM-DD. Current version number is 2016-01-20. |
  8. | AccessKeyId | String | Yes | Access key ID used to access services, issued to a user by Alibaba Cloud. |
  9. | Signature| String | Yes | Signature result string. For details about signature calculation method, refer to signature mechanism section described previously.|
  10. | SignatureMethod | String | Yes | Signature method. Currently, HMAC-SHA1 is supported. |
  11. | Timestamp| String | Yes | Time stamp of request. Date format is represented based on ISO8601, and UTC time is used. The format is YYYY-MM-DDThh:mm:ssZ. For example, 2015-12-01T12:00:00Z (equivalent to 20:00:00, December 1, 2015 Beijing time). |
  12. | SignatureVersion | String | Yes | Signature algorithm version. Current version is 1.0. |
  13. Example:

https://kms.cn-hangzhou.aliyuncs.com/?Format=json&Action=CreateKey&Version=2016-01-20&AccessKeyId=testid&Signature=YlrFhyqDZQ1ThNYARrv3Ptaxqfc%3D&SignatureMethod=HMAC-SHA1&Timestamp=2016-03-25T09:36:58Z&SignatureVersion=1.0

  1. ##Public return parameters
  2. Each time you send a request to call an interface, the system returns a unique identification code (RequestID) to you, no matter the request is successful or not.
  3. XML example:

348d9445-e39a-4d80-907d-298cc6c94447<!—Return result data—>

  1. JSON example:

{“RequestId”: “284b2b80-9b17-4546-a093-adfbae512a54”}

  1. ##Public errors
  2. | Error code | Description | HTTP status code |
  3. | :-- | :-- | :-- |
  4. | InternalFailure | Internal Failure | 500 |
  5. | SerivceUnavailableTemporary | Service Unavailable Temporary | 503 |
  6. | InvalidAccessKeyId.NotFound | The Access Key ID provided does not exist in our records. | 404 |
  7. | Forbidden.KeyNotFound | The specified Key is not found. | 404 |
  8. | Forbidden.NoPermission | This operation is forbidden by permission system. | 403 |
  9. | Forbidden.AccessKey | This AccessKey is not enabled. | 403 |
  10. | ParseRequestParameterException | Server parse parameters exception. Please check your input params. | 400 |
  11. | MissingParameter | The parameter "< parameter name >" is needed but not provided. | 400 |
  12. | InvalidParameter | The specified parameter "< parameter name >" is not valid. | 400 |
  13. | IncompleteSignature | The request signature does not conform to Aliyun standards.| 400 |
  14. | IllegalTimestamp | The input parameter "Timestamp" that is mandatory for processing this request is not supplied. | 400 |
  15. |UnsupportedHTTPMethod |This http method is not supported.|403|
  16. |Forbidden.UbsmsInvalidUserid|Userid Invalid For Ubsms|403|
  17. |Forbidden.UbsmsInvalidBid|Your account partner does not have KMS Service|403|
  18. |Forbidden.KmsServiceNotEnabled|Kms service is not Enabled for current user. Please get access permission first|403|
  19. |Forbidden.ProhibitedByRiskControl|Current user is Prohibited By Risk Control|403|
  20. |Forbidden.InDebtOverdue|Current user is indebted Overdue|403|
  21. |Forbidden.InDebt|Current user is indebted|403|
  22. |Rejected.LimitExceeded|User Key Limit Exceeded|400|
  23. |Rejected.Disabled|The specified Key is not Enable|409|
  24. |Rejected.StateModifiedFailed|Keystate modified failed|409|
  25. When an error occurs in an interface call, no results are returned. The caller can refer to the appended table Error Code Table to locate the cause of the error.
  26. When an error occurs in a call, an HTTP status code 4xx or 5xx will be returned for the HTTP request. The returned message body contains specific error code and error message as well as a globally unique request ID (RequestID). If failing to find the cause of the error, the caller can contact Alibaba Cloud customer service and provide the RequestID and the domain name of the KMS server you accessed, so that we can solve the problem for you as quickly as possible.
  27. XML example (request expired):

400

IllegalTimestamp

The input parameter “Timestamp” that is mandatory for processing this request is not supplied.

3b237773-bc2c-4bea-95fc-319a1a5baa68

  1. JSON example (request expired):

{“HttpStatus”: 400“Code”: “IllegalTimestamp”“Message”: “The input parameter “Timestamp” that is mandatory for processing this request is not supplied.”“RequestId”: “e85db688-a2d3-44ca-9790-4259f59e90d8”}```

Thank you! We've received your feedback.