全部產品
Search

搜尋本產品

    ：請求籤名

    文件中心

    ：請求籤名

    更新時間：Jul 06, 2024

    為保證API的安全調用，KMS會對每個API請求通過簽名（Signature）進行身分識別驗證。

    安全驗證

    安全驗證基於KMS執行個體的應用存取點Client Key，使用非對稱簽名演算法完成，以便實現以下需求：

    • 確認發起API請求的使用者身份。

      因為在發送請求前需要使用者指定產生數位簽章的應用存取點Client Key，在服務端即可通過該應用存取點Client Key確認使用者身份，以便管理存取權限。

    • 確認API請求在網路傳輸過程中是否被篡改。

      因為服務端會對收到的請求內容進行數位簽章驗證，若請求內容在網路上被篡改，則無法通過數位簽章驗證。

    安全驗證流程如下：

    1. 請求端根據API請求內容（包括HTTP Header和Body）產生簽名字串。
    2. 請求端使用應用存取點Client Key的私密金鑰（PrivateKeyData），對步驟1產生的簽名字串進行簽名，形成該API請求的數位簽章。
    3. 請求端將API請求內容和數位簽章一同發送給服務端。
    4. 服務端在接收到請求後使用Client Key的公開金鑰驗證數位簽章。如果驗證通過則認為該請求通過安全驗證，否則直接拒絕該請求。
      說明 服務端會在後台取得該請求使用的應用存取點Client Key的公開金鑰。

    簽名過程

    為了通過API請求的安全驗證，使用者需要在用戶端對API請求進行簽名（即產生正確的數位簽章），並使用HTTP Authorization頭在網路上傳輸該請求的數位簽章。Authorization頭樣本如下： 
    Authorization = "TOKEN" + " " + Signature

    其中，Signature是使用應用存取點Client Key的私密金鑰（PrivateKeyData）對API請求進行簽名的值。您可以根據以下步驟構造Signature。

    1. 準備KMS執行個體的應用存取點Client Key。
      為API請求產生簽名，需使用應用存取點Client Key的私密金鑰。您可以使用已經存在的Client Key，也可以建立新的Client Key，但需要保證使用的Client Key為啟用狀態。
    2. 產生請求的簽名字串。
      KMS API的簽名字串由HTTP請求中的Method、Header和Body資訊一同產生，具體如下： 
      SignString = HTTP-METHOD + "\n"
             + CONTENT-SHA256 + "\n"
             + CONTENT-TYPE + "\n"
             + DATE + "\n"
             + CanonicalizedKMSHeaders + "\n"
             + CanonicalizedResource
      其中，\n表示換行逸出字元，+表示字串串連操作，其餘部分定義如下：
      名稱說明樣本
      HTTP-METHODHTTP請求的方法名稱。PUT、GET、POST等。
      CONTENT-SHA256HTTP要求標頭的Content-SHA256值。AE71057543002AD513AB88D78509A1214192C09F20302C4BF8F59B7EB565****
      CONTENT-TYPEHTTP請求中Body部分的類型。application/x-protobuf
      DATEHTTP請求中的標準時間戳記頭（遵循RFC 1123格式，使用GMT標準時間）。Mon, 27 Sep 2021 11:47:26 GMT
      CanonicalizedKMSHeaders由HTTP請求中KMS自訂頭構造（以x-kms為首碼）的字串。x-kms-acccesskeyid:KAAP.9c84ad54-d3c5-47c3-b0e7-7c26d509****\nx-kms-apiname:Encrypt\nx-kms-apiversion:dkms-gcs-0.2\nx-kms-signaturemethod:RSA_PKCS1_SHA_256
      CanonicalizedResource固定為/。/
      對於部分無Body的HTTP請求，CONTENT-SHA256和CONTENT-TYPE兩個欄位為空白字串，此時簽名字串的產生方式如下： 
      SignString = HTTP-METHOD + "\n"
             + "\n"
             + "\n"
             + DATE + "\n"
             + CanonicalizedKMSHeaders + "\n"
             + CanonicalizedResource
      KMS API中引入了一個自訂要求標頭x-kms。如果您在請求中指定了該要求標頭，則其值會加入簽名計算。CanonicalizedKMSHeaders的產生方式如下：
      1. 將所有以x-kms為首碼的HTTP要求標頭的名稱轉換成小寫字母。
      2. 將所有自訂要求標頭按照字典順序進行升序排序。
      3. 刪除要求標頭和內容之間分隔字元兩端出現的任何空格。例如： CONTENT-TYPE : application/x-protobuf 轉化為CONTENT-TYPE:application/x-protobuf
      4. 將所有的頭和內容用\n分隔字元組合成最後的CanonicalizedKMSHeaders。
    3. 產生請求的數位簽章。
      API當前只支援一種數位簽章演算法（RSA_PKCS1_SHA_256），簽名公式如下： 
      Signature=Base64(RSA_PKCS1_SHA_256(SignString, AAP_KEY))

      產生數位簽章時，請關注以下內容：

      • 將簽名演算法產生的值使用標準Base64進行編碼。
      • 使用RFC 3447中定義的RSASSA-PKCS1-v1_5方法進行簽名。
      • 在計算出數位簽章後，使用簽名值構建完整的API請求安全驗證頭（Authorization）。
      • 參與簽名計算的字串必須為UTF-8編碼。含有漢字的簽名字串必須先進行UTF-8編碼，再計算最終簽名。
      • CONTENT-SHA256和CONTENT-TYPE在請求中不是必需的，如果CONTENT-SHA256和CONTENT-TYPE為空白時以分行符號\n代替。

    簽名樣本

    為了協助您更好地理解整個請求籤名的流程，我們以Encrypt為例來示範簽名過程。

    假設KMS API簽名的應用存取點Client Key和Encrypt介面的加密參數如下：
    • 應用存取點Client Key
      {
  "KeyId": "KAAP.9c84ad54-d3c5-47c3-b0e7-7c26d509****",
  "PrivateKeyData": "MIIJqwIB****UcQ=="
}
    • Encrypt介面的加密參數
      keyId = "1234abcd-12ab-34cd-56ef-12345678****"
plaintext = "plain text"

    簽名過程樣本如下：

    1. 按照KMS API定義構建如下HTTP請求。
      POST / HTTP/1.1
Date: Mon, 27 Sep 2021 11:47:26 GMT
Host: kst-xxxx.cryptoservice.kms.aliyuncs.com
Accept: application/x-protobuf
Content-SHA256: AE71057543002AD513AB88D78509A1214192C09F20302C4BF8F59B7EB565****
Content-Length: 40
Content-Type: application/x-protobuf
x-kms-acccesskeyid: KAAP.9c84ad54-d3c5-47c3-b0e7-7c26d509****
x-kms-apiversion: dkms-gcs-0.2
x-kms-apiname: Encrypt
x-kms-signaturemethod: RSA_PKCS1_SHA_256

<加密參數序列化成ProtoBuffer格式的位元組流>

      其中，加密參數被序列化成ProtoBuffer格式後作為請求Body。該請求的Content-Type頭的值指定為application/x-protobuf、Content-SHA256頭的值是請求Body經過SHA-256計算後的Hex編碼大寫字串。

    2. 構造待簽名字串。
      POST\nAE71057543002AD513AB88D78509A1214192C09F20302C4BF8F59B7EB56551E2\napplication/x-protobuf\nMon, 27 Sep 2021 11:47:26 GMT\nx-kms-acccesskeyid:KAAP.9c84ad54-xxxx-xxxx-xxxx-7c26d509a55d\nx-kms-apiname:Encrypt\nx-kms-apiversion:dkms-gcs-0.2\nx-kms-signaturemethod:RSA_PKCS1_SHA_256\n/
    3. 使用已有Client Key中私密金鑰（PrivateKeyData）進行簽名運算，得到簽名值並進行Base64編碼。 
      BPwBSB9NkxxuepqJ2zRtLT8jgv0FIAELJI2U79k8OPO7M7Y18Sz6+njTSwYWeIIQpJIJKx+mGBl/aR9opPbfQ+PhH+78rIPLJYNAJRvvaSUW/cRr4BMc1ByRXvuBmIcI81MQGutuU8uLnQYh9AURdklpqcW3ODz5OfsbuuxTGV17COoSO10tW3ltADumaMczFGTM0qCYi/pyh8p8i/gpwC3EXo540n5mqEmLexYIWb5/Fo+VonqZxZ3UuhZPw3vQ8uvqMGqvvw0xxKsblGuEdNSHcy/GYGRTFYugwOojZxd7TpADTqys+7SYaBWT38HnQLcH04DeD5rKkhRK7au8HQ==
    4. 發送包含簽名的HTTP請求內容。
      POST / HTTP/1.1
Date: Mon, 27 Sep 2021 11:47:26 GMT
Host: kst-xxxx.cryptoservice.kms.aliyuncs.com
Accept: application/x-protobuf
Content-SHA256: AE71057543002AD513AB88D78509A1214192C09F20302C4BF8F59B7EB565****
Content-Length: 40
Content-Type: application/x-protobuf
x-kms-acccesskeyid: KAAP.9c84ad54-d3c5-47c3-b0e7-7c26d509****
x-kms-apiversion: dkms-gcs-0.2
x-kms-apiname: Encrypt
x-kms-signaturemethod: RSA_PKCS1_SHA_256
Authorization: TOKEN BPwBSB9NkxxuepqJ2zRtLT8jgv0FIAELJI2U79k8OPO7M7Y18Sz6+njTSwYWeIIQpJIJKx+mGBl/aR9opPbfQ+PhH+78rIPLJYNAJRvvaSUW/cRr4BMc1ByRXvuBmIcI81MQGutuU8uLnQYh9AURdklpqcW3ODz5OfsbuuxTGV17COoSO10tW3ltADumaMczFGTM0qCYi/pyh8p8i/gpwC3EXo540n5mqEmLexYIWb5/Fo+VonqZxZ3UuhZPw3vQ8uvqMGqvvw0xxKsblGuEdNSHcy/GYGRTFYugwOojZxd7TpADTqys+7SYaBWT38HnQLcH04DeD5rKkhRK7au8HQ==

<加密參數序列化成ProtoBuffer格式的位元組流>