KMS API
The following explains how to use the Kakao Cloud Key Management Service (KMS) API.
Key information
IAM role management
KMS follows Kakao Cloud’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.
Query data key
Retrieves a symmetric key for symmetric encryption and decryption. This is only available if the default version of the key is in an active state.
caution
- A data key is encrypted with a master key and consists of the format
"KMS prefix + ciphertext".
The KMS prefix is defined askckms:versionformat, 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 DEK. |
data.ciphertext | string | Encrypted DEK. |
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 only available if the default version of the key is in an 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 only available if the default version of the key is in an active 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 |
Sign data
Signs data using an asymmetric key intended for digital signing and verification. This is only available if the default version of the key is in an 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 signature
Verifies signed data using an asymmetric key intended for digital signing and verification. This is only available if the default version of the key is in an active 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 only available if the default version of the key is in an 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 only available if the default version of the key is in an active 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 |