GenerateDataKey - 產生一個資料密鑰 -

介面說明

RAM 使用者或 RAM 角色調用該 OpenAPI 需要被授與權限策略詳情，請參見存取控制。
本介面可以通過共用網關或專屬網關調用。詳細介紹，請參見阿里雲 SDK。
- 共用網關：通過公網、VPC 網域名稱訪問 KMS，該方式需要開啟公網開關。具體操作，請參見通過公網訪問 KMS 執行個體中的密鑰。
- 專屬網關：通過 KMS 私網地址（<YOUR_KMS_INSTANCE_ID>.cryptoservice.kms.aliyuncs.com）訪問 KMS。

QPS 限制

通過共用網關調用：本介面的單使用者 QPS 限制為 1000 次/秒。超過限制，API 呼叫將會被限流，這可能影響您的業務，請合理調用。
通過專屬網關調用：本介面的單使用者 QPS 限制以您 KMS 執行個體的計算效能規格為準。詳細介紹，請參見效能資料。

詳細說明

API 隨機產生的資料密鑰通過您指定的主要金鑰（CMK）加密後，返回資料密鑰的密文和明文。您可以使用返回的資料密鑰明文，在 KMS 之外對資料進行本地離線加密。在儲存加密後的資料時，也需要儲存資料密鑰的密文。您可以通過響應中的 Plaintext 欄位擷取到資料密鑰的明文，通過 CiphertextBlob 欄位擷取到資料密鑰的密文。

在請求中指定的 CMK，僅會被用作資料密鑰的加密，和資料密鑰的產生無關。KMS 不會記錄或儲存隨機產生的資料密鑰，您需要負責對資料密鑰（密文）進行持久化。

建議您使用以下方式在本地進行資料加密：

1.調用 GenerateDataKey 介面，獲得用於資料加密的密鑰。

2.使用資料密鑰的明文（通過響應中的 Plaintext 欄位返回），在本地完成離線資料加密，隨後清除記憶體中的資料密鑰明文。

3.將資料密鑰的密文（通過響應中的 CiphertextBlob 欄位返回），和本地離線加密後的資料一併進行儲存。

在本地解密資料：

調用 Decrypt 介面解密本機存放區的資料密鑰的密文。該操作將返回資料密鑰的明文。
使用資料密鑰的明文，在本地完成離線資料解密，隨後清除記憶體中的資料密鑰明文。

本文將提供一個樣本，為 ID 為key-hzz630494463ejqjx****的密鑰產生隨機的資料密鑰。

調試

您可以在OpenAPI Explorer中直接運行該介面，免去您計算簽名的困擾。運行成功後，OpenAPI Explorer可以自動產生SDK程式碼範例。

調試

授權資訊

當前API暫無授權資訊透出。

請求參數

名稱	類型	必填	描述	樣本值
KeyId	string	是	密鑰的 ID，也可以指定為密鑰別名或密鑰資源名稱（ARN）。關於別名的詳細介紹，請參見管理密鑰別名。說明訪問其他阿里雲帳號下的密鑰時，必須輸入密鑰 ARN。密鑰 ARN 的格式為`acs:kms:${region}:${account}:key/${keyid}`。	key-hzz630494463ejqjx****
KeySpec	string	否	指定產生的資料密鑰的長度，取值： AES_256：256 位元的對稱金鑰。 AES_128：128 位元的對稱金鑰。說明建議使用 KeySpec 或者 NumberOfBytes 來指定資料密鑰長度。如果兩者都不指定，KMS 產生 256 位元的資料密鑰；如果兩者都被指定，KMS 會忽略 KeySpec 參數。	AES_256
NumberOfBytes	integer	否	指定產生的資料密鑰的長度，單位為位元組。取值：1~1024。預設值：當 KeySpec 取值為 AES_256 時，NumberOfBytes 預設值為 32。當 KeySpec 取值為 AES_128 時，NumberOfBytes 預設值為 16。	256
EncryptionContext	object	否	key/value 對的 JSON 字串。如果指定了該參數，則在調用 Decrypt 介面時需要提供同樣的參數。更多資訊，請參見 EncryptionContext 。	{"Example":"Example"}
DryRun	string	否	是否開啟 DryRun 模式。 true：開啟 false（預設值）：關閉 DryRun 模式用於測試 API 呼叫，驗證您是否具有相應資源的許可權，以及請求參數是否配置正確。DryRun 模式開啟後，KMS 會始終返回失敗並提示失敗原因。失敗原因包含如下： DryRunOperationError：不配置 DryRun 參數時，請求會成功。 ValidationError：請求中指定的參數有誤。 AccessDeniedError：您無權在 KMS 資源上執行該操作。	false

關於公用請求參數的詳情，請參見公用參數。

返回參數

名稱	類型	描述	樣本值
	object
KeyVersionId	string	密鑰版本 ID。主要金鑰版本的通用唯一識別碼。	2ab1a983-7072-4bbc-a582-584b5bd8****
KeyId	string	金鑰識別碼。如果請求中的 KeyId 參數使用的是密鑰別名、密鑰 ARN，在響應中也會返回金鑰識別碼。	key-hzz630494463ejqjx****
CiphertextBlob	string	資料密鑰被指定密鑰的主要版本加密後的密文。	ODZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmS7FmDBBQ0BkKsQrtRnidtPwirmDcS0ZuJCU41xxAAWk4Z8qsADfbV0b+i6kQmlvj79dJdGOvtX69Uycs901qOjop4bTS****
RequestId	string	本次調用請求的 ID，是由阿里雲為該請求產生的唯一識別碼，可用於排查和定位問題。	7021b6ec-4be7-4d3c-8a68-1e85d4d515a0
Plaintext	string	資料密鑰的明文經過 Base 64 編碼後的值。	QmFzZTY0IGVuY29kZWQgcGxhaW50****

樣本

正常返回樣本

JSON格式

{
  "KeyVersionId": "2ab1a983-7072-4bbc-a582-584b5bd8****",
  "KeyId": "key-hzz630494463ejqjx****",
  "CiphertextBlob": "ODZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmS7FmDBBQ0BkKsQrtRnidtPwirmDcS0ZuJCU41xxAAWk4Z8qsADfbV0b+i6kQmlvj79dJdGOvtX69Uycs901qOjop4bTS****",
  "RequestId": "7021b6ec-4be7-4d3c-8a68-1e85d4d515a0",
  "Plaintext": "QmFzZTY0IGVuY29kZWQgcGxhaW50****"
}

錯誤碼

HTTP status code	錯誤碼	錯誤資訊	描述
400	UnsupportedOperation	This action is not supported.	不支援的操作
404	Forbidden.AliasNotFound	The specified Alias is not found.	指定的別名找不到
404	Forbidden.KeyNotFound	The specified Key is not found.	指定的密鑰不存在。
409	Rejected.Disabled	The request was rejected because the key state is Disabled.	請求被拒絕，因為密鑰狀態為已禁用。
409	Rejected.PendingDeletion	The request was rejected because the key state is PendingDeletion.	請求被拒絕，原因是密鑰狀態為待刪除。
409	Rejected.Unavailable	The request was rejected because the key state is Unavailable.	請求被拒絕，原因是密鑰狀態為不可用。

訪問錯誤中心查看更多錯誤碼。

變更歷史

更多資訊，參考變更詳情。