Key Management Service overview

Prev Next

Available in Classic and VPC

Key Management Service is a NAVER Cloud Platform service that provides encryption key management functions essential for encryption operations and implementation. Key Management Service provides APIs for various key management features, including encryption and decryption, in the form of RESTful.

Note

On June 19, 2025, the Region isolation key feature will be added to API 2.0. For more information, see Key Management Service concept > Key isolation.

  • All keys created and in operation before the feature is added will automatically be converted to global keys, and there will be no change to the APIs you are using.
Key Management Service API 1.0 Key Management Service API 2.0
Base URL (domain) https://kms.apigw.ntruss.com
  • Global: https://ocapi.ncloud.com
  • Isolation: Korea (KR): https://ocapi-kr.ncloud.com
  • Isolation: Japan (JP): https://ocapi-jp.ncloud.com
API type Only 6 encryption and decryption APIs are provided.
  • Encrypt, Decrypt, Create Custom Key, Re-encrypt, Sign, Verify
  • 6 encryption and decryption APIs are provided.
    • Encrypt, Decrypt, Create Custom Key, Re-encrypt, Sign, Verify
  • All console-based key management features are provided.
Authentication method User authentication using NAVER Cloud Platform account information
  • Account authentication API: user authentication using NAVER Cloud Platform account information
  • token authentication API: key authentication token
Request handling performance Based on Encrypt API (AES), up to 200 TPS
  • All keys share the 200 TPS processing performance.
 Based on Encrypt API (AES), up to 300 TPS per key
  • Each key is individually guaranteed up to 300 TPS processing performance.
Availability guarantee Region-specific high availability (HA)
  • In the event of a failure in the NAVER Cloud Platform Region, APIs such as Encrypt, Decrypt, Sign, and Verify are affected.
 Region-specific or Cross-Region high availability (HA)
  • Global key: Cross-region multi-synchronization ensures uninterrupted operation for APIs such as encryption, decryption, signing, and verification that are not affected by NAVER Cloud Platform Region failures
  • Region isolation key: Support intra-Region redundancy for external transfer restrictions.
Request access control Use the IP ACL feature of the sub account unit provided by the Sub Account service.
  • IP ACL feature of the sub account unit provided by the Sub Account service
  • IP ACL that can be set by token unit

Common Key Management Service API 1.0 settings

The following describes commonly used request and response formats in Key Management Service API 1.0.

Request

The following describes the common request format.

API URL

The request API URL is as follows:

API Gateway request signature v1: https://kms.apigw.ntruss.com/keys/v1
API Gateway request signature v2: https://kms.apigw.ntruss.com/keys/v2

Request headers

The following describes the request headers.

  • API Gateway request signature v1 method request

    Field Required Description
    x-ncp-apigw-timestamp Required
    x-ncp-apigw-api-key Required
    x-ncp-iam-access-key Required
    x-ncp-apigw-signature-v1 Required

  • API Gateway request signature v2 method request

    Field Required Description
    x-ncp-apigw-timestamp Required
    x-ncp-iam-access-key Required
    x-ncp-apigw-signature-v2 Required

Response

The following describes the common response format.

Response status codes

The following describes the response status codes.

HTTP status code Code Message Description
200 - success Succeeded
Note

For information about the HTTP status codes common to all NAVER Cloud Platform, see Ncloud API response status codes.

Error syntax

The following describes the error syntax that results from processing the request.

Field Type Required Description
error Object - Error information
error.errorCode String - Error code
error.message String - Error message
error.details String - Error details 
{
"error": {
"errorCode": "300",
"message": "Not Found Exception",
"details": "URL not found."
}
}

The following describes the error syntax that has failed even though the status code is 200 OK.

Field Type Required Description
code String - Error code
msg String - Error message
data Object - Response result
  • Displayed as null value

  • Example: Invalid request data input

    {
"code": "NOT_VALID_INPUT",
"msg": "Fail: not valid input",
"data": null
}

Common Key Management Service API 2.0 settings

The following describes commonly used request and response formats in Key Management Service API 2.0.

Request

The following describes the common request format.

API URL

The request API URL is as follows:

https://ocapi.ncloud.com/kms/v1

Request headers

The following describes the request headers.

  • Account authentication (Account Auth) method request

    Field Required Description
    x-ncp-apigw-timestamp Required
    x-ncp-iam-access-key Required
    x-ncp-apigw-signature-v2 Required

  • Token authentication (Token Auth) method request

    Field Required Description
    x-ncp-ocapi-token Required

Response

The following describes the common response format.

Response status codes

The following describes the response status codes.

HTTP status code Code Message Description
200 - - Success
400 100 Bad Request Request error
401 - Authentication Failed Authentication error
401 - Permission Denied Permission error
403 - Forbidden Key resource not accessible
404 300 Not Found Key resource not found
429 - Rate Limited Request quota exceeded
500 - Unexpected Error
  • FAIL_SERVER_INTERNAL: KMS system error
  • FAIL_IAM_REQUEST: Account or permission system error
  • FAIL_CLA_REQUEST: CLA system error
  • FAIL_BLOC_REQUEST: Member or contract inquiry system error

Error syntax

The following describes the error syntax that results from processing the request.

Field Type Required Description
error Object - Error information
error.errorCode String - Error code
error.message String - Error message
error.details String - Error details 
{
"error": {
"errorCode": "300",
"message": "Not Found",
"details": "null"
}
}

Key Management Service API

The following describes the APIs provided by the Key Management Service API service.

Key Management Service API 1.0

The following describes the APIs related to Key Management Service API 1.0.

API Description
Encrypt Encrypt data with the current version of the key.
Decrypt Decrypt ciphertext with a key.
Create Custom Key Create a random raw key to be used as a encryption key.
Re-encrypt Re-encrypt the ciphertext with the most recent version of the specified master key.
Sign Create signature value of data.
Verify Compare data and signature value and return verification result.

Key Management Service API 2.0

The following describes the APIs related to Key Management Service API 2.0.

Account Auth API

The following describes the APIs related to the Account Auth API.

API Description
Create Key Create key.
Get Key Info Get key details.
Get Key List Get key list.
Get Public Key Get public key.
Delete Key Delete key.
Enable Key Activate key.
Disable Key Deactivate key.
Enable Key Version Enable key version.
Disable Key Version Disable key version.
Rotate Key Rotate a key to create a new version.
Request Key Deletion Request key deletion.
Cancel Key Deletion Cancel key deletion request.
Enable IP ACL Enable the IP ACL feature to control the IP addresses that are allowed to request tokens.
Disable IP ACL Disable the IP ACL feature to control the IP addresses that are allowed to request tokens.
Get ACL Rule List Get IP ACL configuration information for a key.
Add ACL Rule Add an IP address to the ACL to allow token requests.
Delete ACL Rule Delete an IP address allowed to request tokens from the ACL.
Create Token Generator Activate token generator.
Get Token Generator Get token generator.
Update Token Generator Replace token generator.
Delete Token Generator Delete token generator (disable).
Create Token Set Create a token set (refresh token and access token).
Get Key Activity Logs Get key usage history list.
Get Latest Use Info Get the latest key usage history.
Get Key Version List Get key version list.
Update Memo Edit notes for a key.
Update Rotation Period Edit the automatic rotation cycle of a key.
Enable Auto Rotation Enable automatic rotation of a key.
Disable Auto Rotation Disable automatic rotation of a key.
Encrypt Encrypt data with the current version of the key.
Decrypt Decrypt ciphertext with a key.
Create Custom Key Create a random raw key to be used as a encryption key.
Re-encrypt Re-encrypt the ciphertext with the most recent version of the specified master key.
Sign Create signature value of data.
Verify Compare data and signature value and return verification result.

Token Auth API

The following describes the APIs related to the Token Auth API.

API Description
Encrypt Encrypt data with the current version of the key.
Decrypt Decrypt ciphertext with a key.
Create Custom Key Create a random raw key to be used as a encryption key.
Re-encrypt Re-encrypt the ciphertext with the most recent version of the specified master key.
Sign Create signature value of data.
Verify Compare data and signature value and return verification result.
Get Public Key Get public key.
Create Access Token Create access token
Renew Token Set Recreate the token set (access token and refresh token)

Key Management Service related resources

NAVER Cloud Platform provides a variety of related resources to help users better understand Key Management Service APIs.