KMS API
카카오클라우드 KMS(Key Management Service)의 API 사용 방법은 다음과 같습니다.
주요 정보
IAM 역할 관리
KMS는 카카오클라우드의 IAM 역할 기반 액세스 제어(RBAC)를 따릅니다. 사용자 토큰으로 프로젝트 내 역할을 확인하며, 역할에 따라 API 사용 권한이 부여됩니다.
프로젝트 역할
| 역할 | 프로젝트 관리자 (Admin) | 프로젝트 멤버 (Member) | 프로젝트 리더 (Reader) | KMS 매니저 (Manager) | KMS 사용자 (User) | KMS 뷰어 (Viewer) |
|---|---|---|---|---|---|---|
| 데이터 키 생성 | ✓ | ✓ | ✓ | ✓ | ||
| 데이터 암호화 | ✓ | ✓ | ✓ | ✓ | ||
| 데이터 복호화 | ✓ | ✓ | ✓ | ✓ | ||
| 데이터 서명 | ✓ | ✓ | ✓ | ✓ | ||
| 데이터 서명 검증 | ✓ | ✓ | ✓ | ✓ | ||
| HMAC 생성 | ✓ | ✓ | ✓ | ✓ | ||
| HMAC 검증 | ✓ | ✓ | ✓ | ✓ |
키
키 관련 API는 다음과 같습니다.
데이터 키 생성
지정된 KMS 키를 사용하여 새로운 데이터 키를 생성합니다. 단, 기본 버전 상태가 운영인 경우에만 데이터 키 생성이 가능합니다.
호출 시마다 새로운 데이터 키가 생성됩니다.
주의
- 데이터 키는 KMS 키의 정보와 함께
KMS 접두사 + 암호문형태로 구성됩니다. - KMS 접두사는
kckms:{버전 정보}형식으로 정의되며, 복호화할 때 지정된 키 버전에 따라 처리됩니다. - 암호문에는 KMS 접두사가 정확히 포함되어야 하며, 그렇지 않으면 올바르게 복호화할 수 없습니다.
- 반환된 암호화 데이터는 임의로 제거하거나 수정하지 말고 제공된 형태 그대로 관리하세요.
plaintext(평문 데이터 키)는 암호화 작업 직후 메모리에서 즉시 삭제하고 영구 저장하지 마세요.ciphertext(암호화된 데이터 키)는 암호화한 데이터와 함께 안전한 저장소(예: DB)에 보관하고 복호화할 때만 사용하세요.
Request
데이터 키 생성 Request 예시
curl --location --request POST 'https://kms.kr-gov-central-1.kakaocloud-kr-gov.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-gov-central-1.kakaocloud-kr-gov.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
이 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 | 유효하지 않은 요청 - 에러 메시지를 참고하여 요청 수정 |
401 | Unauthorized | 유효하지 않거나 만료된 인증 토큰 - X-Auth-Token 헤더 정보 확인 요망 |
403 | Forbidden | 인증은 성공했으나 요청한 리소스 또는 작업에 대한 권한 없음 - 올바른 권한이 부여된 계정 또는 프로젝트로 요청했는지 확인 필요 |
404 | Not Found | 존재하지 않는 키 - key_id 정보 확인 필요 |
405 | Method Not Allowed | 허용되지 않은 HTTP 메서드 요청 - API의 HTTP 메서드(GET, POST 등) 확인 요망 |
409 | Conflict | 요청 처리 중 현재 리소스 상태와 충돌 발생 - 에러 메시지를 참고하여 요청 수정 |
500 | Internal Server Error | 내부 서버 에러 - 잠시 후 재요청 요망 |
데이터 암호화
대칭 유형이면서 대칭 암복호화 용도인 키로 데이터를 암호화할 수 있습니다. 키의 기본 버전이 운영 상태인 경우에만 가능합니다.
주의
암호화할 데이터는 최대 4 KB이며, 추가 인증 데이터(Additional Authenticated Data)는 최대 64 KB입니다.
Request
데이터 암호화 Request 예시
curl --location --request POST 'https://kms.kr-gov-central-1.kakaocloud-kr-gov.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-gov-central-1.kakaocloud-kr-gov.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 | 필수 | 암호화할 데이터(최대 4 KB) |
aad | string | 선택 | 추가 인증 데이터(Additional Authenticated Data, 최대 64 KB) |
Response
데이터 암호화 Response
{
"code": "string",
"message": "string",
"data": {
"ciphertext": "string",
"version": 1
},
"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 | 유효하지 않은 요청 - 에러 메시지를 참고하여 요청 수정 |
401 | Unauthorized | 유효하지 않거나 만료된 인증 토큰 - X-Auth-Token 헤더 정보 확인 요망 |
403 | Forbidden | 인증은 성공했으나 요청한 리소스 또는 작업에 대한 권한 없음 - 올바른 권한이 부여된 계정 또는 프로젝트로 요청했는지 확인 필요 |
404 | Not Found | 존재하지 않는 키 - key_id 정보 확인 필요 |
405 | Method Not Allowed | 허용되지 않은 HTTP 메서드 요청 - API의 HTTP 메서드(GET, POST 등) 확인 요망 |
409 | Conflict | 요청 처리 중 현재 리소스 상태와 충돌 발생 - 에러 메시지를 참고하여 요청 수정 |
500 | Internal Server Error | 내부 서버 에러 - 잠시 후 재요청 요망 |
데이터 복호화
대칭 유형이면서 대칭 암복호화 용도인 키로 암호화된 데이터를 복호화할 수 있습니다. 키의 기본 버전이 운영 상태인 경우에만 가능합니다.
Request
데이터 복호화 Request 예시
curl --location --request POST 'https://kms.kr-gov-central-1.kakaocloud-kr-gov.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-gov-central-1.kakaocloud-kr-gov.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 | 유효하지 않은 요청 - 에러 메시지를 참고하여 요청 수정 |
401 | Unauthorized | 유효하지 않거나 만료된 인증 토큰 - X-Auth-Token 헤더 정보 확인 요망 |
403 | Forbidden | 인증은 성공했으나 요청한 리소스 또는 작업에 대한 권한 없음 - 올바른 권한이 부여된 계정 또는 프로젝트로 요청했는지 확인 필요 |
404 | Not Found | 존재하지 않는 키 - key_id 정보 확인 필요 |
405 | Method Not Allowed | 허용되지 않은 HTTP 메서드 요청 - API의 HTTP 메서드(GET, POST 등) 확인 요망 |
409 | Conflict | 요청 처리 중 현재 리소스 상태와 충돌 발생 - 에러 메시지를 참고하여 요청 수정 |
500 | Internal Server Error | 내부 서버 에러 - 잠시 후 재요청 요망 |
데이터 서명
비대칭 유형이면서 디지털 서명/검증 용도인 키로 데이터에 서명할 수 있습니다. 키의 기본 버전이 운영 상태인 경우에만 가능합니다.
주의
서명할 데이터는 Base64로 인코딩된 문자열이어야 하며 최대 4 KB입니다.
Request
데이터 서명 Request 예시
curl --location --request POST 'https://kms.kr-gov-central-1.kakaocloud-kr-gov.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-gov-central-1.kakaocloud-kr-gov.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 인코딩 문자열, 최대 4 KB) |
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 | 유효하지 않은 요청 - 에러 메시지를 참고하여 요청 수정 |
401 | Unauthorized | 유효하지 않거나 만료된 인증 토큰 - X-Auth-Token 헤더 정보 확인 요망 |
403 | Forbidden | 인증은 성공했으나 요청한 리소스 또는 작업에 대한 권한 없음 - 올바른 권한이 부여된 계정 또는 프로젝트로 요청했는지 확인 필요 |
404 | Not Found | 존재하지 않는 키 - key_id 정보 확인 필요 |
405 | Method Not Allowed | 허용되지 않은 HTTP 메서드 요청 - API의 HTTP 메서드(GET, POST 등) 확인 요망 |
409 | Conflict | 요청 처리 중 현재 리소스 상태와 충돌 발생 - 에러 메시지를 참고하여 요청 수정 |
500 | Internal Server Error | 내부 서버 에러 - 잠시 후 재요청 요망 |
서명 검증
비대칭 유형이면서 디지털 서명/검증 용도인 키로 서명된 데이터를 검증할 수 있습니다. 키의 기본 버전이 운영 상태인 경우에만 가능합니다.
Request
서명 검증 Request 예시
curl --location --request POST 'https://kms.kr-gov-central-1.kakaocloud-kr-gov.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-gov-central-1.kakaocloud-kr-gov.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": true,
"requestId": "string"
}
Response Elements
| 필드명 | 유형 | 설명 |
|---|---|---|
code | string | API 요청의 응답 코드를 나타냅니다. |
message | string | API 요청의 응답 메시지를 나타냅니다. |
data | boolean | 데이터 서명 검증 결과 true: 검증 성공, false: 검증 실패 |
requestId | string | API 요청의 식별자를 나타냅니다. |
상태 코드
| 코드 | 응답 내용 | 설명 |
|---|---|---|
200 | OK | 성공 |
400 | Bad Request | 유효하지 않은 요청 - 에러 메시지를 참고하여 요청 수정 |
401 | Unauthorized | 유효하지 않거나 만료된 인증 토큰 - X-Auth-Token 헤더 정보 확인 요망 |
403 | Forbidden | 인증은 성공했으나 요청한 리소스 또는 작업에 대한 권한 없음 - 올바른 권한이 부여된 계정 또는 프로젝트로 요청했는지 확인 필요 |
404 | Not Found | 존재하지 않는 키 - key_id 정보 확인 필요 |
405 | Method Not Allowed | 허용되지 않은 HTTP 메서드 요청 - API의 HTTP 메서드(GET, POST 등) 확인 요망 |
409 | Conflict | 요청 처리 중 현재 리소스 상태와 충돌 발생 - 에러 메시지를 참고하여 요청 수정 |
500 | Internal Server Error | 내부 서버 에러 - 잠시 후 재요청 요망 |
HMAC 생성
대칭 유형이면서 MAC 생성/검증 용도인 키로 HMAC을 생성할 수 있습니다. 키의 기본 버전이 운영 상태인 경우에만 가능합니다.
주의
HMAC 생성에 사용할 원문 데이터는 Base64 인코딩 문자열로 최대 4 KB입니다.
Request
HMAC 생성 Request 예시
curl --location --request POST 'https://kms.kr-gov-central-1.kakaocloud-kr-gov.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-gov-central-1.kakaocloud-kr-gov.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 인코딩 문자열, 최대 4 KB) |
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 | 유효하지 않은 요청 - 에러 메시지를 참고하여 요청 수정 |
401 | Unauthorized | 유효하지 않거나 만료된 인증 토큰 - X-Auth-Token 헤더 정보 확인 요망 |
403 | Forbidden | 인증은 성공했으나 요청한 리소스 또는 작업에 대한 권한 없음 - 올바른 권한이 부여된 계정 또는 프로젝트로 요청했는지 확인 필요 |
404 | Not Found | 존재하지 않는 키 - key_id 정보 확인 필요 |
405 | Method Not Allowed | 허용되지 않은 HTTP 메서드 요청 - API의 HTTP 메서드(GET, POST 등) 확인 요망 |
409 | Conflict | 요청 처리 중 현재 리소스 상태와 충돌 발생 - 에러 메시지를 참고하여 요청 수정 |
500 | Internal Server Error | 내부 서버 에러 - 잠시 후 재요청 요망 |
HMAC 검증
대칭 유형이면서 MAC 생성/검증 용도인 키로 생성된 HMAC 코드를 검증할 수 있습니다. 키의 기본 버전이 운영 상태인 경우에만 가능합니다.
Request
HMAC 검증 Request 예시
curl --location --request POST 'https://kms.kr-gov-central-1.kakaocloud-kr-gov.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-gov-central-1.kakaocloud-kr-gov.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": true,
"requestId": "string"
}
Response Elements
| 필드명 | 유형 | 설명 |
|---|---|---|
code | string | API 요청의 응답 코드를 나타냅니다. |
message | string | API 요청의 응답 메시지를 나타냅니다. |
data | boolean | HMAC 인증 코드 검증 결과 true: 검증 성공, false: 검증 실패 |
requestId | string | API 요청의 식별자를 나타냅니다. |
상태 코드
| 코드 | 응답 내용 | 설명 |
|---|---|---|
200 | OK | 성공 |
400 | Bad Request | 유효하지 않은 요청 - 에러 메시지를 참고하여 요청 수정 |
401 | Unauthorized | 유효하지 않거나 만료된 인증 토큰 - X-Auth-Token 헤더 정보 확인 요망 |
403 | Forbidden | 인증은 성공했으나 요청한 리소스 또는 작업에 대한 권한 없음 - 올바른 권한이 부여된 계정 또는 프로젝트로 요청했는지 확인 필요 |
404 | Not Found | 존재하지 않는 키 - key_id 정보 확인 필요 |
405 | Method Not Allowed | 허용되지 않은 HTTP 메서드 요청 - API의 HTTP 메서드(GET, POST 등) 확인 요망 |
409 | Conflict | 요청 처리 중 현재 리소스 상태와 충돌 발생 - 에러 메시지를 참고하여 요청 수정 |
500 | Internal Server Error | 내부 서버 에러 - 잠시 후 재요청 요망 |