Key Management Service 개요

개요

KMS API는 RESTful 형태로 제공됩니다. KMS Rest API를 호출하기 위해서는 API Gateway와 Sub Account 인증을 수행해야 합니다.

API Gateway를 통한 API 호출은 API Gateway 설명서를 참조하세요. API 요청 메시지는 아래와 같이 구성됩니다.

요청 구성

API Gateway request 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
  fieldName: {Base64 Encoded message}
URL
  https://kms.apigw.fin-ntruss.com/keys/v1/{keyTag}/{action}

API Gateway request 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
  fieldName: {Base64 Encoded message}
URL
  https://kms.apigw.fin-ntruss.com/keys/v2/{keyTag}/{action}

요청 예시

API Gateway request signature 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.fin-ntruss.com/keys/v1/bc6b4afe023f29721934567893905c8f7d2ca631c57533211316c89fa3/encrypt'

API Gateway request signature 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.fin-ntruss.com/keys/v2/bc6b4afe023f29721934567893905c8f7d2ca631c57533211316c89fa3/encrypt'

응답 예시

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

에러 코드

Prefix

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

 ncpkms:v1:XjsPWPjqPrBi1N2DupSiSbX/ATkGmKA
 --------- -------------------------------
KMS prefix        암호문