You must sign all API requests to ensure security. Alibaba Cloud uses the request signature to verify the identity of the API caller. KMS implements symmetric encryption with an AccessKey pair to verify the identity of the request sender. An AccessKey pair consists of an AccessKey ID and an AccessKey secret. You can apply for an AccessKey pair and manage it in the Alibaba Cloud Management Console.

Procedure

  1. Compose and encode a string-to-sign.
    • Create a canonicalized query string by arranging the request parameters (including all common and operation-specific parameters except Signature) in alphabetical order. The canonicalized query string is only made up of the parameters and does not include "https://endpoint/?".
      Note If you use the GET method to send a request, the request parameters are included as a part of the request URL. The request parameters in the URL are placed after a question mark (?) and separated with ampersands (&).
    • Encode the canonicalized query string in UTF-8. Encoding rules:
      • Uppercase letters, lowercase letters, digits, and some special characters such as hyphens (-), underscores (_), periods (.), and tildes (~) do not need to be encoded.
      • Other characters must be percent encoded in %XY format. XY represents the ASCII code of the characters in hexadecimal notation. For example, double quotation marks (") are encoded as %22.
      • Spaces must be encoded as %20. Do not encode spaces as plus signs (+).
        Note Most libraries that support URL encoding, such as java.net.URLEncoder, comply with the Multipurpose Internet Mail Extensions (MIME) encoding rules of application/x-www-form-urlencoded. If this encoding method is used, replace the plus signs (+) in the encoded strings with %20, the asterisks (*) with %2A, and %7E with a tilde (~) to conform to the encoding rules.
    • Connect the encoded parameter names and values by using equal signs (=).
    • Sort the equal sign-connected strings by their parameter names in alphabetical order and connect them with ampersands (&).

      Create a string-to-sign from the encoded canonicalized query string.

      StringToSign=
      HTTPMethod + "&" +
      percentEncode("/") + "&" +
      percentEncode(CanonicalizedQueryString)
                                  

      where:

      • HTTPMethod indicates the HTTP method that is used to submit a request, such as GET.
      • percentEncode("/") specifies the encoded value for the forward slash (/) based on the URL encoding rules previously described. The value is %2F.
      • percentEncode(CanonicalizedQueryString) specifies the encoded string of the canonicalized query string constructed in step 1, produced by following the URL encoding rules previously described.
  2. Use the previous signature string to calculate the HMAC value of the signature as defined in RFC 2104. For more information about RFC 2104, see RFC 2104.
    Notice The key used for signature calculation is your AccessKey secret. An ampersand (&) is added to the end of the key (ASCII: 38). SHA-1 hashing is used.
  3. Encode the HMAC value in Base64 to obtain the signature string.
  4. Add the signature string to the request as the Signature parameter.
    Note When the signature string is submitted to the KMS server as the final request parameter value, the string must be URL-encoded like other parameters based on rules defined in RFC 3986.

Example

The following code is the request URL without a signature for the CreateKey operation:

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

The following code is the CanonicalizedQueryString:

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

The following code is the StringToSign:

GET&%2F&AccessKeyId%3Dtestid%26Action%3DCreateKey%26Format%3Djson%26SignatureMethod%3DHMAC-SHA1%26SignatureVersion%3D1.0%26Timestamp%3D2016-03-28T03%253A13%253A08Z%26Version%3D2016-01-20
            

Assume that the AccessKey ID is testid, the AccessKey secret is testsecret, and the key used for HMAC calculation is testsecret&. The following signature string is obtained:

41wk2SSX1GJh7fwnc5eqOfiJPF****

The following code is the signed request URL with the Signature parameter added:

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