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 October 17, 2024, the Key Management Service API 2.0 was released. Key Management Service API 1.0 will continue to be provided.

Key Management Service API 1.0 Key Management Service API 2.0
Base URL (domain) https://kms.apigw.ntruss.com https://ocapi.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.
 Cross-Region high availability (HA)
  • Uninterrupted operation of APIs such as Encrypt, Decrypt, Sign, and Verify is guaranteed without being affected by a failure in the NAVER Cloud Platform Region.
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 This is the number of milliseconds that have elapsed since January 1, 1970 00:00:00 UTC.
  • Request is considered invalid if the timestamp differs from the current time by more than 5 minutes.
    		•
    x-ncp-apigw-api-key Required Key issued by the API Gateway service of NAVER Cloud Platform
    x-ncp-iam-access-key Required Access key issued on NAVER Cloud Platform
  • Issue and check access key: See Create authentication key.
  • Issue and check access key for sub account: See Create sub account.
    		•
    x-ncp-apigw-signature-v1 Required Base64-encoded signature that encrypts the request information with a secret key that maps to the access key issued on NAVER Cloud Platform, using the HMAC encryption algorithm (HmacSHA256)
  • Issue and check secret key: Create authentication key
  • Create signature: Create signature
    		•
    • API Gateway request signature v2 method request
    Field Required Description
    x-ncp-apigw-timestamp Required This is the number of milliseconds that have elapsed since January 1, 1970 00:00:00 UTC.
  • Request is considered invalid if the timestamp differs from the current time by more than 5 minutes.
    		•
    x-ncp-iam-access-key Required Access key issued on NAVER Cloud Platform
  • Issue and check access key: See Create authentication key.
  • Issue and check access key for sub account: See Create sub account.
    		•
    x-ncp-apigw-signature-v2 Required Base64-encoded signature that encrypts the request information with a secret key that maps to the access key issued on NAVER Cloud Platform, using the HMAC encryption algorithm (HmacSHA256)
  • Issue and check secret key: Create authentication key
  • Create signature: Create signature
    		•

    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 response status codes common to 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 - Errors
    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 - Errors
    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 This is the number of milliseconds that have elapsed since January 1, 1970 00:00:00 UTC.
  • Request is considered invalid if the timestamp differs from the current time by more than 5 minutes.
    		•
    x-ncp-iam-access-key Required Access key issued on NAVER Cloud Platform
  • Issue and check access key: See Create authentication key.
  • Issue and check access key for sub account: See Create sub account.
    		•
    x-ncp-apigw-signature-v2 Required Base64-encoded signature that encrypts the request information with a secret key that maps to the access key issued on NAVER Cloud Platform, using the HMAC encryption algorithm (HmacSHA256)
  • Issue and check secret key: Create authentication key
  • Create signature: Create signature
    		•
    • Token authentication (Token Auth) method request
    Field Required Description
    x-ncp-ocapi-token Required Access token or refresh token for keys generated by Key Management Service

    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 - Errors
    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.