文档中心知识库API Explorer
文档中心›探索更多›ZStack ZSphere›开发手册ZVF
文档目录

密钥提供程序相关接口

查询密钥提供程序(QueryKeyProvider)

API请求

URLs
GET zstack/v1/key-providers
GET zstack/v1/key-providers/{uuid}
Headers
Authorization: OAuth the-session-uuid
Curl示例
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/key-providers?q=uuid=ff0340e5866e385b9a86e592dd7e1900
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/key-providers/be171f47b02632e59eca8602e7413f10

可查询字段

运行CLI命令行工具，输入QueryKeyProvider并按Tab键查看所有可查询字段以及可跨表查询的资源名。

API返回

返回示例
{
  "inventories": [
    {
      "uuid": "ff0340e5866e385b9a86e592dd7e1900",
      "name": "kms-1",
      "description": "example",
      "type": "KMS",
      "connected": true,
      "createDate": "Nov 14, 2017 2:20:57 PM",
      "lastOpDate": "Nov 14, 2017 2:20:57 PM"
    }
  ]
}
名字 类型 描述 起始版本
success boolean 5.0.0
inventories List 详情参考inventories 5.0.0
error ErrorCode 详情参考error 5.0.0
#inventories
名字 类型 描述 起始版本
uuid String 资源的UUID，唯一标示该资源 5.0.0
name String 资源名称 5.0.0
description String 资源的详细描述 5.0.0
type String 密钥提供程序类型 5.0.0
connected boolean 是否已连接 5.0.0
createDate Timestamp 创建时间 5.0.0
lastOpDate Timestamp 最后一次修改时间 5.0.0
#error
名字 类型 描述 起始版本
code String 错误码号，错误的全局唯一标识，例如SYS.1000, HOST.1001 0.6
description String 错误的概要描述 0.6
details String 错误的详细信息 0.6
elaboration String 保留字段，默认为null 0.6
opaque LinkedHashMap 保留字段，默认为null 0.6
cause ErrorCode 根错误，引发当前错误的源错误，若无原错误，该字段为null 0.6

SDK示例

Java SDK
QueryKeyProviderAction action = new QueryKeyProviderAction();
action.conditions = asList("uuid=ff0340e5866e385b9a86e592dd7e1900");
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
QueryKeyProviderAction.Result res = action.call();
Python SDK
action = QueryKeyProviderAction()
action.conditions = ["uuid=ff0340e5866e385b9a86e592dd7e1900"]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

对指定密钥重新加密(RekeyKeyProviderRefs)

API请求

URLs
PUT zstack/v1/key-providers/{providerUuid}/rekey
Headers
Authorization: OAuth the-session-uuid
Body
{
  "rekeyKeyProviderRefs": {
    "refIds": [
      1,
      2
    ],
    "rekeyAll": false
  },
  "systemTags": [],
  "userTags": []
}
Note: 上述示例中systemTags、userTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"rekeyKeyProviderRefs":{"refIds":[1,2],"rekeyAll":false}}' \
http://localhost:8080/zstack/v1/key-providers/ff0340e5866e385b9a86e592dd7e1900/rekey
参数列表
名字 类型 位置 描述 可选值 起始版本
refIds (可选) List body(包含在rekeyKeyProviderRefs结构中) 需要重加密的密钥引用ID列表 5.0.0
resourceUuids (可选) List body(包含在rekeyKeyProviderRefs结构中) 关联资源UUID列表，与resourceType配对使用 5.0.0
resourceType (可选) String body(包含在rekeyKeyProviderRefs结构中) 关联资源类型，与resourceUuids配对使用 5.0.0
providerUuid String url 密钥提供程序UUID 5.0.0
rekeyAll (可选) boolean body(包含在rekeyKeyProviderRefs结构中) 是否执行全量重加密；为true时不能再指定refIds或resourceType/resourceUuids 5.0.0
systemTags (可选) List body 系统标签 5.0.0
userTags (可选) List body 用户标签 5.0.0

API返回

返回示例
{
  "totalCount": 3,
  "successCount": 1,
  "skippedCount": 1,
  "failedCount": 1,
  "providerResults": [
    {
      "providerUuid": "provider-uuid-1",
      "providerName": "provider-1",
      "totalRefCount": 3,
      "successRefCount": 1,
      "skippedRefCount": 1,
      "failedRefCount": 1,
      "skippedResources": [
        {
          "keyRefId": 11,
          "resourceType": "TpmVO",
          "resourceUuid": "ff00de2d3ab43127b1abdac68f1e7f00",
          "reason": "encrypted resource key ref[id:11, resourceType:TpmVO, resourceUuid:ff00de2d3ab43127b1abdac68f1e7f00] has empty secret ref"
        }
      ],
      "failedResources": [
        {
          "keyRefId": 12,
          "resourceType": "TpmVO",
          "resourceUuid": "ff00de2d3ab43127b1abdac68f1e7f00",
          "reason": "key-tool rekey failed: failed to decrypt wrapper DEK with KEK"
        }
      ]
    }
  ]
}
名字 类型 描述 起始版本
success boolean 5.0.0
totalCount int 本次涉及的源密钥提供者数量（按 resource ref 关联的 provider 去重） 5.0.0
successCount int 未出现失败 ref 的 provider 数量（含仅有 skip 的 provider） 5.0.0
skippedCount int 存在被跳过 ref 的 provider 数量 5.0.0
failedCount int 存在失败 ref 的 provider 数量 5.0.0
providerResults List 按源密钥提供者聚合的结果；每个元素内含该 provider 下的 skippedResources、failedResources 及各类 ref 计数 5.0.0
error ErrorCode 详情参考error 5.0.0
#error
名字 类型 描述 起始版本
code String 错误码号，错误的全局唯一标识，例如SYS.1000, HOST.1001 0.6
description String 错误的概要描述 0.6
details String 错误的详细信息 0.6
elaboration String 保留字段，默认为null 0.6
opaque LinkedHashMap 保留字段，默认为null 0.6
cause ErrorCode 根错误，引发当前错误的源错误，若无原错误，该字段为null 0.6

SDK示例

Java SDK
RekeyKeyProviderRefsAction action = new RekeyKeyProviderRefsAction();
action.refIds = asList(1,2);
action.providerUuid = "ff0340e5866e385b9a86e592dd7e1900";
action.rekeyAll = false;
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
RekeyKeyProviderRefsAction.Result res = action.call();
Python SDK
action = RekeyKeyProviderRefsAction()
action.refIds = [1, 2]
action.providerUuid = "ff0340e5866e385b9a86e592dd7e1900"
action.rekeyAll = false
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

创建KMS密钥提供程序(CreateKms)

API请求

URLs
POST zstack/v1/key-providers/kms
Headers
Authorization: OAuth the-session-uuid
Body
{
  "params": {
    "endpoint": "kms.example.com",
    "port": 5696,
    "kmipVersion": "1.2",
    "username": "user",
    "password": "password",
    "name": "kp-kms",
    "description": "example"
  },
  "systemTags": [],
  "userTags": []
}
Note: 上述示例中systemTags、userTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X POST -d '{"params":{"endpoint":"kms.example.com","port":5696,"kmipVersion":"1.2","username":"user","password":"password","name":"kp-kms","description":"example"}}' \
http://localhost:8080/zstack/v1/key-providers/kms
参数列表
名字 类型 位置 描述 可选值 起始版本
endpoint String body(包含在params结构中) KMS地址 5.0.0
port Integer body(包含在params结构中) 端口 5.0.0
kmipVersion (可选) String body(包含在params结构中) KMIP协议版本
  • 1.0
  • 1.1
  • 1.2
  • 1.3
  • 1.4
  • 2.0
  • 2.1
 5.0.0
username (可选) String body(包含在params结构中) 用户名 5.0.0
password (可选) String body(包含在params结构中) 密码 5.0.0
name String body(包含在params结构中) 资源名称 5.0.0
description (可选) String body(包含在params结构中) 资源的详细描述 5.0.0
type (可选) String body(包含在params结构中) 密钥提供程序类型 5.0.0
resourceUuid (可选) String body(包含在params结构中) 资源UUID 5.0.0
tagUuids (可选) List body(包含在params结构中) 标签UUID列表 5.0.0
systemTags (可选) List body 系统标签 5.0.0
userTags (可选) List body 用户标签 5.0.0

API返回

返回示例
{
  "inventory": {
    "endpoint": "kms.example.com",
    "port": 5696,
    "kmipVersion": "1.2",
    "username": "user",
    "trustState": "MUTUAL_TRUSTED",
    "activeIdentityUuid": "ff0fe4c52fce34ff9ffca4d3a0fd4d00",
    "serverCertPem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "serverCertInfo": {
      "subject": "CN\u003dkms.example.com,O\u003dzstack",
      "issuer": "CN\u003dzstack-ca,O\u003dzstack",
      "commonName": "kms.example.com",
      "subjectAltNamesDns": [
        "kms.example.com"
      ],
      "subjectAltNamesIp": [
        "127.0.0.1"
      ],
      "expiredDate": "Nov 14, 2017 2:20:57 PM"
    },
    "activeIdentity": {
      "uuid": "ff0fe4c52fce34ff9ffca4d3a0fd4d00",
      "kmsUuid": "ff0a9250e11b3fe5a553d61be176d300",
      "identityType": "CSR",
      "clientCertPem": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----",
      "csrPem": "-----BEGIN CERTIFICATE REQUEST-----\\n...\\n-----END CERTIFICATE REQUEST-----",
      "certExpiredDate": "Nov 14, 2017 2:20:57 PM",
      "createDate": "Nov 14, 2017 2:20:57 PM",
      "lastOpDate": "Nov 14, 2017 2:20:57 PM"
    },
    "uuid": "ff0a9250e11b3fe5a553d61be176d300",
    "name": "kms-1",
    "description": "example",
    "type": "KMS",
    "connected": true,
    "createDate": "Nov 14, 2017 2:20:57 PM",
    "lastOpDate": "Nov 14, 2017 2:20:57 PM"
  }
}
名字 类型 描述 起始版本
success boolean 5.0.0
inventory KeyProviderInventory 详情参考inventory 5.0.0
error ErrorCode 详情参考error 5.0.0
#inventory
名字 类型 描述 起始版本
uuid String 资源的UUID，唯一标示该资源 5.0.0
name String 资源名称 5.0.0
description String 资源的详细描述 5.0.0
type String 密钥提供程序类型 5.0.0
connected boolean 是否已连接 5.0.0
createDate Timestamp 创建时间 5.0.0
lastOpDate Timestamp 最后一次修改时间 5.0.0
#error
名字 类型 描述 起始版本
code String 错误码号，错误的全局唯一标识，例如SYS.1000, HOST.1001 0.6
description String 错误的概要描述 0.6
details String 错误的详细信息 0.6
elaboration String 保留字段，默认为null 0.6
opaque LinkedHashMap 保留字段，默认为null 0.6
cause ErrorCode 根错误，引发当前错误的源错误，若无原错误，该字段为null 0.6

SDK示例

Java SDK
CreateKmsAction action = new CreateKmsAction();
action.endpoint = "kms.example.com";
action.port = 5696;
action.kmipVersion = "1.2";
action.username = "user";
action.password = "password";
action.name = "kp-kms";
action.description = "example";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
CreateKmsAction.Result res = action.call();
Python SDK
action = CreateKmsAction()
action.endpoint = "kms.example.com"
action.port = 5696
action.kmipVersion = "1.2"
action.username = "user"
action.password = "password"
action.name = "kp-kms"
action.description = "example"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

删除KMS密钥提供程序(DeleteKms)

API请求

URLs
DELETE zstack/v1/key-providers/kms/{uuid}
Headers
Authorization: OAuth the-session-uuid
Curl示例
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X DELETE http://localhost:8080/zstack/v1/key-providers/kms/ff0a9250e11b3fe5a553d61be176d300?deleteMode=Permissive
参数列表
名字 类型 位置 描述 可选值 起始版本
uuid String url 资源的UUID，唯一标示该资源 5.0.0
deleteMode (可选) String query 删除模式(Permissive / Enforcing，Permissive) 5.0.0
systemTags (可选) List query 系统标签 5.0.0
userTags (可选) List query 用户标签 5.0.0

API返回

该API成功时返回一个空的JSON结构{}，出错时返回的JSON结构包含一个error字段，例如：
{
	"error": {
		"code": "SYS.1001",
		"description": "A message or a operation timeout",
		"details": "Create VM on KVM timeout after 300s"
	}
}

SDK示例

Java SDK
DeleteKmsAction action = new DeleteKmsAction();
action.uuid = "ff0a9250e11b3fe5a553d61be176d300";
action.deleteMode = "Permissive";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
DeleteKmsAction.Result res = action.call();
Python SDK
action = DeleteKmsAction()
action.uuid = "ff0a9250e11b3fe5a553d61be176d300"
action.deleteMode = "Permissive"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

从KMS获取服务端证书(GetKmsServerCertFromKms)

API请求

URLs
PUT zstack/v1/key-providers/kms/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "getKmsServerCertFromKms": {},
  "systemTags": [],
  "userTags": []
}
Note: 上述示例中systemTags、userTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"getKmsServerCertFromKms":{}}' \
http://localhost:8080/zstack/v1/key-providers/kms/ff0a9250e11b3fe5a553d61be176d300/actions
参数列表
名字 类型 位置 描述 可选值 起始版本
uuid String url 资源的UUID，唯一标示该资源 5.0.0
systemTags (可选) List body 系统标签 5.0.0
userTags (可选) List body 用户标签 5.0.0

API返回

返回示例
{
  "serverCertPem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "selfSigned": true,
  "serverCertInfo": {
    "subject": "CN\u003dkms.example.com,O\u003dzstack",
    "issuer": "CN\u003dzstack-ca,O\u003dzstack",
    "commonName": "kms.example.com",
    "subjectAltNamesDns": [
      "kms.example.com"
    ],
    "subjectAltNamesIp": [
      "127.0.0.1"
    ],
    "expiredDate": "Nov 14, 2017 2:20:57 PM"
  }
}
名字 类型 描述 起始版本
serverCertPem String 服务端证书 5.0.0
selfSigned boolean 服务端证书是否为自签证书 5.0.0
serverCertInfo CertificateInfo 服务端证书解析信息 5.0.0
success boolean 5.0.0
error ErrorCode 详情参考error 5.0.0
#error
名字 类型 描述 起始版本
code String 错误码号，错误的全局唯一标识，例如SYS.1000, HOST.1001 0.6
description String 错误的概要描述 0.6
details String 错误的详细信息 0.6
elaboration String 保留字段，默认为null 0.6
opaque LinkedHashMap 保留字段，默认为null 0.6
cause ErrorCode 根错误，引发当前错误的源错误，若无原错误，该字段为null 0.6

SDK示例

Java SDK
GetKmsServerCertFromKmsAction action = new GetKmsServerCertFromKmsAction();
action.uuid = "ff0a9250e11b3fe5a553d61be176d300";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
GetKmsServerCertFromKmsAction.Result res = action.call();
Python SDK
action = GetKmsServerCertFromKmsAction()
action.uuid = "ff0a9250e11b3fe5a553d61be176d300"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

查询 KMS 密钥提供程序(QueryKms)

API请求

URLs
GET zstack/v1/key-providers/kms
GET zstack/v1/key-providers/kms/{uuid}
Headers
Authorization: OAuth the-session-uuid
Curl示例
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/key-providers/kms?q=uuid=ff0a9250e11b3fe5a553d61be176d300
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/key-providers/kms/828f3b926950324886a029baeccf85b1

可查询字段

运行CLI命令行工具，输入QueryKms并按Tab键查看所有可查询字段以及可跨表查询的资源名。

API返回

返回示例
{
  "inventories": [
    {
      "endpoint": "kms.example.com",
      "port": 5696,
      "kmipVersion": "1.2",
      "username": "user",
      "trustState": "MUTUAL_TRUSTED",
      "activeIdentityUuid": "ff0fe4c52fce34ff9ffca4d3a0fd4d00",
      "serverCertPem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
      "serverCertInfo": {
        "subject": "CN\u003dkms.example.com,O\u003dzstack",
        "issuer": "CN\u003dzstack-ca,O\u003dzstack",
        "commonName": "kms.example.com",
        "subjectAltNamesDns": [
          "kms.example.com"
        ],
        "subjectAltNamesIp": [
          "127.0.0.1"
        ],
        "expiredDate": "Nov 14, 2017 2:20:57 PM"
      },
      "activeIdentity": {
        "uuid": "ff0fe4c52fce34ff9ffca4d3a0fd4d00",
        "kmsUuid": "ff0a9250e11b3fe5a553d61be176d300",
        "identityType": "CSR",
        "clientCertPem": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----",
        "csrPem": "-----BEGIN CERTIFICATE REQUEST-----\\n...\\n-----END CERTIFICATE REQUEST-----",
        "certExpiredDate": "Nov 14, 2017 2:20:57 PM",
        "createDate": "Nov 14, 2017 2:20:57 PM",
        "lastOpDate": "Nov 14, 2017 2:20:57 PM"
      },
      "uuid": "ff0a9250e11b3fe5a553d61be176d300",
      "name": "kms-1",
      "description": "example",
      "type": "KMS",
      "connected": true,
      "createDate": "Nov 14, 2017 2:20:57 PM",
      "lastOpDate": "Nov 14, 2017 2:20:57 PM"
    }
  ]
}
名字 类型 描述 起始版本
success boolean 5.0.0
inventories List 详情参考inventories 5.0.0
error ErrorCode 详情参考error 5.0.0
#inventories
名字 类型 描述 起始版本
endpoint String KMS服务端地址 5.0.0
port Integer KMS服务端端口 5.0.0
kmipVersion String KMIP协议版本 5.0.0
username String 认证用户名 5.0.0
trustState String KMS双边信任状态，支持双边均不信任、仅MN信任KMS、仅KMS信任MN、双边信任 5.0.0
activeIdentityUuid String 当前生效的客户端身份UUID 5.0.0
serverCertPem String KMS服务端证书内容(PEM) 5.0.0
uuid String 资源的UUID，唯一标示该资源 5.0.0
name String 资源名称 5.0.0
description String 资源的详细描述 5.0.0
type String 密钥提供程序类型 5.0.0
connected boolean 是否已连接 5.0.0
createDate Timestamp 创建时间 5.0.0
lastOpDate Timestamp 最后一次修改时间 5.0.0
serverCertInfo CertificateInfo 详情参考serverCertInfo 5.0.0
activeIdentity KmsIdentityInventory 详情参考activeIdentity 5.0.0
#serverCertInfo
名字 类型 描述 起始版本
subject String 证书主体DN 5.0.0
issuer String 证书颁发者DN 5.0.0
commonName String 证书通用名(CN) 5.0.0
subjectAltNamesDns List Subject Alternative Name 中的 DNS 名称列表 5.0.0
subjectAltNamesIp List Subject Alternative Name 中的 IP 地址列表 5.0.0
expiredDate Timestamp 证书过期时间 5.0.0
#activeIdentity
名字 类型 描述 起始版本
uuid String 资源的UUID，唯一标示该资源 5.0.0
kmsUuid String KmsUUID 5.0.0
identityType String 身份类型 5.0.0
clientCertPem String KMS客户端证书 5.0.0
csrPem String CSR内容 5.0.0
certExpiredDate Timestamp 客户端证书到期时间 5.0.0
createDate Timestamp 创建时间 5.0.0
lastOpDate Timestamp 最后一次修改时间 5.0.0
#error
名字 类型 描述 起始版本
code String 错误码号，错误的全局唯一标识，例如SYS.1000, HOST.1001 0.6
description String 错误的概要描述 0.6
details String 错误的详细信息 0.6
elaboration String 保留字段，默认为null 0.6
opaque LinkedHashMap 保留字段，默认为null 0.6
cause ErrorCode 根错误，引发当前错误的源错误，若无原错误，该字段为null 0.6

SDK示例

Java SDK
QueryKmsAction action = new QueryKmsAction();
action.conditions = asList("uuid=ff0a9250e11b3fe5a553d61be176d300");
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
QueryKmsAction.Result res = action.call();
Python SDK
action = QueryKmsAction()
action.conditions = ["uuid=ff0a9250e11b3fe5a553d61be176d300"]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

更新KMS密钥提供程序(UpdateKms)

API请求

URLs
PUT zstack/v1/key-providers/kms/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "updateKms": {
    "endpoint": "kms.example.com",
    "port": 5696,
    "kmipVersion": "1.2",
    "username": "user",
    "password": "password",
    "description": "example"
  },
  "systemTags": [],
  "userTags": []
}
Note: 上述示例中systemTags、userTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"updateKms":{"endpoint":"kms.example.com","port":5696,"kmipVersion":"1.2","username":"user","password":"password","description":"example"}}' \
http://localhost:8080/zstack/v1/key-providers/kms/ff0a9250e11b3fe5a553d61be176d300/actions
参数列表
名字 类型 位置 描述 可选值 起始版本
endpoint (可选) String body(包含在updateKms结构中) 地址 5.0.0
port (可选) Integer body(包含在updateKms结构中) 端口 5.0.0
kmipVersion (可选) String body(包含在updateKms结构中) KMIP协议版本
  • 1.0
  • 1.1
  • 1.2
  • 1.3
  • 1.4
  • 2.0
  • 2.1
 5.0.0
username (可选) String body(包含在updateKms结构中) 用户名 5.0.0
password (可选) String body(包含在updateKms结构中) 密码 5.0.0
uuid String url 资源的UUID，唯一标示该资源 5.0.0
description (可选) String body(包含在updateKms结构中) 资源的详细描述 5.0.0
systemTags (可选) List body 系统标签 5.0.0
userTags (可选) List body 用户标签 5.0.0

API返回

返回示例
{
  "inventory": {
    "endpoint": "kms.example.com",
    "port": 5696,
    "kmipVersion": "1.2",
    "username": "user",
    "trustState": "MUTUAL_TRUSTED",
    "activeIdentityUuid": "ff0fe4c52fce34ff9ffca4d3a0fd4d00",
    "serverCertPem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "serverCertInfo": {
      "subject": "CN\u003dkms.example.com,O\u003dzstack",
      "issuer": "CN\u003dzstack-ca,O\u003dzstack",
      "commonName": "kms.example.com",
      "subjectAltNamesDns": [
        "kms.example.com"
      ],
      "subjectAltNamesIp": [
        "127.0.0.1"
      ],
      "expiredDate": "Nov 14, 2017 2:20:57 PM"
    },
    "activeIdentity": {
      "uuid": "ff0fe4c52fce34ff9ffca4d3a0fd4d00",
      "kmsUuid": "ff0a9250e11b3fe5a553d61be176d300",
      "identityType": "CSR",
      "clientCertPem": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----",
      "csrPem": "-----BEGIN CERTIFICATE REQUEST-----\\n...\\n-----END CERTIFICATE REQUEST-----",
      "certExpiredDate": "Nov 14, 2017 2:20:57 PM",
      "createDate": "Nov 14, 2017 2:20:57 PM",
      "lastOpDate": "Nov 14, 2017 2:20:57 PM"
    },
    "uuid": "ff0a9250e11b3fe5a553d61be176d300",
    "name": "kms-1",
    "description": "example",
    "type": "KMS",
    "connected": true,
    "createDate": "Nov 14, 2017 2:20:57 PM",
    "lastOpDate": "Nov 14, 2017 2:20:57 PM"
  }
}
名字 类型 描述 起始版本
success boolean 5.0.0
inventory KeyProviderInventory 详情参考inventory 5.0.0
error ErrorCode 详情参考error 5.0.0
#inventory
名字 类型 描述 起始版本
uuid String 资源的UUID，唯一标示该资源 5.0.0
name String 资源名称 5.0.0
description String 资源的详细描述 5.0.0
type String 密钥提供程序类型 5.0.0
connected boolean 是否已连接 5.0.0
createDate Timestamp 创建时间 5.0.0
lastOpDate Timestamp 最后一次修改时间 5.0.0
#error
名字 类型 描述 起始版本
code String 错误码号，错误的全局唯一标识，例如SYS.1000, HOST.1001 0.6
description String 错误的概要描述 0.6
details String 错误的详细信息 0.6
elaboration String 保留字段，默认为null 0.6
opaque LinkedHashMap 保留字段，默认为null 0.6
cause ErrorCode 根错误，引发当前错误的源错误，若无原错误，该字段为null 0.6

SDK示例

Java SDK
UpdateKmsAction action = new UpdateKmsAction();
action.endpoint = "kms.example.com";
action.port = 5696;
action.kmipVersion = "1.2";
action.username = "user";
action.password = "password";
action.uuid = "ff0a9250e11b3fe5a553d61be176d300";
action.description = "example";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
UpdateKmsAction.Result res = action.call();
Python SDK
action = UpdateKmsAction()
action.endpoint = "kms.example.com"
action.port = 5696
action.kmipVersion = "1.2"
action.username = "user"
action.password = "password"
action.uuid = "ff0a9250e11b3fe5a553d61be176d300"
action.description = "example"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

上传KMS客户端CSR与私钥(UploadKmsClientCsr)

API请求

URLs
PUT zstack/v1/key-providers/kms/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "uploadKmsClientCsr": {
    "csrPem": "-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----",
    "csrKeyPem": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
  },
  "systemTags": [],
  "userTags": []
}
Note: 上述示例中systemTags、userTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"uploadKmsClientCsr":{"csrPem":"-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----","csrKeyPem":"-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"}}' \
http://localhost:8080/zstack/v1/key-providers/kms/ff0a9250e11b3fe5a553d61be176d300/actions
参数列表
名字 类型 位置 描述 可选值 起始版本
csrPem String body(包含在uploadKmsClientCsr结构中) CSR 5.0.0
csrKeyPem String body(包含在uploadKmsClientCsr结构中) CSR私钥 5.0.0
uuid String url 资源的UUID，唯一标示该资源 5.0.0
systemTags (可选) List body 系统标签 5.0.0
userTags (可选) List body 用户标签 5.0.0

API返回

返回示例
{
  "inventory": {
    "uuid": "ff0fe4c52fce34ff9ffca4d3a0fd4d00",
    "kmsUuid": "ff0a9250e11b3fe5a553d61be176d300",
    "identityType": "CSR",
    "clientCertPem": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----",
    "csrPem": "-----BEGIN CERTIFICATE REQUEST-----\\n...\\n-----END CERTIFICATE REQUEST-----",
    "certExpiredDate": "Nov 14, 2017 2:20:57 PM",
    "createDate": "Nov 14, 2017 2:20:57 PM",
    "lastOpDate": "Nov 14, 2017 2:20:57 PM"
  }
}
名字 类型 描述 起始版本
success boolean 5.0.0
inventory KmsIdentityInventory 详情参考inventory 5.0.0
error ErrorCode 详情参考error 5.0.0
#inventory
名字 类型 描述 起始版本
uuid String 资源的UUID，唯一标示该资源 5.0.0
kmsUuid String KmsUUID 5.0.0
identityType String 身份类型 5.0.0
clientCertPem String KMS客户端证书 5.0.0
csrPem String CSR内容 5.0.0
certExpiredDate Timestamp 客户端证书到期时间 5.0.0
createDate Timestamp 创建时间 5.0.0
lastOpDate Timestamp 最后一次修改时间 5.0.0
#error
名字 类型 描述 起始版本
code String 错误码号，错误的全局唯一标识，例如SYS.1000, HOST.1001 0.6
description String 错误的概要描述 0.6
details String 错误的详细信息 0.6
elaboration String 保留字段，默认为null 0.6
opaque LinkedHashMap 保留字段，默认为null 0.6
cause ErrorCode 根错误，引发当前错误的源错误，若无原错误，该字段为null 0.6

SDK示例

Java SDK
UploadKmsClientCsrAction action = new UploadKmsClientCsrAction();
action.uuid = "ff0a9250e11b3fe5a553d61be176d300";
action.csrPem = "-----BEGIN CERTIFICATE REQUEST-----
...
-----END CERTIFICATE REQUEST-----";
action.csrKeyPem = "-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
UploadKmsClientCsrAction.Result res = action.call();
Python SDK
action = UploadKmsClientCsrAction()
action.uuid = "ff0a9250e11b3fe5a553d61be176d300"
action.csrPem = "-----BEGIN CERTIFICATE REQUEST-----
...
-----END CERTIFICATE REQUEST-----"
action.csrKeyPem = "-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

上传KMS客户端证书与私钥(UploadKmsClientIdentity)

API请求

URLs
PUT zstack/v1/key-providers/kms/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "uploadKmsClientIdentity": {
    "identityType": "UPLOADED",
    "kmsClientCertPem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "kmsClientKeyPem": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
  },
  "systemTags": [],
  "userTags": []
}
Note: 上述示例中systemTags、userTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"uploadKmsClientIdentity":{"identityType":"UPLOADED","kmsClientCertPem":"-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----","kmsClientKeyPem":"-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"}}' \
http://localhost:8080/zstack/v1/key-providers/kms/ff0a9250e11b3fe5a553d61be176d300/actions
参数列表
名字 类型 位置 描述 可选值 起始版本
identityType String body(包含在uploadKmsClientIdentity结构中) 身份来源类型
  • UPLOADED
  • PLATFORM
 5.0.0
kmsClientCertPem String body(包含在uploadKmsClientIdentity结构中) 客户端证书 5.0.0
kmsClientKeyPem String body(包含在uploadKmsClientIdentity结构中) 客户端私钥 5.0.0
uuid String url 资源的UUID，唯一标示该资源 5.0.0
systemTags (可选) List body 系统标签 5.0.0
userTags (可选) List body 用户标签 5.0.0

API返回

返回示例
{
  "inventory": {
    "uuid": "ff0fe4c52fce34ff9ffca4d3a0fd4d00",
    "kmsUuid": "ff0a9250e11b3fe5a553d61be176d300",
    "identityType": "CSR",
    "clientCertPem": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----",
    "csrPem": "-----BEGIN CERTIFICATE REQUEST-----\\n...\\n-----END CERTIFICATE REQUEST-----",
    "certExpiredDate": "Nov 14, 2017 2:20:57 PM",
    "createDate": "Nov 14, 2017 2:20:57 PM",
    "lastOpDate": "Nov 14, 2017 2:20:57 PM"
  }
}
名字 类型 描述 起始版本
success boolean 5.0.0
inventory KmsIdentityInventory 详情参考inventory 5.0.0
error ErrorCode 详情参考error 5.0.0
#inventory
名字 类型 描述 起始版本
uuid String 资源的UUID，唯一标示该资源 5.0.0
kmsUuid String KmsUUID 5.0.0
identityType String 身份类型 5.0.0
clientCertPem String KMS客户端证书 5.0.0
csrPem String CSR内容 5.0.0
certExpiredDate Timestamp 客户端证书到期时间 5.0.0
createDate Timestamp 创建时间 5.0.0
lastOpDate Timestamp 最后一次修改时间 5.0.0
#error
名字 类型 描述 起始版本
code String 错误码号，错误的全局唯一标识，例如SYS.1000, HOST.1001 0.6
description String 错误的概要描述 0.6
details String 错误的详细信息 0.6
elaboration String 保留字段，默认为null 0.6
opaque LinkedHashMap 保留字段，默认为null 0.6
cause ErrorCode 根错误，引发当前错误的源错误，若无原错误，该字段为null 0.6

SDK示例

Java SDK
UploadKmsClientIdentityAction action = new UploadKmsClientIdentityAction();
action.uuid = "ff0a9250e11b3fe5a553d61be176d300";
action.identityType = "UPLOADED";
action.kmsClientCertPem = "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----";
action.kmsClientKeyPem = "-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
UploadKmsClientIdentityAction.Result res = action.call();
Python SDK
action = UploadKmsClientIdentityAction()
action.uuid = "ff0a9250e11b3fe5a553d61be176d300"
action.identityType = "UPLOADED"
action.kmsClientCertPem = "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----"
action.kmsClientKeyPem = "-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

上传KMS客户端回签证书(UploadKmsClientSignedCert)

API请求

URLs
PUT zstack/v1/key-providers/kms/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "uploadKmsClientSignedCert": {
    "signedClientCertPem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
  },
  "systemTags": [],
  "userTags": []
}
Note: 上述示例中systemTags、userTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"uploadKmsClientSignedCert":{"signedClientCertPem":"-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"}}' \
http://localhost:8080/zstack/v1/key-providers/kms/ff0a9250e11b3fe5a553d61be176d300/actions
参数列表
名字 类型 位置 描述 可选值 起始版本
signedClientCertPem String body(包含在uploadKmsClientSignedCert结构中) 回签客户端证书 5.0.0
uuid String url 资源的UUID，唯一标示该资源 5.0.0
systemTags (可选) List body 系统标签 5.0.0
userTags (可选) List body 用户标签 5.0.0

API返回

返回示例
{
  "inventory": {
    "uuid": "ff0fe4c52fce34ff9ffca4d3a0fd4d00",
    "kmsUuid": "ff0a9250e11b3fe5a553d61be176d300",
    "identityType": "CSR",
    "clientCertPem": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----",
    "csrPem": "-----BEGIN CERTIFICATE REQUEST-----\\n...\\n-----END CERTIFICATE REQUEST-----",
    "certExpiredDate": "Nov 14, 2017 2:20:57 PM",
    "createDate": "Nov 14, 2017 2:20:57 PM",
    "lastOpDate": "Nov 14, 2017 2:20:57 PM"
  }
}
名字 类型 描述 起始版本
success boolean 5.0.0
inventory KmsIdentityInventory 详情参考inventory 5.0.0
error ErrorCode 详情参考error 5.0.0
#inventory
名字 类型 描述 起始版本
uuid String 资源的UUID，唯一标示该资源 5.0.0
kmsUuid String KmsUUID 5.0.0
identityType String 身份类型 5.0.0
clientCertPem String KMS客户端证书 5.0.0
csrPem String CSR内容 5.0.0
certExpiredDate Timestamp 客户端证书到期时间 5.0.0
createDate Timestamp 创建时间 5.0.0
lastOpDate Timestamp 最后一次修改时间 5.0.0
#error
名字 类型 描述 起始版本
code String 错误码号，错误的全局唯一标识，例如SYS.1000, HOST.1001 0.6
description String 错误的概要描述 0.6
details String 错误的详细信息 0.6
elaboration String 保留字段，默认为null 0.6
opaque LinkedHashMap 保留字段，默认为null 0.6
cause ErrorCode 根错误，引发当前错误的源错误，若无原错误，该字段为null 0.6

SDK示例

Java SDK
UploadKmsClientSignedCertAction action = new UploadKmsClientSignedCertAction();
action.uuid = "ff0a9250e11b3fe5a553d61be176d300";
action.signedClientCertPem = "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
UploadKmsClientSignedCertAction.Result res = action.call();
Python SDK
action = UploadKmsClientSignedCertAction()
action.uuid = "ff0a9250e11b3fe5a553d61be176d300"
action.signedClientCertPem = "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

上传KMS服务端证书(UploadKmsServerCert)

API请求

URLs
PUT zstack/v1/key-providers/kms/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "uploadKmsServerCert": {
    "serverCertPem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
  },
  "systemTags": [],
  "userTags": []
}
Note: 上述示例中systemTags、userTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"uploadKmsServerCert":{"serverCertPem":"-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"}}' \
http://localhost:8080/zstack/v1/key-providers/kms/ff0a9250e11b3fe5a553d61be176d300/actions
参数列表
名字 类型 位置 描述 可选值 起始版本
serverCertPem String body(包含在uploadKmsServerCert结构中) 服务端证书 5.0.0
uuid String url 资源的UUID，唯一标示该资源 5.0.0
systemTags (可选) List body 系统标签 5.0.0
userTags (可选) List body 用户标签 5.0.0

API返回

返回示例
{
  "inventory": {
    "endpoint": "kms.example.com",
    "port": 5696,
    "kmipVersion": "1.2",
    "username": "user",
    "trustState": "MUTUAL_TRUSTED",
    "activeIdentityUuid": "ff0fe4c52fce34ff9ffca4d3a0fd4d00",
    "serverCertPem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "serverCertInfo": {
      "subject": "CN\u003dkms.example.com,O\u003dzstack",
      "issuer": "CN\u003dzstack-ca,O\u003dzstack",
      "commonName": "kms.example.com",
      "subjectAltNamesDns": [
        "kms.example.com"
      ],
      "subjectAltNamesIp": [
        "127.0.0.1"
      ],
      "expiredDate": "Nov 14, 2017 2:20:57 PM"
    },
    "activeIdentity": {
      "uuid": "ff0fe4c52fce34ff9ffca4d3a0fd4d00",
      "kmsUuid": "ff0a9250e11b3fe5a553d61be176d300",
      "identityType": "CSR",
      "clientCertPem": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----",
      "csrPem": "-----BEGIN CERTIFICATE REQUEST-----\\n...\\n-----END CERTIFICATE REQUEST-----",
      "certExpiredDate": "Nov 14, 2017 2:20:57 PM",
      "createDate": "Nov 14, 2017 2:20:57 PM",
      "lastOpDate": "Nov 14, 2017 2:20:57 PM"
    },
    "uuid": "ff0a9250e11b3fe5a553d61be176d300",
    "name": "kms-1",
    "description": "example",
    "type": "KMS",
    "connected": true,
    "createDate": "Nov 14, 2017 2:20:57 PM",
    "lastOpDate": "Nov 14, 2017 2:20:57 PM"
  }
}
名字 类型 描述 起始版本
success boolean 5.0.0
inventory KmsInventory 详情参考inventory 5.0.0
error ErrorCode 详情参考error 5.0.0
#inventory
名字 类型 描述 起始版本
endpoint String KMS服务端地址 5.0.0
port Integer KMS服务端端口 5.0.0
kmipVersion String KMIP协议版本 5.0.0
username String 认证用户名 5.0.0
trustState String KMS双边信任状态，支持双边均不信任、仅MN信任KMS、仅KMS信任MN、双边信任 5.0.0
activeIdentityUuid String 当前生效的客户端身份UUID 5.0.0
serverCertPem String KMS服务端证书内容(PEM) 5.0.0
uuid String 资源的UUID，唯一标示该资源 5.0.0
name String 资源名称 5.0.0
description String 资源的详细描述 5.0.0
type String 密钥提供程序类型 5.0.0
connected boolean 是否已连接 5.0.0
createDate Timestamp 创建时间 5.0.0
lastOpDate Timestamp 最后一次修改时间 5.0.0
serverCertInfo CertificateInfo 详情参考serverCertInfo 5.0.0
activeIdentity KmsIdentityInventory 详情参考activeIdentity 5.0.0
#serverCertInfo
名字 类型 描述 起始版本
subject String 证书主体DN 5.0.0
issuer String 证书颁发者DN 5.0.0
commonName String 证书通用名(CN) 5.0.0
subjectAltNamesDns List Subject Alternative Name 中的 DNS 名称列表 5.0.0
subjectAltNamesIp List Subject Alternative Name 中的 IP 地址列表 5.0.0
expiredDate Timestamp 证书过期时间 5.0.0
#activeIdentity
名字 类型 描述 起始版本
uuid String 资源的UUID，唯一标示该资源 5.0.0
kmsUuid String KmsUUID 5.0.0
identityType String 身份类型 5.0.0
clientCertPem String KMS客户端证书 5.0.0
csrPem String CSR内容 5.0.0
certExpiredDate Timestamp 客户端证书到期时间 5.0.0
createDate Timestamp 创建时间 5.0.0
lastOpDate Timestamp 最后一次修改时间 5.0.0
#error
名字 类型 描述 起始版本
code String 错误码号，错误的全局唯一标识，例如SYS.1000, HOST.1001 0.6
description String 错误的概要描述 0.6
details String 错误的详细信息 0.6
elaboration String 保留字段，默认为null 0.6
opaque LinkedHashMap 保留字段，默认为null 0.6
cause ErrorCode 根错误，引发当前错误的源错误，若无原错误，该字段为null 0.6

SDK示例

Java SDK
UploadKmsServerCertAction action = new UploadKmsServerCertAction();
action.uuid = "ff0a9250e11b3fe5a553d61be176d300";
action.serverCertPem = "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
UploadKmsServerCertAction.Result res = action.call();
Python SDK
action = UploadKmsServerCertAction()
action.uuid = "ff0a9250e11b3fe5a553d61be176d300"
action.serverCertPem = "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

备份原生密钥提供程序(BackupNkp)

API请求

URLs
PUT zstack/v1/key-providers/nkp/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "backupNkp": {
    "password": "password"
  },
  "systemTags": [],
  "userTags": []
}
Note: 上述示例中systemTags、userTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"backupNkp":{"password":"password"}}' \
http://localhost:8080/zstack/v1/key-providers/nkp/ff0415ff372f33b5b6b757d3b99ad900/actions
参数列表
名字 类型 位置 描述 可选值 起始版本
uuid String url 资源的UUID，唯一标示该资源 5.0.0
password (可选) String body(包含在backupNkp结构中) 备份保护密码 5.0.0
systemTags (可选) List body 系统标签 5.0.0
userTags (可选) List body 用户标签 5.0.0

API返回

返回示例
{
  "content": "BASE64_ENCODED_NKP_BACKUP"
}
名字 类型 描述 起始版本
success boolean 5.0.0
content String 备份内容（Base64编码） 5.0.0
error ErrorCode 详情参考error 5.0.0
#error
名字 类型 描述 起始版本
code String 错误码号，错误的全局唯一标识，例如SYS.1000, HOST.1001 0.6
description String 错误的概要描述 0.6
details String 错误的详细信息 0.6
elaboration String 保留字段，默认为null 0.6
opaque LinkedHashMap 保留字段，默认为null 0.6
cause ErrorCode 根错误，引发当前错误的源错误，若无原错误，该字段为null 0.6

SDK示例

Java SDK
BackupNkpAction action = new BackupNkpAction();
action.uuid = "ff0415ff372f33b5b6b757d3b99ad900";
action.password = "password";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
BackupNkpAction.Result res = action.call();
Python SDK
action = BackupNkpAction()
action.uuid = "ff0415ff372f33b5b6b757d3b99ad900"
action.password = "password"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

创建原生密钥提供程序(CreateNkp)

API请求

URLs
POST zstack/v1/key-providers/nkp
Headers
Authorization: OAuth the-session-uuid
Body
{
  "params": {
    "kdf": "HKDF-SHA256",
    "saltPolicy": "providerName",
    "name": "kp-nkp",
    "description": "example"
  },
  "systemTags": [],
  "userTags": []
}
Note: 上述示例中systemTags、userTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X POST -d '{"params":{"kdf":"HKDF-SHA256","saltPolicy":"providerName","name":"kp-nkp","description":"example"}}' \
http://localhost:8080/zstack/v1/key-providers/nkp
参数列表
名字 类型 位置 描述 可选值 起始版本
kdf (可选) String body(包含在params结构中) 密钥派生函数
  • HKDF-SHA256
 5.0.0
saltPolicy (可选) String body(包含在params结构中) 加盐策略
  • providerName
 5.0.0
name String body(包含在params结构中) 资源名称 5.0.0
description (可选) String body(包含在params结构中) 资源的详细描述 5.0.0
type (可选) String body(包含在params结构中) 密钥提供程序类型 5.0.0
resourceUuid (可选) String body(包含在params结构中) 资源UUID 5.0.0
tagUuids (可选) List body(包含在params结构中) 标签UUID列表 5.0.0
systemTags (可选) List body 系统标签 5.0.0
userTags (可选) List body 用户标签 5.0.0

API返回

返回示例
{
  "inventory": {
    "kdf": "HKDF-SHA256",
    "saltPolicy": "providerName",
    "backedUp": true,
    "currentVersion": 1,
    "uuid": "ff0415ff372f33b5b6b757d3b99ad900",
    "name": "nkp-1",
    "description": "example",
    "type": "NKP",
    "connected": true,
    "createDate": "Nov 14, 2017 2:20:57 PM",
    "lastOpDate": "Nov 14, 2017 2:20:57 PM"
  }
}
名字 类型 描述 起始版本
success boolean 5.0.0
inventory KeyProviderInventory 详情参考inventory 5.0.0
error ErrorCode 详情参考error 5.0.0
#inventory
名字 类型 描述 起始版本
uuid String 资源的UUID，唯一标示该资源 5.0.0
name String 资源名称 5.0.0
description String 资源的详细描述 5.0.0
type String 密钥提供程序类型 5.0.0
connected boolean 是否已连接 5.0.0
createDate Timestamp 创建时间 5.0.0
lastOpDate Timestamp 最后一次修改时间 5.0.0
#error
名字 类型 描述 起始版本
code String 错误码号，错误的全局唯一标识，例如SYS.1000, HOST.1001 0.6
description String 错误的概要描述 0.6
details String 错误的详细信息 0.6
elaboration String 保留字段，默认为null 0.6
opaque LinkedHashMap 保留字段，默认为null 0.6
cause ErrorCode 根错误，引发当前错误的源错误，若无原错误，该字段为null 0.6

SDK示例

Java SDK
CreateNkpAction action = new CreateNkpAction();
action.kdf = "HKDF-SHA256";
action.saltPolicy = "providerName";
action.name = "kp-nkp";
action.description = "example";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
CreateNkpAction.Result res = action.call();
Python SDK
action = CreateNkpAction()
action.kdf = "HKDF-SHA256"
action.saltPolicy = "providerName"
action.name = "kp-nkp"
action.description = "example"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

删除原生密钥提供程序(DeleteNkp)

API请求

URLs
DELETE zstack/v1/key-providers/nkp/{uuid}
Headers
Authorization: OAuth the-session-uuid
Curl示例
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X DELETE http://localhost:8080/zstack/v1/key-providers/nkp/ff0415ff372f33b5b6b757d3b99ad900?deleteMode=Permissive
参数列表
名字 类型 位置 描述 可选值 起始版本
uuid String url 资源的UUID，唯一标示该资源 5.0.0
deleteMode (可选) String query 删除模式(Permissive / Enforcing，Permissive) 5.0.0
systemTags (可选) List query 系统标签 5.0.0
userTags (可选) List query 用户标签 5.0.0

API返回

该API成功时返回一个空的JSON结构{}，出错时返回的JSON结构包含一个error字段，例如：
{
	"error": {
		"code": "SYS.1001",
		"description": "A message or a operation timeout",
		"details": "Create VM on KVM timeout after 300s"
	}
}

SDK示例

Java SDK
DeleteNkpAction action = new DeleteNkpAction();
action.uuid = "ff0415ff372f33b5b6b757d3b99ad900";
action.deleteMode = "Permissive";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
DeleteNkpAction.Result res = action.call();
Python SDK
action = DeleteNkpAction()
action.uuid = "ff0415ff372f33b5b6b757d3b99ad900"
action.deleteMode = "Permissive"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

解析原生密钥提供程序导入内容(ParseNkpRestore)

API请求

URLs
PUT zstack/v1/key-providers/nkp/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "parseNkpRestore": {
    "contentBase64": "BASE64_ENCODED_NKP_BACKUP",
    "password": "password"
  },
  "systemTags": [],
  "userTags": []
}
Note: 上述示例中systemTags、userTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"parseNkpRestore":{"contentBase64":"BASE64_ENCODED_NKP_BACKUP","password":"password"}}' \
http://localhost:8080/zstack/v1/key-providers/nkp/actions
参数列表
名字 类型 位置 描述 可选值 起始版本
contentBase64 String body(包含在parseNkpRestore结构中) 导入内容（Base64 编码） 5.0.0
password (可选) String body(包含在parseNkpRestore结构中) 导入保护密码 5.0.0
systemTags (可选) List body 系统标签 5.0.0
userTags (可选) List body 用户标签 5.0.0

API返回

返回示例
{
  "restoreInfo": {
    "uuid": "ff0415ff372f33b5b6b757d3b99ad900",
    "name": "nkp-1",
    "description": "example",
    "kdf": "HKDF-SHA256",
    "saltPolicy": "providerName",
    "currentVersion": 1,
    "backupTime": 1700000000000
  },
  "code": "KP.1000"
}
名字 类型 描述 起始版本
code String 解析结果码 5.0.0
reason String 解析失败原因 5.0.0
success boolean 5.0.0
restoreInfo NkpRestoreInfo 详情参考restoreInfo 5.0.0
error ErrorCode 详情参考error 5.0.0
#restoreInfo
名字 类型 描述 起始版本
uuid String 资源的UUID，唯一标示该资源 5.0.0
name String 资源名称 5.0.0
description String 资源的详细描述 5.0.0
kdf String 密钥派生函数 5.0.0
saltPolicy String 加盐策略 5.0.0
currentVersion Integer 当前版本 5.0.0
backupTime Long 备份时间（毫秒时间戳） 5.0.0
#error
名字 类型 描述 起始版本
code String 错误码号，错误的全局唯一标识，例如SYS.1000, HOST.1001 0.6
description String 错误的概要描述 0.6
details String 错误的详细信息 0.6
elaboration String 保留字段，默认为null 0.6
opaque LinkedHashMap 保留字段，默认为null 0.6
cause ErrorCode 根错误，引发当前错误的源错误，若无原错误，该字段为null 0.6

SDK示例

Java SDK
ParseNkpRestoreAction action = new ParseNkpRestoreAction();
action.contentBase64 = "BASE64_ENCODED_NKP_BACKUP";
action.password = "password";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
ParseNkpRestoreAction.Result res = action.call();
Python SDK
action = ParseNkpRestoreAction()
action.contentBase64 = "BASE64_ENCODED_NKP_BACKUP"
action.password = "password"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

查询原生密钥提供程序(QueryNkp)

API请求

URLs
GET zstack/v1/key-providers/nkp
GET zstack/v1/key-providers/nkp/{uuid}
Headers
Authorization: OAuth the-session-uuid
Curl示例
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/key-providers/nkp?q=uuid=ff0415ff372f33b5b6b757d3b99ad900
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/key-providers/nkp/12fcf606191b3b249ef4c419585ca769

可查询字段

运行CLI命令行工具，输入QueryNkp并按Tab键查看所有可查询字段以及可跨表查询的资源名。

API返回

返回示例
{
  "inventories": [
    {
      "kdf": "HKDF-SHA256",
      "saltPolicy": "providerName",
      "backedUp": true,
      "currentVersion": 1,
      "uuid": "ff0415ff372f33b5b6b757d3b99ad900",
      "name": "nkp-1",
      "description": "example",
      "type": "NKP",
      "connected": true,
      "createDate": "Nov 14, 2017 2:20:57 PM",
      "lastOpDate": "Nov 14, 2017 2:20:57 PM"
    }
  ]
}
名字 类型 描述 起始版本
success boolean 5.0.0
inventories List 详情参考inventories 5.0.0
error ErrorCode 详情参考error 5.0.0
#inventories
名字 类型 描述 起始版本
kdf String 密钥派生函数 5.0.0
saltPolicy String 盐值策略 5.0.0
backedUp boolean 是否已完成备份 5.0.0
currentVersion Integer 当前密钥版本号 5.0.0
uuid String 资源的UUID，唯一标示该资源 5.0.0
name String 资源名称 5.0.0
description String 资源的详细描述 5.0.0
type String 密钥提供程序类型 5.0.0
connected boolean 是否已连接 5.0.0
createDate Timestamp 创建时间 5.0.0
lastOpDate Timestamp 最后一次修改时间 5.0.0
#error
名字 类型 描述 起始版本
code String 错误码号，错误的全局唯一标识，例如SYS.1000, HOST.1001 0.6
description String 错误的概要描述 0.6
details String 错误的详细信息 0.6
elaboration String 保留字段，默认为null 0.6
opaque LinkedHashMap 保留字段，默认为null 0.6
cause ErrorCode 根错误，引发当前错误的源错误，若无原错误，该字段为null 0.6

SDK示例

Java SDK
QueryNkpAction action = new QueryNkpAction();
action.conditions = asList("uuid=ff0415ff372f33b5b6b757d3b99ad900");
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
QueryNkpAction.Result res = action.call();
Python SDK
action = QueryNkpAction()
action.conditions = ["uuid=ff0415ff372f33b5b6b757d3b99ad900"]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

导入原生密钥提供程序(RestoreNkp)

API请求

URLs
PUT zstack/v1/key-providers/nkp/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "restoreNkp": {
    "contentBase64": "BASE64_ENCODED_NKP_BACKUP",
    "password": "password"
  },
  "systemTags": [],
  "userTags": []
}
Note: 上述示例中systemTags、userTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"restoreNkp":{"contentBase64":"BASE64_ENCODED_NKP_BACKUP","password":"password"}}' \
http://localhost:8080/zstack/v1/key-providers/nkp/actions
参数列表
名字 类型 位置 描述 可选值 起始版本
contentBase64 String body(包含在restoreNkp结构中) 备份内容（Base64 编码） 5.0.0
password (可选) String body(包含在restoreNkp结构中) 备份保护密码 5.0.0
systemTags (可选) List body 系统标签 5.0.0
userTags (可选) List body 用户标签 5.0.0

API返回

返回示例
{
  "inventory": {
    "kdf": "HKDF-SHA256",
    "saltPolicy": "providerName",
    "backedUp": true,
    "currentVersion": 1,
    "uuid": "ff0415ff372f33b5b6b757d3b99ad900",
    "name": "nkp-1",
    "description": "example",
    "type": "NKP",
    "connected": true,
    "createDate": "Nov 14, 2017 2:20:57 PM",
    "lastOpDate": "Nov 14, 2017 2:20:57 PM"
  }
}
名字 类型 描述 起始版本
success boolean 5.0.0
inventory NkpInventory 详情参考inventory 5.0.0
error ErrorCode 详情参考error 5.0.0
#inventory
名字 类型 描述 起始版本
kdf String 密钥派生函数 5.0.0
saltPolicy String 盐值策略 5.0.0
backedUp boolean 是否已完成备份 5.0.0
currentVersion Integer 当前密钥版本号 5.0.0
uuid String 资源的UUID，唯一标示该资源 5.0.0
name String 资源名称 5.0.0
description String 资源的详细描述 5.0.0
type String 密钥提供程序类型 5.0.0
connected boolean 是否已连接 5.0.0
createDate Timestamp 创建时间 5.0.0
lastOpDate Timestamp 最后一次修改时间 5.0.0
#error
名字 类型 描述 起始版本
code String 错误码号，错误的全局唯一标识，例如SYS.1000, HOST.1001 0.6
description String 错误的概要描述 0.6
details String 错误的详细信息 0.6
elaboration String 保留字段，默认为null 0.6
opaque LinkedHashMap 保留字段，默认为null 0.6
cause ErrorCode 根错误，引发当前错误的源错误，若无原错误，该字段为null 0.6

SDK示例

Java SDK
RestoreNkpAction action = new RestoreNkpAction();
action.contentBase64 = "BASE64_ENCODED_NKP_BACKUP";
action.password = "password";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
RestoreNkpAction.Result res = action.call();
Python SDK
action = RestoreNkpAction()
action.contentBase64 = "BASE64_ENCODED_NKP_BACKUP"
action.password = "password"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

更新原生密钥提供程序(UpdateNkp)

API请求

URLs
PUT zstack/v1/key-providers/nkp/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "updateNkp": {
    "description": "example"
  },
  "systemTags": [],
  "userTags": []
}
Note: 上述示例中systemTags、userTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"updateNkp":{"description":"example"}}' \
http://localhost:8080/zstack/v1/key-providers/nkp/ff0415ff372f33b5b6b757d3b99ad900/actions
参数列表
名字 类型 位置 描述 可选值 起始版本
uuid String url 资源的UUID，唯一标示该资源 5.0.0
description (可选) String body(包含在updateNkp结构中) 资源的详细描述 5.0.0
systemTags (可选) List body 系统标签 5.0.0
userTags (可选) List body 用户标签 5.0.0

API返回

返回示例
{
  "inventory": {
    "kdf": "HKDF-SHA256",
    "saltPolicy": "providerName",
    "backedUp": true,
    "currentVersion": 1,
    "uuid": "ff0415ff372f33b5b6b757d3b99ad900",
    "name": "nkp-1",
    "description": "example",
    "type": "NKP",
    "connected": true,
    "createDate": "Nov 14, 2017 2:20:57 PM",
    "lastOpDate": "Nov 14, 2017 2:20:57 PM"
  }
}
名字 类型 描述 起始版本
success boolean 5.0.0
inventory KeyProviderInventory 详情参考inventory 5.0.0
error ErrorCode 详情参考error 5.0.0
#inventory
名字 类型 描述 起始版本
uuid String 资源的UUID，唯一标示该资源 5.0.0
name String 资源名称 5.0.0
description String 资源的详细描述 5.0.0
type String 密钥提供程序类型 5.0.0
connected boolean 是否已连接 5.0.0
createDate Timestamp 创建时间 5.0.0
lastOpDate Timestamp 最后一次修改时间 5.0.0
#error
名字 类型 描述 起始版本
code String 错误码号，错误的全局唯一标识，例如SYS.1000, HOST.1001 0.6
description String 错误的概要描述 0.6
details String 错误的详细信息 0.6
elaboration String 保留字段，默认为null 0.6
opaque LinkedHashMap 保留字段，默认为null 0.6
cause ErrorCode 根错误，引发当前错误的源错误，若无原错误，该字段为null 0.6

SDK示例

Java SDK
UpdateNkpAction action = new UpdateNkpAction();
action.uuid = "ff0415ff372f33b5b6b757d3b99ad900";
action.description = "example";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
UpdateNkpAction.Result res = action.call();
Python SDK
action = UpdateNkpAction()
action.uuid = "ff0415ff372f33b5b6b757d3b99ad900"
action.description = "example"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()
上一篇从元数据注册虚拟机(RegisterVmInstanceFromMetadata)下一篇vTPM相关接口
开发手册 | ZStack ZSphere · ZVF | ZStack 资源中心