Signature mechanism

System headers

• Required: `X-Ca-Key`. The AppKey.
• Required: `X-Ca-Signature`. The signature string.
• Optional: `X-Ca-Timestamp`. The timestamp sent by the API caller. The value is the number of milliseconds that have elapsed since January 1, 1970. The timestamp is valid for 15 minutes.
• Optional: `X-Ca-Nonce`. A universally unique identifier (UUID) generated by the API caller. This identifier is used with the timestamp to prevent replay attacks.
• Optional: `X-Ca-Stage`. The environment stage of the API to be called. The supported stages are TEST, PRE, and RELEASE. The default value is RELEASE. If you call an API in a non-production environment, you must specify this parameter. Otherwise, a URL error is returned.

Signature verification

1. Build the string to sign.

   String stringToSign= 
   HTTPMethod + "\n" + 
   Accept + "\n" + // Explicitly set the Accept header. If the Accept header is empty, some HTTP clients set a default value of */*, which causes signature verification to fail.
   Content-MD5 + "\n" 
   Content-Type + "\n" + 
   Date + "\n" + 
   Headers + 
   Url

   The HTTPMethod parameter must be in uppercase, such as POST. If the Accept, Content-MD5, Content-Type, or Date parameter is empty, you must still add a line feed \n. However, if the Headers parameter is empty, you do not need to add a line feed \n.

   • Content-MD5

     Content-MD5 is the MD5 hash of the body. The MD5 hash is calculated only when the body is not a form. The calculation method is as follows.

     String content-MD5 = Base64.encodeBase64(MD5(bodyStream.getBytes("UTF-8"))); // bodyStream is a byte array.

   • Headers

     The Headers string consists of the keys and values of the headers that are used in the signature calculation. Signatures are calculated for all headers that start with X-Ca and for all custom headers.

     Note The following parameters are not used in the signature calculation for headers: X-Ca-Signature, X-Ca-Signature-Headers, Accept, Content-MD5, Content-Type, and Date.

     Organize the headers as follows.

     Sort the keys of the headers that are used in the signature calculation in alphabetical order. If the value of a header is empty, use HeaderKey + ":" + "\n" for the signature string. The key and the colon must be retained. The following example shows the required format.

     String headers =
     HeaderKey1 + ":" + HeaderValue1 + "\n"\+
     HeaderKey2 + ":" + HeaderValue2 + "\n"\+
     ...
     HeaderKeyN + ":" + HeaderValueN + "\n"

     You must also concatenate the keys of all headers included in the signature, separated by colons (for example, Key1:Key2:Key3), and add the X-Ca-Signature-Headers : Key1:Key2:Key3 header to the HTTP request.

   • URL

     The URL string consists of the path, query parameters, and form parameters from the request body. Organize the URL as follows.

     Sort the keys of the query and form parameters in alphabetical order and concatenate them. If no query or form parameters exist, the URL string consists of only the path. If a parameter has an empty value, include only its key in the string and omit the equal sign (=).

     String url =
     Path +
     "?" +
     Key1 + "=" + Value1 +
     "&" + Key2 + "=" + Value2 +
     ...
     "&" + KeyN + "=" + ValueN                    

2. Calculate the signature.

   Mac hmacSha256 = Mac.getInstance("HmacSHA256");
   byte[] keyBytes = secret.getBytes("UTF-8");  // For client calls, this is the AppSecret of the app. For cloud API calls, this is the AppSecret for cloud-to-cloud integration.
   hmacSha256.init(new SecretKeySpec(keyBytes, 0, keyBytes.length, "HmacSHA256"));
   String sign = new String(Base64.encodeBase64(hmacSha256.doFinal(stringToSign.getBytes("UTF-8")),"UTF-8"));

3. Include the signature in the request.
   Add the calculated signature to the request header. The Key is X-Ca-Signature.
4. Troubleshoot signature errors.
   If signature verification fails, API Gateway returns the server-side `StringToSign` in the `X-Ca-Error-Message` header of the HTTP response. To troubleshoot the issue, compare the `StringToSign` that you calculated on the client with the `StringToSign` returned by the server.

   If the server-side and client-side `StringToSign` values match, check whether the key used for the signature calculation is correct. The `StringToSign` returned in the `X-Ca-Error-Message` header has line feed characters removed because they are not permitted in HTTP headers. Therefore, when you compare the strings, you must also ignore the line feed characters in the string that you generated on the client.

5. Signature demo.
   For a detailed Java demo of the signature calculation, see api-gateway-demo-sign-java.