포털 바로가기 네이버 클라우드 플랫폼 설명서

네이버 클라우드 플랫폼의 상품 사용 방법을 보다 상세하게 제공하고, 다양한 API의 활용을 돕기 위해 [설명서]와 [API 참조서]를 구분하여 제공하고 있습니다.

Key Management Service API 참조서 바로가기 >>
Key Management Service 설명서 바로가기 >>

Key Management Service API 개요

Key Management Service API는 RESTful 형태로 제공됩니다. Key Management Service Rest API를 호출하기 위해서는 API Gateway와 Sub Account 인증을 수행해야 합니다. API Gateway를 통한 API 호출은 API Gateway 사용자 가이드를 참조하세요. API 요청 메시지는 아래와 같이 구성됩니다.

Key Management Service API 요청 구성

KMS API stage v1을 사용하는 경우 (API Gateway signature v1 생성 예시)

Header
  x-ncp-apigw-timestamp:{Timestamp}
  x-ncp-apigw-api-key:{API Gateway API Key}
  x-ncp-iam-access-key:{Sub Account Access Key}
  x-ncp-apigw-signature-v1:{API Gateway Signature}
  Content-Type:application/json
Body
  key: value
URL
  https://kms.apigw.gov-ntruss.com/keys/v1/{keyTag}/{action}

KMS API stage v2을 사용하는 경우 (API Gateway signature v2 생성 예시)

Header
  x-ncp-apigw-timestamp:{Timestamp}
  x-ncp-iam-access-key:{Sub Account Access Key}
  x-ncp-apigw-signature-v2:{API Gateway Signature}
  Content-Type:application/json
Body
  key: value
URL
  https://kms.apigw.gov-ntruss.com/keys/v2/{keyTag}/{action}

Key Management Service API 요청 샘플

KMS API stage v1을 사용하는 경우

curl -i -s -X POST \
-H "x-ncp-apigw-timestamp:1511759789542" \
-H "x-ncp-apigw-api-key:12345678907qLxeMDTgd2kyKLOb" \
-H "x-ncp-iam-access-key:3A03131E1348C83101" \
-H "x-ncp-apigw-signature-v1:FkL1mw12345678DRu9R50tdGSyc/uQ/oTw=" \
-H "Content-Type:application/json" \
-d '{"plaintext":"dGVzdA=="}' \
'https://kms.apigw.gov-ntruss.com/keys/v1/bc6b4afe023f29721934567893905c8f7d2ca631c57533211316c89fa3/encrypt'

KMS API stage v2을 사용하는 경우

curl -i -s -X POST \
-H "x-ncp-apigw-timestamp:1511759789542" \
-H "x-ncp-iam-access-key:3A03131E1348C83101" \
-H "x-ncp-apigw-signature-v2:FkL1mw12345678DRu9R50tdGSyc/uQ/oTw=" \
-H "Content-Type:application/json" \
-d '{"plaintext":"dGVzdA=="}' \
'https://kms.apigw.gov-ntruss.com/keys/v2/bc6b4afe023f29721934567893905c8f7d2ca631c57533211316c89fa3/encrypt'

Key Management Service API 응답 샘플

{
  "code": "SUCCESS",
  "msg": "",
  "data":{
    "ciphertext": "ncpkms:v1:gsYccPMkd/fAtqbKuj2ov4H+EdZC8Qb/b1GPIIN2Z61+yULo"
  }
}

Key Management Service API 에러 타입

Key Management Service Prefix

마스터키로 암호화되어 반환되는 데이터는 'Key Management Service prefix + 암호문'으로 구성되어 있습니다. Key Management Service prefix는 [ncpkms:버전정보]로 구성되어 있으며, 이는 복호화 시에 반드시 필요한 정보이므로 임의 제거 및 조작이 금지됩니다. Key Management Service prefix가 올바르지 않다면 정확히 복호화되지 않습니다. 반환된 형태 그대로 관리하는 것이 좋습니다.

 ncpkms:v1:XjsPWPjqPrBi1N2DupSiSbX/ATkGmKA
 --------- -------------------------------
Key Management Service prefix        암호문

Key Management Service API 목록

Encrypt

지정된 마스터키의 현재 버전으로 AES256은 최대 32KB, RSA2048은 최대 190B 데이터를 암호화합니다. 암/복호화용 키 타입으로만 요청 가능합니다.

End point

POST https://kms.apigw.gov-ntruss.com/keys/v1/{keyTag}/encrypt

Path parameter

Request body

{
  "plaintext" : string
}

Response body

{
  "ciphertext" : string
}

필요 권한

Manager, Encryptor, Encryptor/Decryptor

Decrypt

지정된 마스터키로 암호문을 복호화합니다. 복호화 요청 시 지정된 키 버전으로 복호화되기 때문에 암호문과 함께 Key Management Service prefix가 정확히 명시되어야 합니다. 암/복호화용 키 타입으로만 요청 가능합니다.

End point

POST https://kms.apigw.gov-ntruss.com/keys/v1/{keyTag}/decrypt

Path parameter

Request body

{
  "ciphertext" : string
}

Response body

{
  "plaintext" : string
}

역할

Manager, Decryptor, Encryptor/Decryptor

Create user custom key

임의의 high-entropy 키를 주어진 bit로 생성합니다(대칭키 방식으로만 지원). 지정된 마스터키의 현재 버전으로 봉인된 키와 함께 평문 형태의 키를 반환받을 수도 있습니다. 암/복호화용 키 타입으로만 요청 가능합니다.

End point

POST https://kms.apigw.gov-ntruss.com/keys/v1/{keyTag}/createCustomKey

Path parameter

Request body

{
  "requestPlainKey", : boolean
  "bits" : integer
}

Response body

{
  "plaintext", : string
  "ciphertext" : string
}

역할

Manager, Encryptor, Encryptor/Decryptor

Re-encrypt

암호문을 지정된 마스터키의 가장 최신 버전으로 재암호화합니다. 암/복호화용 키 타입으로만 요청 가능합니다.

End point

POST https://kms.apigw.gov-ntruss.com/keys/v1/{keyTag}/reencrypt

Path parameter

Request body

{
  "ciphertext" : string
}

Response body

{
  "newCiphertext" : string
}

역할

Manager, Encryptor, Encryptor/Decryptor

Sign

지정된 마스터키(비밀키)로 최대 8KB 데이터의 서명값을 생성합니다(일반적으로 서명을 요청할 데이터의 해쉬값을 전달). 서명/검증용 키 타입으로만 요청 가능합니다.

End point

POST https://kms.apigw.gov-ntruss.com/keys/v1/{keyTag}/sign

Path parameter

Request body

{
  "data" : string
}

Response body

{
  "signature" : string
}

역할

Manager, Encryptor, Encryptor/Decryptor

Verify

지정된 마스터키(공개키)로 최대 8KB 데이터와 서명값을 비교하여 일치 여부를 반환합니다(일반적으로 검증을 요청할 데이터의 해쉬값을 전달). 서명/검증용 키 타입으로만 요청 가능합니다.

End point

POST https://kms.apigw.gov-ntruss.com/keys/v1/{keyTag}/verify

Path parameter

Request body

{
  "data", : string
  "signature" : string
}

Response body

{
  "valid" : boolean
}

역할

Manager, Decryptor, Encryptor/Decryptor

연관 정보

• API Gateway 사용자 가이드
• Key Management Service 샘플 코드: Best Practice