共用網關和專屬網關、整合KMS、KMS SDK使用流程、KMS API使用流程、自建應用整合KMS - Key Management Service

KMS 支援通過 SDK 或代理服務 KMS Agent 調用 API，實現密鑰管理、密碼運算以及憑據值擷取等功能，協助自建應用快速整合 KMS 服務。本文將介紹選擇合適網關、鑒權方式和整合方式，以及不同 API 類型的使用方法。

KMS 整合架構概覽

自建應用整合 KMS 需要在以下四個維度進行選擇：

網關類型：共用網關（公網/VPC）或專屬網關（私網）
鑒權方式：RAM 鑒權或應用存取點 AAP 鑒權（不推薦）
整合方式：SDK（阿里雲 SDK、憑據 SDK、執行個體 SDK）或 KMS Agent
API 類型：管控類操作 API、密碼運算 API、擷取憑據 API

KMS 整合概覽圖如下所示：

選型指南

根據業務情境，按以下步驟選擇合適的網關、鑒權和整合方案：

步驟一：確定網路隔離需求

業務部署在阿里雲 VPC 且需要高效能或高安全性：選擇 專屬網關（私網，資料全鏈路加密）。
業務部署在非阿里雲環境或需要管控操作：選擇 共用網關（公網/VPC）。

步驟二：確定 API 能力需求

需要管控操作（建立密鑰、憑據等）：必須使用 共用網關 + 阿里雲 SDK。
需密碼運算：憑據 SDK 或阿里雲 SDK（對應網關類型）。
擷取憑據：憑據 SDK 或 KMS Agent。
跨語言應用需要簡化整合：使用 KMS Agent（僅支援擷取憑據）。

接入網關類型

KMS 提供兩種訪問網關：共用網關和專屬網關。

共用網關：為 KMS 服務的全域網路，可通過公網或 VPC 網路訪問KMS 服務，同時支援管控類操作和業務操作。
專屬網關：為特定 KMS 執行個體的網路，僅支援私網訪問KMS 服務，提供全鏈路 API 安全保障方案，資料安全性更高，只支援業務類操作。

差異點	共用網關	專屬網關
推薦使用情境	業務需要通過 API 操作包括執行個體、密鑰、憑據相關的管控操作，例如建立密鑰、建立憑據、建立 KMS 執行個體等操作。業務部署在非阿里雲 VPC 上。非正式環境訪問 KMS，例如：自我裝載環境。	業務部署在阿里雲 VPC。業務類操作例如加解密、擷取憑據等操作頻繁，對效能要求較高業務資料有較高的安全性要求。
Endpoint	公網、VPC 網域名稱	KMS 私網網域名稱
效能	以加解密效能為例，通過共用網關訪問 KMS 時 QPS 為 1000。	以您購買的執行個體的計算效能規格為準，例如 1000、2000 等。
支援的整合方式	阿里雲 SDK、憑據 SDK、KMS Agent。	阿里雲 SDK、憑據 SDK、KMS Agent、執行個體 SDK。
支援的 API	全部 OpenAPI。	OpenAPI-密碼運算、OpenAPI-擷取憑據值、執行個體 API（不推薦）。
身份認證和鑒權	RAM 鑒權和 AAP（不推薦）。	RAM 鑒權和 AAP（不推薦）。
CA 憑證	無需配置 CA 憑證。	需要配置 CA 憑證。

整合方式

KMS 提供 SDK 和 KMS Agent 兩種整合方式，兩者在 API 支援和適用情境上有明顯差異。

SDK 和 KMS Agent 對比

維度	SDK（阿里雲/憑據/執行個體）	KMS Agent	整合建議
支援 API	管控類、密碼運算、擷取憑據	僅擷取憑據	需要管控操作：SDK。僅擷取憑據：兩者均可。
語言支援	Java、Python、Go、C++、PHP、.NET、TypeScript、Swift	任意程式設計語言（HTTP 介面）	跨語言情境： Agent。
網路部署	直連網關，支援公網/VPC/私網	本地應用訪問，HTTP 本地通訊	多語言微服務：Agent。直連效能關鍵： SDK
整合複雜度	語言特定 SDK，簽名邏輯內建	簡化認證，標準 HTTP 介面，代理管理憑存	快速整合：Agent。完全控制：SDK。

整合流程說明

SDK 整合

KMS SDK 將複雜的簽名過程封裝在方法內，使用者按照介面說明填入必填參數和認證資訊即可。KMS SDK 包含阿里雲 SDK、憑據 SDK、執行個體 SDK（不推薦）。

若您結合網關、鑒權、API 的情況選擇了合適的 SDK 後，可按照以下流程整合 SDK 以使用 KMS。更多 SDK 整合資訊，可參見SDK參考。

SDK 接入流程

SDK 整合遵循以下標準流程：

使用說明

支援通行金鑰和憑據的所有操作（管控類、操作類），其中管控類操作僅支援 SDK 這一種整合方式。
針對不同的語言環境，需要安裝對應語言的 SDK。

SDK 類型詳細說明

下表匯總三種 SDK 類型在支援 API、網關、鑒權和語言方面的差異，協助選擇合適的 SDK：

SDK 類型	支援的 API	網關及鑒權方式說明	支援的開發語言
憑據 SDK	OpenAPI：擷取憑據：GetSecretValue 執行個體 API（不推薦）：擷取憑據：GetSecretValue	共用網關： RAM 鑒權+OpenAPI AAP 鑒權+OpenAPI（不推薦） AAP 鑒權+執行個體 API（不推薦）專屬網關： RAM 鑒權+OpenAPI AAP 鑒權+執行個體 API（不推薦）	支援 3 種： Java（Java 8 及以上版本） Python Go
阿里雲 SDK	OpenAPI：管控類：服務管理、執行個體管理、密鑰管理、憑據管理、標籤管理、應用管理業務類：密碼運算、擷取憑據值	共用網關：RAM 鑒權+OpenAPI 專屬網關：RAM 鑒權+OpenAPI	支援 8 種： Java Python Go C++ PHP .NET(C#) TypeScript Swift
執行個體 SDK（不推薦）	執行個體 API：密鑰介面、憑據介面、產生隨機數	共用網關：不支援。專屬網關：APP 鑒權+執行個體 API	支援 5 種： Java（Java 8 及以上版本） Python Go PHP .NET（僅 C#）

KMS Agent 整合

KMS Agent 簡化了應用訪問 KMS 的身份認證與緩衝管理流程，是基於標準化 HTTP 介面提供服務。更多資訊，請參見KMS Agent。

使用說明

適用於多語言環境，支援任意程式設計語言的業務應用調用 KMS Agent
僅支援本地業務應用訪問
僅支援擷取憑據值，不可管控憑據資訊例如修改、刪除憑據等操作

KMS Agent 接入流程

開發接入說明

支援的 API

網關類型

鑒權方式

支援的開發語言

OpenAPI：

擷取憑據：GetSecretValue

共用網關、專屬網關

RAM 鑒權

KMS Agent 是基於標準化 HTTP 介面提供服務，支援任意程式設計語言的業務應用調用。

KMS API 類型

KMS 提供 OpenAPI 和 KMS 執行個體 API（不推薦）兩大類型的 API，其中按功能區分又分為管控類操作 API、密碼運算類 API、擷取憑據 API 三大類 API。更多資訊可參見API概覽、執行個體 API。

API 類型對比

下表匯總三種 API 類型與整合方式的對應關係，協助快速定位合適方案：

API 類型	阿里雲 SDK	憑據 SDK	執行個體 SDK	KMS Agent
管控類操作建立、修改、刪除密鑰和憑據。	支援	不支援	不支援	不支援
密碼運算加解密、數位簽章等。	支援	不支援	支援	不支援
擷取憑據值擷取憑據。	支援	支援	支援	支援

管控類操作

管控類操作包括執行個體、密鑰、憑據相關的管控操作，例如建立密鑰、建立憑據、建立KMS執行個體、修改密鑰標籤等。

管控類操作只能使用阿里雲SDK接入，通過訪問共用網關Endpoint調用OpenAPI。

密碼運算

密碼運算操作包括對稱加解密、非對稱加解密、信封加密、產生資料密鑰、數位簽章、驗證簽名等與密碼學相關的操作。

密碼運算操作可以通過阿里雲SDK或者KMS執行個體SDK接入。

重要

通過共用網關調用密碼運算操作API時，需要開啟公網訪問開關。具體操作，請參見通過公網訪問KMS執行個體中的密鑰。

擷取憑據值

可以通過憑據SDK、阿里雲SDK、執行個體SDK、KMS Agent訪問共用網關或專屬網關調用OpenAPI-GetSecretValue或執行個體API-GetSecretValue（不推薦）擷取KMS憑據值。

API介面樣本

以下以OpenAPI為例，展示各類型對應介面說明。

管控類

服務管理

API	標題	API概述
DescribeAccountKmsStatus	查詢當前阿里雲帳號的Key Management Service狀態	查詢當前阿里雲帳號的Key Management Service狀態。
OpenKmsService	為當前阿里雲帳號開通Key Management Service	為當前阿里雲帳號開通Key Management Service。

執行個體管理

API	標題	API概述
ListKmsInstances	擷取執行個體列表	查詢 KMS 執行個體列表。
ConnectKmsInstance	串連執行個體並配置網路	啟用一個KMS執行個體。
GetKmsInstance	擷取執行個體	查詢一個KMS執行個體的詳情。
UpdateKmsInstanceBindVpc	更新執行個體分享VPC	更新KMS執行個體配置的VPC。
ReleaseKmsInstance	釋放KMS隨用隨付執行個體	釋放KMS隨用隨付執行個體。
GetDefaultKmsInstance	擷取預設KMS執行個體	擷取預設KMS執行個體。

密鑰管理

API	標題	API概述
CreateKey	建立一個主要金鑰	建立一個主要金鑰。
ListKeys	查詢調用者在調用地區的所有主要金鑰ID	查詢調用者在調用地區的所有主要金鑰ID。
DescribeKey	返回指定主要金鑰（CMK）的相關資訊	查詢使用者主要金鑰（CMK）詳情。
UpdateKeyDescription	更新主要金鑰描述資訊	更新主要金鑰的描述資訊。
EnableKey	啟用指定的主要金鑰進行加解密	啟用指定的主要金鑰進行加解密。
DisableKey	禁用指定的主要金鑰（CMK）進行加解密	禁用指定的主要金鑰（CMK）進行加解密。
CreateAlias	給主要金鑰（CMK）建立一個別名	為主要金鑰（CMK）建立一個別名。
ListAliases	查詢目前使用者在當前地區的所有別名	查詢目前使用者在當前地區的所有別名。
ListAliasesByKeyId	查詢主要金鑰（CMK）所有別名	查詢與指定主要金鑰（CMK）對應的所有別名。
DeleteAlias	刪除別名	刪除別名。
UpdateAlias	更新主要金鑰（CMK）ID	更新已存在的別名所代表的主要金鑰（CMK）ID。
GetParametersForImport	擷取匯入主要金鑰（CMK）材料的參數	擷取匯入主要金鑰材料的參數。
ImportKeyMaterial	匯入密鑰材料	匯入密鑰材料。
DeleteKeyMaterial	刪除已匯入的密鑰材料	刪除已匯入的密鑰材料。
ScheduleKeyDeletion	申請刪除一個指定的主要金鑰（CMK)	申請刪除一個指定的主要金鑰（CMK)。
CancelKeyDeletion	撤銷密鑰刪除	撤銷密鑰刪除。
SetDeletionProtection	設定刪除保護	為使用者主要金鑰（CMK）開啟或關閉刪除保護。
UpdateRotationPolicy	更新密鑰輪轉策略	更新密鑰的周期性自動輪轉策略。
DescribeKeyVersion	查詢指定密鑰版本資訊	查詢指定密鑰版本資訊。
CreateKeyVersion	為主要金鑰建立一個新的密鑰版本	為使用者主要金鑰（CMK）建立密鑰版本。
ListKeyVersions	列出主要金鑰的所有密鑰版本	列出主要金鑰的所有密鑰版本。
SetKeyPolicy	設定密鑰策略	為KMS執行個體中的密鑰設定密鑰策略。
GetKeyPolicy	查詢密鑰策略	查詢指定密鑰的密鑰策略。

憑據管理

API	標題	API概述
ListSecrets	查詢目前使用者在當前地區建立的所有憑據	查詢目前使用者在當前地區建立的所有憑據。
DeleteSecret	刪除憑據對象	刪除憑據對象。
CreateSecret	建立憑據	建立憑據並存入憑據的初始版本。
UpdateSecret	更新憑據的中繼資料	更新憑據的中繼資料。
UpdateSecretVersionStage	更新憑據的版本狀態	更新憑據的版本狀態。
UpdateSecretRotationPolicy	更新動態憑據的輪轉策略	更新憑據輪轉策略。
DescribeSecret	查詢憑據的中繼資料資訊	查詢憑據的中繼資料資訊。
ListSecretVersionIds	查詢憑據的所有版本資訊	查詢憑據的所有版本資訊。
GetRandomPassword	獲得一個隨機口令字串	獲得一個隨機口令字串。
PutSecretValue	為憑據存入一個新版本的憑據值	為通用憑據存入一個新版本的憑據值。
RestoreSecret	恢複被刪除的憑據	恢複被刪除的憑據。
RotateSecret	主動輪轉動態憑據	立即輪轉憑據。
SetSecretPolicy	設定憑據策略	為KMS執行個體中的憑據鑰設定憑據策略。
GetSecretPolicy	查詢憑據策略	查詢指定憑據的憑據策略。

標籤管理

API	標題	API概述
GetKmsInstanceQuotaInfos	擷取執行個體配額資訊	擷取執行個體配額資訊。
ListResourceTags	擷取使用者主要金鑰的標籤	擷取使用者主要金鑰的標籤。
TagResource	為主要金鑰或憑據設定標籤	為主要金鑰、憑據或認證綁定標籤。
UntagResource	刪除使用者主要金鑰或憑據的指定標籤	為主要金鑰、憑據或認證解除綁定標籤。

應用管理

API	標題	API概述
CreateNetworkRule	建立網路規則	建立一條網路控制規則，設定允許訪問KMS的私網IP或私網的網段。
ListNetworkRules	擷取網路規則列表	查詢網路控制規則列表。
DescribeNetworkRule	擷取網路規則	查詢一個網路控制規則的詳情。
UpdateNetworkRule	更新網路規則	更新一個網路控制規則。
DeleteNetworkRule	刪除網路規則	刪除一條網路控制規則。
CreatePolicy	建立存取原則	建立一個權限原則，設定允許應用訪問的密鑰和憑據。
ListPolicies	擷取存取原則列表	查詢權限原則列表。
DescribePolicy	擷取存取原則	查詢一個權限原則的詳情。
UpdatePolicy	更新存取原則	更新一個權限原則。
DeletePolicy	刪除存取原則	刪除一條權限原則。
CreateApplicationAccessPoint	建立應用存取點	建立一個應用存取點。
ListApplicationAccessPoints	擷取應用存取點列表	查詢應用存取點列表。
DescribeApplicationAccessPoint	擷取應用存取點	查詢一個應用存取點的詳情。
UpdateApplicationAccessPoint	更新應用存取點	更新一個應用存取點資訊。
DeleteApplicationAccessPoint	刪除應用存取點	刪除一個應用存取點。
CreateClientKey	建立應用身份憑證	建立一個應用身份憑證（ClientKey）。
ListClientKeys	擷取應用身份憑證列表	查詢應用身份憑證（ClientKey）列表。
GetClientKey	擷取應用身份憑證	擷取一個應用身份憑證（ClientKey）資訊。
DeleteClientKey	刪除應用身份憑證	刪除一個應用身份憑證（ClientKey）。

業務類-密碼運算

API列表	描述	共用網關	專屬網關
Encrypt	使用對稱金鑰將明文加密為密文。	支援	支援
GenerateDataKey	產生一個隨機的資料密鑰，用於本機資料加密。	支援	支援
GenerateDataKeyWithoutPlaintext	產生一個隨機的資料密鑰，用於本機資料加密，且不返回資料密鑰明文。	支援	支援
ExportDataKey	使用傳入的公開金鑰加密匯出資料密鑰。	支援	支援
GenerateAndExportDataKey	隨機產生一個資料密鑰，通過您指定的KMS密鑰和公開金鑰加密後，返回使用KMS祕密金鑰加密後的資料密鑰密文，以及使用公開金鑰加密後的資料密鑰密文。	支援	支援
Decrypt	解密密文。	支援	支援
ReEncrypt	對密文進行轉加密。即先將密文解密，然後將解密得到的資料或者資料密鑰使用新的主要金鑰再次進行加密，返回加密結果。	支援	不支援
AsymmetricSign	使用非對稱金鑰進行簽名。	支援	支援
AsymmetricVerify	使用非對稱金鑰進行驗簽。	支援	支援
AsymmetricDecrypt	使用非對稱金鑰進行解密。	支援	支援
AsymmetricEncrypt	使用非對稱金鑰進行加密。	支援	支援
GetPublicKey	擷取非對稱金鑰的公開金鑰。	支援	支援

業務類-擷取憑據值

API列表	描述	共用網關	專屬網關
GetSecretValue	擷取憑據值。	支援	支援

認證與鑒權

KMS 支援 RAM 鑒權和應用存取點 AAP 鑒權（不推薦），更多資訊可參見管理 RAM 訪問憑據，應用存取點（AAP）管理。

差異點	RAM 鑒權	AAP 鑒權（不推薦）
功能說明	支援自訂靈活權限原則。支援 RAM 角色、STS Token、ECS RAM 角色、AK 等多種方式。	支援自訂靈活權限原則。需要下載儲存認證檔案 ClientKey，其中包含應用身份憑證內容（ClientKeyContent）和憑證口令（ClientKeyPassword）。
支援的整合方式	阿里雲 SDK、憑據 SDK、KMS Agent。	憑據 SDK、執行個體 SDK。
支援的 API	全部 OpenAPI。	OpenAPI-擷取憑據、執行個體 API。
支援的網關	專屬網關、共用網關	專屬網關、共用網關說明針對不同的網關要求提供專屬網關和共用網關兩種模式，具體操作可參見AAP鑒權（不推薦）。