KMS Overview

Overview

The KMS API is RESTful. In order to make API requests, each of them must be authenticated with Sub Account via API Gateway.
For more information, refer to API Gateway Manual (formerly, User Guide) . An API request message consists of the following:

API request

API Gateway request signature v1 API request

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

API Gateway request signature v2 API request

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

Examples

API Gateway request signature v1 Request example

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'

API Gateway request signature v2 Request example

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'

Response example

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

Error codes

Prefix

The data returned after being encrypted with the master key consists of “KMS prefix + ciphertext.” The KMS prefix is in the form of [ncpkms:version info], which is required for decryption and thus must not be arbitrarily removed or manipulated. The ciphertext will not be correctly decrypted with an invalid KMS prefix. Therefore, keep the returned KMS prefix

 ncpkms:v1:XjsPWPjqPrBi1N2DupSiSbX/ATkGmKA
 --------- -------------------------------
KMS prefix        Ciphertext