Key Management Serviceの概要

Classic/VPC環境で利用できます。

Key Management Serviceは、暗号化の運用と具現化において必須要素の暗号キー管理機能を提供する NAVERクラウドプラットフォームのサービスです。Key Management Serviceは、暗号化と復号化をはじめとするいろいろなキー管理機能関連の APIを RESTful形式で提供します。

参考

2024年10月17日に Key Management Service API 2.0がリリースされました。Key Management Service API 1.0は引き続き提供されます。

	Key Management Service API 1.0	Key Management Service API 2.0
Base URL(ドメイン)	https://kms.apigw.ntruss.com	https://ocapi.ncloud.com
APIの種類	暗号化、復号化 APIを6種類のみ提供 Encrypt、Decrypt、Create Custom Key、Re-encrypt、Sign、Verify	暗号化、復号化 APIを6種類提供 Encrypt、Decrypt、Create Custom Key、Re-encrypt、Sign、Verify コンソールから提供されるキー管理機能をすべて提供
認証方式	NAVERクラウドプラットフォームアカウント情報を利用したユーザー認証	アカウント認証 API: NAVERクラウドプラットフォームアカウント情報を利用したユーザー認証トーク認証 API: キー認証トークン
リクエスト処理性能	Encrypt API (AES)基準でシステム最大200TPS すべてのキーが200TPS処理性能を共有	Encrypt API (AES)基準でキー別に最大300TPS すべてのキーに対しそれぞれ最大300TPSの処理性能を個別に保証
可用性を保証	リージョン限定高可用性(HA) NAVERクラウドプラットフォームのリージョン障害時、暗号化、復号化、署名、検証などの APIに影響がある	クロスリージョン高可用性(HA) NAVERクラウドプラットフォームのリージョン障害により影響されず、暗号化、復号化、署名、検証などの APIの無停止動作を保証
リクエストアクセス制御	Sub Accountサービスが提供するサブアカウント単位の IP ACL機能を利用	Sub Accountサービスが提供するサブアカウント単位の IP ACL機能トークン単位で設定可能な IP ACL

Key Management Service API 1.0の共通設定

Key Management Service API 1.0で共通して使用されるリクエスト形式とレスポンス形式を説明します。

リクエスト

共通リクエスト形式を説明します。

API URL

リクエスト API URLは次の通りです。

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

リクエストヘッダ

リクエストヘッダの説明は次の通りです。

API Gateway request signature v1方式のリクエスト

フィールド	必須の有無	説明
`x-ncp-apigw-timestamp`	Required	1970年1月1日00:00:00協定世界時(UTC)からの経過時間(ミリ秒) API Gatewayサーバとの時間差が5分以上の場合は無効なリクエストとみなす
`x-ncp-apigw-api-key`	Required	NAVERクラウドプラットフォームの API Gatewayサービスから発行されたキー
`x-ncp-iam-access-key`	Required	NAVERクラウドプラットフォームから発行された Access Key Access Keyの発行と確認: 認証キーの作成を参照サブアカウントの Access Key発行と確認: サブアカウントの作成を参照
`x-ncp-apigw-signature-v1`	Required	NAVERクラウドプラットフォームから発行された Access Keyとマッピングする Secret Keyと HMAC暗号化アルゴリズム(HmacSHA256)でリクエスト情報を暗号化した後、Base64にエンコードした署名 Secret Keyの発行と確認: 認証キーの作成を参照署名の作成: シグネチャーの作成を参照

API Gateway request signature v2方式のリクエスト

フィールド	必須の有無	説明
`x-ncp-apigw-timestamp`	Required	1970年1月1日00:00:00協定世界時(UTC)からの経過時間(ミリ秒) API Gatewayサーバとの時間差が5分以上の場合は無効なリクエストとみなす
`x-ncp-iam-access-key`	Required	NAVERクラウドプラットフォームから発行された Access Key Access Keyの発行と確認: 認証キーの作成を参照サブアカウントの Access Key発行と確認: サブアカウントの作成を参照
`x-ncp-apigw-signature-v2`	Required	NAVERクラウドプラットフォームから発行された Access Keyとマッピングする Secret Keyと HMAC暗号化アルゴリズム(HmacSHA256)でリクエスト情報を暗号化した後、Base64にエンコードした署名 Secret Keyの発行と確認: 認証キーの作成を参照署名の作成: シグネチャーの作成を参照

レスポンス

共通レスポンス形式を説明します。

レスポンスステータスコード

レスポンスステータスコードの説明は次の通りです。

HTTPステータスコード	コード	メッセージ	説明
200	-	`success`	成功

参考

NAVERクラウドプラットフォームで共通して使用されるレスポンスステータスコードの詳細は、Ncloud APIのレスポンスステータスコードをご参照ください。

エラー構文

リクエスト処理結果エラー構文の説明は次の通りです。

フィールド	タイプ	必須の有無	説明
`error`	Object	-	エラー情報
`error.errorCode`	String	-	エラーコード
`error.message`	String	-	エラーメッセージ
`error.details`	String	-	エラーの詳細情報

{
"error": {
"errorCode": "300",
"message": "Not Found Exception",
"details": "URL not found."
}
}

状態コードが200 OKの場合でも、結果として失敗したエラー構文の説明は次の通りです。

フィールド	タイプ	必須の有無	説明
`code`	String	-	エラーコード
`msg`	String	-	エラーメッセージ
`data`	Object	-	レスポンス結果 `null`と表示

<例> 有効でないリクエストデータを入力

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

Key Management Service API 2.0の共通設定

Key Management Service API 2.0で共通して使用されるリクエスト形式とレスポンス形式を説明します。

リクエスト

共通リクエスト形式を説明します。

API URL

リクエスト API URLは次の通りです。

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

リクエストヘッダ

リクエストヘッダの説明は次の通りです。

アカウント認証(Account Auth)方式のリクエスト

フィールド	必須の有無	説明
`x-ncp-apigw-timestamp`	Required	1970年1月1日00:00:00協定世界時(UTC)からの経過時間(ミリ秒) API Gatewayサーバとの時間差が5分以上の場合は無効なリクエストとみなす
`x-ncp-iam-access-key`	Required	NAVERクラウドプラットフォームから発行された Access Key Access Keyの発行と確認: 認証キーの作成を参照サブアカウントの Access Key発行と確認: サブアカウントの作成を参照
`x-ncp-apigw-signature-v2`	Required	NAVERクラウドプラットフォームから発行された Access Keyとマッピングする Secret Keyと HMAC暗号化アルゴリズム(HmacSHA256)でリクエスト情報を暗号化した後、Base64にエンコードした署名 Secret Keyの発行と確認: 認証キーの作成を参照署名の作成: シグネチャーの作成を参照

トークン認証(Token Auth)方式のリクエスト

フィールド	必須の有無	説明
`x-ncp-ocapi-token`	Required	Key Management Serviceで生成したキーのアクセストークン(Access Token)またはリフレッシュトークン(Refresh Token) JWT(JSON Web Token)タイプのトークントークンの生成: Create Token Setを参照使用 API アクセストークン: Encrypt、Decrypt、Create Custom Key、Re-encrypt、Sign、Verify、Get Public Key リフレッシュトーク: Create Access Token、Renew Token Set

レスポンス

共通レスポンス形式を説明します。

レスポンスステータスコード

レスポンスステータスコードの説明は次の通りです。

HTTPステータスコード	コード	メッセージ	説明
200	-	-	正常
400	100	`Bad Request`	リクエストエラー
401	-	`Authentication Failed`	認証エラー
401	-	`Permission Denied`	権限エラー
403	-	`Forbidden`	キーリソースにアクセス不可
404	300	`Not Found`	キーリソースが存在しない
429	-	`Rate Limited`	リクエストの割り当て量超過
500	-	`Unexpected Error`	`FAIL_SERVER_INTERNAL`: KMSシステムエラー `FAIL_IAM_REQUEST`: アカウントまたは権限システムエラー `FAIL_CLA_REQUEST`: CLAシステムエラー `FAIL_BLOC_REQUEST`: 会員または契約照会システムエラー

エラー構文

リクエスト処理結果エラー構文の説明は次の通りです。

フィールド	タイプ	必須の有無	説明
`error`	Object	-	エラー情報
`error.errorCode`	String	-	エラーコード
`error.message`	String	-	エラーメッセージ
`error.details`	String	-	エラーの詳細情報

{
"error": {
"errorCode": "300",
"message": "Not Found",
"details": "null"
}
}

Key Management Service API

Key Management Service APIサービスで提供する APIの説明は次の通りです。

Key Management Service API 1.0

Key Management Service API 1.0関連 APIの説明は次の通りです。

API	説明
Encrypt	キーの現在のバージョンでデータを暗号化
Decrypt	キーで暗号文を復号化
Create Custom Key	暗号キーとして使用する任意の生キー(raw key)を作成
Re-encrypt	暗号文を指定されたマスターキーの最新バージョンで再暗号化
Sign	データの署名を作成
Verify	データの署名と照合して検証結果を返す

Key Management Service API 2.0

Key Management Service API 2.0関連 APIの説明は次の通りです。

Account Auth API

Account Auth API関連 APIの説明は次の通りです。

API	説明
Create Key	キーを作成
Get Key Info	キーの詳細情報を照会
Get Key List	キーリストを照会
Get Public Key	公開鍵を照会
Delete Key	キーを削除
Enable Key	キーを有効化
Disable Key	キーを無効化
Enable Key Version	キーのバージョンを有効化
Disable Key Version	キーのバージョンを無効化
Rotate Key	キーをローテーションして新しいバージョンを作成
Request Key Deletion	キーの削除をリクエスト
Cancel Key Deletion	キー削除リクエストをキャンセル
Enable IP ACL	トークンリクエストを許可する IPアドレスを制御する IP ACL機能を有効化
Disable IP ACL	トークンリクエストを許可する IPアドレスを制御する IP ACL機能を無効化
Get ACL Rule List	キーの IP ACL設定情報を照会
Add ACL Rule	トークンリクエスト許可対象の IPアドレスを ACLに追加
Delete ACL Rule	トークンリクエストを許可した IPアドレスを ACLから削除
Create Token Generator	トークンジェネレータを有効化
Get Token Generator	トークンジェネレータを照会
Update Token Generator	トークンジェネレータを交換
Delete Token Generator	トークンジェネレータを削除(無効化時)
Create Token Set	トークンセット(アクセストークンとリフレッシュトークン)を生成
Get Key Activity Logs	キー使用履歴リストを照会
Get Latest Use Info	直近のキー使用履歴を照会
Get Key Version List	キーのバージョンリストを照会
Update Memo	キーに関するメモを更新
Update Rotation Period	キーの自動ローテーション周期を更新
Enable Auto Rotation	キーを自動ローテーションを有効化
Disable Auto Rotation	キーを自動ローテーションを無効化
Encrypt	キーの現在のバージョンでデータを暗号化
Decrypt	キーで暗号文を復号化
Create Custom Key	暗号キーとして使用する任意の生キー(raw key)を作成
Re-encrypt	暗号文を指定されたマスターキーの最新バージョンで再暗号化
Sign	データの署名を作成
Verify	データの署名と照合して検証結果を返す

Token Auth API

Token Auth API関連 APIの説明は次の通りです。

API	説明
Encrypt	キーの現在のバージョンでデータを暗号化
Decrypt	キーで暗号文を復号化
Create Custom Key	暗号キーとして使用する任意の生キー(raw key)を作成
Re-encrypt	暗号文を指定されたマスターキーの最新バージョンで再暗号化
Sign	データの署名を作成
Verify	データの署名と照合して検証結果を返す
Get Public Key	公開鍵を照会
Create Access Token	アクセストークンを生成
Renew Token Set	トークンセット(アクセストークンとリフレッシュトークン)を再生成

Key Management Service関連リソース

Key Management Service APIについてユーザーの理解に役立つよう、さまざまな関連リソースを提供しています。

Key Management Service APIの使用方法
署名(シグネチャー)の作成: リクエストヘッダに追加する署名の作成方法
API Gatewayご利用ガイド: リクエストヘッダに追加する API Keyを発行
Sub Accountご利用ガイド: リクエストヘッダに追加する Access Keyの発行方法
Ncloudの共通レスポンスステータスコード: Key Management Serviceで使用される NAVERクラウドプラットフォームの共通レスポンスステータスコード情報
Key Management Serviceサービスの使用方法
Key Management Serviceご利用ガイド: NAVERクラウドプラットフォームコンソールで Key Management Serviceを使用する方法
Ncloud使用環境ガイド: VPC、Classic環境とサポート有無に関するガイド
料金の紹介、特徴、詳細機能: Key Management Serviceの料金体系、特徴、詳細機能のサマリー
サービスのお知らせ: Key Management Service関連の最新のお知らせ
よくある質問: Key Management Serviceに関するよくあるご質問
お問い合わせ: APIガイドだけでは不明な点が解消されない場合、直接問い合わせ