Signature

Last Updated: Sep 26, 2017

Note:

  • If SDK is used, signature is not required. Currently, Java, PHP, and C# SDKs have been provided.
  • Interfaces support GET and POST requests, but the StringToSigns of a GET request and a POST request are different.

DirectMail service performs sender authentication for each access request. Therefore, whether HTTP or HTTPS protocol is used to submit a request, the request must contain the signature information. DirectMail performs symmetric encryption to authenticate the request sender using the AccessKeyId and AccessKeySecret. The AccessKeyId and AccessKeySecret are officially issued to visitors by Alibaba Cloud (visitors can apply for and manage them on the Alibaba Cloud official website). The AccessKeyId indicates the identity of the visitor. The AccessKeySecret is the secret key to encrypt the signature string and verify the signature string on the server. The AccessKeySecret must be kept strictly confidential and only be known to Alibaba Cloud and the authenticated visitor.

The following method is used to sign the access request:

  1. Construct Canonicalized Query String using the request parameters.

    1. Order all the request parameters (including the public request parameters and custom parameters for the given request interfaces described in this document, but excluding the Signature parameter mentioned in public request parameters) alphabetically by parameter names.

      Note: When a request is submitted using the GET method, these parameters constitute the parameter section of the request URI (that is, the section in the URI following “?” and connected by “&”).

    2. The name and value of each request parameter are encoded. The names and values must adopt URL encoding in the UTF-8 character set. The URL encoding rules are as follows:
      • The characters A-Z, a-z, 0-9, “-“, “_”, “.”, and “~” are not encoded;
      • Other characters are encoded in the %XY format, with XY representing the characters’ ASCII code in hexadecimal notation. For example, the English double quotes (“) are encoded as %22.
      • Extended UTF-8 characters are encoded in the %XY%ZA... format;
      • The English space is encoded as %20, rather than the plus sign “+”.

        Note: Generally, libraries that support URL encoding (such as java.net.URLEncoder in Java) are all encoded following the rules for the application/x-www-form-urlencoded MIME type. This encoding method can apply directly during implementation, namely replacing the plus signs “+” in the encoded strings with %20, the asterisks “*” with %2A, and change %7E back to the tilde “~” to conform to the encoding rules.

    3. Connect the encoded parameter names and values with the English equal sign “=”.
    4. Connect the parameter name and value pairs connected by equal signs alphabetically by the parameter name with the ampersand “&” to produce the Canonicalized Query String.
  2. Follow the following rules to construct the string for signature calculation using the Canonicalized Query String constructed in the previous step:

    1. StringToSign=
    2. HTTPMethod + "&" +
    3. percentEncode("/") + "&" +
    4. percentEncode(CanonicalizedQueryString)

    Here, HTTPMethod is the HTTP method used for request submission, for example, GET or POST.

    percentEncode (“/“) is the encoded value for the character “/“ according to the URL encoding rules, namely %2F.

    percentEncode (CanonicalizedQueryString) is the encoded string of the Canonicalized Query String constructed in step 1, produced by the URL encoding rules.

  3. Based on the RFC2104 definition, the signature string is used to calculate the signature’s HMAC value.

    Note: The Key used for signature calculation is the AccessKeySecret with a “&” character (ASCII:38) added in the end, and the SHA1 hashing algorithm is used.

  4. Encode the HMAC value into a string based on Base64 encoding rules, and you can get the signature value (Signature).
  5. Add the obtained signature value to the request parameters as the Signature parameter. The request signing process is completed.

Note: URL encoding must be implemented for the obtained signature value based on the RFC3986 rule, like in the case of other parameters, before the signature value is submitted to the DirectMail server as the final request parameter value.

Take sending a POST request for calling the SingleSendMail interface over HPPTS as an example.
The request URL is: http://dm.aliyuncs.com/.
The parameters are:

  1. AccessKeyId=testid&AccountName=<a%b'>&Action=SingleSendMail&AddressType=1&Format=xml&HtmlBody=4&ReplyToAddress=true&SignatureMethod=Hmac-SHA1&SignatureNonce=e1b44502-6d13-4433-9493-69eeb068e955&SignatureVersion=1.0&Subject=3&TagName=2&Timestamp=2016-09-18T05%3A06%3A00Z&ToAddress=1%40test.com&Version=2015-11-23
  2. Therefore, the StringToSign is:
  3. POST&%2F&AccessKeyId%3Dtestid&AccountName%3D%253Ca%2525b%2527%253E&Action%3DSingleSendMail&AddressType%3D1&Format%3DXML&HtmlBody%3D4&RegionId%3Dcn-hangzhou&ReplyToAddress%3Dtrue&SignatureMethod%3DHMAC-SHA1&SignatureNonce%3D8ee704e1-152d-4048-9648-8bedd6cbf4f4&SignatureVersion%3D1.0&Subject%3D3&TagName%3D2&Timestamp%3D2016-09-18T03%253A11%253A44Z&ToAddress%3D1%2540test.com&Version%3D2015-11-23

Suppose the AccessKeyId is testid, the AccessKeySecret is testsecret,and the Key used for HMAC calculation is testsecret&, then the calculated signature value is:

  1. GfZ0mNVEKxqP5v4KCkuhcx8ojv8%3D

The BODY content of the signed POST request from https://dm.aliyuncs.com/ .

Note: the Signature parameter added and the change in the request header Content-Type: application/x-www-form-urlencoded.

  1. Signature=GfZ0mNVEKxqP5v4KCkuhcx8ojv8%3D&Format=XML&Subject=3&HtmlBody=4&SignatureMethod=Hmac-SHA1&Timestamp=2015-11-24T05%3A06%3A00Z&TagName=2&Action=SingleSendMail&AccessKeyId=testid&AccountName=1&ReplyToAddress=true&AddressType=1&SignatureNonce=e1b44502-6d13-4433-9493-69eeb068e955&SignatureVersion=1.0&Version=2015-11-23&ToAddress=1%40test.com
Thank you! We've received your feedback.