Encrypts plaintext into ciphertext. - Key Management Service

Encrypts plaintext into ciphertext using the primary version of a symmetric key in a Key Management Service (KMS) software key management instance.

Operation description

AdvanceEncrypt and Encrypt both encrypt plaintext into ciphertext, but differ in which key version is used and which decrypt operation is compatible:

	AdvanceEncrypt	Encrypt
Key version used	Primary version	Initial version
Compatible decrypt operation	AdvanceDecrypt only	Decrypt or AdvanceDecrypt

Important

If automatic key rotation is enabled, use AdvanceEncrypt instead of Encrypt to keep the key rotation feature working correctly. For more information, see Configure key rotation.

This operation is supported only for symmetric keys in KMS software key management instances. For supported key specifications, encryption algorithms, and key versions, see Key types and specifications.

Usage notes

The request body must not exceed 3 MB after encoding with Protocol Buffers. If it does, the server returns HTTP 413. Limit the data size to 6 KB per operation. For larger payloads, use envelope encryption.

Note

Large payloads increase the risk of network failures, extend transmission time, and slow down KMS encryption and decryption.

Request parameters

Parameter	Type	Required	Example	Description
KeyId	string	Yes	key-hzz62f1cb66fa42qo****	The globally unique ID of the key, or an alias bound to the key. The key must be a symmetric key in a KMS software key management instance.
Plaintext	bytes	Yes	Binary data	The plaintext to encrypt.
Algorithm	string	No	AES_GCM	The encryption algorithm. Defaults to the algorithm defined for the key if not set. For supported values, see Key types and specifications.
Iv	bytes	No	Binary data	The initialization vector (IV). Applies only when `Algorithm` is `AES_GCM` or `AES_CBC`. If not set, KMS generates a random value. Valid lengths: 12 bytes for `AES_GCM`, 16 bytes for `AES_CBC`. Important We recommend that you do not set this parameter.
Aad	binary	No	Binary data	The additional authenticated data (AAD) for GCM mode. Applies only when `Algorithm` is `AES_GCM`, and is optional based on your business requirements. If set, pass the same value when calling AdvanceDecrypt.
PaddingMode	string	No	PKCS7_PADDING	The padding mode. Required only when `Algorithm` is `AES_CBC` or `AES_ECB`. Valid values: `PKCS7_PADDING` (default) and `NO_PADDING`. With `PKCS7_PADDING`, the system pads the input with K-(L mod K) bytes, where K is the cipher block size and L is the input length. With `NO_PADDING`, the plaintext length must be an integer multiple of the cipher block size.

Response parameters

Parameter	Type	Example	Description
CiphertextBlob	bytes	Binary data	The ciphertext. Contains embedded metadata for `KeyId`, `Algorithm`, `PaddingMode`, and `Iv` — pass only `CiphertextBlob` when calling AdvanceDecrypt.
Algorithm	string	AES_GCM	The encryption algorithm used.
KeyId	string	key-hzz62f1cb66fa42qo****	The globally unique ID of the key. If you passed an alias in the request, the ID of the key the alias is bound to is returned.
KeyVersionId	string	key-hzz62f1cb66fa42qopd9s-17kedv****	The key version used to encrypt the data. Always the primary version.
Iv	bytes	Binary data	The initialization vector used. Returned only when `Algorithm` is `AES_GCM` or `AES_CBC`; empty otherwise.
PaddingMode	string	PKCS7_PADDING	The padding mode used. Returned only when `Algorithm` is `AES_CBC` or `AES_ECB`; empty otherwise.
RequestId	string	c0037a6d-7784-4ef2-a692-288fdefc7b9d	The request ID, used to locate and troubleshoot issues.

Error codes

HTTP status code	Error code	Error message	Description
404	Forbidden.OnlySymmetricKeySupported	The key %s is not a symmetric key. The API only supports symmetric keys.	The specified key is not a symmetric key. Asymmetric keys are used for cross-security-domain data encryption or key exchange, where KMS is not involved on one side.

For a full list of error codes, see Service error codes.