DocsKnowledge BaseAPI Explorer
Documentation›Explore more›ZStack ZSphere›API ReferenceZVF
Document navigation

Key Provider APIs

QueryKeyProvider

API Request

URLs
GET zstack/v1/key-providers
GET zstack/v1/key-providers/{uuid}
Headers
Authorization: OAuth the-session-uuid
Curl Example
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

Queryable Fields

Run the CLI command line tool, enter QueryKeyProvider, and press Tab to view all queryable fields and resource names that can be used for cross-table queries.

API Response

Response Example
{
  "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"
    }
  ]
}
Name Type Description Since
success boolean Whether the operation succeeded. 5.0.0
inventories List For details, see inventories 5.0.0
error ErrorCode For details, see error 5.0.0
#inventories
Name Type Description Since
uuid String Resource UUID, which uniquely identifies the resource 5.0.0
name String Resource name 5.0.0
description String Resource description 5.0.0
type String Key provider type 5.0.0
connected boolean Whether the key provider is connected 5.0.0
createDate Timestamp Creation time 5.0.0
lastOpDate Timestamp Last modification time 5.0.0
#error
Name Type Description Since
code String Error code, which globally and uniquely identifies an error, such as SYS.1000 or HOST.1001 0.6
description String Summary of the error 0.6
details String Details of the error 0.6
elaboration String Reserved field. The default value is null 0.6
opaque LinkedHashMap Reserved field. The default value is null 0.6
cause ErrorCode Root error that caused the current error. The value is null if no root error exists 0.6

SDK Example

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 Request

URLs
PUT zstack/v1/key-providers/{providerUuid}/rekey
Headers
Authorization: OAuth the-session-uuid
Body
{
  "rekeyKeyProviderRefs": {
    "refIds": [
      1,
      2
    ],
    "rekeyAll": false
  },
  "systemTags": [],
  "userTags": []
}
Note: In the preceding example, the systemTags and userTags fields can be omitted. They are listed to indicate that the body can include these two fields.
Curl Example
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
Parameter List
Name Type Location Description Optional Value Since
refIds (optional) List body (contained in rekeyKeyProviderRefs structure) List of key reference IDs to re-encrypt 5.0.0
resourceUuids (optional) List body (contained in rekeyKeyProviderRefs structure) List of associated resource UUIDs. Use this with resourceType. 5.0.0
resourceType (optional) String body (contained in rekeyKeyProviderRefs structure) Associated resource type. Use this with resourceUuids. 5.0.0
providerUuid String url Key provider UUID 5.0.0
rekeyAll (optional) boolean body (contained in rekeyKeyProviderRefs structure) Whether to perform full re-encryption. If set to true, you cannot specify refIds or resourceType/resourceUuids. 5.0.0
systemTags (optional) List body System tags 5.0.0
userTags (optional) List body User tags 5.0.0

API Response

Response Example
{
  "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"
        }
      ]
    }
  ]
}
Name Type Description Since
success boolean Whether the operation succeeded. 5.0.0
totalCount int Number of source key providers involved in this operation (deduplicated by provider associated with resource refs) 5.0.0
successCount int Number of providers with no failed refs (including providers that only have skipped refs) 5.0.0
skippedCount int Number of providers that have skipped refs 5.0.0
failedCount int Number of providers that have failed refs 5.0.0
providerResults List Results aggregated by source key provider. Each element contains skippedResources, failedResources, and ref counts of each type for the provider. 5.0.0
error ErrorCode For details, see error 5.0.0
#error
Name Type Description Since
code String Error code, which is the globally unique identifier of the error, for example, SYS.1000 or HOST.1001 0.6
description String Summary description of the error 0.6
details String Detailed information about the error 0.6
elaboration String Reserved field. The default value is null. 0.6
opaque LinkedHashMap Reserved field. The default value is null. 0.6
cause ErrorCode Root error that caused the current error. If no root error exists, this field is null. 0.6

SDK Example

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()

CreateKms

API Request

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: In the preceding example, the systemTags and userTags fields can be omitted. They are listed to indicate that the body can include these two fields.
Curl Example
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
Parameter List
Name Type Location Description Optional Value Since
endpoint String body (contained in params structure) KMSEndpoint 5.0.0
port Integer body (contained in params structure) Port 5.0.0
kmipVersion (optional) String body (contained in params structure) KMIP protocol version
  • 1.0
  • 1.1
  • 1.2
  • 1.3
  • 1.4
  • 2.0
  • 2.1
 5.0.0
username (optional) String body (contained in params structure) Username 5.0.0
password (optional) String body (contained in params structure) Password 5.0.0
name String body (contained in params structure) Resource name 5.0.0
description (optional) String body (contained in params structure) Detailed description of the resource 5.0.0
type (optional) String body (contained in params structure) Key provider type 5.0.0
resourceUuid (optional) String body (contained in params structure) Resource UUID 5.0.0
tagUuids (optional) List body (contained in params structure) Tag UUID list 5.0.0
systemTags (optional) List body System tags 5.0.0
userTags (optional) List body User tags 5.0.0

API Response

Response Example
{
  "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"
  }
}
Name Type Description Since
success boolean Whether the operation succeeded. 5.0.0
inventory KeyProviderInventory For details, see inventory 5.0.0
error ErrorCode For details, see error 5.0.0
#inventory
Name Type Description Since
uuid String Resource UUID, which uniquely identifies the resource 5.0.0
name String Resource name 5.0.0
description String Resource description 5.0.0
type String Key provider type 5.0.0
connected boolean Whether the key provider is connected 5.0.0
createDate Timestamp Creation time 5.0.0
lastOpDate Timestamp Last modification time 5.0.0
#error
Name Type Description Since
code String Error code, which globally and uniquely identifies an error, such as SYS.1000 or HOST.1001 0.6
description String Summary of the error 0.6
details String Details of the error 0.6
elaboration String Reserved field. The default value is null 0.6
opaque LinkedHashMap Reserved field. The default value is null 0.6
cause ErrorCode Root error that caused the current error. The value is null if no root error exists 0.6

SDK Example

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()

DeleteKms

API Request

URLs
DELETE zstack/v1/key-providers/kms/{uuid}
Headers
Authorization: OAuth the-session-uuid
Curl Example
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
Parameter List
Name Type Location Description Optional Value Since
uuid String url Resource UUID, which uniquely identifies the resource 5.0.0
deleteMode (optional) String query Deletion mode (Permissive / Enforcing, Permissive) 5.0.0
systemTags (optional) List query System tags 5.0.0
userTags (optional) List query User tags 5.0.0

API Response

When this API succeeds, it returns an empty JSON structure {}. When an error occurs, the returned JSON structure contains an error field. For example:
{
	"error": {
		"code": "SYS.1001",
		"description": "A message or a operation timeout",
		"details": "Create VM on KVM timeout after 300s"
	}
}

SDK Example

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()

GetKmsServerCertFromKms

API Request

URLs
PUT zstack/v1/key-providers/kms/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "getKmsServerCertFromKms": {},
  "systemTags": [],
  "userTags": []
}
Note: In the preceding example, the systemTags and userTags fields can be omitted. They are listed to indicate that the body can include these two fields.
Curl Example
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
Parameter List
Name Type Location Description Optional Value Since
uuid String url Resource UUID, which uniquely identifies the resource 5.0.0
systemTags (optional) List body System tags 5.0.0
userTags (optional) List body User tags 5.0.0

API Response

Response Example
{
  "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"
  }
}
Name Type Description Since
serverCertPem String Server certificate 5.0.0
selfSigned boolean Whether the server certificate is self-signed 5.0.0
serverCertInfo CertificateInfo Parsed server certificate information 5.0.0
success boolean Whether the operation succeeded. 5.0.0
error ErrorCode For details, see error 5.0.0
#error
Name Type Description Since
code String Error code, which is the globally unique identifier of the error, for example, SYS.1000 or HOST.1001 0.6
description String Summary description of the error 0.6
details String Detailed information about the error 0.6
elaboration String Reserved field. The default value is null. 0.6
opaque LinkedHashMap Reserved field. The default value is null. 0.6
cause ErrorCode Root error that caused the current error. If no root error exists, this field is null. 0.6

SDK Example

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()

QueryKms

API Request

URLs
GET zstack/v1/key-providers/kms
GET zstack/v1/key-providers/kms/{uuid}
Headers
Authorization: OAuth the-session-uuid
Curl Example
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

Queryable Fields

Run the CLI command line tool, enter QueryKms, and press Tab to view all queryable fields and resource names that can be used for cross-table queries.

API Response

Response Example
{
  "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"
    }
  ]
}
Name Type Description Since
success boolean Whether the operation succeeded. 5.0.0
inventories List For details, see inventories 5.0.0
error ErrorCode For details, see error 5.0.0
#inventories
Name Type Description Since
endpoint String KMS server address 5.0.0
port Integer KMS server port 5.0.0
kmipVersion String KMIP protocol version 5.0.0
username String Authentication username 5.0.0
trustState String KMS mutual trust state. Supported states: neither side trusts the other, only the MN trusts the KMS, only the KMS trusts the MN, and mutual trust 5.0.0
activeIdentityUuid String UUID of the active client identity 5.0.0
serverCertPem String KMS server certificate content (PEM) 5.0.0
uuid String Resource UUID, which uniquely identifies the resource 5.0.0
name String Resource name 5.0.0
description String Resource description 5.0.0
type String Key provider type 5.0.0
connected boolean Whether the key provider is connected 5.0.0
createDate Timestamp Creation time 5.0.0
lastOpDate Timestamp Last modification time 5.0.0
serverCertInfo CertificateInfo For details, see serverCertInfo 5.0.0
activeIdentity KmsIdentityInventory For details, see activeIdentity 5.0.0
#serverCertInfo
Name Type Description Since
subject String Certificate subject DN 5.0.0
issuer String Certificate issuer DN 5.0.0
commonName String Certificate common name (CN) 5.0.0
subjectAltNamesDns List List of DNS names in Subject Alternative Name 5.0.0
subjectAltNamesIp List List of IP addresses in Subject Alternative Name 5.0.0
expiredDate Timestamp Certificate expiration time 5.0.0
#activeIdentity
Name Type Description Since
uuid String Resource UUID, which uniquely identifies the resource 5.0.0
kmsUuid String KMS UUID 5.0.0
identityType String Identity type 5.0.0
clientCertPem String KMS client certificate 5.0.0
csrPem String CSR content 5.0.0
certExpiredDate Timestamp Client certificate expiration time 5.0.0
createDate Timestamp Creation time 5.0.0
lastOpDate Timestamp Last modification time 5.0.0
#error
Name Type Description Since
code String Error code, which globally and uniquely identifies an error, such as SYS.1000 or HOST.1001 0.6
description String Summary of the error 0.6
details String Details of the error 0.6
elaboration String Reserved field. The default value is null 0.6
opaque LinkedHashMap Reserved field. The default value is null 0.6
cause ErrorCode Root error that caused the current error. The value is null if no root error exists 0.6

SDK Example

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()

UpdateKms

API Request

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: In the preceding example, the systemTags and userTags fields can be omitted. They are listed to indicate that the body can include these two fields.
Curl Example
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
Parameter List
Name Type Location Description Optional Value Since
endpoint (optional) String body (contained in updateKms structure) Endpoint 5.0.0
port (optional) Integer body (contained in updateKms structure) Port 5.0.0
kmipVersion (optional) String body (contained in updateKms structure) KMIP protocol version
  • 1.0
  • 1.1
  • 1.2
  • 1.3
  • 1.4
  • 2.0
  • 2.1
 5.0.0
username (optional) String body (contained in updateKms structure) Username 5.0.0
password (optional) String body (contained in updateKms structure) Password 5.0.0
uuid String url Resource UUID, which uniquely identifies the resource 5.0.0
description (optional) String body (contained in updateKms structure) Detailed description of the resource 5.0.0
systemTags (optional) List body System tags 5.0.0
userTags (optional) List body User tags 5.0.0

API Response

Response Example
{
  "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"
  }
}
Name Type Description Since
success boolean Whether the operation succeeded. 5.0.0
inventory KeyProviderInventory For details, see inventory 5.0.0
error ErrorCode For details, see error 5.0.0
#inventory
Name Type Description Since
uuid String Resource UUID, which uniquely identifies the resource 5.0.0
name String Resource name 5.0.0
description String Resource description 5.0.0
type String Key provider type 5.0.0
connected boolean Whether the key provider is connected 5.0.0
createDate Timestamp Creation time 5.0.0
lastOpDate Timestamp Last modification time 5.0.0
#error
Name Type Description Since
code String Error code, which globally and uniquely identifies an error, such as SYS.1000 or HOST.1001 0.6
description String Summary of the error 0.6
details String Details of the error 0.6
elaboration String Reserved field. The default value is null 0.6
opaque LinkedHashMap Reserved field. The default value is null 0.6
cause ErrorCode Root error that caused the current error. The value is null if no root error exists 0.6

SDK Example

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()

UploadKmsClientCsr

API Request

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: In the preceding example, the systemTags and userTags fields can be omitted. They are listed to indicate that the body can include these two fields.
Curl Example
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
Parameter List
Name Type Location Description Optional Value Since
csrPem String body (contained in uploadKmsClientCsr structure) CSR 5.0.0
csrKeyPem String body (contained in uploadKmsClientCsr structure) CSR private key 5.0.0
uuid String url Resource UUID, which uniquely identifies the resource 5.0.0
systemTags (optional) List body System tags 5.0.0
userTags (optional) List body User tags 5.0.0

API Response

Response Example
{
  "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"
  }
}
Name Type Description Since
success boolean Whether the operation succeeded. 5.0.0
inventory KmsIdentityInventory For details, see inventory 5.0.0
error ErrorCode For details, see error 5.0.0
#inventory
Name Type Description Since
uuid String Resource UUID, which uniquely identifies the resource 5.0.0
kmsUuid String KmsUUID 5.0.0
identityType String Identity type 5.0.0
clientCertPem String KMSClient certificate 5.0.0
csrPem String CSR content 5.0.0
certExpiredDate Timestamp Client certificate expiration time 5.0.0
createDate Timestamp Creation time 5.0.0
lastOpDate Timestamp Last modification time 5.0.0
#error
Name Type Description Since
code String Error code, which is the globally unique identifier of the error, for example, SYS.1000 or HOST.1001 0.6
description String Summary description of the error 0.6
details String Detailed information about the error 0.6
elaboration String Reserved field. The default value is null. 0.6
opaque LinkedHashMap Reserved field. The default value is null. 0.6
cause ErrorCode Root error that caused the current error. If no root error exists, this field is null. 0.6

SDK Example

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()

UploadKmsClientIdentity

API Request

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: In the preceding example, the systemTags and userTags fields can be omitted. They are listed to indicate that the body can include these two fields.
Curl Example
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
Parameter List
Name Type Location Description Optional Value Since
identityType String body (contained in uploadKmsClientIdentity structure) Identity source type
  • UPLOADED
  • PLATFORM
 5.0.0
kmsClientCertPem String body (contained in uploadKmsClientIdentity structure) Client certificate 5.0.0
kmsClientKeyPem String body (contained in uploadKmsClientIdentity structure) Client private key 5.0.0
uuid String url Resource UUID, which uniquely identifies the resource 5.0.0
systemTags (optional) List body System tags 5.0.0
userTags (optional) List body User tags 5.0.0

API Response

Response Example
{
  "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"
  }
}
Name Type Description Since
success boolean Whether the operation succeeded. 5.0.0
inventory KmsIdentityInventory For details, see inventory 5.0.0
error ErrorCode For details, see error 5.0.0
#inventory
Name Type Description Since
uuid String Resource UUID, which uniquely identifies the resource 5.0.0
kmsUuid String KmsUUID 5.0.0
identityType String Identity type 5.0.0
clientCertPem String KMSClient certificate 5.0.0
csrPem String CSR content 5.0.0
certExpiredDate Timestamp Client certificate expiration time 5.0.0
createDate Timestamp Creation time 5.0.0
lastOpDate Timestamp Last modification time 5.0.0
#error
Name Type Description Since
code String Error code, which is the globally unique identifier of the error, for example, SYS.1000 or HOST.1001 0.6
description String Summary description of the error 0.6
details String Detailed information about the error 0.6
elaboration String Reserved field. The default value is null. 0.6
opaque LinkedHashMap Reserved field. The default value is null. 0.6
cause ErrorCode Root error that caused the current error. If no root error exists, this field is null. 0.6

SDK Example

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()

UploadKmsClientSignedCert

API Request

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: In the preceding example, the systemTags and userTags fields can be omitted. They are listed to indicate that the body can include these two fields.
Curl Example
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
Parameter List
Name Type Location Description Optional Value Since
signedClientCertPem String body (contained in uploadKmsClientSignedCert structure) Signed client certificate 5.0.0
uuid String url Resource UUID, which uniquely identifies the resource 5.0.0
systemTags (optional) List body System tags 5.0.0
userTags (optional) List body User tags 5.0.0

API Response

Response Example
{
  "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"
  }
}
Name Type Description Since
success boolean Whether the operation succeeded. 5.0.0
inventory KmsIdentityInventory For details, see inventory 5.0.0
error ErrorCode For details, see error 5.0.0
#inventory
Name Type Description Since
uuid String Resource UUID, which uniquely identifies the resource 5.0.0
kmsUuid String KmsUUID 5.0.0
identityType String Identity type 5.0.0
clientCertPem String KMSClient certificate 5.0.0
csrPem String CSR content 5.0.0
certExpiredDate Timestamp Client certificate expiration time 5.0.0
createDate Timestamp Creation time 5.0.0
lastOpDate Timestamp Last modification time 5.0.0
#error
Name Type Description Since
code String Error code, which is the globally unique identifier of the error, for example, SYS.1000 or HOST.1001 0.6
description String Summary description of the error 0.6
details String Detailed information about the error 0.6
elaboration String Reserved field. The default value is null. 0.6
opaque LinkedHashMap Reserved field. The default value is null. 0.6
cause ErrorCode Root error that caused the current error. If no root error exists, this field is null. 0.6

SDK Example

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()

UploadKmsServerCert

API Request

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: In the preceding example, the systemTags and userTags fields can be omitted. They are listed to indicate that the body can include these two fields.
Curl Example
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
Parameter List
Name Type Location Description Optional Value Since
serverCertPem String body (contained in uploadKmsServerCert structure) Server certificate 5.0.0
uuid String url Resource UUID, which uniquely identifies the resource 5.0.0
systemTags (optional) List body System tags 5.0.0
userTags (optional) List body User tags 5.0.0

API Response

Response Example
{
  "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"
  }
}
Name Type Description Since
success boolean Whether the operation succeeded. 5.0.0
inventory KmsInventory For details, see inventory 5.0.0
error ErrorCode For details, see error 5.0.0
#inventory
Name Type Description Since
endpoint String KMS server address 5.0.0
port Integer KMS server port 5.0.0
kmipVersion String KMIP protocol version 5.0.0
username String Authentication username 5.0.0
trustState String KMS mutual trust state. Supported states: neither side trusts the other, only the MN trusts the KMS, only the KMS trusts the MN, and mutual trust 5.0.0
activeIdentityUuid String UUID of the active client identity 5.0.0
serverCertPem String KMS server certificate content (PEM) 5.0.0
uuid String Resource UUID, which uniquely identifies the resource 5.0.0
name String Resource name 5.0.0
description String Resource description 5.0.0
type String Key provider type 5.0.0
connected boolean Whether the key provider is connected 5.0.0
createDate Timestamp Creation time 5.0.0
lastOpDate Timestamp Last modification time 5.0.0
serverCertInfo CertificateInfo For details, see serverCertInfo 5.0.0
activeIdentity KmsIdentityInventory For details, see activeIdentity 5.0.0
#serverCertInfo
Name Type Description Since
subject String Certificate subject DN 5.0.0
issuer String Certificate issuer DN 5.0.0
commonName String Certificate common name (CN) 5.0.0
subjectAltNamesDns List List of DNS names in Subject Alternative Name 5.0.0
subjectAltNamesIp List List of IP addresses in Subject Alternative Name 5.0.0
expiredDate Timestamp Certificate expiration time 5.0.0
#activeIdentity
Name Type Description Since
uuid String Resource UUID, which uniquely identifies the resource 5.0.0
kmsUuid String KMS UUID 5.0.0
identityType String Identity type 5.0.0
clientCertPem String KMS client certificate 5.0.0
csrPem String CSR content 5.0.0
certExpiredDate Timestamp Client certificate expiration time 5.0.0
createDate Timestamp Creation time 5.0.0
lastOpDate Timestamp Last modification time 5.0.0
#error
Name Type Description Since
code String Error code, which globally and uniquely identifies an error, such as SYS.1000 or HOST.1001 0.6
description String Summary of the error 0.6
details String Details of the error 0.6
elaboration String Reserved field. The default value is null 0.6
opaque LinkedHashMap Reserved field. The default value is null 0.6
cause ErrorCode Root error that caused the current error. The value is null if no root error exists 0.6

SDK Example

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 Request

URLs
PUT zstack/v1/key-providers/nkp/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "backupNkp": {
    "password": "password"
  },
  "systemTags": [],
  "userTags": []
}
Note: In the preceding example, the systemTags and userTags fields can be omitted. They are listed to indicate that the body can include these two fields.
Curl Example
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
Parameter List
Name Type Location Description Optional Value Since
uuid String url Resource UUID, which uniquely identifies the resource 5.0.0
password (optional) String body (contained in backupNkp structure) Backup protection password 5.0.0
systemTags (optional) List body System tags 5.0.0
userTags (optional) List body User tags 5.0.0

API Response

Response Example
{
  "content": "BASE64_ENCODED_NKP_BACKUP"
}
Name Type Description Since
success boolean Whether the operation succeeded. 5.0.0
content String Backup content (Base64-encoded) 5.0.0
error ErrorCode For details, see error 5.0.0
#error
Name Type Description Since
code String Error code, which is the globally unique identifier of the error, for example, SYS.1000 or HOST.1001 0.6
description String Summary description of the error 0.6
details String Detailed information about the error 0.6
elaboration String Reserved field. The default value is null. 0.6
opaque LinkedHashMap Reserved field. The default value is null. 0.6
cause ErrorCode Root error that caused the current error. If no root error exists, this field is null. 0.6

SDK Example

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 Request

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: In the preceding example, the systemTags and userTags fields can be omitted. They are listed to indicate that the body can include these two fields.
Curl Example
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
Parameter List
Name Type Location Description Optional Value Since
kdf (optional) String body (contained in params structure) Key derivation function
  • HKDF-SHA256
 5.0.0
saltPolicy (optional) String body (contained in params structure) Salt policy
  • providerName
 5.0.0
name String body (contained in params structure) Resource name 5.0.0
description (optional) String body (contained in params structure) Detailed description of the resource 5.0.0
type (optional) String body (contained in params structure) Key provider type 5.0.0
resourceUuid (optional) String body (contained in params structure) Resource UUID 5.0.0
tagUuids (optional) List body (contained in params structure) Tag UUID list 5.0.0
systemTags (optional) List body System tags 5.0.0
userTags (optional) List body User tags 5.0.0

API Response

Response Example
{
  "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"
  }
}
Name Type Description Since
success boolean Whether the operation succeeded. 5.0.0
inventory KeyProviderInventory For details, see inventory 5.0.0
error ErrorCode For details, see error 5.0.0
#inventory
Name Type Description Since
uuid String Resource UUID, which uniquely identifies the resource 5.0.0
name String Resource name 5.0.0
description String Resource description 5.0.0
type String Key provider type 5.0.0
connected boolean Whether the key provider is connected 5.0.0
createDate Timestamp Creation time 5.0.0
lastOpDate Timestamp Last modification time 5.0.0
#error
Name Type Description Since
code String Error code, which globally and uniquely identifies an error, such as SYS.1000 or HOST.1001 0.6
description String Summary of the error 0.6
details String Details of the error 0.6
elaboration String Reserved field. The default value is null 0.6
opaque LinkedHashMap Reserved field. The default value is null 0.6
cause ErrorCode Root error that caused the current error. The value is null if no root error exists 0.6

SDK Example

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 Request

URLs
DELETE zstack/v1/key-providers/nkp/{uuid}
Headers
Authorization: OAuth the-session-uuid
Curl Example
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
Parameter List
Name Type Location Description Optional Value Since
uuid String url Resource UUID, which uniquely identifies the resource 5.0.0
deleteMode (optional) String query Deletion mode (Permissive / Enforcing, Permissive) 5.0.0
systemTags (optional) List query System tags 5.0.0
userTags (optional) List query User tags 5.0.0

API Response

When this API succeeds, it returns an empty JSON structure {}. When an error occurs, the returned JSON structure contains an error field. For example:
{
	"error": {
		"code": "SYS.1001",
		"description": "A message or a operation timeout",
		"details": "Create VM on KVM timeout after 300s"
	}
}

SDK Example

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 Request

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: In the preceding example, the systemTags and userTags fields can be omitted. They are listed to indicate that the body can include these two fields.
Curl Example
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
Parameter List
Name Type Location Description Optional Value Since
contentBase64 String body (contained in parseNkpRestore structure) Import content (Base64-encoded) 5.0.0
password (optional) String body (contained in parseNkpRestore structure) Import protection password 5.0.0
systemTags (optional) List body System tags 5.0.0
userTags (optional) List body User tags 5.0.0

API Response

Response Example
{
  "restoreInfo": {
    "uuid": "ff0415ff372f33b5b6b757d3b99ad900",
    "name": "nkp-1",
    "description": "example",
    "kdf": "HKDF-SHA256",
    "saltPolicy": "providerName",
    "currentVersion": 1,
    "backupTime": 1700000000000
  },
  "code": "KP.1000"
}
Name Type Description Since
code String Parse result code 5.0.0
reason String Reason for parse failure 5.0.0
success boolean Whether the operation succeeded. 5.0.0
restoreInfo NkpRestoreInfo For details, see restoreInfo 5.0.0
error ErrorCode For details, see error 5.0.0
#restoreInfo
Name Type Description Since
uuid String Resource UUID, which uniquely identifies the resource 5.0.0
name String Resource name 5.0.0
description String Detailed description of the resource 5.0.0
kdf String Key derivation function 5.0.0
saltPolicy String Salt policy 5.0.0
currentVersion Integer Current version 5.0.0
backupTime Long Backup time (millisecond timestamp) 5.0.0
#error
Name Type Description Since
code String Error code, which is the globally unique identifier of the error, for example, SYS.1000 or HOST.1001 0.6
description String Summary description of the error 0.6
details String Detailed information about the error 0.6
elaboration String Reserved field. The default value is null. 0.6
opaque LinkedHashMap Reserved field. The default value is null. 0.6
cause ErrorCode Root error that caused the current error. If no root error exists, this field is null. 0.6

SDK Example

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 Request

URLs
GET zstack/v1/key-providers/nkp
GET zstack/v1/key-providers/nkp/{uuid}
Headers
Authorization: OAuth the-session-uuid
Curl Example
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

Queryable Fields

Run the CLI command line tool, enter QueryNkp, and press Tab to view all queryable fields and resource names that can be used for cross-table queries.

API Response

Response Example
{
  "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"
    }
  ]
}
Name Type Description Since
success boolean Whether the operation succeeded. 5.0.0
inventories List For details, see inventories 5.0.0
error ErrorCode For details, see error 5.0.0
#inventories
Name Type Description Since
kdf String Key derivation function 5.0.0
saltPolicy String Salt policy 5.0.0
backedUp boolean Whether backup is complete 5.0.0
currentVersion Integer Current key version 5.0.0
uuid String Resource UUID, which uniquely identifies the resource 5.0.0
name String Resource name 5.0.0
description String Resource description 5.0.0
type String Key provider type 5.0.0
connected boolean Whether the key provider is connected 5.0.0
createDate Timestamp Creation time 5.0.0
lastOpDate Timestamp Last modification time 5.0.0
#error
Name Type Description Since
code String Error code, which globally and uniquely identifies an error, such as SYS.1000 or HOST.1001 0.6
description String Summary of the error 0.6
details String Details of the error 0.6
elaboration String Reserved field. The default value is null 0.6
opaque LinkedHashMap Reserved field. The default value is null 0.6
cause ErrorCode Root error that caused the current error. The value is null if no root error exists 0.6

SDK Example

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 Request

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: In the preceding example, the systemTags and userTags fields can be omitted. They are listed to indicate that the body can include these two fields.
Curl Example
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
Parameter List
Name Type Location Description Optional Value Since
contentBase64 String body (contained in restoreNkp structure) Backup content (Base64-encoded) 5.0.0
password (optional) String body (contained in restoreNkp structure) Backup protection password 5.0.0
systemTags (optional) List body System tags 5.0.0
userTags (optional) List body User tags 5.0.0

API Response

Response Example
{
  "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"
  }
}
Name Type Description Since
success boolean Whether the operation succeeded. 5.0.0
inventory NkpInventory For details, see inventory 5.0.0
error ErrorCode For details, see error 5.0.0
#inventory
Name Type Description Since
kdf String Key derivation function 5.0.0
saltPolicy String Salt policy 5.0.0
backedUp boolean Whether backup is complete 5.0.0
currentVersion Integer Current key version 5.0.0
uuid String Resource UUID, which uniquely identifies the resource 5.0.0
name String Resource name 5.0.0
description String Resource description 5.0.0
type String Key provider type 5.0.0
connected boolean Whether the key provider is connected 5.0.0
createDate Timestamp Creation time 5.0.0
lastOpDate Timestamp Last modification time 5.0.0
#error
Name Type Description Since
code String Error code, which globally and uniquely identifies an error, such as SYS.1000 or HOST.1001 0.6
description String Summary of the error 0.6
details String Details of the error 0.6
elaboration String Reserved field. The default value is null 0.6
opaque LinkedHashMap Reserved field. The default value is null 0.6
cause ErrorCode Root error that caused the current error. The value is null if no root error exists 0.6

SDK Example

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 Request

URLs
PUT zstack/v1/key-providers/nkp/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "updateNkp": {
    "description": "example"
  },
  "systemTags": [],
  "userTags": []
}
Note: In the preceding example, the systemTags and userTags fields can be omitted. They are listed to indicate that the body can include these two fields.
Curl Example
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
Parameter List
Name Type Location Description Optional Value Since
uuid String url Resource UUID, which uniquely identifies the resource 5.0.0
description (optional) String body (contained in updateNkp structure) Detailed description of the resource 5.0.0
systemTags (optional) List body System tags 5.0.0
userTags (optional) List body User tags 5.0.0

API Response

Response Example
{
  "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"
  }
}
Name Type Description Since
success boolean Whether the operation succeeded. 5.0.0
inventory KeyProviderInventory For details, see inventory 5.0.0
error ErrorCode For details, see error 5.0.0
#inventory
Name Type Description Since
uuid String Resource UUID, which uniquely identifies the resource 5.0.0
name String Resource name 5.0.0
description String Resource description 5.0.0
type String Key provider type 5.0.0
connected boolean Whether the key provider is connected 5.0.0
createDate Timestamp Creation time 5.0.0
lastOpDate Timestamp Last modification time 5.0.0
#error
Name Type Description Since
code String Error code, which globally and uniquely identifies an error, such as SYS.1000 or HOST.1001 0.6
description String Summary of the error 0.6
details String Details of the error 0.6
elaboration String Reserved field. The default value is null 0.6
opaque LinkedHashMap Reserved field. The default value is null 0.6
cause ErrorCode Root error that caused the current error. The value is null if no root error exists 0.6

SDK Example

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()
PreviousRegisterVmInstanceFromMetadataNextvTPM-related APIs
API Reference | ZStack ZSphere · ZVF | ZStack Resource Center