네이버 클라우드 플랫폼의 상품 사용 방법을 보다 상세하게 제공하고, 다양한 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.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.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.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.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 에러 타입

HTTP 상태 코드 응답 코드 응답 메시지
200 EMPTY_PLAINTEXT "Empty: plaintext"
EMPTY_CIPHERTEXT "Empty: ciphertext"
EMPTY_KEY_TAG "Empty: keyTag"
NOT_VALID_INPUT "Fail: not valid input"
NOT_VALID_BITS "Fail: not valid bits"
NOT_VALID_KEY_TAG "Fail: key tag"
NOT_VALID_KEYTYPE "Fail: not valid keytype"
NOT_VALID_KEY_VERSION "Fail: not valid key version"
NOT_VALID_ENCODING "Not valid input: not base 64 encoded"
NOT_FOUND_KEY "Not found: key"
NOT_AUTHORIZED_REQUEST "Fail: unauthorized request"
FAIL_EXCEED_DATA_SIZE "Fail: exceed data size"
FAIL_SERVER_INTERNAL "Fail: server internal error"
그 외 API Gateway 응답 코드 참조

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.ntruss.com/keys/v1/{keyTag}/encrypt

Path parameter

파라미터 이름 타입 설명
keyTag String(Required) 암호화에 사용할 마스터키의 tag값

Request body

{
  "plaintext" : string
}
파라미터 이름 타입 설명
plaintext String(Required) 암호화할 데이터 (최대 32KB)
(Base64 Encoding이 필요합니다)

Response body

{
  "ciphertext" : string
}
파라미터 이름 타입 설명
ciphertext String 암호문 데이터
(Key Management Service prefix와 Base64 Encoding된 암호문으로 구성되어 있습니다)

필요 권한

Manager, Encryptor, Encryptor/Decryptor

Decrypt

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

End point

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

Path parameter

파라미터 이름 타입 설명
keyTag String(Required) 복호화에 사용할 마스터키의 tag값

Request body

{
  "ciphertext" : string
}
파라미터 이름 타입 설명
ciphertext String(Required) 복호화할 데이터
(Key Management Service prefix와 Base64 Encoding된 암호문으로 구성되어야합니다)

Response body

{
  "plaintext" : string
}
파라미터 이름 타입 설명
plaintext String 평문 데이터
(Base64 Encoding 되어있습니다.)

역할

Manager, Decryptor, Encryptor/Decryptor

Create user custom key

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

End point

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

Path parameter

파라미터 이름 타입 설명
keyTag String(Required) 생성된 키 봉인에 사용할 마스터키의 tag값

Request body

{
  "requestPlainKey", : boolean
  "bits" : integer
}
파라미터 이름 타입 설명
requestPlainKey Boolean(Required) 생성된 키를 평문 형태로 반환받을지 선택하는 플래그
bits Integer(Optional) 생성될 키의 비트
128, 256, 512(기본 256)

Response body

{
  "plaintext", : string
  "ciphertext" : string
}
파라미터 이름 타입 설명
plaintext String 생성된 키의 평문 형태(requestPlainKey: true일 때만 반환)
(Base64 Encoding 되어있습니다.)
ciphertext String 생성된 키의 봉인된 형태
(Key Management Service prefix와 Base64 Encoding된 암호문으로 구성있습니다)

역할

Manager, Encryptor, Encryptor/Decryptor

Re-encrypt

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

End point

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

Path parameter

파라미터 이름 타입 설명
keyTag String(Required) 재암호화에 사용할 마스터키의 tag값

Request body

{
  "ciphertext" : string
}
파라미터 이름 타입 설명
ciphertext String(Required) 재암호화할 데이터
(Key Management Service prefix와 Base64 Encoding된 암호문으로 구성되어야합니다)

Response body

{
  "newCiphertext" : string
}
파라미터 이름 타입 설명
newCiphertext String 암호문 데이터
(Key Management Service prefix와 Base64 Encoding된 암호문으로 구성되어 있습니다)

역할

Manager, Encryptor, Encryptor/Decryptor

Sign

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

End point

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

Path parameter

파라미터 이름 타입 설명
keyTag String(Required) 서명에 사용할 마스터키의 tag값

Request body

{
  "data" : string
}
파라미터 이름 타입 설명
data String(Required) 서명값을 생성할 데이터 (최대 8KB)
(Base64 Encoding이 필요합니다)

Response body

{
  "signature" : string
}
파라미터 이름 타입 설명
signature String 서명값 데이터
(Key Management Service prefix와 Base64 Encoding된 서명값으로 구성되어 있습니다)

역할

Manager, Encryptor, Encryptor/Decryptor

Verify

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

End point

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

Path parameter

파라미터 이름 타입 설명
keyTag String(Required) 서명 검증에 사용할 마스터키의 tag값

Request body

{
  "data", : string
  "signature" : string
}
파라미터 이름 타입 설명
data String(Required) 서명 생성에 사용된 데이터 (최대 8KB)
(Base64 Encoding이 필요합니다)
signature String(Required) 서명값 데이터
(Key Management Service prefix와 Base64 Encoding된 서명값으로 구성되어 있습니다)

Response body

{
  "valid" : boolean
}
파라미터 이름 타입 설명
valid boolean 검증값 비교 결과

역할

Manager, Decryptor, Encryptor/Decryptor

연관 정보

""에 대한 건이 검색되었습니다.

    ""에 대한 검색 결과가 없습니다.

    처리중...