Updated on 2026-10-12 GMT+08:00

Encrypting a DEK

Function

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

Calling Method

For details, see Calling APIs.

URI

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

**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 If AES is used for the CMK, the value is the plaintext DEK + its SHA256 value (32 bytes). If SM4 is used for the CMK, the value is the plaintext DEK + its SM3 value (32 bytes). The values are hexadecimal strings. Combine the two parts as a string. Constraints N/A Range N/A Default Value N/A
datakey_plain_length	Yes	String	Definition Length of a plaintext DEK, in bytes Constraints N/A Range 1 to 1,024 Default Value N/A
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
pin	No	String	Definition PIN code, which is used to authenticate the DEK. This parameter is valid only in the level-4 cryptography test scenario. Constraints N/A Range N/A Default Value N/A
pin_type	No	String	Definition PIN code type Constraints N/A Range PlainText: plaintext PIN CipherText: ciphertext PIN Default Value CipherText
key_spec	No	String	Definition Type of the DEK to be encrypted Constraints This parameter is valid only in the level-4 cryptography test scenario. Range SM2 RSA 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	Definition Key ID Range N/A
cipher_text	String	Definition Hexadecimal EDK plaintext Range N/A
datakey_length	String	Definition Length of a plaintext EDK, in bytes Range N/A

Example Requests

Encrypt a 512-bit plaintext key using the key whose ID is 0d0466b0-e727-4d9c-b35d-f84bb474a37f and add 123add as the associated data.

{
  "key_id" : "0d0466b0-e727-4d9c-b35d-f84bb474a37f",
  "plain_text" : "7549d9aea901767bf3c0b3e14b10722eaf6f59053bbd82045d04e075e809a0fe6ccab48f8e5efe74e4b18ff0512525e527b10331100f357bf42125d8d5ced94ffbc8ac72b0785ca7fe33eb6776ce3990b11e32b299d9c0a9ee0305fb9540f797",
  "datakey_plain_length" : "64",
  "additional_authenticated_data" : "123aad"
}

Example Responses

Status code: 200

{
  "key_id" : "0d0466b0-e727-4d9c-b35d-f84bb474a37f",
  "datakey_length" : "64",
  "cipher_text" : "020098009EEAFCE122CAA5927D2XXX..."
}

Status Codes

Status Code	Description
200	Request succeeded.

Error Codes

See Error Codes.

Parent Topic: DEK Management