Signature mechanism

Last Updated: Dec 11, 2017

The DNS service performs authentication on each access request. Therefore, whether sent through HTTP or HTTPS, each request must contain signature information. DNS uses AccessKey ID and AccessKey Secret symmetric encryption to verify the identity of request senders.

The AccessKey ID and AccessKey Secret are officially issued to visitors by Alibaba Cloud (visitors can apply for and manage them at Alibaba Cloud’s official website). The AccessKey ID indicates the identity of the visitor. The AccessKey Secret is the secret key used to encrypt and verify the signature string on the server, and it must be kept strictly confidential and only be known to Alibaba Cloud and the user.

Method

When a user calls an API, the following method is used to sign the request:

  • The Canonicalized Query String is constructed by using the request parameters.

    • The request parameters are sorted alphabetically by parameter names. These parameters include public request parameters and custom parameters for the given request interfaces described in this document, but not the signature parameter mentioned in “Public request parameters”.

      Note:

      • The sorting method is strictly case sensitive.
      • When a request is submitted by using the GET method, these parameters are included in the parameter section of the request URI. For example, the section in the URI following “?” and connected by “&”.
    • The name and value of each request parameter are encoded. The names and values must be URL encoded by using the UTF-8 character set. The URL encoding rules are as follows:

      • The characters A-Z, a-z, 0-9, hyphen (-), underscore (_), period (.), and tilde (~) are not encoded.
      • Other characters are encoded in “%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 “%XY%ZA…” format.
      • The English space is encoded as %20, rather than the plus sign (+).

      Note: Generally, libraries that support URL encoding (for example, java.net.URLEncoder in Java) are all encoded according to the rules for the “application/x-www-form-urlencoded” MIME-type. Specifically, the plus signs (+) are replaced with %20, the asterisks (*) with %2A, and %7E with the tilde (~) to generate coded strings that match the preceding encoding rules.

    • The encoded parameter names and values are connected with the English equal sign (=).

    • The parameter name and value pairs are sorted in alphabetical order and are connected with ampersand (&) to construct the Canonicalized Query String.

  • With the Canonicalized Query String constructed, follow these rules to produce the string for signature calculation:

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

    Here,

    • HTTPMethod is used for request submission. For example, GET.
    • percentEncode("/") is the coded value for the character “/“ (that is, %2F).
    • percentEncode(CanonicalizedQueryString) is the encoded string for the constructed Canonicalized Query String, and is produced by following the URL encoding rules.
  • As defined in RFC2104, the preceding signature sting is used to calculate the signature’s HMAC value.

    Note: The Key used for calculating the signature is the AccessKey Secret held by the user, ending with the “&” character (ASCII: 38) based on the SHA1 hashing.

  • According to Base64 encoding rules, the preceding HMAC value is encoded into a string. This is the signature value.

  • The obtained signature value is added to the request parameters as the “Signature” parameter to sign the request.

Note: When the obtained signature value is submitted to the DNS server as the final request parameter value, the value will be URL encoded like other parameters according to RFC3986 rules.

Example

Take DescribeDomainRecords as an example. The request URL before signing is as follows:

  1. http://dns.aliyuncs.com/
  2. ?TimeStamp=2014-08-15T11%3A10%3A07Z
  3. &Format=xml&AccessKeyId=testid
  4. &Action=DescribeDomainRecords
  5. &SignatureMethod=HMAC-SHA1&DomainName=example.com
  6. &SignatureNonce=1324fd0e-e2bb-4bb1-917c-bd6e437f1710
  7. &SignatureVersion=1.0
  8. &Version=2015-01-09

Thus, the StringToSign is:

  1. GET
  2. &%2F&AccessKeyId%3Dtestid
  3. &Action%3DDescribeDomainRecords
  4. &Format%3Dxml&DomainName%3Dexample.com
  5. &SignatureMethod%3DHMAC-SHA1
  6. &SignatureNonce%3D1324fd0e-e2bb-4bb1-917c-bd6e437f1710
  7. &SignatureVersion%3D1.0
  8. &TimeStamp%3D2014-08-15T11%253A10%253A07Z
  9. &Version%3D2015-01-09

Assuming that the “AccessKey ID” is “testid”, the “AccessKey Secret” is “testsecret”, and the Key used for HMAC calculation is “testsecret&”, then the calculated signature value will be:

  1. SmhZuLUnXmqxSEZ/GqyiwGqmf+M=

The signed request URL is (note the added Signature parameter):

  1. http://dns.aliyuncs.com/?TimeStamp=2014-08-15T11%3A10%3A07Z&Format=xml&AccessKeyId=testid&Action=DescribeDomainRecords&SignatureMethod=HMAC-SHA1&DomainName=example.com&SignatureNonce=1324fd0e-e2bb-4bb1-917c-bd6e437f1710&SignatureVersion=1.0&Version=2015-01-09&Signature=SmhZuLUnXmqxSEZ%2FGqyiwGqmf%2BM%3D

For more information about request signing and submission, see How to call interfaces.

Thank you! We've received your feedback.