將明文資料加密為密文。 - Key Management Service

用於將明文資料通過KMS祕密金鑰加密為密文。

使用說明

僅當密鑰為KMS軟體密鑰管理執行個體中的對稱金鑰時，支援使用本介面。關於密鑰規格、加密模式以及密鑰版本的詳細資料，請參見密鑰管理類型和密鑰規格。

AdvanceEncrypt和Encrypt都用於將明文資料加密為密文，區別為：

AdvanceEncrypt：加密時使用密鑰的主要版本，加密後需要使用AdvanceDecrypt解密。
Encrypt：加密時使用密鑰的初始版本，加密後可以使用Decrypt或AdvanceDecrypt解密。

重要

如果密鑰開啟了自動輪轉，加密時請使用AdvanceEncrypt，以避免輪轉功能不生效。關於密鑰輪轉的相關內容，請參見密鑰輪轉。

注意事項

所有請求參數使用Protocol Buffers編碼後（即Request Body），內容長度不能超過3 MB，超過3 MB後服務端會拒絕處理並返回HTTP 413狀態代碼。建議單次加解密的資料不超過6 KB，超過6 KB時請使用信封加密方案。詳細資料，請參見使用KMS密鑰進行信封加密。

說明

單次加解密的資料量越大，網路傳輸失敗可能性越大，網路傳輸所需時間越長，KMS執行個體對資料進行加解密所需時間也越長。

請求參數

名稱	類型	是否必選	樣本值	描述
KeyId	string	是	key-hzz62f1cb66fa42qo****	密鑰的通用唯一識別碼。該參數也可以被指定為密鑰別名。重要密鑰必須為KMS軟體密鑰管理執行個體中的對稱金鑰。
Plaintext	bytes	是	位元據	待加密的明文資料。
Algorithm	string	否	AES_GCM	密碼編譯演算法。如果未指定本參數，KMS會使用密碼編譯演算法預設值。更多資訊，請參見密鑰管理類型和密鑰規格。
Iv	bytes	否	位元據	對資料加密時使用的初始向量。僅當密碼編譯演算法（Algorithm）為AES_GCM、AES_CBC時本參數有效。密碼編譯演算法（Algorithm）為AES_CBC時：Iv長度為16位元組。密碼編譯演算法（Algorithm）為AES_GCM時：Iv長度為12位元組。如果未指定本參數，KMS將隨機產生。重要推薦您不指定本參數，由KMS隨機產生。
Aad	binary	否	位元據	對資料祕密金鑰加密時使用的GCM加密模式認證資料。當密碼編譯演算法（Algorithm）是AES_GCM時，您可以根據業務需要使用本參數。重要如果指定了本參數，調用AdvanceDecrypt解密時需要指定相同的參數。
PaddingMode	string	否	PKCS7_PADDING	填充模式。僅當密碼編譯演算法（Algorithm）為AES_CBC或AES_ECB時，需要指定本參數。取值： PKCS7_PADDING（預設值）：即PKCS#7填充。資料明文或密文內容的長度可以不是相應密碼演算法的塊大小（K位元組）的整數倍。當輸入資料明文或密文內容長度為L位元組時，系統將填充K -（L mod K）位元組的內容，填充的每個位元組均為K -（L mod K）。 NO_PADDING：不對資料明文填充。資料明文內容的長度必須為相應密碼演算法的塊大小的整數倍。

響應資料

名稱	類型	樣本值	描述
CiphertextBlob	bytes	位元據	資料被指定祕密金鑰加密後的密文。說明 CiphertextBlob中還包含密鑰標識（KeyId）、密碼編譯演算法（Algorithm）、填充模式（PaddingMode）、加密資料時使用的初始向量（Iv）等資訊，通過AdvanceDecrypt解密時僅需傳入CiphertextBlob。
Algorithm	string	AES_GCM	密碼編譯演算法。
KeyId	string	key-hzz62f1cb66fa42qo****	密鑰的通用唯一識別碼。如果請求中的KeyId參數使用的是密鑰別名，在響應中會返回別名對應的密鑰的通用唯一識別碼。
KeyVersionId	string	key-hzz62f1cb66fa42qopd9s-17kedv****	加密時使用的密鑰版本。本介面使用密鑰當時的主要版本。
Iv	bytes	位元據	加密資料時使用的初始向量。僅當密碼編譯演算法（Algorithm）為AES_GCM、AES_CBC時，本參數返回有效值，其他情境返回空值。
PaddingMode	string	PKCS7_PADDING	填充模式。僅當密碼編譯演算法（Algorithm）為AES_CBC或AES_ECB時，本參數返回有效值，其他情境返回空值。
RequestId	string	c0037a6d-7784-4ef2-a692-288fdefc7b9d	本次調用請求的ID，是由阿里雲為該請求產生的唯一識別碼，可用於排查和定位問題。

錯誤碼

HTTP狀態代碼	錯誤碼	錯誤訊息	描述
404	Forbidden.OnlySymmetricKeySupported	The key %s is not a symmetric key. The API only supports symmetric keys.	僅支援使用對稱金鑰。說明非對稱式加密一般用於跨安全域的資料加密或金鑰交換，這意味著通常有一端不使用阿里雲KMS。

訪問公用錯誤碼查看更多錯誤碼。