API網關提供前端簽名及驗簽能力，前端簽名及驗簽主要兩點用途：

• 驗證客戶端請求的合法性，確認請求中攜帶授權后的AK生成的簽名；

• 防止請求數據在網絡傳輸過程中被篡改。

API的擁有者可以在API網關控制臺的應用管理頁面生成APP，每個APP會攜帶一對簽名密鑰（APP Key和APP Secret）,API擁有者將API授權給指定的APP（APP可以是API擁有者頒發或者API調用者所有）后，API調用者就可以用APP的簽名密鑰來調用相關的API了。

客戶端調用 API 時，需要使用已授權簽名密鑰對請求內容的關鍵數據進行加密簽名計算，并且將APP Key和加密后生成的字符串放在請求的 Header 傳輸給API網關，API網關會讀取請求中的APP Key的頭信息，并且根據APP Key的值查詢到對應的APP Secret的值，使用APP Secret對收到的請求中的關鍵數據進行簽名計算，并且使用自己的生成的簽名和客戶端傳上來的簽名進行比對，來驗證簽名的正確性。只有簽名驗證通過的請求才會發送給后端服務，否則API網關會認為該請求為非法請求，直接返回錯誤應答。

API網關只會驗證安全認證類型為“阿里云APP”類型的API請求的簽名，其他安全類型的API請求不會驗證簽名。

3.1簽名生成流程和認證流程概述

3.1.1 前置條件

API的調用方需要在調用API之前獲取到已經授權給對應API的簽名密鑰對：

• APP Key

• APP Secret

被調用的API的安全認證類型為“阿里云APP”。

3.1.2 客戶端生成簽名

客戶端生成簽名一共分三步處理：

1. 從原始請求中提取關鍵數據，得到一個用來簽名的簽名串；

2. 使用加密算法加APP Secret對關鍵數據簽名串進行加密處理，得到簽名；

3. 將簽名所相關的所有頭加入到原始HTTP請求中，得到最終HTTP請求。

3.1.3 服務器端驗證簽名

服務器驗證客戶端簽名一共分四步處理：

1. 從接收到的請求中提取關鍵數據，得到一個用來簽名的簽名串；

2. 從接收到的請求中讀取APP Key，通過APP Key查詢到對應的APP Secret；

3. 使用加密算法和APP Secret對關鍵數據簽名串進行加密處理，得到簽名；

4. 從接收到的請求中讀取客戶端簽名，對比服務器端簽名和客戶端簽名的一致性。

3.2 生成與傳遞簽名

3.2.1 提取簽名串

客戶端需要從HTTP請求中提取出關鍵數據，組合成一個簽名串，生成的簽名串的格式如下：

HTTPMethod
Accept
Content-MD5
Content-Type
Date
Headers
PathAndParameters

以上7個字段構成整個簽名串，字段之間使用\n間隔，如果Headers為空，則不需要加\n，其他字段如果為空都需要保留\n。簽名大小寫敏感。下面介紹下每個字段的提取規則：

• HTTPMethod：HTTP的方法，全部大寫，比如POST

• Accept：請求中的Accept頭的值，可為空。建議顯式設置 Accept Header。當 Accept 為空時，部分 HTTP 客戶端會給 Accept 設置默認值為 */*，導致簽名校驗失敗。

• Content-MD5：請求中的Content-MD5頭的值，可為空。只有在請求存在Body且Body為非Form形式時才計算Content-MD5頭，下面是Java的Content-MD5值的參考計算方式：

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

• Content-Type：請求中的Content-Type頭的值，可為空

• Date：請求中的Date頭的值，可為空

• Headers：用戶可以選取指定的header參與簽名，關于header的簽名串拼接方式有以下規則：

  • 參與簽名計算的Header的Key按照字典排序后使用如下方式拼接

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

  • 某個Header的Value為空，則使用HeaderKey+":"+"\n"參與簽名，需要保留Key和英文冒號。

  • 所有參與簽名的Header的Key的集合使用英文逗號分割放到Key為X-Ca-Signature-Headers的Header中；

  • 以下Header不參與Header簽名計算：X-Ca-Signature、X-Ca-Signature-Headers、Accept、Content-MD5、Content-Type、Date。

• PathAndParameters這個字段包含Path，Query和Form中的所有參數，具體組織形式如下：

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

  • Query和Form參數對的Key按照字典排序后使用上面的方式拼接；

  • Query和Form參數為空時，則直接使用Path，不需要添加？；

  • 參數的Value為空時只保留Key參與簽名，等號不需要再加入簽名；

  • Query和Form存在數組參數時（key相同，value不同的參數） ，取第一個Value參與簽名計算。

下面我們看一個例子，這里有一個普通的HTTP請求：

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

生成的正確簽名串為：

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

3.2.2 計算簽名

客戶端從HTTP請求中提取出關鍵數據組裝成簽名串后，需要對簽名串進行加密及編碼處理，形成最終的簽名，目前API網關支持以下兩種加密算法：

• HmacSHA256

• HmacSHA1

具體的加密形式如下，其中stringToSign是提取出來的簽名串，secret是APP Secret：

Mac hmacSha256 = Mac.getInstance("HmacSHA256");
byte[] appSecretBytes = appSecret.getBytes(Charset.forName("UTF-8"));
hmacSha256.init(new SecretKeySpec(appSecretBytes, 0, appSecretBytes.length, "HmacSHA256"));
byte[] md5Result = hmacSha256.doFinal(stringToSign.getBytes(Charset.forName("UTF-8")));
String signature = Base64.encodeBase64String(md5Result);

Mac hmacSha1 = Mac.getInstance("HmacSHA1");
byte[] appSecretBytes = appSecret.getBytes(Charset.forName("UTF-8"));
hmacSha1.init(new SecretKeySpec(appSecretBytes, 0, appSecretBytes.length, "HmacSHA1"));
byte[] md5Result = hmacSha1.doFinal(stringToSign.getBytes(Charset.forName("UTF-8")));
String signature = Base64.encodeBase64String(md5Result);

抽象一下就是將串（StringToSign）使用UTF-8解碼后得到Byte數組，然后使用加密算法對Byte數組進行加密，然后使用Base64算法進行編碼，形成最終的簽名。

3.2.3 傳輸簽名

客戶端需要將以下四個Header放在HTTP請求中傳輸給API網關，進行簽名校驗：

• x-ca-key：取值APP Key，必選；

• x-ca-signature-method：簽名算法，取值HmacSHA256或者HmacSHA1，可選，默認值為HmacSHA256；

• X-Ca-Signature-Headers：所有簽名頭的Key的集合，使用英文逗號分隔，可選；

• X-Ca-Signature：簽名，必選；

下面是攜帶簽名的整個HTTP請求的示例：

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

3.3 簽名排錯方法

API網關簽名校驗失敗時，會將服務端的簽名串（StringToSign）放到HTTP Response的Header中返回到客戶端，Key為：X-Ca-Error-Message，用戶只需要將本地計算的簽名串（StringToSign）與服務端返回的簽名串進行對比即可找到問題；

如果服務端與客戶端的StringToSign一致請檢查用于簽名計算的APP Secret是否正確；

因為HTTP Header中無法表示換行，因此StringToSign中的換行符都被替換成#。

errorMessage:  Invalid Signature, Server StringToSign:`GET#application/json##application/json##X-Ca-Key:200000#X-Ca-Timestamp:1589458000000#/app/v1/config/keys?keys=TEST`

說明服務器的簽名是：

GET
application/json
application/json
X-Ca-Key:200000
X-Ca-Timestamp:1589458000000
/app/v1/config/keys?keys=TEST