KMS 개요

Prev Next

Classic/VPC 환경에서 이용 가능합니다.

Key Management Service는 암호화 운영 및 구현에 필수적인 암호 키 관리 기능을 제공하는 네이버 클라우드 플랫폼의 서비스입니다. Key Management Service에서는 암호화와 복호화를 비롯한 여러 키 관리 기능에 대한 API를 RESTful 형태로 제공합니다.

Key Management Service 공통 설정

Key Management Service API에서 공통으로 사용하는 요청 형식과 응답 형식을 설명합니다.

요청

공통 요청 형식을 설명합니다.

API URL

요청 API URL은 다음과 같습니다.

API Gateway request signature v1: https://kms.apigw.gov-ntruss.com/keys/v1
API Gateway request signature v2: https://kms.apigw.gov-ntruss.com/keys/v2

요청 헤더

요청 헤더에 대한 설명은 다음과 같습니다.

  • API Gateway request signature v1 방식 요청

    필드 필수 여부 설명
    x-ncp-apigw-timestamp Required 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간(밀리초)
  • API Gateway 서버와 5분 이상 시간차 발생 시 유효하지 않은 요청으로 간주
    		•
    x-ncp-apigw-api-key Required 네이버 클라우드 플랫폼의 API Gateway 서비스에서 발급받은 키
    x-ncp-iam-access-key Required 네이버 클라우드 플랫폼에서 발급받은 Access Key
  • Access Key 발급 및 확인: 인증키 생성 참조
  • 서브 계정의 Access Key 발급 및 확인: 서브 계정 생성 참조
    		•
    x-ncp-apigw-signature-v1 Required 네이버 클라우드 플랫폼에서 발급받은 Access Key에 맵핑되는 Secret Key 및 HMAC 암호화 알고리즘(HmacSHA256)으로 요청 정보를 암호화한 후 Base64로 인코딩한 서명
  • Secret Key 발급 및 확인: 인증키 생성 참조
  • 서명 생성: 시그니처 생성 참조
    		•

  • API Gateway request signature v2 방식 요청

    필드 필수 여부 설명
    x-ncp-apigw-timestamp Required 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간(밀리초)
  • API Gateway 서버와 5분 이상 시간차 발생 시 유효하지 않은 요청으로 간주
    		•
    x-ncp-iam-access-key Required 네이버 클라우드 플랫폼에서 발급받은 Access Key
  • Access Key 발급 및 확인: 인증키 생성 참조
  • 서브 계정의 Access Key 발급 및 확인: 서브 계정 생성 참조
    		•
    x-ncp-apigw-signature-v2 Required 네이버 클라우드 플랫폼에서 발급받은 Access Key에 맵핑되는 Secret Key 및 HMAC 암호화 알고리즘(HmacSHA256)으로 요청 정보를 암호화한 후 Base64로 인코딩한 서명
  • Secret Key 발급 및 확인: 인증키 생성 참조
  • 서명 생성: 시그니처 생성 참조
    		•

응답

공통 응답 형식을 설명합니다.

응답 상태 코드

응답 상태 코드에 대한 설명은 다음과 같습니다.

HTTP 상태 코드 코드 메시지 설명
200 - success 성공
참고

네이버 클라우드 플랫폼에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 Ncloud API 응답 상태 코드를 참조해 주십시오.

오류 구문

요청 처리 결과 오류 구문에 대한 설명은 다음과 같습니다.

필드 타입 필수 여부 설명
error Object - 오류 정보
error.errorCode String - 오류 코드
error.message String - 오류 메시지
error.details String - 오류에 대한 상세 정보 
{
    "error": {
        "errorCode": "300",
        "message": "Not Found Exception",
        "details": "URL not found."
    }
}

상태 코드가 200 OK이더라도 결과적으로 실패한 오류 구문에 대한 설명은 다음과 같습니다.

필드 타입 필수 여부 설명
code String - 오류 코드
msg String - 오류 메시지
data Object - 응답 결과
  • null 값으로 표시
  • <예시> 유효하지 않은 요청 데이터 입력
{
    "code": "NOT_VALID_INPUT",
    "msg": "Fail: not valid input",
    "data": null
}
주의

Key Management Service는 API 단위로 요청 속도 제어를 적용하고 있습니다. Encrypt/Decrypt API 기준으로 초당 약 300건(300 TPS) 내외의 요청을 처리하며, 초과되는 요청은 자동으로 필터링됩니다. 이 경우, HTTP 상태 코드 429가 응답됩니다.

Key Management Service API

Key Management Service API 서비스에서 제공하는 API에 대한 설명은 다음과 같습니다.

API 설명
Encrypt 키의 현재 버전으로 데이터 암호화
Decrypt 키로 암호문 복호화
Create Custom Key 암호 키로 사용할 임의의 원시 키(raw key) 생성
Re-encrypt 암호문을 지정된 마스터 키의 가장 최신 버전으로 재암호화
Sign 데이터의 서명값 생성
Verify 데이터와 서명값 비교하여 검증 결과 반환

Key Management Service 연관 리소스

Key Management Service API에 대한 사용자의 이해를 돕기 위해 다양한 연관 리소스를 제공하고 있습니다.