Microservices Engine:hmac-auth

Overview

To generate a signature, the client performs the following steps:

1. Extracts the key data from the original request and generates a signature string.

2. Uses the encryption algorithm and the configured secret to encrypt the signature string and generates a signature.

3. Adds all headers that are related to the signature to the original HTTP request to obtain the final HTTP request.

Extract a signature string

To generate a signature, the client needs to extract key data from the HTTP request and combine the key data into a signature string. The signature string is 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.aliyun.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 the client extracts the key data from the HTTP request and generates a signature string, the client needs to encrypt and encode the signature string to form the final signature.

In the encryption process, stringToSign specifies the extracted signature string, secret is specified in the plug-in configuration, and sign specifies 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);

In summary, stringToSign is decoded into a byte array by using UTF-8. The byte array is encrypted by using an encryption algorithm and then encoded by using the Base64 algorithm to generate a signature.

Add a signature

The client must include the following headers in the requests sent to API Gateway for signature verification:

• x-ca-key: the AppKey, which is required.

• x-ca-signature-method: the signature algorithm, which is optional. Valid values: HmacSHA256 and HmacSHA1. Default value: HmacSHA256.

• x-ca-signature-headers: the collection of keys for all signature headers, which is optional. The keys are separated by commas (,).

• x-ca-signature: the signature, which is required.

The following example shows an HTTP request with a signature:

POST /http2test/test?param1=test HTTP/1.1
host:api.aliyun.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

Procedure

To verify the signature received from the client, the server performs the following steps:

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

2. Reads the key from the request and uses the key to obtain the secret.

3. Uses an encryption algorithm and the secret to encrypt the signature string to obtain a signature.

4. Reads the client-side signature from the request and compares the server-side signature with the client-side signature.

Troubleshoot signature errors

If signature verification fails, the system adds the server-side signature string (StringToSign) to the header of the HTTP response that is returned to the client. The key is X-Ca-Error-Message. You can identify errors when you compare the client-side signature string (StringToSign) with the server-side signature string.

If the two values are the same, check the AppSecret that is used for signature calculation.

HTTP headers do not support line breaks. Line breaks in the signature string (StringToSign) are replaced with number signs (#).

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`