Backend Signature Demo

Last Updated: Mar 28, 2017

API Gateway provides the backend HTTP service signature verification function. To enable backend signature, you need to create a signature key and bind the key to the corresponding API. ( keep this key properly. API Gateway encrypts and stores the key to ensure the security of the key.) After backend signature is enabled, API Gateway will add 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 will be 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 details about the demo (Java) of signature calculation, refer to https://github.com/aliyun/api-gateway-demo-sign-backend-java.

The signature calculation procedure is as follows:

Organize Data Involved in Signature Adding

  1. String stringToSign=
  2. HTTPMethod + "\n" + // All letters in the HTTPMethod should 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 details, refer to the headers organization method described below.
  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.

Description

Content-MD5

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

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

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

Debug 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 just 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.

Thank you! We've received your feedback.