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