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 Sign API簽署的交易僅限於使用KMS錢包金鑰創建的交易。

先決條件¶

在Hive 控制台 > 区块链 > KMS 凭证 > 添加凭证中注册您的 Cloud KMS 凭证。

創建區塊鏈帳戶錢包地址和 KMS 錢包金鑰¶

使用您的雲服務帳戶在 KMS 中創建錢包密鑰，並基於此錢包密鑰創建區塊鏈帳戶錢包地址。錢包密鑰存儲在 KMS 中，無法驗證。如果在密鑰創建過程中有延遲，則錢包地址可能不會包含在 API 響應中。您可以使用 KMS 錢包信息查詢 API 和密鑰 ID (keyId) 檢索錢包地址。

請求網址¶

實時 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	區塊鏈網絡	字串	是
x-credential-id	在 Hive 控制台註冊 `Credentials` 時獲得的唯一值	字串	是
Authorization	調用 API 所需的身份驗證令牌	字串	是

請求主體¶

欄位名稱	描述	類型	必填
keyName	輸入要創建的密鑰的名稱。	字串	Y
keyOptions	KMS 錢包密鑰選項資訊	json	Y
keyOptions.location	密鑰將被儲存的位置。這指的是各雲服務使用的 KMS 位置資訊。	字串	* GCP: Y (位置，例如: asia-northeast3) * AWS: Y (區域，例如: ap-northeast-2d)
keyOptions.project	GCP 專案 ID	字串	* GCP: Y * AWS: N
keyOptions.keyRing	GCP KeyRing 的資訊	字串	* GCP: Y * AWS: 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 KeyRing 信息	string
data.options.keyVersion	GCP 密钥版本信息	string
data.regId	密钥注册人 ID	string
data.modId	密钥修改人 ID	string
data.createdAt	密钥注册日期	string
data.updatedAt	密钥修改日期	string

請求範例¶

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¶

直播網址	https://bc-api.qpyou.cn/core/v1/kms/import
沙盒網址	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 (位置，範例：asia-northeast3) * AWS: Y (區域，範例：ap-northeast-2d)
keyOptions.project	GCP 專案 ID	string	* GCP: Y * AWS: N
keyOptions.keyRing	GCP 金鑰環的資訊	string	* GCP: Y * AWS: N
requesterId	請求者 ID。這是一個任意值，用於區分 API 呼叫者。登錄到 Hive 控制台的帳戶 ID 在創建 KMS 錢包時作為 requesterId 輸入。	string	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 密鑰環的信息	字串
data.options.keyVersion	GCP 密鑰版本的信息	字串
data.regId	密鑰註冊人的 ID。與 `requesterId` 相同。	字串
data.modId	密鑰修改者的 ID	字串
data.createdAt	密鑰註冊日期	字串
data.updatedAt	密鑰修改日期	字串

請求範例¶

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 鍵錢包的唯一 ID (keyId) 或鍵名稱 (keyName) 來檢索 KMS 鍵錢包信息和帳戶錢包地址。如果您在創建鍵時無法驗證錢包地址，則可以使用此功能。

請求 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 或鍵名稱	字串	Y

標頭參數¶

欄位名稱	描述	類型	是否必填
x-credential-id	在 Hive 控制台註冊 `Credentials` 時獲得的唯一值	字串	是
Authorization	呼叫 API 所需的身份驗證令牌	字串	是

回應¶

欄位名稱	描述	類型
code	API 呼叫結果代碼，0:成功	數字
message	結果訊息	字串
data	API 回應數據	json
data.keyId	創建的金鑰唯一 ID	字串
data.keyName	創建的金鑰別名	字串
data.purpose	金鑰使用目的	字串
data.algorithm	金鑰生成算法類型	字串
data.cloudType	雲平台類型	字串
data.network	金鑰將使用的區塊鏈網絡	字串
data.options	金鑰選項信息	json
data.options.project	GCP 專案 ID	字串
data.options.location	金鑰存儲位置	字串
data.options.keyRing	GCP 金鑰環信息	字串
data.options.keyVersion	GCP 金鑰版本信息	字串
data.regId	金鑰註冊者 ID	字串
data.modId	金鑰修改者 ID	字串
data.createdAt	金鑰註冊日期	字串
data.updatedAt	金鑰修改日期	字串

請求範例¶

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¶

直播網址	https://bc-api.qpyou.cn/core/v1/kms
沙盒網址	https://sandbox-bc-api.qpyou.cn/core/v1/kms
HTTP 方法	GET
內容類型	application/json

標頭參數¶

欄位名稱	描述	類型	必需
x-network	區塊鏈網絡	字串	是
x-credential-id	在 Hive 控制台註冊 `Credentials` 時獲得的唯一值	字串	是
Authorization	調用 API 所需的身份驗證令牌	字串	是

查詢參數¶

欄位名稱	描述	類型	必填
page	當前頁碼	數字	否
limit	每頁顯示的 KMS 金鑰錢包資訊和帳戶錢包地址的數量	數字	否

回應¶

欄位名稱	描述	類型
code	API 呼叫結果代碼，0: 成功	數字
message	結果訊息	字串
data	API 回應數據	json
data.kms	KMS 錢包金鑰資訊和錢包地址的列表	array(json)
data.meta	分頁資訊	json
data.meta.totalItems	查詢的項目總數（KMS 錢包金鑰和錢包地址資訊的數量）	數字
data.meta.itemsPerPage	每頁顯示的 KMS 錢包金鑰和錢包地址資訊的數量	數字
data.meta.totalPages	總頁數	數字
data.meta.currentPage	當前頁碼	數字

`data.kms` 陣列中包含的每個元素的信息：KMS 錢包密鑰信息和帳戶錢包地址¶

欄位名稱	描述	類型
keyId	創建的密鑰的唯一 ID	字串
keyName	創建的密鑰的別名	字串
address	使用 KMS 密鑰創建的區塊鏈帳戶錢包地址	字串
purpose	使用該密鑰的目的	字串
algorithm	密鑰生成算法的類型	字串
cloudType	雲平台的類型	字串
network	將使用該密鑰的區塊鏈網絡	字串
options	密鑰選項信息	json
options.project	GCP 項目 ID	字串
options.location	密鑰存儲的位置	字串
options.keyRing	GCP 密鑰環信息	字串
options.keyVersion	GCP 密鑰版本信息	字串
regId	密鑰註冊 ID	字串
modId	密鑰修改者 ID	字串
createdAt	密鑰註冊日期	字串
updatedAt	密鑰修改日期	字串

請求範例¶

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¶

直播網址	https://bc-api.qpyou.cn/core/v1/kms/sign
沙盒網址	https://sandbox-bc-api.qpyou.cn/core/v1/kms/sign
HTTP 方法	POST
內容類型	application/json

標頭參數¶

欄位名稱	描述	類型	必填
x-credential-id	在 Hive 控制台註冊 `Credentials` 時獲得的唯一值	字串	是
Authorization	呼叫 API 所需的身份驗證令牌	字串	是

請求主體¶

欄位名稱	描述	類型	必需
from	簽名將從中生成的 KMS 錢包地址。它必須與創建交易的 API 請求主體中的 `from` 相同 (範例)。	字串	是
unsignedTx	未簽名的交易數據。這是您在創建交易時收到的 `data.rawTx`。對於 unsignedTx 支持以下類型： 1. 交易數據 2. 多重簽名交易數據（當 `x-network` 為 `polygon` 時）	字串	是

回應¶

欄位名稱	描述	類型
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¶

標頭參數¶

請求主體¶

回應¶

請求範例¶

回應範例¶

檢索 KMS 金鑰錢包資訊和帳戶錢包地址¶

請求 URL¶

路徑參數¶

標頭參數¶

回應¶

請求範例¶

回應範例¶

檢索 KMS 金鑰錢包資訊和帳戶錢包地址列表¶

請求 URL¶

標頭參數¶

查詢參數¶

回應¶

data.kms 陣列中包含的每個元素的信息：KMS 錢包密鑰信息和帳戶錢包地址¶

請求範例¶

回應範例¶

使用 KMS 錢包金鑰簽署交易¶

請求 URL¶

標頭參數¶

請求主體¶

回應¶

請求範例¶

回應範例¶

`data.kms` 陣列中包含的每個元素的信息：KMS 錢包密鑰信息和帳戶錢包地址¶