edit-icon download-icon

Sign RPC APIs

Last Updated: Nov 08, 2018

To ensure the security of your API, you must sign the API request. Alibaba Cloud uses the signature in the request to verify the identity of the person who calls the API.

Alibaba Cloud provides multiple SDKs and third-party SDKs to make the manual signature process more efficient. Click here to know more about Alibaba Cloud SDKs.

Signature overview

For RPC APIs, you must add the calculated signature to the request query in the following format:

  1. https://endpoint/?SignatureVersion=1.0&SignatureMethod=HMAC-SHA1&Signature=VyBL52idtt+oImX0NZC+2ngk15Q%3D&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf

where:

  • AccessKeyId: The AccessKey ID of the user who calls the API.

  • SignatureMethod: The hash method used to calculate the signature. HMAC-SHA1 is supported.

  • SignatureVersion: The version of the signature. The current version is 1.0.

  • SignatureNonce: A random number of the signature used to prevent network attacks. You must use different random numbers for different requests. We recommend using a Universally Unique Identifier (UUID).

  • Signature: The signature generated by performing symmetric encryption on the request by using the AccessKey Secret.

Calculate signatures

Calculate the HMAC value of the encoded and formatted string according to RFC 2104. The calculated HMAC value is the signature.

  1. Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(
  2. StringToSign) ) )

The signature algorithm follows the RFC 2014 HMAC-SHA1 specification. Different APIs contain different parameters, which results in different HMAC signatures.

1. Construct the string to sign

Follow these steps to construct the string to sign:

  1. Use the request parameters to create a canonicalized query string to sign.

    i. Sort parameters.

    Sort the parameter names in the lexicographical order, including the common required parameters and the API specific parameters but not including the Signature PARAMETER.

    Note: When using the GET method to call an API, the parameters to sort are any parameters after the question mark (?) that are connected by the ampersands (&).

    ii. Encode parameters.

    Use UTF-8 to URL-encode the parameter names and values according to the following rules:

    • Do not URL-encode the following characters: A-Z, a-z, 0-9, hyphen (-), underscore (_), period (.), and tilde (~).

    • Encode other characters to %XY. XY is the hexadecimal representation of characters corresponding to the ASCII code. For example, the double quotation marks (“”) must be encoded as %22.

    • Encode the extended UTF-8 characters in the form of %XY%ZA….

    • Encode space as %20.

      This encoding method is different from the common application/x-www-form-urlencoded MIME encoding such as the implementation of java.net.URLEncoder. However, you can use the java.net.URLEncoder method to encode the parameters, and then replace the plus sign (+) with %20, replace the asterisk (*) with %2A, replace %7E with the tilde (~) in the encoded string. The final result is the same. This algorithm can be achieved by the percentEncode function as follows:

      1. private static final String ENCODING = "UTF-8";
      2. private static String percentEncode(String value) throws UnsupportedEncodingException {
      3. return value != null ? URLEncoder.encode(value, ENCODING).replace("+", "%20").replace("*", "%2A").replace("%7E", "~") : null;
      4. }

      iii. Use the equals sign (=) to append the encoded parameter values to the corresponding encoded parameters.

      iv. Append the ampersand (&) after each parameter value according to the order in the step i.

  2. Follow these rules to construct the canonicalized query string to sign:

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

    where:

    • HTTPMethod is the used HTTP method. For example: Get.
    • percentEncode("/") is the encoded value for a forward slash (/), that is, %2F.
    • percentEncode(CanonicalizedQueryString) is the string that is encoded in the way as described in 1.2.

2. Calculate the signature

  1. Calculate the HMAC value of the string to sign according to RFC 2104.

    Note: The key used for calculation is the AccessKey Secret appended with an ampersand (&). The hash algorithm used is SHA1.

  2. Encode the HMAC value as according to the base-64 encoding.

  3. Add the signature to the request parameters as the Signature parameter.

    Note: When submitting the signature as the final request parameter, you must also encode it according to RFC 3986.

Example

The following shows the signing process of the DescribeRegions API. The AccessKey ID is testid, and the AccessKey Secret is testsecret.

The original request URL is as follows:

  1. http://ecs.aliyuncs.com/?Timestamp=2016-02-23T12:46:24Z&Format=XML&AccessKeyId=testid&Action=DescribeRegions&SignatureMethod=HMAC-SHA1&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&Version=2014-05-26&SignatureVersion=1.0
  1. The following is the calculated string to sign:

    1. GET&%2F&AccessKeyId%3Dtestid%26Action%3DDescribeRegions%26Format%3DXML%26SignatureMethod%3DHMAC-SHA1%26SignatureNonce%3D3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf%26SignatureVersion%3D1.0%26Timestamp%3D2016-02-23T12%253A46%253A24Z%26Version%3D2014-05-26
  2. The following signature is the calculated HMAC value using the AccessKey Secret:

    Note: Append an ampersand (&) to the AccessKey Secret when calculating the signature.

    OLeaidS1JvxuMvnyHOwuJ+uX5qY=

  3. The following is the signed URL:

    1. http://ecs.aliyuncs.com/?SignatureVersion=1.0&Action=DescribeRegions&Format=XML&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&Version=2014-05-26&AccessKeyId=testid&Signature=OLeaidS1JvxuMvnyHOwuJ+uX5qY=&SignatureMethod=HMAC-SHA1&Timestamp=2016-02-23T12%3A46%3A24Z
Thank you! We've received your feedback.