All Products
Document Center

Backend Signature Demo

Last Updated: Dec 01, 2017

API Gateway provides the backend HTTP service signature verification function. To enable backend signature, you must create a signature key and bind the key to the corresponding API. ( keep this key properly. API Gateway encrypts and stores the key to guarantee the security of the key.) After backend signature is enabled, API Gateway adds signature information to the request destined to the backend HTTP service. The backend HTTP service reads the signature string of API Gateway and performs local signature calculation on the received request to check whether the gateway signature and local signature result are consistent.

All the parameters you have defined are added to the signature, including the service parameters you have entered, and constant system parameters and API Gateway system parameters (such as CaClientIp) you have defined.

How to read the API Gateway signature

  • Save the signature calculated by the gateway in the header of the request. The Header name is X-Ca-Signature.

How to add a signature at the backend HTTP service

For more information about the demo (Java) of signature calculation, see

The signature calculation procedure is as follows:

Organize data involved in signature adding

  1. String stringToSign=
  2. HTTPMethod + "\n" + // All letters in the HTTPMethod must be capitalized.
  3. Content-MD5 + "\n" + // Check whether Content-MD5 is empty. If yes, add a linefeed "\n".
  4. Headers + // If Headers is empty, "\n" is not required. The specified Headers includes "\n". For more information, see the headers organization method described as follows.
  5. Url

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(Sha256.doFinal(stringToSign.getBytes("UTF-8")),"UTF-8"));

secret is the signature key bound to an API.



Content-MD5 indicates the MD5 value of the body. MD5 is calculated only when HTTPMethod is PUT or POST and the body is not a form. The calculation method is as follows:

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


Headers indicates the keys and values of the headers involved in signature calculation. Read the keys of all headers involved in signature calculation from the header of the request. The key is X-Ca-Proxy-Signature-Headers. Multiple keys are separated by commas.

Headers organization method

Rank the keys of all headers involved in signature calculation in lexicographic order, and change all uppercase letters in the key of the header to lowercase, and splice the keys in the following method:

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


URL indicates the Form parameter in the Path + Query + Body. The organization method is as follows:If Query or Form is not empty, add a ?, 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.

  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 multiple values exist, use the first value for signature calculation.

Debugging mode

To access and debug the backend signature conveniently, you can enable the Debug mode. The debugging procedure is as follows:

  1. Add X-Ca-Request-Mode = debug to the header of the request destined to API Gateway.

  2. The backend service can only read X-Ca-Proxy-Signature-String-To-Sign from the header because the linefeed is not allowed in the HTTP Header and thereby is replaced with “|”.

NOTE: X-Ca-Proxy-Signature-String-To-Sign is not involved in backend signature calculation.

Verify the time stamp

When the backend verifies the time stamp of the request, the system parameter CaRequestHandleTime is selectable in API definition and its value is the Greenwich mean time when the gateway receives the request.