阿里雲SDK - Key Management Service

阿里雲SDK不僅支援通過調用OpenAPI執行建立執行個體、建立密鑰等管控類操作，還支援執行加密解密、擷取憑據值等業務類操作。其中管控類操作僅可通過共用網關訪問，而業務類操作既支援通過共用網關也能通過專屬網關訪問。本文介紹業務如何通過阿里雲SDK接入KMS。

接入流程簡述

共用網關和專屬網關的差異

以下表格僅對比在業務類操作中網關之間的差異。

差異點	共用網關	專屬網關
網路差異	公網或VPC網路。	KMS私人網路。
效能差異	以加解密效能為例，通過共用網關訪問KMS時QPS為1000。	以您購買的執行個體的計算效能規格為準，例如1000、2000等。
初始化用戶端時的配置差異	Endpoint：共用網關Endpoint，例如`kms.cn-hangzhou.aliyuncs.com`。具體請參見共用網關Endpoint（又稱KMS服務Endpoint）。 KMS執行個體CA認證：無需配置。	Endpoint：專屬網關Endpoint，格式為`<YOUR_KMS_INSTANCE_ID>.cryptoservice.kms.aliyuncs.com`。例如`kst-hzz65f176a0ogplgq****.cryptoservice.kms.aliyuncs.com`。 KMS執行個體CA認證：需要配置。但僅阿里雲SDK（2.0）支援，阿里雲SDK（1.0）不支援，阿里雲SDK（1.0）需要將運行時參數HTTPSInsecure設定為true，即`client.SetHTTPSInsecure(true)`。
API差異	支援所有業務類OpenAPI。具體API列表，請參見本文的業務類-密碼運算、業務類-擷取憑據值。	專屬網關不支援ReEncrypt，其他支援的API和公網訪問相同。具體API列表，請參見本文的業務類-密碼運算、業務類-擷取憑據值。
身份認證和鑒權差異	使用STS Token認證並擷取憑據的過程中，僅對GetSecretValue操作進行鑒權，不對Decrypt操作進行鑒權。其他認證方式對兩種操作均鑒權。支援通過acs:SourceVpc、acs:VpcSourceIp條件鍵進行網路存取控制。	擷取憑據的過程中，對GetSecretValue操作、Decrypt操作均進行鑒權。不支援通過acs:SourceVpc、acs:VpcSourceIp條件鍵進行網路存取控制。您有網路存取控制的需求時，請聯絡阿里雲支援人員。設定密鑰策略、憑據策略後生效時間長度最長為5分鐘。
審計差異	通過ActionTrail，審計動作記錄。	通過Simple Log Service (SLS)，審計動作記錄。

支援的OpenAPI

您可以通過共用網關執行管控類操作和業務類操作，通過專屬網關執行業務類操作。具體的 API 列表，請查看以下內容。

重要

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

管控類

服務管理

API	描述
DescribeRegions	查詢當前阿里雲帳號的可用地區列表。
OpenKmsService	為當前阿里雲帳號開通Key Management Service。
DescribeAccountKmsStatus	查詢當前阿里雲帳號的Key Management Service狀態。

執行個體管理

API	描述
ConnectKmsInstance	啟用一個KMS執行個體。
GetKmsInstance	查詢一個KMS執行個體的詳情。
ListKmsInstances	查詢KMS執行個體列表。
UpdateKmsInstanceBindVpc	更新KMS執行個體配置的VPC。

密鑰管理

API	描述
CreateKey	建立密鑰。使用者可以選擇由KMS產生密鑰材料，也可以選擇自己上傳密鑰材料（即BYOK方式）。
GetParametersForImport	用於在建立外部金鑰（BYOK）時，擷取將密鑰材料匯入密鑰時所需的參數。
ImportKeyMaterial	用於在建立外部金鑰（BYOK）時，將密鑰材料匯入密鑰。
EnableKey	修改密鑰的狀態為啟用。
DisableKey	修改密鑰的狀態為禁用。
DescribeKey	查詢指定密鑰的資訊。
ListKeys	查詢阿里雲帳號在調用地區的所有密鑰。
UpdateKeyDescription	更新密鑰的描述資訊。
CreateAlias	建立一個別名，並且將別名與一個密鑰綁定。
UpdateAlias	更新已存在的別名所代表的密鑰ID。
DeleteAlias	刪除別名。
ListAliases	查詢阿里雲帳號在調用地區的所有別名。
ListAliasesByKeyId	查詢與指定密鑰綁定的別名。
SetDeletionProtection	為密鑰開啟或關閉刪除保護。
ScheduleKeyDeletion	計劃刪除密鑰。將密鑰的狀態設定為待刪除狀態，處於待刪除狀態的密鑰，會在計劃日期到期後刪除。
CancelKeyDeletion	取消計劃刪除。處於待刪除狀態的密鑰，在計劃的日期到期之前，可以取消刪除的計劃，重新設定密鑰狀態為啟用。
DeleteKeyMaterial	刪除密鑰材料。重要僅支援刪除預設密鑰（主要金鑰）中的外部金鑰材料。
CreateKeyVersion	為密鑰建立新的密鑰版本。僅軟體密鑰管理執行個體中的對稱金鑰支援。說明如果您的密鑰不是在KMS執行個體中建立的密鑰，則該操作僅非對稱金鑰支援。
DescribeKeyVersion	查詢指定密鑰版本資訊。
ListKeyVersions	查詢密鑰的所有密鑰版本。
UpdateRotationPolicy	更新密鑰的輪轉策略。如果配置密鑰自動輪轉，KMS將周期性自動產生新的密鑰版本。

憑據管理

API	描述
CreateSecret	建立憑據，並存入憑據的初始版本。
ListSecrets	查詢當前阿里雲帳號在調用地區的所有憑據。
DescribeSecret	擷取憑據的中繼資料資訊。
UpdateSecret	更新憑據的中繼資料。
PutSecretValue	為憑據存入一個新版本的憑據值。說明僅通用憑據支援。
UpdateSecretVersionStage	更新憑據的版本狀態。說明僅通用憑據支援。
DeleteSecret	計劃刪除或直接刪除憑據。
RestoreSecret	恢複計劃刪除中的憑據。
ListSecretVersionIds	查詢憑據的所有版本資訊。
GetRandomPassword	獲得一個隨機密碼串。
RotateSecret	手動輪轉憑據。
UpdateSecretRotationPolicy	更新憑據輪轉策略。

標籤管理

API	描述
TagResource	為單個密鑰或者單個憑據綁定標籤。
UntagResource	刪除單個密鑰或者單個憑據的指定標籤。
ListResourceTags	查詢單個密鑰的所有標籤。
TagResources	批量為密鑰或憑據綁定標籤。
UntagResources	大量刪除密鑰或者憑據的指定標籤。
ListTagResources	批量查詢密鑰或憑據的所有標籤或指定標籤。

應用管理

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

業務類-密碼運算

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

業務類-擷取憑據值

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

Endpoint

共用網關Endpoint（又稱KMS服務Endpoint）

中國地區

地區	地區ID	公網接入地址	VPC接入地址
華東1（杭州）	cn-hangzhou	kms.cn-hangzhou.aliyuncs.com	kms-vpc.cn-hangzhou.aliyuncs.com
華東2（上海）	cn-shanghai	kms.cn-shanghai.aliyuncs.com	kms-vpc.cn-shanghai.aliyuncs.com
華南1（深圳）	cn-shenzhen	kms.cn-shenzhen.aliyuncs.com	kms-vpc.cn-shenzhen.aliyuncs.com
華南2（河源）	cn-heyuan	kms.cn-heyuan.aliyuncs.com	kms-vpc.cn-heyuan.aliyuncs.com
華南3（廣州）	cn-guangzhou	kms.cn-guangzhou.aliyuncs.com	kms-vpc.cn-guangzhou.aliyuncs.com
華北1（青島）	cn-qingdao	kms.cn-qingdao.aliyuncs.com	kms-vpc.cn-qingdao.aliyuncs.com
華北2（北京）	cn-beijing	kms.cn-beijing.aliyuncs.com	kms-vpc.cn-beijing.aliyuncs.com
華北3（張家口）	cn-zhangjiakou	kms.cn-zhangjiakou.aliyuncs.com	kms-vpc.cn-zhangjiakou.aliyuncs.com
華北5（呼和浩特）	cn-huhehaote	kms.cn-huhehaote.aliyuncs.com	kms-vpc.cn-huhehaote.aliyuncs.com
華北6（烏蘭察布）	cn-wulanchabu	kms.cn-wulanchabu.aliyuncs.com	kms-vpc.cn-wulanchabu.aliyuncs.com
西南1（成都）	cn-chengdu	kms.cn-chengdu.aliyuncs.com	kms-vpc.cn-chengdu.aliyuncs.com
中國香港	cn-hongkong	kms.cn-hongkong.aliyuncs.com	kms-vpc.cn-hongkong.aliyuncs.com

其他國家和地區

地區	地區ID	公網接入地址	VPC接入地址
新加坡	ap-southeast-1	kms.ap-southeast-1.aliyuncs.com	kms-vpc.ap-southeast-1.aliyuncs.com
馬來西亞（吉隆坡）	ap-southeast-3	kms.ap-southeast-3.aliyuncs.com	kms-vpc.ap-southeast-3.aliyuncs.com
印尼（雅加達）	ap-southeast-5	kms.ap-southeast-5.aliyuncs.com	kms-vpc.ap-southeast-5.aliyuncs.com
菲律賓（馬尼拉）重要該地區下僅有一個可用性區域，KMS在該地區不承諾SLA。	ap-southeast-6	kms.ap-southeast-6.aliyuncs.com	kms-vpc.ap-southeast-6.aliyuncs.com
泰國（曼穀）重要該地區下僅有一個可用性區域，KMS在該地區不承諾SLA。	ap-southeast-7	kms.ap-southeast-7.aliyuncs.com	kms-vpc.ap-southeast-7.aliyuncs.com
日本（東京）	ap-northeast-1	kms.ap-northeast-1.aliyuncs.com	kms-vpc.ap-northeast-1.aliyuncs.com
德國（法蘭克福）	eu-central-1	kms.eu-central-1.aliyuncs.com	kms-vpc.eu-central-1.aliyuncs.com
英國（倫敦）	eu-west-1	kms.eu-west-1.aliyuncs.com	kms-vpc.eu-west-1.aliyuncs.com
美國（矽谷）	us-west-1	kms.us-west-1.aliyuncs.com	kms-vpc.us-west-1.aliyuncs.com
美國（維吉尼亞）	us-east-1	kms.us-east-1.aliyuncs.com	kms-vpc.us-east-1.aliyuncs.com
阿聯酋（杜拜）	me-east-1	kms.me-east-1.aliyuncs.com	kms-vpc.me-east-1.aliyuncs.com

專屬網關Endpoint（又稱KMS執行個體Endpoint）

格式為<YOUR_KMS_INSTANCE_ID>.cryptoservice.kms.aliyuncs.com，例如kst-hzz65f176a0ogplgq****.cryptoservice.kms.aliyuncs.com。

說明

請將<YOUR_KMS_INSTANCE_ID>替換為您實際使用的KMS執行個體ID。

身份認證與授權

使用阿里雲SDK通過共用網關和專屬網關訪問OpenAPI時認證方式相同，支援AK、STS Token、RamRoleArn、ECS執行個體RAM角色等基於RAM的身份認證方式。詳細內容，請參見管理訪問憑據。

AccessKey

阿里雲帳號預設有所有資源的Administrator許可權且不可修改，其AccessKey泄露會危及資源安全，因此強烈建議不要為主帳號建立AccessKey，請建立專用於API訪問的RAM使用者並建立對應的AccessKey，並完成最小化授權。具體操作，請參見建立AccessKey。

登入RAM控制台，在使用者頁面，單擊目標RAM使用者名稱稱。
在認證管理頁簽下的AccessKey地區，單擊建立AccessKey，並按照指引完成建立。
授予RAM使用者訪問KMS的許可權。
- 方式一：設定基於身份的策略
  KMS內建了系統權限原則，可以直接綁定到RAM使用者，詳細介紹，請參見Key Management Service系統權限原則參考。您也可以自訂權限原則。
- 方式二：設定基於資源的策略
  KMS支援基於資源的策略，即為單個密鑰和憑據設定存取權限，用於控制哪些阿里雲帳號、RAM使用者、RAM角色有許可權來管理或使用KMS密鑰、憑據。詳細介紹，請參見密鑰策略、憑據策略。

STS Token

通過STS服務為RAM使用者或RAM角色頒發一個臨時訪問憑證，可以在限定的有效期間內，以符合策略規定的許可權訪問KMS，超過有效期間後，該憑證自動失效。

登入RAM控制台，建立RAM使用者或RAM角色。具體操作，請參見建立RAM使用者、建立RAM角色。
為RAM使用者或RAM角色授予AliyunSTSAssumeRoleAccess許可權。具體操作，請參見為RAM使用者授權、為RAM角色授權。
授予RAM使用者或RAM角色訪問KMS的許可權。
- 方式一：設定基於身份的策略
  KMS內建了系統權限原則，可以直接綁定到RAM使用者或RAM角色，詳細介紹，請參見Key Management Service系統權限原則參考。您也可以自訂權限原則。
- 方式二：設定基於資源的策略
  KMS支援基於資源的策略，即為單個密鑰和憑據設定存取權限，用於控制哪些阿里雲帳號、RAM使用者、RAM角色有許可權來管理或使用KMS密鑰、憑據。詳細介紹，請參見密鑰策略、憑據策略。
使用RAM使用者或RAM角色調用STS服務的AssumeRole介面擷取STS臨時訪問憑證。具體操作，請參見AssumeRole - 擷取扮演角色的臨時身份憑證。

RamRoleArn

RAM使用者或雲產品可以通過扮演角色的方式擷取臨時許可權，而不是直接使用長期密鑰，降低了密鑰泄露的風險。例如，在臨時的資料處理任務中，RAM使用者或雲產品臨時扮演一個具有特定RamRoleArn的角色，完成任務后角色許可權被收回，減少泄露風險。

登入RAM控制台，建立RAM角色。具體操作，請參見建立RAM角色。
授予RAM角色訪問KMS的許可權。
- 方式一：設定基於身份的策略
  KMS內建了系統權限原則，可以直接綁定到RAM角色，詳細介紹，請參見Key Management Service系統權限原則參考。您也可以自訂權限原則。
- 方式二：設定基於資源的策略
  KMS支援基於資源的策略，即為單個密鑰和憑據設定存取權限，用於控制哪些阿里雲帳號、RAM使用者、RAM角色有許可權來管理或使用KMS密鑰、憑據。詳細介紹，請參見密鑰策略、憑據策略。
擷取目標RAM角色的RamRoleArn。具體操作，請參見查看RAM角色。
說明
RamRoleArn是RAM角色的ARN資訊，即需要扮演的角色ID。格式為acs:ram::$accountID:role/$roleName。$accountID為阿里雲帳號ID。$roleName為RAM角色名稱。

ECS RAM角色

ECS RAM角色是指為ECS執行個體授予的RAM角色，該RAM角色是一個受信服務為雲端服務器的普通服務角色。使用執行個體RAM角色可以實現在ECS執行個體內部無需配置AccessKey即可擷取臨時訪問憑證（STS Token），從而調用KMS的OpenAPI。

具體操作，請參見執行個體RAM角色。

登入RAM控制台，建立可信實體為阿里雲服務的RAM角色。
- 信任主體類型：選擇雲端服務。
- 信任主體名稱：選擇Elastic Compute Service。
授予RAM角色訪問KMS的許可權。
- 方式一：設定基於身份的策略
  KMS內建了系統權限原則，可以直接綁定到RAM角色，詳細介紹，請參見Key Management Service系統權限原則參考。您也可以自訂權限原則。
- 方式二：設定基於資源的策略
  KMS支援基於資源的策略，即為單個密鑰和憑據設定存取權限，用於控制哪些阿里雲帳號、RAM使用者、RAM角色有許可權來管理或使用KMS密鑰、憑據。詳細介紹，請參見密鑰策略、憑據策略。
登入ECS管理主控台，將RAM角色授予ECS執行個體。