API Documentation
Table of Contents
1. General Information
1.1 Request Headers
| Field | Type | Required | Description |
|---|---|---|---|
| Content-Type | string | Yes | Content-Type header |
| Accept | string | No | Accept header |
| API-Key | string | No | For API authentication |
| User-Id | string | Yes | User identifier |
| User-Name | string | No | Username |
| Request-Id | string | No | Request ID |
2. Agent API
2.1 Get Token
Description: Get token
Request Method: POST /global-trust-authority/agent/v1/tokens
Request Parameters
| Field | Sub-field | Type | Required | parameter constraint | Description |
|---|---|---|---|---|---|
| attester_info | list of object | No | Challenge information | ||
| attester_type | string | No | tpm_boot/tpm/tpm_ima/virt_cca/ascend_npu/itrustee/cca/dice | Challenge type, defaults to traversing activated client plugins if not specified | |
| policy_ids | list of string | No | Supports up to 10 IDs | Applied policies, uses default policy if not specified | |
| attester_ids | list of string | No | Attester ids , such as uuid of TA in itrustee. | ||
| challenge | bool | No | Whether to challenge, defaults to no challenge | ||
| token_fmt | string | No | eat/ear | Token format, default value is eat | |
| attester_data | object | No | User data, reserved field |
Response Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| message | string | Yes for failed request | Error message |
| token | object | Yes for successful request | Token object |
Example of request
request body
{
"attester_info": [
{
"attester_type": "tpm_boot",
"policy_ids": []
}
],
"challenge": true,
"token_fmt": "eat",
"attester_data": {"test_key": "test_value"}
}
response body
{
"token":"xxx"
}
2.2 Get Evidence
Description: Provides encapsulated Evidence data
Request Method: POST /global-trust-authority/agent/v1/evidences
Request Parameters
| Field | Sub-field | Type | Required | parameter constraint | Description |
|---|---|---|---|---|---|
| attesters | list of objects | Yes | challenge information | ||
| attester_type | string | yes | tpm_boot/tpm/tpm_ima/virt_cca/ascend_npu/itrustee/cca/dice | challenge types | |
| log_types | list of string | No | boot_log/ima_log/dim_log | types of log to collect | |
| attester_ids | list of string | No | Attester ids , such as uuid of TA in itrustee. | ||
| nonce_type | string | No | ignore、 user or verifier | ignore/user/verifier(default value) corresponds to not verifying nonce, using user nonce, using verifier-generated nonce | |
| nonce | string | No | Length 1-1024 bytes | Nonce value, format: Base64 | |
| token_fmt | string | No | eat/ear | Token format, default value is eat | |
| attester_data | object | No | User data, reserved field |
Response Parameters
| Field | Sub-field | Second-level Sub-field | Type | Required | Description |
|---|---|---|---|---|---|
| agent_version | string | No | Client version number | ||
| measurements | list of objects | No | Measurement data | ||
| node_id | string | No | Node ID, corresponds to ueid | ||
| nonce_type | string | No | Nonce type, possible values: ignore, user or verifier | ||
| nonce | string | No | Nonce value, format: Base64 | ||
| attester_data | object | No | User-defined data to be passed through, must be placed in token as-is | ||
| token_fmt | string | No | Token format, default value is eat | ||
| evidences | list of objects | No | Challenge report | ||
| attester_type | string | No | Challenge type | ||
| evidence | list of objects | No | Specific evidence |
Example of request
request body
{
"attesters": [
{
"attester_type": "tpm_boot",
"log_types": ["boot_log"]
}
],
"nonce_type": "verifier",
"nonce": "eyJpYXQiOjE3NTY5ODAwNjMsInZhbHVlIjoiZjMrYVc0cm1vWHUxSjNjaGlJZWNkMkJUWWYrdS84WXU0Q2VTZWYwUmt4MXYzeHJhNHZNYkNrc1locC9UaTRVWW9wN1ZvMm5XNXlsMGs4VXNQNnZrTkE9PSIsInNpZ25hdHVyZSI6Im9Mc09WbTh2OHY3ZllUTW9SZHdySjBrbWl4blFmRXIwTVliNExDa2NyZUpveUFDZmFBdlpGdmJiYURHTFJjOW9ndWkycVhMbnUwWFgvZDhEc1hhK2xwQzg2dXhSeWZtYklSdVpza2xscHd5WVV4TXlEbmFZQS9SSlFGaEtEakJjYUp0Ri9sQnpZYWMzVVNzQmFkNE5tMVE1cnBEb3RscFpHbHd5akhhdGtxUENPVzZORG9wbU9pZWtzM3RNVXpJV0NyNVZPVGhhRnpZdUdIZUZJMHdhdVdMWHY4TnlwRnlIbnllay8zdWhjdEhIc2gyRExZZUVBZW1keWQ2VnVDWmNqNjBzSjNyenF5ME9LTUFIQVRuOWhhZjk0M0k3SllDUlkvTU0xQ08rWmk1MHNTUXV1UHllVUpuTERpMGxwQmdDZmwyeWgyQ2phcU9QdE15ckhTREJwRlNNaC8xVW5xdDBlaXFzcFRESDNtNm81TXd3dUFQWGJmRFZvaDArR2dPaUowaENLUnhLY3NXSXVHNythemNoS0U3U1kyakIxWWg0NjlpSTN2MUpQRWhobnVtdC9YWENhRXBYd29aVENLRUN6NjJMYnByOWp3SzZXVVZyS2t5L3hmbkdKTlR3NWxHNGFBS1hlOFdzSldtYnpXK0Yvd0JFa0E2amdHK1hWT1J6In0=",
"token_fmt": "eat",
"attester_data": {"test_key": "test_value"}
}
response body
{"agent_version":"0.1.0","measurements":[{"node_id":"TPM AK","nonce":"eyJpYXQiOjE3NTY5ODAwNjMsInZhbHVlIjoiZjMrYVc0cm1vWHUxSjNjaGlJZWNkMkJUWWYrdS84WXU0Q2VTZWYwUmt4MXYzeHJhNHZNYkNrc1locC9UaTRVWW9wN1ZvMm5XNXlsMGs4VXNQNnZrTkE9PSIsInNpZ25hdHVyZSI6Im9Mc09WbTh2OHY3ZllUTW9SZHdySjBrbWl4blFmRXIwTVliNExDa2NyZUpveUFDZmFBdlpGdmJiYURHTFJjOW9ndWkycVhMbnUwWFgvZDhEc1hhK2xwQzg2dXhSeWZtYklSdVpza2xscHd5WVV4TXlEbmFZQS9SSlFGaEtEakJjYUp0Ri9sQnpZYWMzVVNzQmFkNE5tMVE1cnBEb3RscFpHbHd5akhhdGtxUENPVzZORG9wbU9pZWtzM3RNVXpJV0NyNVZPVGhhRnpZdUdIZUZJMHdhdVdMWHY4TnlwRnlIbnllay8zdWhjdEhIc2gyRExZZUVBZW1keWQ2VnVDWmNqNjBzSjNyenF5ME9LTUFIQVRuOWhhZjk0M0k3SllDUlkvTU0xQ08rWmk1MHNTUXV1UHllVUpuTERpMGxwQmdDZmwyeWgyQ2phcU9QdE15ckhTREJwRlNNaC8xVW5xdDBlaXFzcFRESDNtNm81TXd3dUFQWGJmRFZvaDArR2dPaUowaENLUnhLY3NXSXVHNythemNoS0U3U1kyakIxWWg0NjlpSTN2MUpQRWhobnVtdC9YWENhRXBYd29aVENLRUN6NjJMYnByOWp3SzZXVVZyS2t5L3hmbkdKTlR3NWxHNGFBS1hlOFdzSldtYnpXK0Yvd0JFa0E2amdHK1hWT1J6In0=","nonce_type":"verifier","attester_data":{"test_key":"test_value"},"token_fmt":"eat","evidences":[{"attester_type":"tpm_boot","evidence":{"ak_certs":[{"cert_type":"iak","cert_data":"-----BEGIN CERTIFICATE-----\nMIIDBjCCAe4CFBL8z+Gow59PViXBqsqFMR2GhOUdMA0GCSqGSIb3DQEBCwUAMEcxCzAJBgNVBAYTAkNOMRAwDgYDVQQKDAd0ZXN0IENBMQ0wCwYDVQQLDAR0ZXN0MRcwFQYDVQQDDA5UUE0gUm9vdCBDQSB2MjAeFw0yNTA0MjgxNDA2MjJaFw0zNTA0MjYxNDA2MjJaMDgxDzANBgNVBAMMBlRQTSBBSzEYMBYGA1UECgwPTXkgT3JnYW5pemF0aW9uMQswCQYDVQQGEwJDTjCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALKuVeLxr1WUlf3/IgDEmQ4KcIZQfsuu38U6s8PeiNbQytEBhMSIiqdteGevb+DHU7jtO+n39GJaBwp1OjuOJCo5QemaKidlG1IEfRxVO82cQ99FPXuqxFNIWcM4c6nWTmx+e3WDDSv8hRAowVgRsdqFkcR9fP9H7ahl8kyrOm5aSU2wKGfopxVBdUDlD+H+EaflwU0okXV8NW/Vq6+dFloCo6dMp37e3VI+YDc73Jp8xed7KmXqzUGUOWclBjAADg1W5hBdSDdCEzwJ9+1DspcyNkMYhs0UlXsHfxRY28Fmk66MIPEmcbbL/9Fs68qa0KEENABV5Vwb+rWFLlYviEkCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAw3l3M5Mq2hlL3mt01kzgRDJH5zLooWpq1Ze2BKKGaSbpqcvLI48WV0pvtJXrKELZecyTnVWMHjOVqrsWXUpzIx7sd4Gwrg4wa5xAU4azSI70Fa8apESI/m9K0ECUyhIOWdIo1xUHr21wPlLn09v1Ey59MQnfu/HvIhRifaEqEbHTw6PyQBBuWJ+YoAJ+Ry1Xs445Pvq2/wvBq6uypRcBnki/1mfabkOacE+pTQTvmji1iAl+40t6wcU+5KI6l4Mdor5wOzxWPIJJaq4NVUErAwtY/o44ZU1YAqdw2z5tyFz1SapWCDvqaEqm3FaOHtcozkHoHeZPMzKlWEupJf/Ekw==\n-----END CERTIFICATE-----"}],"quote":{"quote_data":"/1RDR4AYACIAC6dK2j3UWnqCmI9se9Itpmwo+GB2VAKRbS/VU2Iczqe1ACCt3tsBfBuY8awf4+x3f57JuaOsDHMDnS5mMyIN/sRT5gAAAAKiT1w+AAAAHgAAAAABIBkQIwAWNjYAAAABAAsD/wAAACDmjVToNmS/+eKvnv6kvbrY+7FU8ALNmB8Ntz2L9wJotw==","signature":"ABQACwEAcV8BD4Y+6Gi4sR2MkhbqVpN/Zr7UxkcWBXAEpbnbVOX/dF5Z3mvSr/mFSoxCpK6NFL2TtsILblT0nw4nKvc6B3Sl8wzzOrGMWPKvN15Akj6qg"}}}]}]}
3. Service API
3.1 Reference Value Management
3.1.1 Add Reference Value
Description: Add reference value
Request Method: POST /global-trust-authority/service/v1/ref_value
Request Parameters
| Field | Sub-field | Type | Required | parameter constraint | Description |
|---|---|---|---|---|---|
| name | string | Yes | Length 1-255 characters | Reference value name | |
| description | string | No | Length 0-512 characters | Reference value description | |
| attester_type | string | Yes | tpm/tpm_ima/virt_cca/ascend_npu/cca | Applicable challenge plugin type | |
| content | string | Yes | Maximum length 100M | Reference value content(only support ima-ng type) | |
| is_default | bool | No | Default false | Whether it is the default reference value |
Response Parameters
| Field | Sub-field | Type | Required | Description |
|---|---|---|---|---|
| message | string | Yes for failed request | Error message | |
| ref_value | object | Yes for successful request | Reference value information | |
| id | string | Yes | Reference value ID | |
| name | string | Yes | Reference value name | |
| version | string | Yes | Reference value version number |
Example of request
request body
{
"name": "test",
"description": "test",
"attester_type": "tpm_ima",
"content": "xxxx"
}
response body
{
"ref_value": {
"id": "7255326052342740548",
"version": "1",
"name": "test"
}
}
3.1.2 Update Reference Value
Description: Update Reference Value
Request Method: PUT /global-trust-authority/service/v1/ref_value
Request Parameters
| Field | Sub-field | Type | Required | parameter constraint | Description |
|---|---|---|---|---|---|
| id | string | Yes | Length 1-36 characters | Reference value ID | |
| name | string | No | Length 1-255 characters | Reference value name, directly overwrites when name is the same | |
| description | string | No | Length 0-512 characters | Reference value description | |
| content | string | No | Maximum length 100M | Reference value content | |
| attester_type | string | No | tpm/tpm_ima/virt_cca/ascend_npu/cca | Applicable challenge plugin type |
Response Parameters
| Field | Sub-field | Type | Required | Description |
|---|---|---|---|---|
| message | string | Yes for failed request | Error message | |
| ref_value | object | Yes for successful request | Reference value information | |
| id | string | Yes | Reference value ID | |
| name | string | Yes | Reference value name | |
| version | string | Yes | Reference value update version number |
Example of request
request body
{
"id": "7255326052342740548",
"name": "test",
"description": "test_description",
"content": "xxxx"
}
response body
{
"ref_value": {
"id": "7255326052342740548",
"version": "2",
"name": "test"
}
}
3.1.3 Query Reference Value
Description: Query Reference Value
Request Method: GET /global-trust-authority/service/v1/ref_value
Request Parameters
| Field | Sub-field | Type | Required | parameter constraint | Description |
|---|---|---|---|---|---|
| attester_type | string | No | tpm/tpm_ima/virt_cca/ascend_npu/cca | Reference value type (ignored if ids is not empty) | |
| ids | List of String | No | Length 1-36 characters | Reference value IDs |
Response Parameters
| Field | Sub-field | Type | Required | Description |
|---|---|---|---|---|
| message | string | Yes for failed request | Error message | |
| ref_values | list of objects | Yes for successful request | Reference value information | |
| id | string | Yes | Reference value ID | |
| name | string | No | Reference value name | |
| uid | string | Yes | User ID | |
| description | string | No | Reference value description | |
| content | string | No | Reference value content | |
| attester_type | string | Yes | Applicable challenge plugin type | |
| version | int | No | Reference value version | |
| create_time | Long | Yes | Creation time | |
| update_time | Long | Yes | Update time |
Note: When querying with ids, returns all fields of entries filtered by id; without ids, only returns required fields like id, name, version, etc., does not return specific content (entries filtered by type, if type not filled returns all for that user)
Example of request
request url
http(s)://ip:port/global-trust-authority/service/v1/ref_value?ids=2b0ead4b-6a15-4239-bf68-b1413df538bb
response body
{
"ref_value": [
{
"id": "2b0ead4b-6a15-4239-bf68-b1413df538bb",
"name": "test_refvalue",
"description": "This is Test",
"content": "xxxx",
"attester_type": [
"tpm_ima"
],
"version": 1,
"update_time": 1747640682,
"valid_code": 0
}
]
}
3.1.4 Delete Reference Value
Description: Delete reference value
Request Method: DELETE /global-trust-authority/service/v1/ref_value
Request Parameters
| Field | Sub-field | Type | Required | parameter constraint | Description |
|---|---|---|---|---|---|
| id | List of String | No | Length 1-36 characters | Reference value IDs | |
| attester_type | string | No | tpm/tpm_ima/virt_cca/ascend_npu/cca | Reference value type | |
| delete_type | string | Yes | ids, type, all | Delete Type |
Response Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| message | string | Yes for failed request | Error message |
Example of request
request body
{
"delete_type": "id",
"ids": ["8710919450846562689"]
}
response body
{}
3.2 Certificate Management
3.2.1 Add Certificate
Description: Add certificate
Request Method: POST /global-trust-authority/service/v1/cert
Request Parameters
| Field | Sub-field | Type | Required | parameter constraint | Description |
|---|---|---|---|---|---|
| name | string | Yes | Length 1-255 characters | Certificate name | |
| description | string | No | Length 0-512 characters | Description | |
| type | List of String | Yes | refvalue/policy/tpm_boot/tpm/tpm_ima/crl/ascend_npu | Certificate type, supported enums: refvalue/policy/tpm_boot/tpm/tpm_ima/crl/ascend_npu | |
| content | string | No | Certificate content, required when type is not crl | ||
| is_default | boolean | No | true or false | Whether it's default certificate, defaults to false | |
| crl_content | string | No | Certificate revocation list, required when type is crl |
Response Parameters
| Field | Sub-field | Type | Required | Description |
|---|---|---|---|---|
| message | string | Yes for failed request | Error message | |
| cert | object | Yes for successful request | Certificate | |
| cert_id | string | Yes | Certificate ID | |
| cert_name | string | Yes | Certificate name | |
| description | string | No | Description | |
| content | string | No | Certificate content | |
| cert_type | List of String | No | Certificate type | |
| is_default | boolean | No | Whether it's default certificate | |
| version | int | Yes | Certificate version number | |
| create_time | long | No | Creation timestamp | |
| update_time | long | No | Update timestamp | |
| valid_code | int | No | 0-Normal; 1-Signature verification failed; 2-Revoked | |
| cert_revoked_date | long | No | Certificate revocation time | |
| cert_revoked_reason | string | No | Certificate revocation reason | |
| crl | object | Yes for successful request | Certificate revocation list | |
| crl_id | string | Yes | Certificate revocation list id | |
| crl_name | string | Yes | Certificate revocation list name |
Example of request
insert cert request body
{
"name": "root.crt",
"type": ["tpm_ima", "tpm_boot"],
"content": "-----BEGIN CERTIFICATE-----\nxxxxx\n-----END CERTIFICATE-----"
}
insert cert response body
{
"cert": {
"cert_id": "4740ac7fb9c659e5a1cafad301e1ed00",
"cert_name": "root.crt.refvalue",
"version": 1
}
}
insert crl request body
{
"name": "crl.pem",
"type": ["crl"],
"crl_content": "-----BEGIN X509 CRL-----\nxxxxx\n-----END X509 CRL-----"
}
insert crl response body
{
"crl": {
"crl_id": "11398858-cc4b-49f8-8e6e-b98c82aaf496",
"crl_name": "crl.pem"
}
}
3.2.2 Update Certificate
Description: Update certificate
Request Method: PUT /global-trust-authority/service/v1/cert
Request Parameters
| Field | Type | Required | parameter constraint | Description |
|---|---|---|---|---|
| id | string | Yes | Length 1-32 characters | Certificate ID |
| name | string | No | Length 1-255 characters | Certificate name |
| description | string | No | Length 0-512 characters | Description |
| type | List of String | No | refvalue/policy/tpm_boot/tpm/tpm_ima/ascend_npu | Certificate type, supported: refvalue, policy, tpm_boot, tpm, tpm_ima, ascend_npu (crl not supported) |
| is_default | boolean | No | true or false | Whether it's default certificate, defaults to false |
Response Parameters
| Field | Sub-field | Type | Required | Description |
|---|---|---|---|---|
| message | string | Yes for failed request | Error message | |
| cert | object | Yes for successful request | ||
| cert_id | string | Yes | Certificate ID | |
| cert_name | string | Yes | Certificate name | |
| description | string | No | Description | |
| content | string | No | Certificate content | |
| cert_type | List of String | No | Certificate type | |
| is_default | boolean | No | Whether it's default certificate | |
| version | int | Yes | Certificate update version number | |
| create_time | long | No | Creation timestamp | |
| update_time | long | No | Update timestamp | |
| valid_code | int | No | 0-Normal; 1-Signature verification failed; 2-Revoked | |
| cert_revoked_date | long | No | Certificate revocation time | |
| cert_revoked_reason | string | No | Certificate revocation reason |
Example of request
request body
{
"name": "root.crt.refvalue",
"type": ["tpm_ima", "tpm_boot"],
"is_default": true
}
response body
{
"cert": {
"cert_id": "4740ac7fb9c659e5a1cafad301e1ed00",
"cert_name": "root.crt.refvalue",
"version": 2
}
}
3.2.3 Query Certificate
Description: Query certificate
Request Method: GET /global-trust-authority/service/v1/cert
Request Parameters
Note: To query revoked certificates, type must specify crl.
| Field | Sub-field | Type | Required | parameter constraint | Description |
|---|---|---|---|---|---|
| cert_type | string | No | refvalue/policy/tpm_boot/tpm/tpm_ima/crl/ascend_npu | Query certificate for specified purpose | |
| ids | List of String | No | Certificate ID, maximum 100 |
Response Parameters
| Field | Sub-field | Type | Required | Description |
|---|---|---|---|---|
| message | string | Yes for failed request | Error message | |
| certs | List of Object | Yes for successful request | Certificate information | |
| cert_id | string | Yes | Certificate ID | |
| cert_name | string | Yes | Certificate name | |
| description | string | No | Certificate description | |
| content | string | No | Certificate content | |
| cert_type | List of String | No | Certificate purpose | |
| is_default | boolean | No | Whether it's default certificate | |
| version | int | Yes | Certificate version | |
| create_time | long | No | Creation timestamp | |
| update_time | long | No | Update timestamp | |
| valid_code | int | No | 0-Normal; 1-Signature verification failed; 2-Revoked | |
| cert_revoked_date | long | No | Certificate revocation time, optional when type is crl | |
| cert_revoked_reason | string | No | Certificate revocation reason, optional when type is crl | |
| crls | List of Object | Yes for successful request | Certificate revocation list information | |
| crl_id | string | Yes | Certificate revocation list ID | |
| crl_name | string | Yes | Certificate revocation list name | |
| crl_content | string | Yes | Certificate revocation list content |
Note: When querying with ids, returns all fields of entries filtered by id; without ids, only returns required fields like id, name, version, etc., does not return specific content (entries filtered by type, if type not filled returns all for that user)
Example of request
query cert request url
http(s)://ip:port/global-trust-authority/service/v1/cert?ids=4740ac7fb9c659e5a1cafad301e1ed00
query cert response body
{
"certs": [
{
"cert_id": "4740ac7fb9c659e5a1cafad301e1ed00",
"cert_name": "root.crt.refvalue",
"content": "-----BEGIN CERTIFICATE-----\nxxxxx\n-----END CERTIFICATE-----",
"cert_type": [
"tpm_ima",
"tpm_boot"
],
"version": 1,
"create_time": 1747643045307,
"update_time": 1747643045307,
"valid_code": 0
}
]
}
query crl request url
http(s)://ip:port/global-trust-authority/service/v1/cert?cert_type=crl
query crl response body
{
"crls": [
{
"crl_id": "3ca52323-aa6a-4e70-af1f-46f015630d77",
"crl_name": "crl.pem",
"crl_content": "-----BEGIN X509 CRL-----\nxxxxx\n-----END X509 CRL-----"
}
]
}
3.2.4 Delete Certificate
Description: Delete certificate
Request Method: DELETE /global-trust-authority/service/v1/cert
Request Parameters
Note: To delete revoked certificates, type must specify crl.
| Field | Sub-field | Type | Required | parameter constraint | Description |
|---|---|---|---|---|---|
| delete_type | string | Yes | "id""type""all" | Delete type "id""type""all", When the type is crl, there is no need to pass it | |
| ids | List of String | No | Maximum 10 ids | Certificate ID list | |
| type | string | No | refvalue/policy/tpm_boot/tpm/tpm_ima/crl/ascend_npu | Certificate type, refvalue/policy/tpm_boot/tpm/tpm_ima/crl/ascend_npu |
Response Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| message | string | Yes for failed request | Error message |
delete cert request body
{
"delete_type": "id",
"ids": ["9acc144ed3515b1a84a4e00bccaeb4e2"]
}
delete crl request body
{
"type": "crl",
"ids": ["7b7462bd-7187-4cb9-a392-14f0e5fa8656"]
}
3.3 Challenge Related
3.3.1 Request Nonce
Description: Request nonce
Request Method: GET /global-trust-authority/service/v1/challenge
Response Parameters
| Field | Type | Required | Description | Note |
|---|---|---|---|---|
| service_version | string | Yes | Server version | Format is x.x.x, e.g., 1.0.0 |
| message | string | Yes for failed request | Error message | Maximum length 1024 bytes |
| nonce | string | Yes for successful request | Nonce information | Base64 encoded of nonce struct. Nonce struct is described in following table. |
nonce struct:
| Field | Type | Required | Description |
|---|---|---|---|
| iat | number | Yes | Timestamp for issuance |
| value | string | Yes | Random bytes, base64 encoded |
| signature | string | Yes | Signature of iat and value, base64 encoded |
Example of request
response body
{
"service_version": "1.0",
"nonce": "eyJpYXQiOjE3NTQ1NTIzNjQsInZhbHVlIjoiR3dvL3Z4WUZCYU5ZMWZlUGJUNytYdVZ2QXZ1ck9qU1JBTEx0bWg2OTZVcGFDR21qM1RrT1NRK3pqYkVBSWlkbUNvSmlySVF0RFAyZkJKdHFlNVFnT0E9PSIsInNpZ25hdHVyZSI6Im9VOFYwVnZYenhEbFJQRG56UzdnTGF4bkQvVEticGVwcytUNEpmenBPQkZ2ekR0b0NmOEEwRTF3RVB0dVVGajJmYjVSQkVsZkoxajc3WXQya1lQWFU5ZjIzWExOeXhFejRDZnZmQnZKQ2NFVjZCT0hYcVNTd3RKN25PUjZZN1JjekhoWnJ5UnhYd093N3dzcU9ZYVdRSGl0aW52ZGtRYzNjSDhUS1JzUjFaaS9FeFhHNHNYMXl6LzZ4eW9tbFRFOC9rYVZTY1dZSkI5K3A3ZnBMZTQ0S29MQXN5N3ZxcWhob1JYZXhaZXRzOUlLaE5FMmNXNityWHYxTFBOYzdXT3RWT2ZOQm1ZNUhrTW5hOHRIbUVHM0Z1SUNaVDdadjI3V3IxNmh1V2s5SEh6T1BDZjlhVHk5SnkvcnV0UUVRenZTOEhhbitweGZjZThQV0greFpKUFFVSFpZZkI3SmFZZVkwb1ltUWIzbDFHZ3RVWmc2TjZmVHFTRWdRMzBhL1BEMjVaNkNzb3Njdi9zb1B2b0NSZzNUQ2xwKzM0cFVpSXM2c2Z2OG56ZzZFQ2ZtOXBKazhKS2p3ZlNtcHA2N2VUWDVUN1cyNjFGdGlRcDNMQnVKbzF6Y1pZWmxXVlpFRCtqUDdYdk1OZnB1Ulg3emlJMFFUbVhVelBmSldoY3pzbUFTIn0="
}
Note: nonce can be base64 decoded as:
{
"iat": 1754552364,
"value": "Gwo/vxYFBaNY1fePbT7+XuVvAvurOjSRALLtmh696UpaCGmj3TkOSQ+zjbEAIidmCoJirIQtDP2fBJtqe5QgOA==",
"signature": "oU8V0VvXzxDlRPDnzS7gLaxnD/TKbpeps+T4JfzpOBFvzDtoCf8A0E1wEPtuUFj2fb5RBElfJ1j77Yt2kYPXU9f23XLNyxEz4CfvfBvJCcEV6BOHXqSSwtJ7nOR6Y7RczHhZryRxXwOw7wsqOYaWQHitinvdkQc3cH8TKRsR1Zi/ExXG4sX1yz/6xyomlTE8/kaVScWYJB9+p7fpLe44KoLAsy7vqqhhoRXexZets9IKhNE2cW6+rXv1LPNc7WOtVOfNBmY5HkMna8tHmEG3FuICZT7Zv27Wr16huWk9HHzOPCf9aTy9Jy/rutQEQzvS8Han+pxfce8PWH+xZJPQUHZYfB7JaYeY0oYmQb3l1GgtUZg6N6fTqSEgQ30a/PD25Z6Csoscv/soPvoCRg3TClp+34pUiIs6sfv8nzg6ECfm9pJk8JKjwfSmpp67eTX5T7W261FtiQp3LBuJo1zcZYZlWVZED+jP7XvMNfpuRX7ziI0QTmXUzPfJWhczsmAS"
}
3.3.2 Remote Attestation
Description: Report evidence for remote attestation
Request Method: POST /global-trust-authority/service/v1/attest
3.3.2.1 Request Parameters
| Field | Sub-field | Second-level Sub-field | Type | Required | parameter constraint | Description |
|---|---|---|---|---|---|---|
| agent_version | string | No | Length 1-50 characters | Client version number | ||
| measurements | list of objects | Yes | Measurement data | |||
| node_id | string | Yes | Length 1-255 characters | Node ID, corresponds to uied, recommended 32~128 characters, based on actual device | ||
| nonce_type | string | No | ignore/user/verifier (default value) corresponds to not verifying nonce, using user nonce, using verifier-generated nonce | |||
| nonce | string | No | Nonce, base64 encoded, 1~1024bytes | |||
| token_fmt | string | No | eat/ear | Token format, only support ear or eat, default is eat | ||
| attester_data | object | No | User-defined data to be passed through, must be placed in token as-is | |||
| evidences | list of objects | Yes | Challenge report | |||
| attester_type | string | Yes | Challenge type, see attester_type specification | |||
| mode | string | No | host/device | Challenge mode, host indicates host mode, device indicates device mode | ||
| evidence | object | Yes | Specific evidence | |||
| policy_ids | list of string | No | Each element 1-36 characters, max 10 items | If provided, the Policy ID list must contain between 1 and 10 entries. |
3.3.2.2 Response Parameters
| Field | Sub-field | Type | Required | Description |
|---|---|---|---|---|
| service_version | string | Yes | Server version number, format is x.x.x, e.g., 1.0.0 | |
| message | string | Yes for failed request | Error message, maximum 1024 characters | |
| tokens | list of objects | Yes for successful request | ||
| node_id | string | Yes | Node ID, not corresponding to uied, recommended 32~128 characters, based on actual device | |
| token | string | Yes | JWT format object, see token structure |
3.3.2.3 Token Object Structure
The Token is divided into EAT (Entity Attestation Token) and EAR (Entity Attestation Result) formats based on the token_fmt parameter. The Token itself is in JWT format.
3.3.2.3.1 JWT Header
The JWT Header is consistent across all Token formats:
| Field | Type | Required | Description |
|---|---|---|---|
| alg | string | Yes | Token signature algorithm, such as PS256, SM2 |
| typ | string | Yes | Token type, fixed as JWT |
| jku | string | No | JSON Web Key Set URI |
| kid | string | No | Signature key ID |
3.3.2.3.2 JWT Body Standard Fields
All Token formats include the following standard fields in the JWT Body:
| Field | Type | Required | Description |
|---|---|---|---|
| iat | number | Yes | Issue timestamp |
| exp | number | Yes | Expiration timestamp |
| iss | string | Yes | Issuer |
| jti | string | Yes | JWT identifier |
| ver | string | Yes | Token version, fixed as 1.0 |
| nbf | number | Yes | Not before timestamp |
| eat_profile | string | Yes | EAT profile URL |
3.3.2.3.3 EAT Token Format
When token_fmt is eat, an EAT Token is returned.
In addition to the JWT standard fields, the EAT Token Body includes the following fields:
| Field | Type | Required | Description |
|---|---|---|---|
| nonce_type | string | Yes | Nonce type: ignore/user/verifier |
| intuse | string | No | Expected usage, fixed as "generic" |
| eat_nonce | object | No | Nonce value, filled when nonce_type is user or verifier |
| attester_data | object | No | User-defined passthrough data |
| ueid | string | No | Device unique identifier |
| secure_boot | boolean | No | Secure boot status |
| dbgstat | string | No | Debug status |
| matched_policy | list of object | Yes | Matched policy list, see PolicyMatchedInfo Object |
| unmatched_policy | list of object | Yes | Unmatched policy list |
| status | string | Yes | Overall verification status: pass/no_pass |
| ${attester_type} | object | Yes | Verification result for corresponding attester_type, see EatAttesterResult Object |
EatAttesterResult Object:
| Field | Type | Required | Description |
|---|---|---|---|
| attestation_status | string | Yes | Attester verification status: pass/no_pass |
| policy_info | list of object | No | Policy information list, see PolicyInfo Object |
| raw_evidence | object | No | Original evidence uploaded by attester, such as PCR values |
| mode | string | No | Challenge mode: host/device |
PolicyMatchedInfo Object:
| Field | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | Policy ID |
| version | number | Yes | Policy version |
| sha256 | string | Yes | SHA256 of policy content |
PolicyInfo Object:
| Field | Type | Required | Description |
|---|---|---|---|
| appraisal_policy_id | string | Yes | Applied policy ID |
| policy_version | number | Yes | Policy version |
| policy_matched | boolean | Yes | Whether policy matched |
| custom_data | object | No | Policy-defined output |
3.3.2.3.4 EAR Token Format
When token_fmt is ear, an EAR Token is returned.
In addition to the JWT standard fields, the EAR Token Body includes the following fields:
| Field | Type | Required | Description |
|---|---|---|---|
| matched_policy | list of object | Yes | Matched policy list, see PolicyMatchedInfo Object |
| unmatched_policy | list of object | Yes | Unmatched policy list |
| ueid | string | No | Device unique identifier |
| secure_boot | boolean | No | Secure boot status |
| dbgstat | string | No | Debug status |
| ear.verifier-id | object | Yes | Verifier information, see EarTokenVerifierId Object |
| ear.raw-evidence | object | No | Raw evidence |
| submods | list of object | Yes | Submodule result list, see EarSubmodResult Object |
| status | string | Yes | Overall verification status: pass/no_pass |
EarTokenVerifierId Object:
| Field | Type | Required | Description |
|---|---|---|---|
| developer | string | Yes | Developer identifier |
| version | string | Yes | Verifier version |
EarSubmodResult Object:
| Field | Type | Required | Description |
|---|---|---|---|
| ${attester_type} | object | Yes | Verification result for corresponding attester_type, see EarAttesterResult Object |
EarAttesterResult Object:
| Field | Type | Required | Description |
|---|---|---|---|
| ear.status | string | Yes | Verification status: affirming/contarindicated/none |
| ear.trustworthiness-vector | list of object | No | Trustworthiness vector, see EarTrustworthinessVector Object |
| ear.appraisal-policy-id | string | No | Applied policy ID |
| ear.gta-annotated-evidence | object | No | GTA annotated evidence |
| mode | string | No | Challenge mode: host/device |
EarTrustworthinessVector Object:
| Field | Type | Required | Description |
|---|---|---|---|
| hardware | integer | No | Hardware trustworthiness |
| executables | integer | No | Executables trustworthiness |
3.3.2.4 Example of Request
3.3.2.4.1 Request Body
{
"agent_version": "0.1.0",
"measurements": [
{
"node_id": "TPM AK",
"nonce_type": "ignore",
"token_fmt": "eat",
"evidences": [
{
"attester_type": "tpm_boot",
"evidence": {
"ak_cert": "-----BEGIN CERTIFICATE-----\nxxxxx\n-----END CERTIFICATE-----",
"quote": {
"quote_data": "/1RDR4AYACIAC6dK2j3UWnqCmI9se9Itpmwo+GB2VAKRbS/VU2Iczqe1AAAAAAAAqTW9RAAAABsAAAAAASAZECMAFjY2AAAAAQALA/8AAAAg5o1U6DZkv/nir57+pL262PuxVPACzZgfDbc9i/cCaLc=",
"signature": "ABQACwEAB2a8RxbLV10KdV4rBaKvYZBxBrknL3E6flmOs1UCEz3U8v81RNWDxq5y7q301HsaF6HrP7TQWVq/5dX56RAgEtSxgiiKSIbR7S0SSaKMjHWKGHf+BeehZIaaxubl9rhlSVqBd+/K9rbHP3ADFJI8q1Ikg/6oAeYHsw1yZGinMocOF1+feMXBxri8YsEnX8a8/1tY8mAH34fhLf1OI8BjBnDmZG1kHQg930lJLcxB5uVNtEZd9Hcq/UMn9Hq+GQ6eVcpS4KgG9KwePnk96i/pjDTeDPk6VsZbYiXZPn9wQrAnwzDJX+7nTQj8QEOat49X7A57sAWHX9zRQV/mkVmvrw=="
},
"pcrs": {
"hash_alg": "sha256",
"pcr_values": [
{
"pcr_index": 0,
"pcr_value": "e21b703ee69c77476bccb43ec0336a9a1b2914b378944f7b00a10214ca8fea93"
},
{
"pcr_index": 1,
"pcr_value": "a32bf8bf329907dc2b4839ff3c61b456a9856d12110f49d490df33baf189340e"
},
{
"pcr_index": 2,
"pcr_value": "a9d5bdf3b0b034a434ef3adde2d5cb0a7533803f97f8889f1174ab60bd4dcb70"
},
{
"pcr_index": 3,
"pcr_value": "e21b703ee69c77476bccb43ec0336a9a1b2914b378944f7b00a10214ca8fea93"
},
{
"pcr_index": 4,
"pcr_value": "fce7f1083082b16cfe2b085dd7858bb11a37c09b78e36c79e5a2fd529353c4e2"
},
{
"pcr_index": 5,
"pcr_value": "8edde912699ceddddc7d9a3d7ee44a8b1b1910815692def6c9e637e2b939f941"
},
{
"pcr_index": 6,
"pcr_value": "e21b703ee69c77476bccb43ec0336a9a1b2914b378944f7b00a10214ca8fea93"
},
{
"pcr_index": 7,
"pcr_value": "e21b703ee69c77476bccb43ec0336a9a1b2914b378944f7b00a10214ca8fea93"
}
]
},
"logs": [
{
"log_type": "boot_log",
"log_data": "xxxxx"
}
]
}
}
]
}
]
}
3.3.2.4.2 response body
{
"service_version": "1.0",
"tokens": [
{
"node_id": "TPM AK",
"token": "xxxxxx"
}
]
}
3.4 Policy Management
3.4.1 Add Policy
Description: Add policy
Request Method: POST /global-trust-authority/service/v1/policy
Request Parameters
| Field | Type | Required | parameter constraint | Description |
|---|---|---|---|---|
| name | string | Yes | length 1~255 characters | Policy name |
| description | string | No | length not exceeding 512 characters | Policy description |
| attester_type | list of string | Yes | Each element character length 1~255 characters, supports: all/tpm/tpm_boot/tpm_ima/virt_cca/ascend_npu/itrustee/cca/dice | Applicable challenge plugin type, supports "all" type (applies to all challenge plugin types), see previous specification |
| content_type | string | Yes | jwt or text | jwt/text (corresponding to unsigned case) |
| content | string | Yes | Default maximum 500kb | Policy content, maximum 500KB before encoding, should not contain custom function definitions or loops with custom iterations |
| is_default | boolean | No | true or false | Whether it's default policy, defaults to false |
When content_type is jwt, jwt content:
| Field Location | Field | Type | Required | Description |
|---|---|---|---|---|
| header | alg | string | Yes | Token signature algorithm |
| header | kid | string | No | Public key ID |
| body | policy | string | Yes | Policy content |
The content requires Base64 encoding. For the original content, please refer to:https://gitcode.com/openeuler/global-trust-authority/blob/master/docs/en/Challenge_Request_Challenge_Response_Environment_Preparation.md#tpm_boot
Response Parameters
| Field | Sub-field | Type | Required | Description |
|---|---|---|---|---|
| message | string | Yes for failed request | Error message | |
| policy | object | Yes for successful request | Policy information | |
| id | string | Yes | Policy ID, UUID, 16byte, 36 characters with hyphen | |
| name | string | Yes | Policy name | |
| version | u32 | Yes | Policy version, created as 1, increments by 1 on update |
Example of request
request body
{
"name": "test_policy",
"description": "This is Test",
"attester_type": [
"tpm_ima"
],
"content": "cGFja2FnZSB2ZXJpZmljYXRpb24KCiMgRXh0cmFjdCBpc19sb2dfdmFsaWQgZnJvbSBmaXJzdCB0cG1faW1hIGxvZwppc19sb2dfdmFsaWQgPSB2YWxpZCB7CiAgICBzb21lIGkKICAgIGxvZ3MgOj0gaW5wdXQuZXZpZGVuY2UubG9ncwogICAgbG9nc1tpXS5sb2dfdHlwZSA9PSAiSW1hTG9nIgogICAgdmFsaWQgOj0gbG9nc1tpXS5pc19sb2dfdmFsaWQKfQoKIyBDaGVjayBpZiBwY3JzIDEwIGlzIHByZXNlbnQgaW4gYW55IGhhc2ggYWxnb3JpdGhtIChzaGExLCBzaGEyNTYsIHNoYTM4NCwgc2hhNTEyKQpwY3JfcHJlc2VudCB7CiAgICBhbGwgOj0ge3ggfCB4IDo9IFsxMF1bX10gfQogICAgbWVhc3VyZWQgOj0ge3Bjci5wY3JfaW5kZXggfCBwY3IgOj0gaW5wdXQuZXZpZGVuY2UucGNycy5wY3JfdmFsdWVzW19dfQogICAgYWxsX3BjcnNfc3Vic2V0IDo9IGFsbCAtIG1lYXN1cmVkCiAgICBjb3VudChhbGxfcGNyc19zdWJzZXQpID09IDAKfQoKIyBBdHRlc3RhdGlvbiB2YWxpZCBpZiBhbGwgY29uZGl0aW9ucyBtZXQKZGVmYXVsdCBhdHRlc3RhdGlvbl92YWxpZCA9IGZhbHNlCmF0dGVzdGF0aW9uX3ZhbGlkIHsKICAgIGlzX2xvZ192YWxpZCA9PSB0cnVlCiAgICBwY3JfcHJlc2VudAp9CgojIE91dHB1dCByZXN1bHQKcmVzdWx0ID0gewogICAgInBvbGljeV9tYXRjaGVkIjogYXR0ZXN0YXRpb25fdmFsaWQsCiAgICAiY3VzdG9tX2RhdGEiOiB7CiAgICAgICAgImhhc2hfYWxnIjogaW5wdXQuZXZpZGVuY2UucGNycy5oYXNoX2FsZwogICAgfQp9",
"content_type": "text",
"is_default": true
}
response body
{
"policy": {
"id": "349fb201-311d-4cd9-9ef5-a7b9f33a5ecf",
"name": "test_policy",
"version": 1
}
}
3.4.2 Update Policy
Description: Update policy
Request Method: PUT /global-trust-authority/service/v1/policy
Request Parameters
| Field | Type | Required | parameter constraint | Description |
|---|---|---|---|---|
| id | string | Yes | length 1~36 characters | Policy ID |
| name | string | No | length 1~255 characters | Policy name |
| description | string | No | length 0~512 characters | Policy description |
| attester_type | list of string | No | Each element character length 1~255 characters, supports: all/tpm/tpm_boot/tpm_ima/virt_cca/ascend_npu/itrustee/cca/dice | Applicable challenge plugin type, supports "all" type (applies to all challenge plugin types) |
| content_type | string | No | jwt or text | jwt/text (corresponding to unsigned case) |
| content | string | No | Default maximum 500kb | Policy content |
| is_default | boolean | No | true or false | Whether it's default policy, defaults to false |
Response Parameters
| Field | Sub-field | Type | Required | Description |
|---|---|---|---|---|
| message | string | Yes for failed request | Error message | |
| policy | object | Yes for successful request | Policy information | |
| id | string | Yes | Policy ID | |
| name | string | Yes | Policy name | |
| version | u32 | Yes | Policy version |
Example of request
request body
{
"id": "349fb201-311d-4cd9-9ef5-a7b9f33a5ecf",
"name": "Test",
"description": "123",
"content": "cGFja2FnZSBkaWdlc3RfdmVyaWZpY2F0aW9uCgppbXBvcnQgZnV0dXJlLmtleXdvcmRzLmlmCmltcG9ydCBmdXR1cmUua2V5d29yZHMuaW4KCiMgRGVmYXVsdCByZXN1bHQgaXMgcGFzcwpkZWZhdWx0IHJlc3VsdCA9IHsic3RhdHVzIjogInBhc3MifQoKIyBNYWluIHJ1bGUgdG8gZXZhbHVhdGUgdGhlIGlucHV0IGFnYWluc3QgYmFzZWxpbmUKcmVzdWx0ID0gb3V0cHV0IGlmIHsKICAgICMgR2V0IGlucHV0IGRhdGEKICAgIGlucHV0X2RhdGEgOj0gaW5wdXQKICAgIAogICAgIyBFeHRyYWN0IGFsbCBTSEEyNTYgZGlnZXN0cyBmcm9tIGV2ZW50cwogICAgZGlnZXN0cyA6PSBbZGlnZXN0IHwKICAgICAgICBldmVudCA6PSBpbnB1dF9kYXRhLmV2ZW50c1tfXQogICAgICAgIGRpZ2VzdF9vYmogOj0gZXZlbnQuRGlnZXN0c1tfXQogICAgICAgIGRpZ2VzdF9vYmouQWxnb3JpdGhtSWQgPT0gInNoYTI1NiIKICAgICAgICBkaWdlc3QgOj0gZGlnZXN0X29iai5EaWdlc3QKICAgIF0KICAgIAogICAgIyBGaW5kIG1pc3NpbmcgZGlnZXN0cyB1c2luZyB0aGUgUnVzdCBmdW5jdGlvbgogICAgIyBUaGlzIGZ1bmN0aW9uIG5vdyByZWFkcyB0aGUgYmFzZWxpbmUgZnJvbSBhIGZpbGUgZGlyZWN0bHkKICAgIG1pc3NpbmdfZGlnZXN0cyA6PSBmaW5kX21pc3NpbmdfZGlnZXN0cyhkaWdlc3RzKQogICAgCiAgICAjIENyZWF0ZSBtYXBwaW5nIG9mIG1pc3NpbmcgZGlnZXN0cyB0byBldmVudCBudW1iZXJzCiAgICBtaXNzaW5nX2V2ZW50cyA6PSB7ZGlnZXN0OiB7ImV2ZW50X251bWJlciI6IGV2ZW50LkV2ZW50TnVtfSB8CiAgICAgICAgZXZlbnQgOj0gaW5wdXRfZGF0YS5ldmVudHNbX10KICAgICAgICBkaWdlc3Rfb2JqIDo9IGV2ZW50LkRpZ2VzdHNbX10KICAgICAgICBkaWdlc3Rfb2JqLkFsZ29yaXRobUlkID09ICJzaGEyNTYiCiAgICAgICAgZGlnZXN0IDo9IGRpZ2VzdF9vYmouRGlnZXN0CiAgICAgICAgZGlnZXN0IGluIG9iamVjdC5rZXlzKG1pc3NpbmdfZGlnZXN0cykKICAgIH0KICAgIAogICAgIyBEZXRlcm1pbmUgaWYgYW55IGRpZ2VzdHMgYXJlIG1pc3NpbmcKICAgIGNvdW50KG9iamVjdC5rZXlzKG1pc3NpbmdfZGlnZXN0cykpID4gMAogICAgCiAgICAjIENyZWF0ZSBvdXRwdXQgd2l0aCBmYWlsdXJlIHN0YXR1cyBhbmQgbWlzc2luZyBkaWdlc3RzCiAgICBvdXRwdXQgOj0gewogICAgICAgICJzdGF0dXMiOiAiZmFpbCIsCiAgICAgICAgIm1pc3NpbmdfZGlnZXN0cyI6IG1pc3NpbmdfZXZlbnRzCiAgICB9Cn0=",
"content_type": "text"
}
response body
{
"policy": {
"id": "349fb201-311d-4cd9-9ef5-a7b9f33a5ecf",
"name": "test_policy",
"version": 2
}
}
3.4.3 Delete Policy
Description: Delete policy
Request Method: DELETE /global-trust-authority/service/v1/policy
Request Parameters
| Field | Type | Required | parameter constraint | Description |
|---|---|---|---|---|
| delete_type | string | Yes | "id", "attester_type", "all" | Delete type "id", "attester_type", "all" |
| ids | List of String | No | maximum 10 | Policy IDs, maximum 10 |
| attester_type | string | No | length 1~255 characters, supports: tpm/tpm_boot/tpm_ima/virt_cca/ascend_npu/itrustee/cca/dice | Policy type |
Response Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| message | string | Yes for failed request | Error message |
Example of request
request body
{
"delete_type": "attester_type",
"attester_type": "tpm_ima"
}
response body
{}
3.4.4 Query Policy
Description: Query policy
Request Method: GET /global-trust-authority/service/v1/policy
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| ids | List of String | No | Policy IDs maximum 10, error if exceeding maximum message limit |
| attester_type | string | No | Policy type, supports: tpm/tpm_boot/tpm_ima/virt_cca/ascend_npu/itrustee/cca/dice |
Response Parameters
| Field | Sub-field | Type | Required | Description |
|---|---|---|---|---|
| message | string | Yes for failed request | Error message | |
| policies | list of objects | Yes for successful request | Policy information | |
| id | string | Yes | Policy ID | |
| name | string | Yes | Policy name | |
| description | string | No | Policy description | |
| content | string | No | Policy content | |
| attester_type | list of string | No | Applicable challenge plugin type | |
| is_default | boolean | No | Whether it's default policy, defaults to false | |
| version | u64 | No | Policy version | |
| update_time | u64 | Yes | Update time | |
| valid_code | u8 | No | Signature verification result, 0-pass, 1-fail |
Note: When querying with ids, returns all fields of entries filtered by id; without ids, only returns required fields like id, name, version, etc., does not return specific content (entries filtered by type, if type not filled returns all for that user)
Example of request
request url
http(s)://ip:port/global-trust-authority/service/v1/policy?ids=2b0ead4b-6a15-4239-bf68-b1413df538bb
response body
{
"policies": [
{
"id": "2b0ead4b-6a15-4239-bf68-b1413df538bb",
"name": "test_policy3891702073167223",
"description": "This is Test",
"content": "cGFja2FnZSB2ZXJpZmljYXRpb24KCiMgRXh0cmFjdCBpc19sb2dfdmFsaWQgZnJvbSBmaXJzdCB0cG1faW1hIGxvZwppc19sb2dfdmFsaWQgPSB2YWxpZCB7CiAgICBzb21lIGkKICAgIGxvZ3MgOj0gaW5wdXQuZXZpZGVuY2UubG9ncwogICAgbG9nc1tpXS5sb2dfdHlwZSA9PSAiSW1hTG9nIgogICAgdmFsaWQgOj0gbG9nc1tpXS5pc19sb2dfdmFsaWQKfQoKIyBDaGVjayBpZiBwY3JzIDEwIGlzIHByZXNlbnQgaW4gYW55IGhhc2ggYWxnb3JpdGhtIChzaGExLCBzaGEyNTYsIHNoYTM4NCwgc2hhNTEyKQpwY3JfcHJlc2VudCB7CiAgICBhbGwgOj0ge3ggfCB4IDo9IFsxMF1bX10gfQogICAgbWVhc3VyZWQgOj0ge3Bjci5wY3JfaW5kZXggfCBwY3IgOj0gaW5wdXQuZXZpZGVuY2UucGNycy5wY3JfdmFsdWVzW19dfQogICAgYWxsX3BjcnNfc3Vic2V0IDo9IGFsbCAtIG1lYXN1cmVkCiAgICBjb3VudChhbGxfcGNyc19zdWJzZXQpID09IDAKfQoKIyBBdHRlc3RhdGlvbiB2YWxpZCBpZiBhbGwgY29uZGl0aW9ucyBtZXQKZGVmYXVsdCBhdHRlc3RhdGlvbl92YWxpZCA9IGZhbHNlCmF0dGVzdGF0aW9uX3ZhbGlkIHsKICAgIGlzX2xvZ192YWxpZCA9PSB0cnVlCiAgICBwY3JfcHJlc2VudAp9CgojIE91dHB1dCByZXN1bHQKcmVzdWx0ID0gewogICAgInBvbGljeV9tYXRjaGVkIjogYXR0ZXN0YXRpb25fdmFsaWQsCiAgICAiY3VzdG9tX2RhdGEiOiB7CiAgICAgICAgImhhc2hfYWxnIjogaW5wdXQuZXZpZGVuY2UucGNycy5oYXNoX2FsZwogICAgfQp9",
"attester_type": [
"tpm_ima"
],
"is_default": true,
"version": 1,
"update_time": 1747640682,
"valid_code": 0
}
]
}
3.5 Token Validation
3.5.1 Validate Token
Description: Validate Token
Request Method: POST /global-trust-authority/service/v1/token/verify
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| token | string | Yes | Token to be validated and parsed |
Response Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| message | string | Yes for failed request | Error message |
| verification_pass | boolean | Yes for successful request | Whether signature verification passed |
| token_body | object | No | Required when verification passes, returns parsed token body |
| token_header | object | No | Required when verification passes, returns parsed token header |
Example of request
request body
{
"token": "xxxxx"
}
response body
{
"verification_pass": true,
"token_body": {
"nonce_type": "ignore",
"intuse": "generic",
"attester_data": "custom_data",
"ueid": "a4e7c719-6b05-4ac6-b95a-7e71a9d6f9d5",
"virt_cca": {
"attestation_status": "unknown",
"vcca_ccel_log_status": "replay_success",
"vcca_cvm_token_hash_alg": "sha-256",
"vcca_firmware_state": {
"grub_cfg": "1aaeda68126809b20f88f6ed6fac2ec720ddf4ae4ea99b2d2ba6fafc18d79971",
"grub_image_list": [
"87276d2d4f3d17714e120d5b68694873880043e5abe7747fb4a47b5f6f38ca7a"
],
"initramfs": "fc7269847648cdab5323a4213a6d7b9a47512851beae8106a81b3e507e6dfc79",
"kernel": "e14bd37fd6d957b48d3ddde9be14c6d977f74127a6c6e4846c6b2a9f4fe48b41"
},
"vcca_ima_log_status": "replay_success",
"vcca_ima_ref_value_match_status": "matched",
"vcca_platform_token_config": "",
"vcca_platform_token_hash_algo": "sha-256",
"vcca_platform_token_implementation": "1213071ad6425b5bac0de45b6b1827b080476085162e32293ac947755250649e",
"vcca_platform_token_instance": "01e3e5e2548bcf2cf712fb005ee4c7fcbbd9394edde3597ea889b678878608248d",
"vcca_platform_token_lifecycle": 8192,
"vcca_platform_token_profile": "",
"vcca_platform_token_sw_components": [
{
"firware_name": "ipu",
"firware_version": "21.23.0",
"measurement": "abdfaad091595b7310aafc6d9762e793e4653eaf936988b75187a62b3dd01f3d"
},
{
"firware_name": "imu",
"firware_version": "21.23.0",
"measurement": "5034faa5b8bcc68c6dc5953b8c0f0cb552b23bd6d306bcd7909d65f03f303672"
},
{
"firware_name": "imf_ap",
"firware_version": "21.23.0",
"measurement": "f72d095e952acadd60a486a0a1d9c2ede8ee1a918d33682781e03631597b953b"
},
{
"firware_name": "tf_bl2",
"firware_version": "21.23.0",
"measurement": "f3f8a175e7eaca582ee886b60c98a708ab86bca361484630c73b4074fe6a884e"
},
{
"firware_name": "uefi",
"firware_version": "21.23.0",
"measurement": "498e3cb6773c59fdb498f268ebdb1fe0391ab7956dcc135e904b5fd202b0c3c9"
},
{
"firware_name": "tee",
"firware_version": "1.6",
"measurement": "f5a5fd42d16a20302798ef6ed309979b43003d2320d9f0e8ea9831a92759fb4b"
}
],
"vcca_platform_token_verification_service": "",
"vcca_rem0": "f5f0f64f4b3e3dd6e29e8613825b739e89912527996635f9e555d00c1ea91ad4",
"vcca_rem1": "646fdfc8b716bf958471a20378f178c472679216c911ddd0349cd74924eda7e9",
"vcca_rem2": "ed2ff313b2cb951cbab6f1e3ed4c8209e1541c20fbce614882df7748a6b7092b",
"vcca_rem3": "0000000000000000000000000000000000000000000000000000000000000000",
"vcca_rim": "ec7f23be62e51c8dc62e495d2d6e20df14d95d5284044223fb86cbaac1edb3a1",
"vcca_rpv": "00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
},
"iat": 1755672484,
"exp": 1756272484,
"iss": "iss",
"jti": "6d981d6b-7fae-479b-9fd5-ea6395f3b2ae",
"ver": "1.0",
"nbf": 1755672484,
"eat_profile": "eat_profile"
},
"token_header": {
"typ": "JWT",
"alg": "RS256",
"jku": "jku",
"kid": "kid"
}
}
3.6 register apikey
3.6.1 register apikey
Description:
- If both
User-IdandAPI-Keyare absent, the service generates a new credential set. - If
User-IdandAPI-Keyare provided, the service refreshes credentials after validation. API-Keyaccepts either a main key or a sub key:m.xxxx...refreshes both keys and salt, whiles.xxxx...refreshes only the sub key.
Request Method: GET /global-trust-authority/service/v1/register
Request Headers
| Field | Type | Required | Description |
|---|---|---|---|
| User-Id | string | No | User identifier. Required for credential refresh. |
| API-Key | string | No | Current API credential. m.-prefixed keys refresh both keys and salt; s.-prefixed keys refresh only the sub key. |
Response Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| User-Id | string | Yes | User identifier |
| Main-API-Key | string | Returned when a new main key is generated | |
| Sub-API-Key | string | Returned when a new sub key is generated |
Example of request
response body
{
"User-Id": "1d7f7ceb-edf2-443d-8c03-ceeb9d9ead85",
"Main-API-Key": "m.N7r6cL3dZPZHjGhNQo5XqGjzdfK43Hhx",
"Sub-API-Key": "s.HUmsAsUhNVR18qSxMTNDezyCRIUFGn5E"
}
For other protected interfaces, pass User-Id together with the required API credential in the request header.
If credential validation fails, the service returns 401 Unauthorized:
API credential validation failed
If the user is temporarily locked after repeated authentication failures, the service returns 429 Too Many Requests:
User is locked due to too many failed authentication attempts. Please retry after 30 seconds.
4. Key Manager API
4.1 Query key
Description: Query all the keys of the current key management component
Request Method: GET /v1/vault/get_signing_keys
Request Parameters
None
Response Parameters
| Field | Sub-field | Type | Required | Description |
|---|---|---|---|---|
| NSK | string | YES | key NSK | |
| private_key | string | Yes | key info | |
| algorithm | string | Yes | Private key algorithm | |
| encoding | string | Yes | Private key format | |
| version | string | Yes | Private key version | |
| PSK | string | YES | key PSK | |
| private_key | string | Yes | key info | |
| algorithm | string | Yes | Private key algorithm | |
| encoding | string | Yes | Private key format | |
| version | string | Yes | Private key version | |
| TSK | string | YES | key TSK | |
| private_key | string | Yes | key info | |
| algorithm | string | Yes | Private key algorithm | |
| encoding | string | Yes | Private key format | |
| version | string | Yes | Private key version |