為保證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格式的字節流>