All Products
Search
Document Center

Key Management Service:AdvanceEncrypt

Last Updated:Oct 18, 2023

Encrypts plaintext into ciphertext.

Usage notes

You can call this operation only for symmetric keys in Key Management Service (KMS) instances of the software key management type. For more information about key specifications, encryption modes, and key versions, see Key types and specifications.

You can call the AdvanceEncrypt operation or the Encrypt operation to encrypt plaintext into ciphertext. Take note of the following differences between the two operations:

  • AdvanceEncrypt: The primary version of a key is used to encrypt plaintext into ciphertext. You must call the AdvanceDecrypt operation to decrypt the ciphertext.

  • Encrypt: The initial version of a key is used to encrypt plaintext into ciphertext. You can call the Decrypt operation or the AdvanceDecrypt operation to decrypt the ciphertext.

Important

If you enable automatic key rotation, you must call the AdvanceEncrypt operation to prevent the key rotation feature from becoming invalid. For more information about automatic key rotation, see Configure key rotation.

Request parameters

Parameter

Type

Required

Example

Description

KeyId

string

Yes

key-hzz62f1cb66fa42qo****

The globally unique ID of the key. You can set the value to an alias that is bound to the key.

Important

The key must be a symmetric key in KMS instances of the software key management type.

Plaintext

bytes

Yes

Binary data

The plaintext that you want to encrypt.

Algorithm

string

No

AES_GCM

The encryption algorithm.

If you do not set this parameter, KMS uses the default value. For more information, see Key types and specifications.

Iv

bytes

No

Binary data

The initial vector that is used to encrypt data.

This parameter takes effect only when Algorithm is set to AES_GCM or AES_CBC.

  • If Algorithm is set to AES_CBC, the value of Iv must be 16 bytes in length.

  • If Algorithm is set to AES_GCM, the value of Iv must be 12 bytes in length.

If you do not set this parameter, KMS generates a random number.

Important

We recommend that you do not set this parameter.

Aad

binary

No

Binary data

The authentication data when the GCM mode is used to encrypt a data key.

If Algorithm is set to AES_GCM, you can use this parameter based on your business requirements.

Important

If Aad is set, you must set the same parameter when you call the AdvanceDecrypt operation.

PaddingMode

string

No

PKCS7_PADDING

The padding mode.

This parameter is required only when Algorithm is set to AES_CBC or AES_ECB.

Valid values:

  • PKCS7_PADDING: PKCS#7 padding is used. This is the default value. The length of the plaintext or ciphertext may not be an integer multiple of the cipher block size in bytes.

    If the input plaintext or ciphertext is L bytes in length, the system adds a padding string of K -(L mod K) bytes. Each padding string is K -(L mod K) bytes in length.

  • NO_PADDING: Padding strings are not added to plaintext. The length of the plaintext must be an integer multiple of the cipher block size in bytes.

Response parameters

Parameter

Type

Example

Description

CiphertextBlob

bytes

Binary data

The ciphertext of the plaintext that is encrypted by using a key.

Note

CiphertextBlob contains information about KeyId, Algorithm, PaddingMode, and Iv. You need to only set CiphertextBlob when you call the AdvanceDecrypt operation to decrypt data.

Algorithm

string

AES_GCM

The encryption algorithm.

KeyId

string

key-hzz62f1cb66fa42qo****

The globally unique ID of the key. If you set KeyId to an alias of the key, the ID of the key to which the alias is bound is returned.

KeyVersionId

string

key-hzz62f1cb66fa42qopd9s-17kedv****

The version of the key. The primary version is used.

Iv

bytes

Binary data

The initial vector that is used to encrypt data.

A valid value is returned only when Algorithm is set to AES_GCM or AES_CBC. In other scenarios, an empty value is returned.

PaddingMode

string

PKCS7_PADDING

The padding mode. This parameter returns a valid value only when Algorithm is set to AES_CBC or AES_ECB. In other scenarios, an empty value is returned.

RequestId

string

c0037a6d-7784-4ef2-a692-288fdefc7b9d

The ID of the request, which is 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.

Only symmetric keys are supported.

Note

Asymmetric encryption is used for data encryption or key exchange across security domains. In this case, Alibaba Cloud KMS is not used on one side.

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