Signature mechanism

Last Updated: Jul 03, 2017

The RAM service will perform identity authentication on each access request. Therefore, whether submitted through HTTP or HTTPS, a request must contain signature information. RAM uses Access Key ID and Access Key Secret symmetric encryption to verify the identity of request senders. The Access Key ID and Access Key Secret are officially issued to visitors by Alibaba Cloud (visitors can apply for and manage them on the official Alibaba Cloud website). The Access Key ID indicates the identity of the visitor. The Access Key Secret is the secret key used to encrypt the signature string and to verify the signature string on the server. It must be kept strictly confidential and should only be known to Alibaba Cloud and authenticated visitors.

Request signing process

  1. Use request parameters to construct a canonicalized query string.

    a) Sort all request parameters (including “public request parameters” and user-defined parameters for the given request interfaces described in this document, excluding the Signature parameter mentioned in “public request parameters”) alphabetically by the parameter name.

    Note: If you use the “GET” method to submit requests, these parameters are included in the request URI (namely, the part after the question mark “?” follows the ampersand “&” in the URI).

    b) Encode the name and value of each request parameter. URL encoding using the UTF-8 character set is required. URL encoding rules are as follows:

    • Upper case letters from A to Z, lowercase letters from a to z, integers from 0 to 9, and other characters including the en dashes “-“, underlines “_”, periods”.”, and tildes “~” are not encoded.
    • Other characters are encoded in “%XY” format, with XY representing the characters’ ASCII code in hexadecimal notation. For example, double quotation marks (“) are encoded as “%22”.
    • It must be noted that the space ( ) is encoded as “%20”, rather than the plus sign “+”.

    Note: Generally, URL-encoded libraries (such as “java.net.URLEncoder” in Java) are encoded based on rules of the MIME type in the “application/x-www-form-urlencoded” format. You can use this encoding method directly by replacing the plus sign “+” in the encoded string with “%20”, the asterisk “*” with “%2A”, and change “%7E” back to the tilde “~” to conform to the encoding rules described above.

    c) Connect the encoded parameter names and values with the equal sign “=”.

    d) 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 use the canonicalized query string to construct the string for signature calculation:

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

    Where,

    • HTTPMethod is the HTTP method (such as “GET”) used for request submission.
    • percentEncode("/") is the encoded value (namely, “%2F”) for the character “/“ according to the URL encoding rules described in 1.b.
    • percentEncode(CanonicalizedQueryString) is the canonicalized query string encoded by following the URL encoding rules described in 1.b.
  3. Use the string for signature calculation to calculate the HMAC value of the signature based on RFC2104.

    Note: The key used for signature calculation is your access key secret adding the ampersand “&” (ASCII:38) and it is based on hash algorithm SHA1.

  4. Encode the HMAC value into a string based on Base64 encoding rules to obtain the signature value.

  5. Add the obtained signature value to request parameters as the “Signature” parameter to complete the request signing process.

    Note: The obtained signature value requires URL encoding based on the RFC3986 rule like other parameters before it is submitted to the RAM server as the final request parameter value.

Example

Take CreateUser as an example, the request URL before signature is:

  1. https://ram.aliyuncs.com/
  2. ?UserName=test
  3. &SignatureVersion=1.0
  4. &Format=JSON
  5. &Timestamp=2015-08-18T03%3A15%3A45Z
  6. &AccessKeyId=testid
  7. &SignatureMethod=HMAC-SHA1&Version=2015-05-01
  8. &Action=CreateUser
  9. &SignatureNonce=6a6e0ca6-4557-11e5-86a2-b8e8563dc8d2

The corresponding “StringToSign” is:

  1. GET
  2. &%2F
  3. &AccessKeyId%3Dtestid
  4. &Action%3DCreateUser
  5. &Format%3DJSON
  6. &SignatureMethod%3DHMAC-SHA1
  7. &SignatureNonce%3D6a6e0ca6-4557-11e5-86a2-b8e8563dc8d2
  8. &SignatureVersion%3D1.0
  9. &Timestamp%3D2015-08-18T03%253A15%253A45Z
  10. &UserName%3Dtest
  11. &Version%3D2015-05-01

Assume that the “Access Key ID” parameter value is “testid”, the “Access Key Secret” parameter value is “testsecret”, the key used for HMAC calculation will be “testsecret&” and the calculated signature value will be:

  1. kRA2cnpJVacIhDMzXnoNZG9tDCI%3D

The signed request URL is (with the “Signature” parameter added):

  1. https://ram.aliyuncs.com/
  2. ?UserName=test
  3. &SignatureVersion=1.0
  4. &Format=JSON
  5. &Timestamp=2015-08-18T03%3A15%3A45Z
  6. &AccessKeyId=testid
  7. &SignatureMethod=HMAC-SHA1&Version=2015-05-01
  8. &Signature=kRA2cnpJVacIhDMzXnoNZG9tDCI%3D
  9. &Action=CreateUser
  10. &SignatureNonce=6a6e0ca6-4557-11e5-86a2-b8e8563dc8d2
Thank you! We've received your feedback.