--- title: "Key Management Service 개요" slug: "security-kms" tags: ["Key Management Service", "KMS Rest API", "API Gateway", "Sub Account"] updated: 2026-09-17T09:10:34Z published: 2026-09-17T09:10:34Z canonical: "api-fin.ncloud-docs.com/security-kms" --- > ## Documentation Index > Fetch the complete documentation index at: https://api-fin.ncloud-docs.com/llms.txt > Use this file to discover all available pages before exploring further. # Key Management Service 개요 Key Management Service는 암호화 운영 및 구현에 필수적인 암호 키 관리 기능을 제공하는 네이버 클라우드 플랫폼의 서비스입니다. Key Management Service에서는 암호화와 복호화를 비롯한 여러 키 관리 기능에 대한 API를 RESTful 형태로 제공합니다. ## Key Management Service 공통 설정 Key Management Service API에서 공통으로 사용하는 요청 형식과 응답 형식을 설명합니다. ### 요청 공통 요청 형식을 설명합니다. #### API URL 요청 API URL은 다음과 같습니다. ``` https://kms.apigw.fin-ntruss.com ``` #### 요청 헤더 요청 헤더에 대한 설명은 다음과 같습니다. - **API Gateway request signature v1 방식 요청** | 필드 | 필수 여부 | 설명 | | --- | --- | --- | | `x-ncp-apigw-timestamp` | Required | 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간(밀리초) - API Gateway 서버와 5분 이상 시간차 발생 시 유효하지 않은 요청으로 간주 - Unix Timestamp 형식 | | `x-ncp-apigw-api-key` | Required | 네이버 클라우드 플랫폼의 API Gateway 서비스에서 발급받은 키 | | `x-ncp-iam-access-key` | Required | 네이버 클라우드 플랫폼에서 발급받은 Access Key - Access Key 발급 및 확인: [인증키 생성](/docs/common-ncpapi#API%EC%9D%B8%EC%A6%9D%ED%82%A4) 참조 - 서브 계정의 Access Key 발급 및 확인: [서브 계정 생성](https://guide-fin.ncloud-docs.com/docs/subaccount-use#%EC%84%9C%EB%B8%8C%EA%B3%84%EC%A0%95%EC%83%9D%EC%84%B1) 참조 | | `x-ncp-apigw-signature-v1` | Required | 네이버 클라우드 플랫폼에서 발급받은 Access Key에 맵핑되는 Secret Key 및 HMAC 암호화 알고리즘(HmacSHA256)으로 요청 정보를 암호화한 후 Base64로 인코딩한 서명 - Secret Key 발급 및 확인: [인증키 생성](/docs/common-ncpapi#API%EC%9D%B8%EC%A6%9D%ED%82%A4) 참조 - 서명 생성: [시그니처 생성](/docs/common-ncpapi#%EC%8B%9C%EA%B7%B8%EB%8B%88%EC%B2%98%EC%83%9D%EC%84%B1) 참조 | - **API Gateway request signature v2 방식 요청** | 필드 | 필수 여부 | 설명 | | --- | --- | --- | | `x-ncp-apigw-timestamp` | Required | 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간(밀리초) - API Gateway 서버와 5분 이상 시간차 발생 시 유효하지 않은 요청으로 간주 - Unix Timestamp 형식 | | `x-ncp-iam-access-key` | Required | 네이버 클라우드 플랫폼에서 발급받은 Access Key - Access Key 발급 및 확인: [인증키 생성](/docs/common-ncpapi#API%EC%9D%B8%EC%A6%9D%ED%82%A4) 참조 - 서브 계정의 Access Key 발급 및 확인: [서브 계정 생성](https://guide-fin.ncloud-docs.com/docs/subaccount-use#%EC%84%9C%EB%B8%8C%EA%B3%84%EC%A0%95%EC%83%9D%EC%84%B1) 참조 | | `x-ncp-apigw-signature-v2` | Required | 네이버 클라우드 플랫폼에서 발급받은 Access Key에 맵핑되는 Secret Key 및 HMAC 암호화 알고리즘(HmacSHA256)으로 요청 정보를 암호화한 후 Base64로 인코딩한 서명 - Secret Key 발급 및 확인: [인증키 생성](/docs/common-ncpapi#API%EC%9D%B8%EC%A6%9D%ED%82%A4) 참조 - 서명 생성: [시그니처 생성](/docs/common-ncpapi#%EC%8B%9C%EA%B7%B8%EB%8B%88%EC%B2%98%EC%83%9D%EC%84%B1) 참조 | ### 응답 공통 응답 형식을 설명합니다. #### 응답 상태 코드 응답 상태 코드에 대한 설명은 다음과 같습니다. | HTTP 상태 코드 | 코드 | 메시지 | 설명 | | --- | --- | --- | --- | | 200 | - | `success` | 성공 | 참고 네이버 클라우드 플랫폼에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 [Ncloud API 응답 상태 코드](/docs/common-ncpapi#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C)를 참조해 주십시오. #### 오류 구문 요청 처리 결과 오류 구문에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `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](/docs/security-kms-encrypt) | 키의 현재 버전으로 데이터 암호화 | | [Decrypt](/docs/security-kms-decrypt) | 키로 암호문 복호화 | | [Create Custom Key](/docs/security-kms-createusercustomkey) | 암호 키로 사용할 임의의 원시 키(raw key) 생성 | | [Re-encrypt](/docs/security-kms-reencrypt) | 암호문을 지정된 마스터 키의 가장 최신 버전으로 재암호화 | | [Sign](/docs/security-kms-sign) | 데이터의 서명값 생성 | | [Verify](/docs/security-kms-verify) | 데이터와 서명값 비교하여 검증 결과 반환 | ## Key Management Service 연관 리소스 Key Management Service API에 대한 사용자의 이해를 돕기 위해 다양한 연관 리소스를 제공하고 있습니다. - Key Management Service API 사용 방법 - [서명(시그니처) 생성](/docs/common-ncpapi#%EC%8B%9C%EA%B7%B8%EB%8B%88%EC%B2%98%EC%83%9D%EC%84%B1): 요청 헤더에 추가할 서명 생성 방법 - [API Gateway 사용 가이드](https://guide-fin.ncloud-docs.com/docs/application-apigateway-apigatewayoverview): 요청 헤더에 추가할 API Key 발급 - [Sub Account 사용 가이드](https://guide-fin.ncloud-docs.com/docs/subaccount-overview): 요청 헤더에 추가할 Access Key 발급 방법 - [Ncloud 공통 응답 상태 코드](/docs/common-ncpapi#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C): Key Management Service에서 사용하는 네이버 클라우드 플랫폼의 공통 응답 상태 코드 정보 - Key Management Service 서비스 사용 방법 - [Key Management Service 사용 가이드](https://guide-fin.ncloud-docs.com/docs/kms-overview): 네이버 클라우드 플랫폼 콘솔에서 Key Management Service 사용하는 방법 - [요금 소개, 특징, 상세 기능](https://www.fin-ncloud.com/product/security/kms): Key Management Service의 요금 체계, 특징, 상세 기능 요약 - [서비스 최신 소식](https://www.fin-ncloud.com/intro/news?categoryCode=SEC&serviceCode=SV_0049): Key Management Service 관련 최신 소식 - [자주 하는 질문](https://www.fin-ncloud.com/support/faq/prod?categoryCode2=SEC&categoryCode3=SV_0049&page=1): Key Management Service 사용자들이 자주 하는 질문 - [문의하기](https://www.fin-ncloud.com/support/question/service): API 가이드를 통해서도 궁금증이 해결되지 않는 경우 직접 문의