You must sign all API requests to ensure security. Alibaba Cloud uses the request signature to verify the identity of the API caller. ActionTrail 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 console.

Alibaba Cloud offers Alibaba Cloud service SDKs and third-party SDKs in multiple languages, helping you easily sign API requests. For more information, download SDKs through GitHub. This topic describes how to manually sign an API request.

Procedure

  1. Compose and encode a string-to-sign.

    1. Create a canonicalized query string by arranging the request parameters (including all common and operation-specific parameters except Signature) in alphabetical order.
      Note If you use the GET method to submit the request, these parameters are the part located after the question mark (?) and connected by the ampersands (&) in the request uniform resource identifier (URI).
    2. 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 Generally, all the libraries that support URL encoding, such as java.net.URLEncoder, perform encoding based on the rule of the application/x-www-form-urlencoded MIME type. If you use this encoding method, you can replace plus signs (+) in the encoded strings with %20, asterisks (*) with %2A, and %7E with tildes (~) to obtain the required strings.
    3. Connect the encoded parameter names and values by using equal signs (=).
    4. Sort the connected parameter name and value pairs in the order specified in step 1.i and connect the pairs by using ampersands (&) to obtain the canonicalized query string.

      Create a string-to-sign from the encoded canonicalized query string as follows:

      StringToSign=
      HTTPMethod + "&" +
      percentEncode("/") + "&" +
      percentEncode(CanonicalizedQueryString)
      							
    • HTTPMethod indicates the HTTP method used to make the request, such as GET.
    • percentEncode("/") specifies the encoded value for the forward slash (/) based on the URL encoding rules described in step 1.ii, which is %2F.
    • percentEncode(CanonicalizedQueryString) specifies the encoded string of the canonicalized query string constructed in step 1.i, produced by following the URL encoding rules described in step 1.ii.
  2. Calculate the hash-based message authentication code (HMAC) value of the string-to-sign based on RFC 2104.
    Note Use the SHA1 algorithm to calculate the HMAC value of the string-to-sign. The combination of your AccessKey secret and an ampersand (&) (ASCII code 38) that follows the secret is used as the key for the HMAC calculation.
  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 obtained signature value is submitted to the Resource Access Management (RAM) server as the final request parameter value, the value must be URL-encoded like other parameters based on rules defined in RFC 3986.

Signature examples

Take the CreateTrail API operation as an example. The request URL to be signed is as follows:

http://actiontrail.cn-hangzhou.aliyuncs.com/actiontrail?SignatureVersion=1.0
&OssBucketName=yuanch****
&Name=CreateTest
&Format=JSON
&Timestamp=2015-12-01T08%3A23%3****
&AccessKeyId=te****
&SignatureMethod=HMAC-SHA1
&Version=2015-09-28
&RoleName=aliyunactiontraildefaultrole
&Action=CreateTrail
&OssKeyPrefix=
			

The corresponding string-to-sign is as follows:

GET&%2F&AccessKeyId%3Dtestid&Action%3DCreateTrail&Format%3DJSON&Name%3DCreateTest&OssBucketName%3Dyuanchuang&OssKeyPrefix%3D&RoleName%3Daliyunactiontraildefaultrole&SignatureMethod%3DHMAC-SHA1&SignatureNonce%3Dce999197-9804-11e5-abfe-7831c1c8022e&SignatureVersion%3D1.0&Timestamp%3D2015-12-01T08%253A23%253A31Z&Version%3D2015-09-28
			

Assume that the AccessKey ID is testid and the AccessKey secret is testsecret. The signature string calculated by using testsecret& is as follows:

vAeYfUeJUctqeqQGUkFITGnFAeo=
			

In this example, the URL of the signed request is as follows:

http://actiontrail.cn-hangzhou.aliyuncs.com/actiontrail?SignatureVersion=1.0
&OssBucketName=yuanch****
&Name=CreateTest
&Format=JSON
&Timestamp=2015-12-01T08%3A23%3****
&Signature=vAeYfUeJUctqeqQGUkFITGnFAe****
&AccessKeyId=te****
&SignatureMethod=HMAC-SHA1
&Version=2015-09-28
&RoleName=aliyunactiontraildefaultrole
&Action=CreateTrail
&SignatureNonce=ce999197-9804-11e5-abfe-7831c1c8****
&OssKeyPrefix=