MENU
      Key Management Service 개요

        Key Management Service 개요


        기사 요약

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

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

        참고

        2024년 10월 17일 Key Management Service API 2.0이 릴리스되었습니다. Key Management Service API 1.0은 계속 제공됩니다.

        Key Management Service API 1.0Key Management Service API 2.0
        Base URL(도메인)https://kms.apigw.ntruss.comhttps://ocapi.ncloud.com
        API 종류암호화, 복호화 API 6종만 제공
        • Encrypt, Decrypt, Create Custom Key, Re-encrypt, Sign, Verify
        • 암호화, 복호화 API 6종 제공
          • Encrypt, Decrypt, Create Custom Key, Re-encrypt, Sign, Verify
        • 콘솔로 제공되는 키 관리 기능 모두 제공
        인증 방식네이버 클라우드 플랫폼 계정 정보를 이용한 사용자 인증
        • 계정 인증 API: 네이버 클라우드 플랫폼 계정 정보를 이용한 사용자 인증
        • 토큰 인증 API: 키 인증 토큰
        요청 처리 성능Encrypt API (AES) 기준 시스템 최대 200 TPS
        • 모든 키가 200 TPS 처리 성능을 공유
        Encrypt API (AES) 기준 키별 최대 300 TPS
        • 모든 키에 대해 각각 최대 300 TPS의 처리 성능을 개별적으로 보장
        가용성 보장리전 한정 고가용성(HA)
        • 네이버 클라우드 플랫폼 리전 장애 시 암호화, 복호화, 서명, 검증 등의 API에 영향이 있음
        크로스 리전 고가용성(HA)
        • 네이버 클라우드 플랫폼 리전 장애에 영향 없이 암호화, 복호화, 서명, 검증 등의 API에 대해 무중단 동작 보장
        요청 접근 제어Sub Account 서비스에서 제공하는 부계정 단위의 IP ACL 기능을 이용
        • Sub Account 서비스에서 제공하는 부계정 단위의 IP ACL 기능
        • 토큰 단위로 설정 가능한 IP ACL

        Key Management Service API 1.0 공통 설정

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

        요청

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

        API URL

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

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

        요청 헤더

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

        • API Gateway request signature v1 방식 요청

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

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

        응답

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

        응답 상태 코드

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

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

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

        오류 구문

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

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

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

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

        Key Management Service API 2.0 공통 설정

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

        요청

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

        API URL

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

        https://ocapi.ncloud.com/kms/v1
        HTTP

        요청 헤더

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

        • 계정 인증(Account Auth) 방식 요청

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

          필드필수 여부설명
          x-ncp-ocapi-tokenRequiredKey Management Service에서 생성한 키의 액세스 토큰(Access Token) 또는 리프레시 토큰(Refresh Token)

        응답

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

        응답 상태 코드

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

        HTTP 상태 코드코드메시지설명
        200--정상
        400100Bad Request요청 오류
        401-Authentication Failed인증 오류
        401-Permission Denied권한 오류
        403-Forbidden키 리소스 접근 불가
        404300Not Found키 리소스 존재하지 않음
        429-Rate Limited쿼터, 요청량 초과
        500-Unexpected Error
        • FAIL_SERVER_INTERNAL: KMS 시스템 오류
        • FAIL_IAM_REQUEST: 계정 또는 권한 시스템 오류
        • FAIL_CLA_REQUEST: CLA 시스템 오류
        • FAIL_BLOC_REQUEST: 회원 또는 계약 조회 시스템 오류

        오류 구문

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

        필드타입필수 여부설명
        errorObject-오류 정보
        error.errorCodeString-오류 코드
        error.messageString-오류 메시지
        error.detailsString-오류에 대한 상세 정보
        {
            "error": {
                "errorCode": "300",
                "message": "Not Found",
                "details": "null"
            }
        }
        JSON

        Key Management Service API

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

        Key Management Service API 1.0

        Key Management Service API 1.0 관련 API에 대한 설명은 다음과 같습니다.

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

        Key Management Service API 2.0

        Key Management Service API 2.0 관련 API에 대한 설명은 다음과 같습니다.

        Account Auth API

        Account Auth API 관련 API에 대한 설명은 다음과 같습니다.

        API설명
        Create Key키 생성
        Get Key Info키 상세 정보 조회
        Get Key List키 목록 조회
        Get Public Key공개 키 조회
        Delete Key키 삭제
        Enable Key키 활성화
        Disable Key키 비활성화
        Enable Key Version키 버전 활성화
        Disable Key Version키 버전 비활성화
        Rotate Key키를 회전하여 새로운 버전 생성
        Request Key Deletion키 삭제 요청
        Cancel Key Deletion키 삭제 요청 취소
        Enable IP ACL토큰 요청을 허용할 IP 주소를 제어할 수 있는 IP ACL 기능 활성화
        Disable IP ACL토큰 요청을 허용할 IP 주소를 제어할 수 있는 IP ACL 기능 비활성화
        Get ACL Rule List키의 IP ACL 설정 정보 조회
        Add ACL Rule토큰 요청을 허용할 IP 주소를 ACL에 추가
        Delete ACL Rule토큰 요청을 허용한 IP 주소를 ACL에서 삭제
        Create Token Generator토큰 생성자 활성화
        Get Token Generator토큰 생성자 조회
        Update Token Generator토큰 생성자 교체
        Delete Token Generator토큰 생성자 삭제(비활성화)
        Create Token Set토큰 셋(액세스 토큰과 리프레시 토큰) 생성
        Get Key Activity Logs키 사용 이력 목록 조회
        Get Latest Use Info가장 최근의 키 사용 이력 조회
        Get Key Version List키 버전 목록 조회
        Update Memo키에 대한 메모 수정
        Update Rotation Period키의 자동 회전 주기 수정
        Enable Auto Rotation키의 자동 회전 활성화
        Disable Auto Rotation키의 자동 회전 비활성화
        Encrypt키의 현재 버전으로 데이터 암호화
        Decrypt키로 암호문 복호화
        Create Custom Key암호 키로 사용할 임의의 원시 키(raw key) 생성
        Re-encrypt암호문을 지정된 마스터 키의 가장 최신 버전으로 재암호화
        Sign데이터의 서명값 생성
        Verify데이터와 서명값 비교하여 검증 결과 반환

        Token Auth API

        Token Auth API 관련 API에 대한 설명은 다음과 같습니다.

        API설명
        Encrypt키의 현재 버전으로 데이터 암호화
        Decrypt키로 암호문 복호화
        Create Custom Key암호 키로 사용할 임의의 원시 키(raw key) 생성
        Re-encrypt암호문을 지정된 마스터 키의 가장 최신 버전으로 재암호화
        Sign데이터의 서명값 생성
        Verify데이터와 서명값 비교하여 검증 결과 반환
        Get Public Key공개 키 조회
        Create Access Token액세스 토큰 생성
        Renew Token Set토큰 셋(액세스 토큰과 리프레시 토큰) 재생성

        Key Management Service 연관 리소스

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


        이 문서가 도움이 되었습니까?

        Changing your password will log you out immediately. Use the new password to log back in.
        First name must have atleast 2 characters. Numbers and special characters are not allowed.
        Last name must have atleast 1 characters. Numbers and special characters are not allowed.
        Enter a valid email
        Enter a valid password
        Your profile has been successfully updated.