KMS API

카카오클라우드 KMS(Key Management Service)의 API 사용 방법은 다음과 같습니다.

주요 정보

IAM 기반 역할 관리

KMS는 카카오클라우드의 IAM 역할 기반 액세스 제어(RBAC)를 따릅니다. 사용자 토큰으로 프로젝트 내 역할을 확인하며, 역할에 따라 API 사용 권한이 부여됩니다.

프로젝트 역할

역할	프로젝트 관리자 (Admin)	프로젝트 멤버 (Member)	KMS 매니저 (Manager)	KMS 사용자 (User)
데이터 키 생성	✓	✓	✓	✓
데이터 암호화	✓	✓	✓	✓
데이터 복호화	✓	✓	✓	✓
데이터 서명	✓	✓	✓	✓
데이터 서명 검증	✓	✓	✓	✓
HMAC 생성	✓	✓	✓	✓
HMAC 검증	✓	✓	✓	✓

키

키 관련 API는 다음과 같습니다.

데이터 키 생성

지정된 KMS 키를 사용하여 새로운 데이터 키를 생성합니다. 단, 기본 버전 상태가 운영인 경우에만 데이터 키 생성이 가능합니다.
호출 시마다 새로운 데이터 키가 생성됩니다.

주의

데이터 키는 KMS 키의 정보와 함께 KMS prefix + 암호문 형태로 구성됩니다.
KMS prefix는 kckms:버전정보 형식으로 정의되고, 복호화 시 지정된 키 버전에 따라 처리됩니다.
암호문과 함께 KMS prefix가 반드시 정확히 포함되어야 하며, 그렇지 않으면 올바르게 복호화할 수 없습니다.
반환된 암호화 데이터는 임의로 제거하거나 수정하지 말고, 제공된 형태 그대로 관리해 주십시오.
plaintext(평문 데이터 키)는 암호화 작업 직후 메모리에서 즉시 삭제하고, 영구 저장하지 마십시오.
ciphertext(암호화된 데이터 키)는 암호화한 데이터와 함께 안전한 저장소(예: DB)에 보관하고, 복호화 시에만 사용하십시오.

Request

데이터 키 생성 Request 예시
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 호출 방식

메서드	요청 URL
POST	`https://kms.kr-central-2.kakaocloud.com/api/v1/keys/{key_id}/data-key`

Path Parameter

Parameter	유형	필수 여부	설명
`key_id`	string	필수	키의 고유 ID

Request Header

Request Header	유형	필수 여부	설명
`X-Auth-Token`	string	필수	사용자 인증 토큰 입력
`Content-Type`	string	필수	`application/json`

Request Body

데이터 키 생성 Request Body
이 API는 요청 본문을 사용하지 않습니다.

Response

데이터 키 생성 Response
{
  "code": "string",
  "message": "string",
  "data": {
    "plaintext": "string",
    "ciphertext": "string"
  },
  "requestId": "string"
}

Response Elements

필드명	유형	설명
`code`	string	API 요청의 응답 코드를 나타냅니다.
`message`	string	API 요청의 응답 메시지를 나타냅니다.
`data`	object	생성된 데이터 키 정보를 담은 객체입니다.
`data.plaintext`	string	Base64로 인코딩된 평문 데이터 키입니다. 암호화에 즉시 사용하며, 사용 후 메모리에서 즉시 삭제하십시오. 영구 저장하시 마십시오.
`data.ciphertext`	string	KMS 키로 암호화된 데이터 키입니다. 암호화된 데이터와 함께 DB 등 안전한 저장소에 보관하고 복호화가 필요할 때 복호화 API에 전달하시기 바랍니다.
`requestId`	string	API 요청의 식별자를 나타냅니다.

상태 코드

코드	응답 내용	설명
`200`	OK	성공
`400`	Bad Request	유효하지 않은 요청 - 에러 메시지를 참고하여 요청 수정
`403`	Forbidden	인증은 성공했으나 요청한 리소스 또는 작업에 대한 권한 없음 - 올바른 권한이 부여된 계정 또는 프로젝트로 요청했는지 확인 필요
`404`	Not Found	존재하지 않는 키 - `key_id` 정보 확인 필요
`500`	Internal Server Error	내부 서버 에러 - 잠시 후 재요청 요망

데이터 암호화

대칭 유형이면서 대칭 암복호화 용도의 키로 데이터 암호화를 할 수 있습니다. 키의 기본 버전의 상태가 운영 상태일 경우만 가능합니다.

주의

암호화할 데이터는 최대 4KB까지만 가능하며 추가 인증 데이터(Additional Authenticated Data)는 64KB까지 가능합니다.

Request

데이터 암호화 Request 예시
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 호출 방식

메서드	요청 URL
POST	`https://kms.kr-central-2.kakaocloud.com/api/v1/keys/{key_id}/encrypt`

Path Parameter

Parameter	유형	필수 여부	설명
`key_id`	string	필수	키의 고유 ID

Request Header

Request Header	유형	필수 여부	설명
`X-Auth-Token`	string	필수	사용자 인증 토큰 입력
`Content-Type`	string	필수	`application/json`

Request Body

데이터 암호화 Request Body
{
  "input": "string",
  "aad": "string"
}

Request Elements	유형	필수 여부	설명
`input`	string	필수	암호화할 데이터 (최대 4KB 데이터 암호화 가능)
`aad`	string	선택	추가 인증 데이터 (Additional Authenticated Data) 64KB까지 가능

Response

데이터 암호화 Response
{
  "code": "string",
  "message": "string",
  "data": {
    "ciphertext": "string",
    "version": integer
  },
  "requestId": "string"
}

Response Elements

필드명	유형	설명
`code`	string	API 요청의 응답 코드를 나타냅니다.
`message`	string	API 요청의 응답 메시지를 나타냅니다.
`data`	object	암호화 데이터를 담은 객체를 나타냅니다.
`data.ciphertext`	string	Base64로 인코딩된 암호화 데이터로 나타냅니다.
`data.version`	integer	암호화에 사용된 키의 버전 번호를 나타냅니다.
`requestId`	string	API 요청의 식별자를 나타냅니다.

상태 코드

코드	응답 내용	설명
`200`	OK	성공
`400`	Bad Request	유효하지 않은 요청 - 에러 메시지를 참고하여 요청 수정
`403`	Forbidden	인증은 성공했으나 요청한 리소스 또는 작업에 대한 권한 없음 - 올바른 권한이 부여된 계정 또는 프로젝트로 요청했는지 확인 필요
`404`	Not Found	존재하지 않는 키 - `key_id` 정보 확인 필요
`500`	Internal Server Error	내부 서버 에러 - 잠시 후 재요청 요망

데이터 복호화

대칭 유형이면서 대칭 암복호화 용도의 키와 암호화된 데이터로 복호화를 할 수 있습니다. 키의 기본 버전의 상태가 운영 상태일 경우만 가능합니다.

Request

데이터 복호화 Request 예시
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 호출 방식

메서드	요청 URL
POST	`https://kms.kr-central-2.kakaocloud.com/api/v1/keys/{key_id}/decrypt`

Path Parameter

Parameter	유형	필수 여부	설명
`key_id`	string	필수	키의 고유 ID

Request Header

Request Header	유형	필수 여부	설명
`X-Auth-Token`	string	필수	사용자 인증 토큰 입력
`Content-Type`	string	필수	`application/json`

Request Body

데이터 복호화 Request Body
{
  "ciphertext": "string",
  "aad": "string"
}

Request Elements	유형	필수 여부	설명
`ciphertext`	string	필수	암호화된 데이터
`aad`	string	선택	추가 인증 데이터 (Additional Authenticated Data)

Response

데이터 복호화 Response
{
  "code": "string",
  "message": "string",
  "data": {
    "plaintext": "string"
  },
  "requestId": "string"
}

Response Elements

필드명	유형	설명
`code`	string	API 요청의 응답 코드를 나타냅니다.
`message`	string	API 요청의 응답 메시지를 나타냅니다.
`data`	object	복호화된 데이터를 담은 객체를 나타냅니다.
`data.plaintext`	string	복호화된 문자열 데이터를 나타냅니다.
`requestId`	string	API 요청의 식별자를 나타냅니다.

상태 코드

코드	응답 내용	설명
`200`	OK	성공
`400`	Bad Request	유효하지 않은 요청 - 에러 메시지를 참고하여 요청 수정
`403`	Forbidden	인증은 성공했으나 요청한 리소스 또는 작업에 대한 권한 없음 - 올바른 권한이 부여된 계정 또는 프로젝트로 요청했는지 확인 필요
`404`	Not Found	존재하지 않는 키 - `key_id` 정보 확인 필요
`500`	Internal Server Error	내부 서버 에러 - 잠시 후 재요청 요망

데이터 서명

비대칭 유형이면서 디지털 서명/확인 용도의 키로 데이터 서명을 할 수 있습니다. 키의 기본 버전의 상태가 운영 상태일 경우만 가능합니다.

주의

서명할 데이터는 Base64로 인코딩된 문자열이어야 하며 최대 4KB까지만 가능합니다.

Request

데이터 서명 Request 예시
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 호출 방식

메서드	요청 URL
POST	`https://kms.kr-central-2.kakaocloud.com/api/v1/keys/{key_id}/sign`

Path Parameter

Parameter	유형	필수 여부	설명
`key_id`	string	필수	키의 고유 ID

Request Header

Request Header	유형	필수 여부	설명
`X-Auth-Token`	string	필수	사용자 인증 토큰 입력
`Content-Type`	string	필수	`application/json`

Request Body

데이터 서명 Request Body
{
  "content": "string"
}

Request Elements	유형	필수 여부	설명
`content`	string	필수	서명에 사용할 원문 데이터(Base64 인코딩 문자열) 최대 4KB 가능

Response

데이터 서명 Response
{
  "code": "string",
  "message": "string",
  "data": {
    "signature": "string"
  },
  "requestId": "string"
}

Response Elements

필드명	유형	설명
`code`	string	API 요청의 응답 코드를 나타냅니다.
`message`	string	API 요청의 응답 메시지를 나타냅니다.
`data`	object	서명된 데이터를 담은 객체를 나타냅니다.
`data.signature`	string	서명값을 나타냅니다.
`requestId`	string	API 요청의 식별자를 나타냅니다.

상태 코드

코드	응답 내용	설명
`200`	OK	성공
`400`	Bad Request	유효하지 않은 요청 - 에러 메시지를 참고하여 요청 수정
`403`	Forbidden	인증은 성공했으나 요청한 리소스 또는 작업에 대한 권한 없음 - 올바른 권한이 부여된 계정 또는 프로젝트로 요청했는지 확인 필요
`404`	Not Found	존재하지 않는 키 - `key_id` 정보 확인 필요
`500`	Internal Server Error	내부 서버 에러 - 잠시 후 재요청 요망

서명 검증

비대칭 유형이면서 디지털 서명/확인 용도의 키로 서명된 데이터를 검증할 수 있습니다. 키의 기본 버전의 상태가 운영 상태일 경우만 가능합니다.

Request

서명 검증 Request 예시
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 호출 방식

메서드	요청 URL
POST	`https://kms.kr-central-2.kakaocloud.com/api/v1/keys/{key_id}/sign/verify`

Path Parameter

Parameter	유형	필수 여부	설명
`key_id`	string	필수	키의 고유 ID

Request Header

Request Header	유형	필수 여부	설명
`X-Auth-Token`	string	필수	사용자 인증 토큰 입력
`Content-Type`	string	필수	`application/json`

Request Body

서명 검증 Request Body
{
  "input": "string",
  "output": "string"
}

Request Elements	유형	필수 여부	설명
`input`	string	필수	데이터 서명 검증에 사용할 원문 데이터(Base64 인코딩 문자열)
`output`	string	필수	`input` 값과 지정된 키로 생성한 데이터 서명

Response

서명 검증 Response
{
  "code": "string",
  "message": "string",
  "data": boolean,
  "requestId": "string"
}

Response Elements

필드명	유형	설명
`code`	string	API 요청의 응답 코드를 나타냅니다.
`message`	string	API 요청의 응답 메시지를 나타냅니다.
`data`	boolean	데이터 서명 검증 결과 true: 검증 성공, false: 검증 실패
`requestId`	string	API 요청의 식별자를 나타냅니다.

상태 코드

코드	응답 내용	설명
`200`	OK	성공
`400`	Bad Request	유효하지 않은 요청 - 에러 메시지를 참고하여 요청 수정
`403`	Forbidden	인증은 성공했으나 요청한 리소스 또는 작업에 대한 권한 없음 - 올바른 권한이 부여된 계정 또는 프로젝트로 요청했는지 확인 필요
`404`	Not Found	존재하지 않는 키 - `key_id` 정보 확인 필요
`500`	Internal Server Error	내부 서버 에러 - 잠시 후 재요청 요망

HMAC 생성

대칭 유형이면서 MAC 서명/확인 용도의 키로 HMAC을 생성할 수 있습니다. 키의 기본 버전의 상태가 운영 상태일 경우만 가능합니다.

주의

HMAC 생성에 사용할 원문 데이터는 Base64 인코딩 문자열로 최대 4KB까지만 가능합니다.

Request

HMAC 생성 Request 예시
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 호출 방식

메서드	요청 URL
POST	`https://kms.kr-central-2.kakaocloud.com/api/v1/keys/{key_id}/hmac`

Path Parameter

Parameter	유형	필수 여부	설명
`key_id`	string	필수	키의 고유 ID

Request Header

Request Header	유형	필수 여부	설명
`X-Auth-Token`	string	필수	사용자 인증 토큰 입력
`Content-Type`	string	필수	`application/json`

Request Body

HMAC 생성 Request Body
{
  "content": "string"
}

Request Elements	유형	필수 여부	설명
`content`	string	필수	HMAC 생성에 사용할 원문 데이터(Base64 인코딩 문자열) 최대 4KB 가능

Response

HMAC 생성 Response
{
  "code": "string",
  "message": "string",
  "data": {
    "hmac": "string"
  },
  "requestId": "string"
}

Response Elements

필드명	유형	설명
`code`	string	API 요청의 응답 코드를 나타냅니다.
`message`	string	API 요청의 응답 메시지를 나타냅니다.
`data`	object	HMAC 데이터를 담고 있는 객체를 나타냅니다.
`data.hmac`	string	HMAC 인증 코드를 나타냅니다.
`requestId`	string	API 요청의 식별자를 나타냅니다.

상태 코드

코드	응답 내용	설명
`200`	OK	성공
`400`	Bad Request	유효하지 않은 요청 - 에러 메시지를 참고하여 요청 수정
`403`	Forbidden	인증은 성공했으나 요청한 리소스 또는 작업에 대한 권한 없음 - 올바른 권한이 부여된 계정 또는 프로젝트로 요청했는지 확인 필요
`404`	Not Found	존재하지 않는 키 - `key_id` 정보 확인 필요
`500`	Internal Server Error	내부 서버 에러 - 잠시 후 재요청 요망

HMAC 검증

대칭 유형이면서 MAC 서명/확인 용도의 키로 생성된 HMAC 코드를 검증할 수 있습니다. 키의 기본 버전의 상태가 운영 상태일 경우만 가능합니다.

Request

HMAC 검증 Request 예시
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 호출 방식

메서드	요청 URL
POST	`https://kms.kr-central-2.kakaocloud.com/api/v1/keys/{key_id}/hmac/verify`

Path Parameter

Parameter	유형	필수 여부	설명
`key_id`	string	필수	키의 고유 ID

Request Header

Request Header	유형	필수 여부	설명
`X-Auth-Token`	string	필수	사용자 인증 토큰 입력
`Content-Type`	string	필수	`application/json`

Request Body

HMAC 검증 Request Body
{
  "input": "string",
  "output": "string"
}

Request Elements	유형	필수 여부	설명
`input`	string	필수	HMAC 검증에 사용할 원문 데이터(Base64 인코딩 문자열)
`output`	string	필수	`input` 값과 지정된 키로 생성한 HMAC 인증 코드(Base64 인코딩 문자열)

Response

HMAC 검증 Response
{
  "code": "string",
  "message": "string",
  "data": boolean,
  "requestId": "string"
}

Response Elements

필드명	유형	설명
`code`	string	API 요청의 응답 코드를 나타냅니다.
`message`	string	API 요청의 응답 메시지를 나타냅니다.
`data`	boolean	HMAC 인증 코드 검증 결과 true: 검증 성공, false: 검증 실패
`requestId`	string	API 요청의 식별자를 나타냅니다.

상태 코드

코드	응답 내용	설명
`200`	OK	성공
`400`	Bad Request	유효하지 않은 요청 - 에러 메시지를 참고하여 요청 수정
`403`	Forbidden	인증은 성공했으나 요청한 리소스 또는 작업에 대한 권한 없음 - 올바른 권한이 부여된 계정 또는 프로젝트로 요청했는지 확인 필요
`404`	Not Found	존재하지 않는 키 - `key_id` 정보 확인 필요
`500`	Internal Server Error	내부 서버 에러 - 잠시 후 재요청 요망

주요 정보​

IAM 기반 역할 관리​

프로젝트 역할​

키​

데이터 키 생성​

Request​

API 호출 방식​

Path Parameter​

Request Header​

Request Body​

Response​

Response Elements​

상태 코드​

데이터 암호화​

Request​

API 호출 방식​

Path Parameter​

Request Header​

Request Body​

Response​

Response Elements​

상태 코드​

데이터 복호화​

Request​

API 호출 방식​

Path Parameter​

Request Header​

Request Body​

Response​

Response Elements​

상태 코드​

데이터 서명​

Request​

API 호출 방식​

Path Parameter​

Request Header​

Request Body​

Response​

Response Elements​

상태 코드​

서명 검증​

Request​

API 호출 방식​

Path Parameter​

Request Header​

Request Body​

Response​

Response Elements​

상태 코드​

HMAC 생성​

Request​

API 호출 방식​

Path Parameter​

Request Header​

Request Body​

Response​

Response Elements​

상태 코드​

HMAC 검증​

Request​

API 호출 방식​

Path Parameter​

Request Header​

Request Body​

Response​

Response Elements​

상태 코드​

주요 정보

IAM 기반 역할 관리

프로젝트 역할

키

데이터 키 생성

Request

API 호출 방식

Path Parameter

Request Header

Request Body

Response

Response Elements

상태 코드

데이터 암호화

Request

API 호출 방식

Path Parameter

Request Header

Request Body

Response

Response Elements

상태 코드

데이터 복호화

Request

API 호출 방식

Path Parameter

Request Header

Request Body

Response

Response Elements

상태 코드

데이터 서명

Request

API 호출 방식

Path Parameter

Request Header

Request Body

Response

Response Elements

상태 코드

서명 검증

Request

API 호출 방식

Path Parameter

Request Header

Request Body

Response

Response Elements

상태 코드

HMAC 생성

Request

API 호출 방식

Path Parameter

Request Header

Request Body

Response

Response Elements

상태 코드

HMAC 검증

Request

API 호출 방식

Path Parameter

Request Header

Request Body

Response

Response Elements

상태 코드