REST API簽名認證機制

為保證API的安全呼叫，在呼叫API時公交雲會對每個API請求通過簽名進行身份驗證。即無論使用HTTP還是HTTPS協議提交請求，都需要在請求中包含簽名（Signature）資訊。

一、概述

REST API需要按如下格式在API請求的Header中新增Authorization頭來簽名：

Authorization:ptcs AccessKeyId:Singature

其中：

ptcs：Public Transport Cloud Service的縮寫，固定標識不可修改。

AccessKeyId：使用者呼叫API所用的金鑰ID。金鑰ID和其對應的AccessSecret由服務端分配給客戶端。

Signature：使用AccessKey Secret對請求進行對稱加密的簽名。

二、計算簽名

按照RFC2104的定義，使用AccessSecret對編碼、排序後的整個請求串計算HMAC值作為簽名。

Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(

StringToSign) ) )

簽名演算法遵循RFC2104 HMAC-SHA1規範，簽名的元素是請求自身的引數，由於每個API請求內容不同，所以簽名的結果也不盡相同。

1. 構建待簽名字串

待簽名字串（StringToSign）是API請求拼裝的字串，用於計算簽名，包含：

HTTP協議Header

公交雲協議Header (CanonicalizedHeaders)

規範資源（CanonicalizedResource）

Body

待簽名字串必須按照以下順序構造：

StringToSign =

//http協議Header

        HTTP-Verb + "\n" +

        Accept + "\n" +

Content-MD5 + "\n" +//Body的MD5值放在此處

        Content-Type + "\n" +

        Date + "\n" +

       //公交雲協議header(CanonicalizedHeaders)

        CanonicalizedHeaders +

//簽名中如何包含CanonicalizedResource（規範資源）

        CanonicalizedResource

示例：原始請求

1. POST /stacks?name=test_alert&status=COMPLETE HTTP/1.1

2. Host: ***.ptcs.com

3. Accept: application/json

4. Content-MD5: ChDfdfwC+Tn874znq7Dw7Q==

5. Content-Type: application/x-www-form-urlencoded;charset=utf-8

6. Date: Fri Oct 12 10:00:00 GMT+08:00 2018

7. x-ptcs-signature-nonce: 550e8400-e29b-41d4-a716-446655440000

8. x-ptcs-signature-method: HMAC-SHA1

9. x-ptcs-signature-version: 1.0

10. x-ptcs-version: v1

示例：規範請求

1. POST

2. application/json

3. ChDfdfwC+Tn874znq7Dw7Q==

4. application/x-www-form-urlencoded;charset=utf-8

5. Fri Oct 12 10:00:00 GMT+08:00 2018

6. x-ptcs-signature-nonce: 550e8400-e29b-41d4-a716-446655440000

7. x-ptcs-signature-method:HMAC-SHA1

8. x-ptcs-signature-version:1.0

9. x-ptcs-version:v1

10. /stacks?name=test_alert&status=COMPLETE

HTTP協議Header

計算簽名必須包含引數：Accept、Content-MD5、Content-Type、Date的值（不包含key），並按字典順序排列；若值不存在則以“\n”補齊。

示例：原始header

Accept: application/json

Content-MD5: ChDfdfwC+Tn874znq7Dw7Q==

Content-Type: application/x-www-form-urlencoded;charset=utf-8

Date: Fri Oct 12 10:00:00 GMT+08:00 2018

示例：規範header

application/json

ChDfdfwC+Tn874znq7Dw7Q==

application/x-www-form-urlencoded;charset=utf-8

Fri Oct 12 10:00:00 GMT+08:00 2018

公交雲協議Header (CanonicalizedHeaders)

公交雲規範頭，非標準HTTP頭部資訊，是請求中出現的以x-ptcs-為字首的引數。請求中必須包含：

將所有的頭和內容用“\n”分隔符分隔拼成最後的CanonicalizedHeaders。

示例:原始Header

x-ptcs-signature-nonce: 550e8400-e29b-41d4-a716-446655440000

x-ptcs-signature-method: HMAC-SHA1

x-ptcs-signature-version: 1.0

x-ptcs-version: v1

示例：規範header（只取協議Header頭的value）

550e8400-e29b-41d4-a716-446655440000

HMAC-SHA1

1.0

v1

規範資源（CanonicalizedResource）

CanonicalizedResource表示想要訪問資源的規範描述，需要將子資源和query引數一同按照字典序，從小到大排列並以“&”為分隔符生成子資源字串(?後的所有引數）。

示例：原始請求

/stacks?status=COMPLETE&name=test_alert

示例：規範請求（只取問號後面的請求引數）

name=test_alert&status=COMPLETE

Body

將請求的body用MD5演算法加密，在進行base64編碼，將結果新增到Content-MD5中。如果body內容為空，則Content-MD5的值也為空。

2. 將簽名放入請求

將計算好的簽名以如下格式新增到請求的Header中：

Authorization: ptcs AccessKeyId:Signature

三、防止重放攻擊

Date：發起請求的時間，可以取自機器的本地實現。當服務端收到請求時，會校驗這個引數的有效性，誤差不超過15分鐘。

x-ptcs-signature-nonce：這個是請求的唯一標識，一般使用UUID來標識。服務端收到這個引數後會校驗這個引數的有效性，同樣的值，15分內只能被使用一次。

四、舉例

簽名原始字串：

POST

application/json

ChDfdfwC+Tn874znq7Dw7Q==

application/json

Fri Oct 12 10:00:00 GMT+08:00 2018

BK70J6ChwnGCyq9r

HMAC-SHA1

1.0

v1

cityCode=330100&planId=50690

訊息頭內容，以postman為例：