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

Path parameter

パラメータ名 タイプ 説明
keyTag String(Required) 暗号化に使用するマスタキーのtagの値

Request body

{
  "plaintext" : string
}
パラメータ名 タイプ 説明
plaintext String(Required) 暗号化するデータ(最大32KB)
(*Base64 Encodinggが必要です。)

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

関連情報のご確認

に対する検索結果は~件です。 ""

    に対する検索結果がありません。 ""

    処理中...