KMS API

クラウドキー管理システム（KMS）は、クラウドがユーザーに代わって暗号化されたキーを管理するサービスです（Google Cloud Platform（GCP）KMS、Amazon Web Services（AWS）KMS）。

ブロックチェーンオープンAPI - KMS APIは、クラウドKMSに保存されたキーをブロックチェーンアカウントウォレットキー（秘密鍵またはウォレット秘密鍵）として使用することを可能にします。KMS APIを使用すると、ユーザーはトランザクションを生成し、それに署名し、ブロックチェーンに送信することができ、ブロックチェーンアカウントウォレットキーを直接管理することなく、代わりにKMSに保存されたキーを介して行うことができます。KMS APIがサポートするクラウドKMSプラットフォームは**GCP**と**AWS**です。

例えば、KMS APIは次のように使用できます：

クラウドKMSにすでにキーがある場合

クラウド認証情報を準備する
Hive コンソール > ブロックチェーン > KMS 認証情報 > 認証情報の追加 にクラウドサービスアカウント情報（Credentials）を登録し、x-credential-idを取得する
クラウド KMS キー情報を準備する
APIを呼び出してウォレットアドレスを登録する
ウォレットアドレスを取得する
KMS ウォレット情報を照会する
KMS ウォレットでトランザクションを作成する: トークンを送信するやスマートコントラクトをデプロイするなどの新しいトランザクションを生成するためのAPIを呼び出す
KMS サイン APIで作成したトランザクションに署名する
署名されたトランザクションをブロックチェーンネットワークに送信する

クラウドKMSを使用していない場合、またはクラウドKMSにキーがない場合

クラウドKMSサービスアカウントを準備する
ウォレットキーを作成する: ウォレットキー作成APIによって生成された
1. クラウド認証情報を準備する
2. ブロックチェーンAPI認証キーを準備する
3. Hive コンソール > ブロックチェーン > KMS認証情報 > 認証情報を追加でクラウドサービスアカウント情報（Credentials）を登録し、x-credential-idを取得する
4. x-credential-idとAPI認証キーを使用してKMSウォレットキーを作成する
5. ウォレットキーとウォレットアドレスを取得する
KMSウォレット情報を照会する
KMSウォレットでトランザクションを作成する: トークンを送信するやスマートコントラクトを展開するなどの新しいトランザクションを生成するためのAPIを呼び出す
KMSサインAPIで作成したトランザクションに署名する
署名されたトランザクションをブロックチェーンネットワークに送信する

Note

KMSサインAPIで署名できるトランザクションは、KMSウォレットキーで作成されたもののみです。

前提条件¶

クラウド KMS Credentials をHive コンソール > ブロックチェーン > KMS 認証情報 > 認証情報を追加に登録してください。

ブロックチェーンアカウントのウォレットアドレスとKMSウォレットキーの作成¶

クラウドサービスアカウントを使用してKMSにウォレットキーを作成し、このウォレットキーに基づいてブロックチェーンアカウントのウォレットアドレスを作成します。ウォレットキーはKMSに保存され、検証することはできません。キー作成プロセスに遅延がある場合、ウォレットアドレスがAPIレスポンスに含まれないことがあります。キーID（keyId）を使用して、KMSウォレット情報照会APIを使用してウォレットアドレスを取得できます。

リクエストURL¶

ライブURL	https://bc-api.qpyou.cn/core/v1/kms
サンドボックスURL	https://sandbox-bc-api.qpyou.cn/core/v1/kms
HTTPメソッド	POST
コンテンツタイプ	application/json

ヘッダーパラメータ¶

フィールド名	説明	タイプ	必須
x-network	ブロックチェーンネットワーク	文字列	Y
x-credential-id	Hive コンソールに`Credentials`を登録した際に取得される一意の値	文字列	Y
Authorization	APIを呼び出すために必要な認証トークン	文字列	Y

リクエストボディ¶

フィールド名	説明	タイプ	必須
keyName	作成するキーの希望名を入力します。	文字列	Y
keyOptions	KMS ウォレットキーオプション情報	json	Y
keyOptions.location	キーが保存される場所。これは各クラウドサービスで使用されるKMSの位置情報を指します。	文字列	* GCP: Y (location, 例: asia-northeast3) * AWS: Y (region, 例: ap-northeast-2d)
keyOptions.project	GCP プロジェクト ID	文字列	* GCP: Y * AWS: N
keyOptions.keyRing	GCP KeyRing に関する情報	文字列	* GCP: Y * AWS: N

応答¶

フィールド名	説明	タイプ
code	API呼び出し結果コード、0: 成功	数値
message	結果メッセージ	文字列
data	APIレスポンスデータ	JSON
data.keyId	作成されたキーの一意のID	文字列
data.keyName	作成されたキーのエイリアス	文字列
data.address	KMSキーで作成されたブロックチェーンアカウントのウォレットアドレス	文字列
data.purpose	キー使用の目的	文字列
data.algorithm	キー生成アルゴリズムのタイプ	文字列
data.cloudType	クラウドプラットフォームのタイプ	文字列
data.network	キーが使用されるブロックチェーンネットワーク	文字列
data.options	キーオプション情報	JSON
data.options.project	GCPプロジェクトID	文字列
data.options.location	キーが保存されている場所	文字列
data.options.keyRing	GCP KeyRingに関する情報	文字列
data.options.keyVersion	GCPキーのバージョンに関する情報	文字列
data.regId	キー登録者ID	文字列
data.modId	キー修正者ID	文字列
data.createdAt	キー登録日	文字列
data.updatedAt	キー修正日	文字列

リクエストサンプル¶

curl -X 'POST' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/kms' 
  -H 'accept: application/json' 
  -H 'x-credential-id: eb6cc005-b8d0-bc96-8b60-a531c2f15fd2' 
  -H 'x-network: polygon' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXlObyI6MSwiaWQiOiJwbGF0Zm9ybSIsImNvbXBhbnkiO... 
  -H 'Content-Type: application/json' 
  -d '{
  "keyName": "test-key",
  "keyOptions": {
    "project": "test-project",
    "location": "asia-northeast3",
    "keyRing": "test-keyring"
    },
    "requesterId": "system"
    }'

応答サンプル¶

{
  "code": 0,
  "message": "success",
  "data": {
    "keyId": "test1-game-provider",
    "keyName": "projects/tribal-octane-403302/locations/asia-northeast3/keyRings/test-keyring-001/cryptoKeys/test1-game-provider/cryptoKeyVersions/1",
    "address": "0xc5AC98006fe612395b132742Fbe80a6Dc184670a",
    "purpose": "ASYMMETRIC_SIGN",
    "algorithm": "EC_SIGN_SECP256K1_SHA256",
    "cloudType": "gcp",
    "network": "polygon",
    "options": {
      "project": "project",
      "location": "asia-northeast3",
      "keyRing": "keyring",
      "keyVersion": "1"
    },
    "regId": "test",
    "modId": null,
    "createdAt": "2024-02-22T08:28:04.000Z",
    "updatedAt": null
  }
}

ブロックチェーンアカウントウォレットアドレスを登録する¶

KMSウォレットキーに基づいてブロックチェーンアカウントウォレットアドレスを作成し、それをHiveサーバーに登録します。GCPを使用する場合は、キーのバージョン（keyVersion）を指定する必要があります。

リクエストURL¶

ライブURL	https://bc-api.qpyou.cn/core/v1/kms/import
サンドボックスURL	https://sandbox-bc-api.qpyou.cn/core/v1/kms/import
HTTPメソッド	POST
コンテンツタイプ	application/json

ヘッダーパラメータ¶

フィールド名	説明	タイプ	必須
x-network	ブロックチェーンネットワーク	文字列	Y
x-credential-id	Hive コンソールで `Credentials` を登録した際に取得されるユニークな値	文字列	Y
Authorization	APIを呼び出すために必要な認証トークン	文字列	Y

リクエストボディ¶

フィールド名	説明	タイプ	必須
keys	KMSウォレットキー情報	array(json)	Y
keys.keyId	作成されたキーの一意のID	string	Y
keys.keyVersion	GCPを使用する際のキーのバージョン情報	string	* GCP: Y * AWS: N
keyOptions	キーオプション情報	json	Y
keyOptions.location	キーを保存する場所。この情報は各クラウドが使用するKMSの場所情報です。	string	* GCP: Y (location, 例: asia-northeast3) * AWS: Y (region, 例: ap-northeast-2d)
keyOptions.project	GCPプロジェクトID	string	* GCP: Y * AWS: N
keyOptions.keyRing	GCPキーリングに関する情報	string	* GCP: Y * AWS: N
requesterId	リクエスターID。API呼び出しを区別するための任意の値です。KMSウォレットが作成される際には、HiveコンソールにログインしているアカウントIDがrequesterIdとして入力されます。	string	N

応答¶

フィールド名	説明	タイプ
code	API呼び出し結果コード、0: 成功	number
message	結果メッセージ	string
data	APIレスポンスデータ	json
data.keyId	作成されたキーのユニークID	string
data.keyName	作成されたキーのエイリアス	string
data.address	KMSキーで作成されたブロックチェーンアカウントのウォレットアドレス	string
data.purpose	キーの使用目的	string
data.algorithm	キー生成アルゴリズムのタイプ	string
data.cloudType	クラウドプラットフォームのタイプ	string
data.network	キーが使用されるブロックチェーンネットワーク	string
data.options	キーオプション情報	json
data.options.project	GCPプロジェクトID	string
data.options.location	キーが保存されている場所	string
data.options.keyRing	GCPキーリングの情報	string
data.options.keyVersion	GCPキーのバージョン情報	string
data.regId	キー登録者のID。`requesterId`と同じです。	string
data.modId	キー修正者のID	string
data.createdAt	キー登録日	string
data.updatedAt	キー修正日	string

リクエストサンプル¶

curl -X 'POST' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/kms/import' 
  -H 'accept: application/json' 
  -H 'x-credential-id: 9b3c0c1d-868c-71ea-a1a9-e615148b7f14' 
  -H 'x-network: polygon' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXlObyI6MSwiaWQiOiJwbGF0Zm9ybSIsImNvbXBhbnkiOm51bGwsInJvb...' 
  -H 'Content-Type: application/json' 
  -d '{
  "keys": [
    {
      "keyId": "test1-game-provider",
      "keyVersion": "1"
    }
  ],
  "keyOptions": {
    "project": "kms-test",
    "location": "asia-northeast3",
    "keyRing": "key-ring"
  },
  "requesterId": "system"
}'

レスポンスサンプル¶

{
  "code": 0,
  "message": "success",
  "data": {
    "keyId": "kms-key-002",
    "keyName": "projects/quixotic-carver-412405/locations/asia-northeast3/keyRings/keyring/cryptoKeys/kms-key-002/cryptoKeyVersions/1",
    "address": "0x1e0481127b0ed12b6b6911bec32d414d76042860",
    "purpose": "ASYMMETRIC_SIGN",
    "algorithm": "EC_SIGN_SECP256K1_SHA256",
    "cloudType": "gcp",
    "network": "polygon",
    "options": {
      "project": "quixotic-carver-412405",
      "location": "asia-northeast3",
      "keyRing": "keyring",
      "keyVersion": "1"
    },
    "regId": "system",
    "modId": null,
    "createdAt": "2024-02-22T08:28:04.000Z",
    "updatedAt": null
  }
}

KMSキーウォレット情報とアカウントウォレットアドレスを取得する¶

KMSキーウォレット情報とアカウントウォレットアドレスを、KMSウォレットキーのユニークID（keyId）またはキー名（keyName）を使用して取得します。これは、キーを作成する際にウォレットアドレスを確認できなかった場合に使用できます。

リクエストURL¶

ライブURL	https://bc-api.qpyou.cn/core/v1/kms/{key}
サンドボックスURL	https://sandbox-bc-api.qpyou.cn/core/v1/kms/{key}
HTTPメソッド	GET
コンテンツタイプ	application/json

パスパラメータ¶

フィールド名	説明	タイプ	必須
key	キーのユニークIDまたはキー名	string	Y

ヘッダーパラメータ¶

フィールド名	説明	タイプ	必須
x-credential-id	Hive コンソールで`Credentials`を登録した際に取得されるユニークな値	文字列	Y
Authorization	APIを呼び出すために必要な認証トークン	文字列	Y

応答¶

フィールド名	説明	タイプ
code	API呼び出し結果コード、0:成功	number
message	結果メッセージ	string
data	APIレスポンスデータ	json
data.keyId	作成されたキーのユニークID	string
data.keyName	作成されたキーのエイリアス	string
data.purpose	キー使用の目的	string
data.algorithm	キー生成アルゴリズムのタイプ	string
data.cloudType	クラウドプラットフォームのタイプ	string
data.network	キーが使用されるブロックチェーンネットワーク	string
data.options	キーオプション情報	json
data.options.project	GCPプロジェクトID	string
data.options.location	キーが保存されている場所	string
data.options.keyRing	GCPキーリング情報	string
data.options.keyVersion	GCPキーのバージョン情報	string
data.regId	キー登録者ID	string
data.modId	キー修正者ID	string
data.createdAt	キー登録日	string
data.updatedAt	キー修正日	string

リクエストサンプル¶

curl -X 'GET' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/kms/kms-key-002' 
  -H 'accept: application/json' 
  -H 'x-credential-id: 9b3c0c1d-868c-71ea-a1a9-e615148b7f14' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXlObyI6MSwiaWQiOiJwbGF0Zm9ybSIsImNvbXBhbnkiOm51bGwsInJvbGUiOiJhZG1pb...'

応答サンプル¶

{
  "code": 0,
  "message": "success",
  "data": {
    "keyId": "test1-game-provider",
    "keyName": "projects/tribal-octane-403302/locations/asia-northeast3/keyRings/test-keyring-001/cryptoKeys/test1-game-provider/cryptoKeyVersions/1",
    "address": "0xc5AC98006fe612395b132742Fbe80a6Dc184670a",
    "purpose": "ASYMMETRIC_SIGN",
    "algorithm": "EC_SIGN_SECP256K1_SHA256",
    "cloudType": "gcp",
    "network": "polygon",
    "options": {
      "project": "project",
      "location": "asia-northeast3",
      "keyRing": "keyring",
      "keyVersion": "1"
    },
    "regId": "test",
    "modId": null,
    "createdAt": "2024-02-22T08:28:04.000Z",
    "updatedAt": null
  }
}

KMSキーウォレット情報とアカウントウォレットアドレスリストを取得する¶

KMSキーのウォレット情報とアカウントウォレットアドレスのリストを取得します。

リクエストURL¶

ライブURL	https://bc-api.qpyou.cn/core/v1/kms
サンドボックスURL	https://sandbox-bc-api.qpyou.cn/core/v1/kms
HTTPメソッド	GET
コンテンツタイプ	application/json

ヘッダーパラメータ¶

フィールド名	説明	タイプ	必須
x-network	ブロックチェーンネットワーク	文字列	Y
x-credential-id	Hive コンソールに`Credentials`を登録した際に取得されるユニークな値	文字列	Y
Authorization	APIを呼び出すために必要な認証トークン	文字列	Y

クエリパラメータ¶

フィールド名	説明	タイプ	必須
page	現在のページ番号	数字	N
limit	1ページあたり表示するKMSキーウォレット情報とアカウントウォレットアドレスの数	数字	N

応答¶

フィールド名	説明	タイプ
code	API呼び出し結果コード、0: 成功	数字
message	結果メッセージ	文字列
data	APIレスポンスデータ	json
data.kms	KMSウォレットキー情報とウォレットアドレスのリスト	配列(json)
data.meta	ページネーション情報	json
data.meta.totalItems	取得したアイテムの総数（KMSウォレットキーとウォレットアドレス情報の数）	数字
data.meta.itemsPerPage	ページごとに表示されるKMSウォレットキーとウォレットアドレス情報の数	数字
data.meta.totalPages	総ページ数	数字
data.meta.currentPage	現在のページ番号	数字

`data.kms` 配列に含まれる各要素の情報: KMS ウォレットキー情報とアカウントウォレットアドレス¶

フィールド名	説明	タイプ
keyId	作成されたキーのユニークID	string
keyName	作成されたキーのエイリアス	string
address	KMSキーで作成されたブロックチェーンアカウントのウォレットアドレス	string
purpose	キーの使用目的	string
algorithm	キー生成アルゴリズムのタイプ	string
cloudType	クラウドプラットフォームのタイプ	string
network	キーが使用されるブロックチェーンネットワーク	string
options	キーオプション情報	json
options.project	GCPプロジェクトID	string
options.location	キーが保存されている場所	string
options.keyRing	GCPキーリング情報	string
options.keyVersion	GCPキーのバージョン情報	string
regId	キー登録者ID	string
modId	キー修正者ID	string
createdAt	キー登録日	string
updatedAt	キー修正日	string

リクエストサンプル¶

curl -X 'GET' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/kms?page=1&limit=10' 
  -H 'accept: application/json' 
  -H 'x-credential-id: 41e26545-547e-7632-be1f-289f75c092d2' 
  -H 'x-network: polygon' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXlObyI6MSwiaWQiOiJwbGF0Zm9ybSIsImNvbXBhbnkiOm51bGwsInJv...'

レスポンスサンプル¶

{
  "code": 0,
  "message": "success",
  "data": {
    "kms": [
      {
        "keyId": "test-polygon-001",
        "keyName": "projects/tribal-octane-403302/locations/asia-northeast3/keyRings/test-keyring-001/cryptoKeys/test-polygon-001/cryptoKeyVersions/1",
        "address": "0x599220fb6cd54553b9c2dfda3b0f711d7ebc21fb",
        "purpose": "ASYMMETRIC_SIGN",
        "algorithm": "EC_SIGN_SECP256K1_SHA256",
        "cloudType": "gcp",
        "network": "polygon",
        "options": {
          "project": "tribal-octane-403302",
          "location": "asia-northeast3",
          "keyRing": "test-keyring-001",
          "keyVersion": "1"
        },
        "regId": "system",
        "modId": null,
        "createdAt": "2024-02-22T08:27:58.000Z",
        "updatedAt": null
      },{
        "keyId": "kms-key-002",
        "keyName": "projects/quixotic-carver-412405/locations/asia-northeast3/keyRings/keyring/cryptoKeys/kms-key-002/cryptoKeyVersions/1",
        "address": "0x1e0481127b0ed12b6b6911bec32d414d76042860",
        "purpose": "ASYMMETRIC_SIGN",
        "algorithm": "EC_SIGN_SECP256K1_SHA256",
        "cloudType": "gcp",
        "network": "polygon",
        "options": {
          "project": "quixotic-carver-412405",
          "location": "asia-northeast3",
          "keyRing": "keyring",
          "keyVersion": "1"
        },
        "regId": "system",
        "modId": null,
        "createdAt": "2024-02-22T08:28:04.000Z",
        "updatedAt": null
      }
    ],
    "meta": {
      "totalItems": 2,
      "itemCount": 2,
      "itemsPerPage": 10,
      "totalPages": 1,
      "currentPage": 1
    }
  }
}

KMSウォレットキーでトランザクションに署名する¶

KMSウォレットキーでトランザクションに署名します。KMSウォレットアカウントで作成されたトランザクションのみ、KMSウォレットキーで署名できます。

リクエストURL¶

ライブURL	https://bc-api.qpyou.cn/core/v1/kms/sign
サンドボックスURL	https://sandbox-bc-api.qpyou.cn/core/v1/kms/sign
HTTPメソッド	POST
コンテンツタイプ	application/json

ヘッダーパラメータ¶

フィールド名	説明	タイプ	必須
x-credential-id	Hive コンソールで`Credentials`を登録したときに取得される一意の値	文字列	Y
Authorization	APIを呼び出すために必要な認証トークン	文字列	Y

リクエストボディ¶

フィールド名	説明	タイプ	必須
from	署名が行われるKMSウォレットアドレス。APIのリクエストボディ内の`from`と同一でなければなりません（例）そのトランザクションを作成します。	string	Y
unsignedTx	署名されていないトランザクションデータ。これは、トランザクションが作成されたときに受け取る`data.rawTx`です。unsignedTxにサポートされているタイプは次のとおりです: 1. トランザクションデータ 2. マルチシグネチャトランザクションデータ（`x-network`が`polygon`の場合）	string	Y

応答¶

フィールド名	説明	タイプ
code	APIコール結果コード、0: 成功	数値
message	結果メッセージ	文字列
data	APIレスポンスデータ	json
data.signedTx	署名されたトランザクションの情報	文字列

リクエストサンプル¶

curl -X 'POST' 
  'http://sandbox-bc-api.qpyou.cn/core/v1/kms/sign' 
  -H 'accept: application/json' 
  -H 'x-credential-id: eb6cc005-b8d0-bc96-8b60-a531c2f15fd2' 
  -H 'Content-Type: application/json' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20yd...' 
  -d '{
  "from": "0xc5AC98006fe612395b132742Fbe80a6Dc184670a",
  "unsignedTx": "0x5a0ca3a7eebbafa946da6ed0160930fc4f334887dbf11a9b38937ab8831fd125..."
}'

応答サンプル¶

{
  "code": 0,
  "message": "success",
  "data": {
    "signedData": "string"
  }
}

KMS API

前提条件¶

ブロックチェーンアカウントのウォレットアドレスとKMSウォレットキーの作成¶

リクエストURL¶

ヘッダーパラメータ¶

リクエストボディ¶

応答¶

リクエストサンプル¶

応答サンプル¶

ブロックチェーンアカウントウォレットアドレスを登録する¶

リクエストURL¶

ヘッダーパラメータ¶

リクエストボディ¶

応答¶

リクエストサンプル¶

レスポンスサンプル¶

KMSキーウォレット情報とアカウントウォレットアドレスを取得する¶

リクエストURL¶

パスパラメータ¶

ヘッダーパラメータ¶

応答¶

リクエストサンプル¶

応答サンプル¶

KMSキーウォレット情報とアカウントウォレットアドレスリストを取得する¶

リクエストURL¶

ヘッダーパラメータ¶

クエリパラメータ¶

応答¶

data.kms 配列に含まれる各要素の情報: KMS ウォレットキー情報とアカウントウォレットアドレス¶

リクエストサンプル¶

レスポンスサンプル¶

KMSウォレットキーでトランザクションに署名する¶

リクエストURL¶

ヘッダー パラメータ¶

リクエストボディ¶

応答¶

リクエストサンプル¶

応答サンプル¶

`data.kms` 配列に含まれる各要素の情報: KMS ウォレットキー情報とアカウントウォレットアドレス¶

ヘッダーパラメータ¶