Common HTTP parameters

Last Updated: Nov 17, 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 later versions.

Request method

HTTP POST and GET requests are supported.

Signature

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

When you access KMS, follow these steps 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 question mark (?) and connected by ampersand (&)).

    • (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, dashes (-), underscores (_), periods (.) or tildes (~).
      • 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 preceding rules.```
    • (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 slash (/) 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 the preceding signature to calculate HMAC value of the signature. NOTE: The Key used when calculating the signature is the AccessKey Secret held by the user with an extra character ampersand (&) (ASCII:38), and SHA1 hashing algorithm is used.

-Encode preceding 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 "AccessKey ID" parameter value is "testid", the "AccessKey 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. |
  7. | Version | String | Yes | API version number. The format is YYYY-MM-DD. Current version number is 2016-01-20. |
  8. | AccessKeyId | String | Yes | AccessKey ID used to access services, issued to a user by Alibaba Cloud. |
  9. | Signature| String | Yes | Signature result string. For more information about signature calculation method, see the signature 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 AccessKey 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 Alibaba Cloud standards.| 400 |
  14. | IllegalTimestamp | The input parameter "Timestamp" that is required 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 returns for the HTTP request. The returned message body contains specific error code, error message, and 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 required 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 required for processing this request is not supplied.”“RequestId”: “e85db688-a2d3-44ca-9790-4259f59e90d8”}```

Thank you! We've received your feedback.