KMS API

The following explains how to use the KakaoCloud Key Management Service (KMS) API.

info

This guide documents the existing KMS API. For new KMS API integrations on KakaoCloud Public Cloud, use the endpoint and request/response schema provided in the OpenAPI documentation. The OpenAPI may differ from this guide in available API scope and endpoint.

Key information

IAM role management

KMS follows KakaoCloud’s IAM role-based access control (RBAC). It verifies the user’s token within a project, and API permissions are granted according to the assigned role.

Project roles

Role	Project Admin	Project Member	Project Reader	KMS Manager	KMS Viewer
Data key creation	✓	✓		✓
Data encryption	✓	✓		✓
Data decryption	✓	✓		✓
Data signing	✓	✓		✓
Signature verification	✓	✓		✓
HMAC creation	✓	✓		✓
HMAC verification	✓	✓		✓

Keys

The following are APIs related to secrets.

Generate data key

Generates a new data key using the specified KMS key. This is available only when the default version of the key is in the Active state.
A new data key is generated with each request.

caution

• A data key is encrypted with a master key and consists of the format "KMS prefix + ciphertext".
  The KMS prefix is defined as kckms:version format, and decryption is processed based on the specified key version.
  Therefore, the ciphertext must include the correct KMS prefix, otherwise it cannot be decrypted properly.
  Do not remove or modify the returned encrypted data—manage it exactly as provided.

Request

Query Data Key Request Example

curl --location --request POST 'https://kms.kr-central-2.kakaocloud.com/api/v1/keys/{key_id}/data-key' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/json'

API call

Method	Request URL
POST	https://kms.kr-central-2.kakaocloud.com/api/v1/keys/{key_id}/data-key

Path parameter

Parameter	Type	Required	Description
key_id	string	Yes	Unique key ID

Request header

Header	Type	Required	Description
X-Auth-Token	string	Yes	User authentication token
Content-Type	string	Yes	application/json

Request body

Query Data Key Request Body

This API does not use a request body.

Response

Query Data Key Response

{
  "code": "string",
  "message": "string",
  "data": {
    "plaintext": "string",
    "ciphertext": "string"
  },
  "requestId": "string"
}

Response elements

Field	Type	Description
code	string	Response code for the API request.
message	string	Response message for the API request.
data	object	Object containing the data key.
data.plaintext	string	Base64-encoded plaintext data key. Use it immediately for encryption, and delete it from memory immediately after use. Do not store it permanently.
data.ciphertext	string	Data key encrypted with the KMS key. Store it with the encrypted data in a secure repository, such as a database, and pass it to the decryption API when decryption is required.
requestId	string	Identifier of the API request.

Status codes

Code	Response	Description
200	OK	Success
400	Bad Request	Invalid request - Check error message and correct the request
403	Forbidden	Authenticated, but no permission for the requested resource or action - Verify you are using the correct account or project with the appropriate permissions
404	Not Found	Resource not found - Check tag_id information
500	Internal Server Error	Internal server error - Retry later

Encrypt data

Encrypts data using a symmetric key intended for encryption and decryption. This is available only when the default version of the key is in the Active state.

caution

The maximum size of data that can be encrypted is 4 KB. Additional Authenticated Data (AAD) can be up to 64 KB.

Request

Encrypt Data Request Example

curl --location --request POST 'https://kms.kr-central-2.kakaocloud.com/api/v1/keys/{key_id}/encrypt' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "input": "string",
  "aad": "string"
}'

API call

Method	Request URL
POST	https://kms.kr-central-2.kakaocloud.com/api/v1/keys/{key_id}/encrypt

Path parameter

Parameter	Type	Required	Description
key_id	string	Yes	Unique key ID

Request header

Header	Type	Required	Description
X-Auth-Token	string	Yes	User authentication token
Content-Type	string	Yes	application/json

Request body

Encrypt Data Request Body

{
  "input": "string",
  "aad": "string"
}

Request element	Type	Required	Description
input	string	Yes	Data to encrypt (up to 4 KB)
aad	string	No	Additional Authenticated Data (up to 64 KB)

Response

Encrypt Data Response

{
  "code": "string",
  "message": "string",
  "data": {
    "ciphertext": "string",
    "version": integer
  },
  "requestId": "string"
}

Response elements

Field	Type	Description
code	string	Response code for the API request.
message	string	Response message for the API request.
data	object	Object containing the encrypted data.
data.ciphertext	string	Base64-encoded ciphertext.
data.version	integer	Version of the key used for encryption.
requestId	string	Identifier of the API request.

Status codes

Code	Response	Description
200	OK	Success
400	Bad Request	Invalid request - Check error message and correct the request
403	Forbidden	Authenticated, but no permission for the requested resource or action - Verify you are using the correct account or project with the appropriate permissions
404	Not Found	Resource not found - Check tag_id information
500	Internal Server Error	Internal server error - Retry later

Decrypt data

Decrypts encrypted data using a symmetric key intended for encryption and decryption. This is available only when the default version of the key is in the Active or Deactivated state.

Request

Decrypt Data Request Example

curl --location --request POST 'https://kms.kr-central-2.kakaocloud.com/api/v1/keys/{key_id}/decrypt' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "ciphertext": "string",
  "aad": "string"
}'

API call

Method	Request URL
POST	https://kms.kr-central-2.kakaocloud.com/api/v1/keys/{key_id}/decrypt

Path parameter

Parameter	Type	Required	Description
key_id	string	Yes	Unique key ID

Request header

Header	Type	Required	Description
X-Auth-Token	string	Yes	User authentication token
Content-Type	string	Yes	application/json

Request body

Decrypt Data Request Body

{
  "ciphertext": "string",
  "aad": "string"
}

Request element	Type	Required	Description
ciphertext	string	Yes	Encrypted data
aad	string	No	Additional Authenticated Data (AAD)

Response

Decrypt Data Response

{
  "code": "string",
  "message": "string",
  "data": {
    "plaintext": "string"
  },
  "requestId": "string"
}

Response elements

Field	Type	Description
code	string	Response code for the API request.
message	string	Response message for the API request.
data	object	Object containing the decrypted data.
data.plaintext	string	Decrypted plaintext string.
requestId	string	Identifier of the API request.

Status codes

Code	Response	Description
200	OK	Success
400	Bad Request	Invalid request - Check error message and correct the request
403	Forbidden	Authenticated, but no permission for the requested resource or action - Verify you are using the correct account or project with the appropriate permissions
404	Not Found	Resource not found - Check tag_id information
500	Internal Server Error	Internal server error - Retry later

Generate data signature

Signs data using an asymmetric key intended for digital signing and verification. This is available only when the default version of the key is in the Active state.

caution

The data to be signed must be a Base64-encoded string and cannot exceed 4 KB.

Request

Sign Data Request Example

curl --location --request POST 'https://kms.kr-central-2.kakaocloud.com/api/v1/keys/{key_id}/sign' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "content": "string"
}'

API call

Method	Request URL
POST	https://kms.kr-central-2.kakaocloud.com/api/v1/keys/{key_id}/sign

Path parameter

Parameter	Type	Required	Description
key_id	string	Yes	Unique key ID

Request header

Header	Type	Required	Description
X-Auth-Token	string	Yes	User authentication token
Content-Type	string	Yes	application/json

Request body

Sign Data Request Body

{
  "content": "string"
}

Request element	Type	Required	Description
content	string	Yes	Original data to be signed (Base64-encoded string), up to 4 KB

Response

Sign Data Response

{
  "code": "string",
  "message": "string",
  "data": {
    "signature": "string"
  },
  "requestId": "string"
}

Response elements

Field	Type	Description
code	string	Response code for the API request.
message	string	Response message for the API request.
data	object	Object containing the signed data.
data.signature	string	The generated signature value.
requestId	string	Identifier of the API request.

Status codes

Code	Response	Description
200	OK	Success
400	Bad Request	Invalid request - Check error message and correct the request
403	Forbidden	Authenticated, but no permission for the requested resource or action - Verify you are using the correct account or project with the appropriate permissions
404	Not Found	Resource not found - Check tag_id information
500	Internal Server Error	Internal server error - Retry later

Verify data signature

Verifies signed data using an asymmetric key intended for digital signing and verification. This is available only when the default version of the key is in the Active or Deactivated state.

Request

Verify Signature Request Example

curl --location --request POST 'https://kms.kr-central-2.kakaocloud.com/api/v1/keys/{key_id}/sign/verify' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "input": "string",
  "output": "string"
}'

API call

Method	Request URL
POST	https://kms.kr-central-2.kakaocloud.com/api/v1/keys/{key_id}/sign/verify

Path parameter

Parameter	Type	Required	Description
key_id	string	Yes	Unique key ID

Request header

Header	Type	Required	Description
X-Auth-Token	string	Yes	User authentication token
Content-Type	string	Yes	application/json

Request body

Verify Signature Request Body

{
  "input": "string",
  "output": "string"
}

Request element	Type	Required	Description
input	string	Yes	Original data to verify the signature (Base64-encoded string)
output	string	Yes	Signature generated with the specified key from the input value

Response

Verify Signature Response

{
  "code": "string",
  "message": "string",
  "data": boolean,
  "requestId": "string"
}

Response elements

Field	Type	Description
code	string	Response code for the API request.
message	string	Response message for the API request.
data	boolean	Result of signature verification true: success, false: failure
requestId	string	Identifier of the API request.

Status codes

Code	Response	Description
200	OK	Success
400	Bad Request	Invalid request - Check error message and correct the request
403	Forbidden	Authenticated, but no permission for the requested resource or action - Verify you are using the correct account or project with the appropriate permissions
404	Not Found	Resource not found - Check tag_id information
500	Internal Server Error	Internal server error - Retry later

Create HMAC

Generates an HMAC using a symmetric key intended for MAC signing and verification. This is available only when the default version of the key is in the Active state.

caution

The original data used for HMAC generation must be Base64-encoded and cannot exceed 4 KB.

Request

Create HMAC Request Example

curl --location --request POST 'https://kms.kr-central-2.kakaocloud.com/api/v1/keys/{key_id}/hmac' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "content": "string"
}'

API call

Method	Request URL
POST	https://kms.kr-central-2.kakaocloud.com/api/v1/keys/{key_id}/hmac

Path parameter

Parameter	Type	Required	Description
key_id	string	Yes	Unique key ID

Request header

Header	Type	Required	Description
X-Auth-Token	string	Yes	User authentication token
Content-Type	string	Yes	application/json

Request body

Create HMAC Request Body

{
  "content": "string"
}

Request element	Type	Required	Description
content	string	Yes	Original data for HMAC generation (Base64-encoded string), up to 4 KB

Response

Create HMAC Response

{
  "code": "string",
  "message": "string",
  "data": {
    "hmac": "string"
  },
  "requestId": "string"
}

Response elements

Field	Type	Description
code	string	Response code for the API request.
message	string	Response message for the API request.
data	object	Object containing the HMAC data.
data.hmac	string	The generated HMAC authentication code.
requestId	string	Identifier of the API request.

Status codes

Code	Response	Description
200	OK	Success
400	Bad Request	Invalid request - Check error message and correct the request
403	Forbidden	Authenticated, but no permission for the requested resource or action - Verify you are using the correct account or project with the appropriate permissions
404	Not Found	Resource not found - Check tag_id information
500	Internal Server Error	Internal server error - Retry later

Verify HMAC

Verifies an HMAC code generated with a symmetric key intended for MAC signing and verification. This is available only when the default version of the key is in the Active or Deactivated state.

Request

Verify HMAC Request Example

curl --location --request POST 'https://kms.kr-central-2.kakaocloud.com/api/v1/keys/{key_id}/hmac/verify' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "input": "string",
  "output": "string"
}'

API call

Method	Request URL
POST	https://kms.kr-central-2.kakaocloud.com/api/v1/keys/{key_id}/hmac/verify

Path parameter

Parameter	Type	Required	Description
key_id	string	Yes	Unique key ID

Request header

Header	Type	Required	Description
X-Auth-Token	string	Yes	User authentication token
Content-Type	string	Yes	application/json

Request body

Verify HMAC Request Body

{
  "input": "string",
  "output": "string"
}

Request element	Type	Required	Description
input	string	Yes	Original data to verify the HMAC (Base64-encoded string)
output	string	Yes	HMAC authentication code generated from the input with the specified key (Base64-encoded string)

Response

Verify HMAC Response

{
  "code": "string",
  "message": "string",
  "data": boolean,
  "requestId": "string"
}

Response elements

Field	Type	Description
code	string	Response code for the API request.
message	string	Response message for the API request.
data	boolean	Result of HMAC verification true: verification success, false: verification failure
requestId	string	Identifier of the API request.

Status codes

Code	Response	Description
200	OK	Success
400	Bad Request	Invalid request - Check error message and correct the request
403	Forbidden	Authenticated, but no permission for the requested resource or action - Verify you are using the correct account or project with the appropriate permissions
404	Not Found	Resource not found - Check tag_id information
500	Internal Server Error	Internal server error - Retry later