vTPM-related APIs

AddTpm

API Request

URLs

POST zstack/v1/tpms

Headers

Authorization: OAuth the-session-uuid

Body

{
  "params": {
    "keyProviderUuid": "ff03c7091617357eb4022d11c6860e00",
    "vmInstanceUuid": "ff01ec80fd11327cba7519b66119d900"
  },
  "systemTags": [],
  "userTags": []
}

Note: In the preceding example, the systemTags and userTags fields can be omitted. They are listed to indicate that the body can contain these two fields.

Curl Example

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X POST -d '{"params":{"keyProviderUuid":"ff03c7091617357eb4022d11c6860e00","vmInstanceUuid":"ff01ec80fd11327cba7519b66119d900"}}' \
http://localhost:8080/zstack/v1/tpms

Parameters

Name	Type	Location	Description	Since
keyProviderUuid (optional)	String	body(contained in the `params` structure)	Key provider UUID	5.0.0
vmInstanceUuid	String	body(contained in the `params` structure)	VM UUID	5.0.0
resourceUuid (optional)	String	body(contained in the `params` structure)	Resource UUID	5.0.0
tagUuids (optional)	List	body(contained in the `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": {
    "uuid": "ff00de2d3ab43127b1abdac68f1e7f00",
    "name": "TPM-for-VM-ff01ec80fd11327cba7519b66119d900",
    "vmInstanceUuid": "ff01ec80fd11327cba7519b66119d900",
    "createDate": "Nov 14, 2017 2:20:57 PM",
    "lastOpDate": "Nov 14, 2017 2:20:57 PM"
  }
}

Name	Type	Description	Since
success	boolean	Whether the add operation succeeded	5.0.0
inventory	TpmInventory	For details, see inventory	5.0.0
error	ErrorCode	For details, see error	5.0.0

#inventory

Name	Type	Description	Since
uuid	String	TPM UUID	5.0.0
name	String	TPM resource name	5.0.0
vmInstanceUuid	String	VM UUID	5.0.0
createDate	Timestamp	Creation time	5.0.0
lastOpDate	Timestamp	Last modification time	5.0.0
hostRefs	List	For details, see hostRefs	5.0.0

#hostRefs

Name	Type	Description	Since
uuid	String	Related file UUID	5.0.0
vmInstanceUuid	String	VM UUID	5.0.0
hostUuid	String	Host UUID	5.0.0
type	String	File type, classified by usage. Possible values are NvRam or TpmState	5.0.0
path	String	Path of the related file or directory on the host	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, a globally unique identifier of the error, for example, SYS.1000 or HOST.1001	0.6
description	String	Brief 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, which is the source error that caused the current error. If there is no source error, this field is null	0.6

SDK Example

Java SDK

AddTpmAction action = new AddTpmAction();
action.keyProviderUuid = "ff03c7091617357eb4022d11c6860e00";
action.vmInstanceUuid = "ff01ec80fd11327cba7519b66119d900";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
AddTpmAction.Result res = action.call();

Python SDK

action = AddTpmAction()
action.keyProviderUuid = "ff03c7091617357eb4022d11c6860e00"
action.vmInstanceUuid = "ff01ec80fd11327cba7519b66119d900"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

GetTpmCapability

API Request

URLs

GET zstack/v1/tpms/capability

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/tpms/capability?vmInstanceUuid=ff01ec80fd11327cba7519b66119d900

Parameters

Name	Type	Location	Description	Since
tpmUuid (optional)	String	query	TPM UUID	5.0.0
vmInstanceUuid (optional)	String	query	VM UUID	5.0.0
systemTags (optional)	List	query	System tags	5.0.0
userTags (optional)	List	query	User tags	5.0.0

API Response

Response Example

{
  "inventory": {
    "uuid": "ff00de2d3ab43127b1abdac68f1e7f00",
    "name": "TPM-for-VM-ff01ec80fd11327cba7519b66119d900",
    "vmInstanceUuid": "ff01ec80fd11327cba7519b66119d900",
    "createDate": "Nov 14, 2017 2:20:57 PM",
    "lastOpDate": "Nov 14, 2017 2:20:57 PM",
    "fileRefs": [
      {
        "uuid": "ff0ee7dfcb8a3aa5b3534a1667c90400",
        "vmInstanceUuid": "ff01ec80fd11327cba7519b66119d900",
        "hostUuid": "ff0192fa70113da886101145c084bd00",
        "type": "TpmState",
        "path": "/var/lib/libvirt/swtpm/ff0192fa70113da886101145c084bd00/",
        "lastSyncReason": "on libvirt shutdown event",
        "createDate": "Nov 14, 2017 2:20:57 PM",
        "lastOpDate": "Nov 14, 2017 2:20:57 PM"
      }
    ],
    "edkVersion": "edk2-ovmf-20220126gitbb1bba3d77-3.el8.noarch",
    "swtpmVersion": "0.8.2",
    "resetTpmAfterVmCloneConfig": true
  }
}

Name	Type	Description	Since
success	boolean	Whether the get operation succeeded	5.0.0
inventory	TpmCapabilityView	For details, see inventory	5.0.0
error	ErrorCode	For details, see error	5.0.0

#inventory

Name	Type	Description	Since
uuid	String	TPM UUID	5.0.0
name	String	TPM resource name	5.0.0
vmInstanceUuid	String	VM UUID	5.0.0
createDate	Timestamp	Creation time	5.0.0
lastOpDate	Timestamp	Last modification time	5.0.0
edkVersion	String	EDK suite version	5.0.0
swtpmVersion	String	SWTPM version	5.0.0
resetTpmAfterVmCloneConfig	boolean	Configuration that specifies whether to reset the TPM state after VM cloning	5.0.0
fileRefs	List	For details, see fileRefs	5.0.0

#fileRefs

Name	Type	Description	Since
uuid	String	Related file UUID	5.0.0
vmInstanceUuid	String	VM UUID	5.0.0
hostUuid	String	Host UUID	5.0.0
type	String	File type, classified by usage. Possible values are NvRam or TpmState	5.0.0
path	String	Path of the related file or directory on the host	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, a globally unique identifier of the error, for example, SYS.1000 or HOST.1001	0.6
description	String	Brief 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, which is the source error that caused the current error. If there is no source error, this field is null	0.6

SDK Example

Java SDK

GetTpmCapabilityAction action = new GetTpmCapabilityAction();
action.vmInstanceUuid = "ff01ec80fd11327cba7519b66119d900";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
GetTpmCapabilityAction.Result res = action.call();

Python SDK

action = GetTpmCapabilityAction()
action.vmInstanceUuid = "ff01ec80fd11327cba7519b66119d900"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

QueryTpm

API Request

URLs

GET zstack/v1/tpms

GET zstack/v1/tpms/{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/tpms?q=uuid=ff00de2d3ab43127b1abdac68f1e7f00

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/tpms/c7ff0c86fd7c38908f619a9dfb610e68

Queryable Fields

Run the CLI tool, enter QueryTpm, and press Tab to view all queryable fields and resource names that support cross-table queries.

API Response

Response Example

{
  "inventories": [
    {
      "uuid": "ff00de2d3ab43127b1abdac68f1e7f00",
      "name": "TPM-for-VM-ff01ec80fd11327cba7519b66119d900",
      "vmInstanceUuid": "ff01ec80fd11327cba7519b66119d900",
      "createDate": "Nov 14, 2017 2:20:57 PM",
      "lastOpDate": "Nov 14, 2017 2:20:57 PM"
    }
  ]
}

Name	Type	Description	Since
success	boolean	Whether the query 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	TPM UUID	5.0.0
name	String	TPM resource name	5.0.0
vmInstanceUuid	String	VM UUID	5.0.0
createDate	Timestamp	Creation time	5.0.0
lastOpDate	Timestamp	Last modification time	5.0.0
hostRefs	List	For details, see hostRefs	5.0.0

#fileRefs

Name	Type	Description	Since
uuid	String	Related file UUID	5.0.0
vmInstanceUuid	String	VM UUID	5.0.0
hostUuid	String	Host UUID	5.0.0
type	String	File type, classified by usage. Possible values are NvRam or TpmState	5.0.0
path	String	Path of the related file or directory on the host	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, a globally unique identifier of the error, for example, SYS.1000 or HOST.1001	0.6
description	String	Brief 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, which is the source error that caused the current error. If there is no source error, this field is null	0.6

SDK Example

Java SDK

QueryTpmAction action = new QueryTpmAction();
action.conditions = asList("uuid=ff00de2d3ab43127b1abdac68f1e7f00");
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
QueryTpmAction.Result res = action.call();

Python SDK

action = QueryTpmAction()
action.conditions = ["uuid=ff00de2d3ab43127b1abdac68f1e7f00"]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

RemoveTpm

API Request

URLs

DELETE zstack/v1/tpms

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/tpms?vmInstanceUuid=ff01ec80fd11327cba7519b66119d900&deleteMode=Permissive

Parameters

Name	Type	Location	Description	Since
tpmUuid (optional)	String	query	TPM UUID	5.0.0
vmInstanceUuid (optional)	String	query	VM UUID	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. Example:

{
	"error": {
		"code": "SYS.1001",
		"description": "A message or a operation timeout",
		"details": "Create VM on KVM timeout after 300s"
	}
}

SDK Example

Java SDK

RemoveTpmAction action = new RemoveTpmAction();
action.vmInstanceUuid = "ff01ec80fd11327cba7519b66119d900";
action.deleteMode = "Permissive";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
RemoveTpmAction.Result res = action.call();

Python SDK

action = RemoveTpmAction()
action.vmInstanceUuid = "ff01ec80fd11327cba7519b66119d900"
action.deleteMode = "Permissive"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

UpdateTpm

API Request

URLs

PUT zstack/v1/tpms

Headers

Authorization: OAuth the-session-uuid

Body

{
  "updateTpm": {
    "vmInstanceUuid": "ff01ec80fd11327cba7519b66119d900",
    "keyProviderUuid": "ff03c7091617357eb4022d11c6860e00"
  },
  "systemTags": [],
  "userTags": []
}

Note: In the preceding example, the systemTags and userTags fields can be omitted. They are listed to indicate that the body can contain these two fields.

Curl Example

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"updateTpm":{"vmInstanceUuid":"ff01ec80fd11327cba7519b66119d900","keyProviderUuid":"ff03c7091617357eb4022d11c6860e00"}}' \
http://localhost:8080/zstack/v1/tpms

Parameters

Name	Type	Location	Description	Since
vmInstanceUuid (optional)	String	body(contained in the `updateTpm` structure)	VM UUID	5.0.0
tpmUuid (optional)	String	body(contained in the `updateTpm` structure)	TPM UUID	5.0.0
keyProviderUuid (optional)	String	body(contained in the `updateTpm` structure)	Key provider UUID	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": "ff00de2d3ab43127b1abdac68f1e7f00",
    "name": "TPM-for-VM-ff01ec80fd11327cba7519b66119d900",
    "vmInstanceUuid": "ff01ec80fd11327cba7519b66119d900",
    "createDate": "Nov 14, 2017 2:20:57 PM",
    "lastOpDate": "Nov 14, 2017 2:20:57 PM"
  }
}

Name	Type	Description	Since
success	boolean	Whether the update operation succeeded	5.0.0
inventory	TpmInventory	For details, see inventory	5.0.0
error	ErrorCode	For details, see error	5.0.0

#inventory

Name	Type	Description	Since
uuid	String	TPM UUID	5.0.0
name	String	TPM resource name	5.0.0
vmInstanceUuid	String	VM UUID	5.0.0
createDate	Timestamp	Creation time	5.0.0
lastOpDate	Timestamp	Last modification time	5.0.0
hostRefs	List	For details, see hostRefs	5.0.0

#fileRefs

Name	Type	Description	Since
uuid	String	Related file UUID	5.0.0
vmInstanceUuid	String	VM UUID	5.0.0
hostUuid	String	Host UUID	5.0.0
type	String	File type, classified by usage. Possible values are NvRam or TpmState	5.0.0
path	String	Path of the related file or directory on the host	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, a globally unique identifier of the error, for example, SYS.1000 or HOST.1001	0.6
description	String	Brief 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, which is the source error that caused the current error. If there is no source error, this field is null	0.6

SDK Example

Java SDK

UpdateTpmAction action = new UpdateTpmAction();
action.vmInstanceUuid = "ff01ec80fd11327cba7519b66119d900";
action.keyProviderUuid = "ff03c7091617357eb4022d11c6860e00";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
UpdateTpmAction.Result res = action.call();

Python SDK

action = UpdateTpmAction()
action.vmInstanceUuid = "ff01ec80fd11327cba7519b66119d900"
action.keyProviderUuid = "ff03c7091617357eb4022d11c6860e00"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

PreviousKey Provider APIs NextBare Metal Management