Request signature description

Last Updated: Sep 19, 2017

Domain name

  • Each API belongs to an API group, and each API group has a unique domain name. These independent domain names are bound by the service provider. API Gateway uses a domain name to locate an API group.
  • The domain name is in the format of “www.[Independent domain name].com/[Path]?[HTTPMethod].” At the public beta stage, the API user needs to obtain this domain name offline from the API service provider.
  • Alibaba Cloud API Gateway uses the domain name to locate a unique API group, and then locate the unique API through Path+HTTPMethod.
  • You need to obtain API documentation in the deprecation environment from the API service provider. This documentation must include necessary parameter information, such as the domain name and path.

System headers

  • [Required] X-Ca-Key: AppKey
  • [Required] X-Ca-Signature: Signature string
  • [Optional] X-Ca-Timestamp: The time stamp in milliseconds passed by the API caller, that is, the milliseconds of the time from January 1, 1970 until now. By default, it is valid within 15 minutes.
  • [Optional] X-Ca-Nonce: The UUID generated by the API caller. This header is used with the time stamp to prevent replay.
  • [Optional] Content-MD5: When the request body is not a Form, calculate the MD5 value of the body and send that value to the cloud gateway for checking.
  • [Optional] X-Ca-Stage: The stage where the requested API belongs. Only test and release are supported, and the default value is release.

Signature verification

For details about the demo (Java) of signature calculation, refer to here.

The signature calculation procedure is as follows:

Organize the strings involved in signature calculation

  1. String stringToSign=
  2. HTTPMethod + "\n" +
  3. Accept + "\n" +
  4. Content-MD5 + "\n"
  5. Content-Type + "\n" +
  6. Date + "\n" +
  7. Headers +
  8. Url

Each letter of the HTTPMethod value should be capitalized.

If “Accept”, “Content-MD5”, “Content-Type”, and “Date” are empty, add a linefeed “\n.” If “Headers” is empty, “\n” is not required. The specified “Headers” includes “\n.” For details, refer to the headers organization method described below.

Content-MD5

Content-MD5 indicates the MD5 value of the body. MD5 is only calculated when the body is not a Form. The calculation method is as follows:

  1. String content-MD5 = Base64.encodeBase64(MD5(bodyStream.getbytes("UTF-8")));

The “bodyStream” indicates the byte array.

Headers

Headers indicates the keys and values of the headers involved in signature calculation. Note that X-Ca-Signature and X-Ca-Signature-Headers are excluded in Headers signature calculation.

Headers organization method:

Rank the keys of all Headers involved in signature calculation in lexicographic order and then splice them in the following method:

  1. String headers =
  2. HeaderKey1 + ":" + HeaderValue1 + "\n"\+
  3. HeaderKey2 + ":" + HeaderValue2 + "\n"\+
  4. ...
  5. HeaderKeyN + ":" + HeaderValueN + "\n"
URL

URL indicates the Form parameter in the Path+Query+Body. The organization method is as follows:

Rank the keys of Query+Form in lexicographic order and then splice them in the following method. If Query or Form is empty, then URL is equal to Path, and “?” does not need to be added.

  1. String url =
  2. Path +
  3. "?" +
  4. Key1 + "=" + Value1 +
  5. "&" + Key2 + "=" + Value2 +
  6. ...
  7. "&" + KeyN + "=" + ValueN

Note that Query or Form may have multiple values. If there are multiple values, use the first value for signature calculation.

Calculate the signature

  1. Mac hmacSha256 = Mac.getInstance("HmacSHA256");
  2. byte[] keyBytes = secret.getBytes("UTF-8");
  3. hmacSha256.init(new SecretKeySpec(keyBytes, 0, keyBytes.length, "HmacSHA256"));
  4. String sign = new String(Base64.encodeBase64(hmacSha256.doFinal(stringToSign.getBytes("UTF-8")),"UTF-8"));

The “secret” indicates the key corresponding to an app.

Pass the signature

Put the calculated signature in the Header of the Request. The key is X-Ca-Signature.

Separate the keys of all Headers involved in signature calculation by commas and put them in the Header of the Request regardless of the order. The key is X-Ca-Signature-Headers.

For details about the demo of signature calculation, refer to here.

Thank you! We've received your feedback.