KMS 接口

云密钥管理系统（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 钱包密钥创建的交易可以通过 KMS 签名 API 进行签名。

先决条件¶

在Hive 控制台 > 区块链 > KMS 凭据 > 添加凭据中注册您的 Cloud 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	区块链网络	字符串	是
x-credential-id	在 Hive 控制台注册 `Credentials` 时获得的唯一值	字符串	是
Authorization	调用 API 所需的身份验证令牌	字符串	是

请求体¶

字段名称	描述	类型	必需
keyName	输入要创建的密钥的名称。	字符串	是
keyOptions	KMS 钱包密钥选项信息	json	是
keyOptions.location	密钥将存储的位置。这指的是每个云服务使用的 KMS 位置信息。	字符串	* GCP: 是 (位置，例如: asia-northeast3) * AWS: 是 (区域，例如: ap-northeast-2d)
keyOptions.project	GCP 项目 ID	字符串	* GCP: 是 * AWS: 否
keyOptions.keyRing	GCP KeyRing 信息	字符串	* GCP: 是 * AWS: 否

响应¶

字段名称	描述	类型
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	区块链网络	字符串	是
x-credential-id	在 Hive 控制台注册 `Credentials` 时获得的唯一值	字符串	是
Authorization	调用 API 所需的身份验证令牌	字符串	是

请求体¶

字段名称	描述	类型	必需
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：成功	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 钱包密钥的唯一 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:成功	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¶

直播网址	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	当前页码	number	N
limit	每页显示的KMS密钥钱包信息和账户钱包地址的数量	number	N

响应¶

字段名称	描述	类型
code	API调用结果代码，0：成功	number
message	结果消息	string
data	API响应数据	json
data.kms	KMS钱包密钥信息和钱包地址列表	array(json)
data.meta	分页信息	json
data.meta.totalItems	查询的项目总数（KMS钱包密钥和钱包地址信息的数量）	number
data.meta.itemsPerPage	每页显示的KMS钱包密钥和钱包地址信息的数量	number
data.meta.totalPages	页数总数	number
data.meta.currentPage	当前页码	number

`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：成功	number
message	结果消息	string
data	API 响应数据	json
data.signedTx	签名交易的信息	string

请求示例¶

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 接口

先决条件¶

创建区块链账户钱包地址和 KMS 钱包密钥¶

请求 URL¶

头部参数¶

请求体¶

响应¶

请求示例¶

响应示例¶

注册区块链账户钱包地址¶

请求 URL¶

头部参数¶

请求体¶

响应¶

请求示例¶

响应示例¶

检索 KMS 密钥钱包信息和账户钱包地址¶

请求 URL¶

路径参数¶

头部参数¶

响应¶

请求示例¶

响应示例¶

检索 KMS 密钥钱包信息和账户钱包地址列表¶

请求 URL¶

头部参数¶

查询参数¶

响应¶

data.kms 数组中包含的每个元素的信息：KMS 钱包密钥信息和账户钱包地址¶

请求示例¶

响应示例¶

使用 KMS 钱包密钥签名交易¶

请求 URL¶

头部参数¶

请求体¶

响应¶

请求示例¶

响应示例¶

`data.kms` 数组中包含的每个元素的信息：KMS 钱包密钥信息和账户钱包地址¶