API Gateway:Hmac-auth

Process

The client generates a signature by performing these steps:

1. Extract key data from the original request to generate a signature string.

2. Encrypt the signature string with the configured secret to produce the signature.

3. Add all signature-related headers to the original HTTP request.

Extract a signature string

The client extracts key data from the HTTP request and combines it into a signature string in the following format:

HTTPMethod
Accept
Content-MD5
Content-Type
Date
Headers
PathAndParameters

Example of extracting a signature string

Initial HTTP request:

POST /http2test/test?param1=test HTTP/1.1
host:api.alibabacloud.com
accept:application/json; charset=utf-8
ca_version:1
content-type:application/x-www-form-urlencoded; charset=utf-8
x-ca-timestamp:1525872629832
date:Wed, 09 May 2018 13:30:29 GMT+00:00
user-agent:ALIYUN-ANDROID-DEMO
x-ca-nonce:c9f15cbf-f4ac-4a6c-b54d-f51abf4b5b44
content-length:33
username=xiaoming&password=123456789

Generated signature string:

POST
application/json; charset=utf-8
application/x-www-form-urlencoded; charset=utf-8
Wed, 09 May 2018 13:30:29 GMT+00:00
x-ca-key:203753385
x-ca-nonce:c9f15cbf-f4ac-4a6c-b54d-f51abf4b5b44
x-ca-signature-method:HmacSHA256
x-ca-timestamp:1525872629832
/http2test/test?param1=test&password=123456789&username=xiaoming

Calculate a signature

After generating the signature string, the client encrypts and encodes it to produce the final signature.

In this code, stringToSign is the extracted signature string, secret is from the plug-in configuration, and sign is the final signature.

Mac hmacSha256 = Mac.getInstance("HmacSHA256");
byte[] secretBytes = secret.getBytes("UTF-8");
hmacSha256.init(new SecretKeySpec(secretBytes, 0, secretBytes.length, "HmacSHA256"));
byte[] result = hmacSha256.doFinal(stringToSign.getBytes("UTF-8"));
String sign = Base64.encodeBase64String(result);

The stringToSign is decoded into a UTF-8 byte array, encrypted with the HMAC algorithm, and then Base64-encoded to produce the signature.

Add a signature

Include the following headers in requests sent to Cloud-native API Gateway for signature verification:

• x-ca-key: the AppKey. Required.

• x-ca-signature-method: the signature algorithm. Optional. Valid values: HmacSHA256 and HmacSHA1. Default value: HmacSHA256.

• x-ca-signature-headers: all signature header keys, separated by commas (,). Optional.

• x-ca-signature: the signature. Required.

Example HTTP request with a signature:

POST /http2test/test?param1=test HTTP/1.1
host:api.alibabacloud.com
accept:application/json; charset=utf-8
ca_version:1
content-type:application/x-www-form-urlencoded; charset=utf-8
x-ca-timestamp:1525872629832
date:Wed, 09 May 2018 13:30:29 GMT+00:00
user-agent:ALIYUN-ANDROID-DEMO
x-ca-nonce:c9f15cbf-f4ac-4a6c-b54d-f51abf4b5b44
x-ca-key:203753385
x-ca-signature-method:HmacSHA256
x-ca-signature-headers:x-ca-timestamp,x-ca-key,x-ca-nonce,x-ca-signature-method
x-ca-signature:xfX+bZxY2yl7EB/qdoDy9v/uscw3Nnj1pgoU+Bm6xdM=
content-length:33
username=xiaoming&password=123456789

Process

The server verifies the client signature by performing these steps:

1. Extract key data from the request to obtain a signature string.

2. Read the key from the request and look up the corresponding secret.

3. Encrypt the signature string with the secret to produce a signature.

4. Compare the server-side signature with the client-side signature from the request.

Troubleshoot signature errors

When signature verification fails, the server returns the server-side StringToSign in the X-Ca-Error-Message response header. Compare it with the client-side StringToSign to identify the discrepancy.

If the two values match, verify the AppSecret used for signature calculation.

HTTP headers do not support line breaks, so line breaks in StringToSign are replaced with #.

X-Ca-Error-Message:  Server StringToSign:`GET#application/json##application/json##X-Ca-Key:200000#X-Ca-Timestamp:1589458000000#/app/v1/config/keys?keys=TEST`