Updated on 2026-09-21 GMT+08:00

Encrypting Data

Function

This API is used to encrypt data using a specified CMK.

Constraints

If you use an asymmetric key for encryption, record the key ID and encryption algorithm, which are required for decryption. If the specified key ID and encryption algorithm do not match those used for encrypting data, the decryption fails.

If you use a symmetric key for decryption, you do not need to provide the key ID and encryption algorithm. KMS stores the information as ciphertext. KMS cannot store metadata in the ciphertext generated using an asymmetric key. A standard asymmetric key ciphertext does not contain configurable fields.

Calling Method

For details, see Calling APIs.

URI

POST /v1.0/{project_id}/kms/encrypt-data

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition Project ID. For details, see Obtaining a Project ID. Constraints N/A Range The value returned by the IAM API is used, which contains 32 characters. Default Value N/A

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Definition User token. It can be obtained by calling the IAM API. The value of X-Subject-Token in the response header is the user token. Constraints N/A Range Obtain the value by calling the IAM API for obtaining the user token. Default Value N/A

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
key_id	Yes	String	Definition Key ID Constraints The value must be a 36-byte ID. The value must match the regular expression ^[0-9a-z]{8}-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{12}$. Range N/A Default Value N/A
plain_text	Yes	String	Definition Plaintext data Constraints The value must match the regular expression ^.{1,4096}$. After being converted into a byte array, the length of the value contains 1 to 4,096 bytes. Range N/A Default Value N/A
encryption_algorithm	No	String	Definition Data encryption algorithm. This parameter must be specified if only an asymmetric key is used. Constraints N/A Range SYMMETRIC_DEFAULT RSAES_OAEP_SHA_256 SM2_ENCRYPT Default Value SYMMETRIC_DEFAULT
additional_authenticated_data	No	String	Definition Non-sensitive extra data used for authentication Constraints Maximum length: 128 bytes Range Any string Default Value N/A
sequence	No	String	Definition A 36-byte serial number of a request message, for example, 919c82d4-8046-4722-9094-35c3c6524cff. Constraints N/A Range N/A Default Value N/A

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
key_id	String	Key ID.
cipher_text	String	Definition Encrypted ciphertext Range N/A

Example Requests

Encrypt the plaintext hello world using the CMK whose ID is 0d0466b0-e727-4d9c-b35d-f84bb474a37f and add 123aad as the associated data. The data encryption algorithm is SYMMETRIC_DEFAULT.

{
  "key_id" : "0d0466b0-e727-4d9c-b35d-f84bb474a37f",
  "plain_text" : "hello world",
  "encryption_algorithm" : "SYMMETRIC_DEFAULT",
  "additional_authenticated_data" : "123aad"
}

Example Responses

Status code: 200

Request succeeded.

{
  "key_id" : "bb6a3d22-dc93-47ac-b5bd-88df7ad35f1e",
  "cipher_text" : "AgDoAG7EsEc2OHpQxz4gDFDH54CqwaelpTdEl+RFXXX..."
}

Status Codes

Status Code	Description
200	Request succeeded.

Error Codes

See Error Codes.

Parent Topic: Small-Size Data Encryption and Decryption