Evidence API helps the diverse applications to access and process the trust states which was represented by integrity measurement, event record, report/quote in the confidential computing environment. Find more details in the wiki.
Evidence APIs aims to collect confidential evidence (i.e., measurement, event log, quote) for zero-trust design, supporting multiple deployment environments (firmware/VM/cloud native cluster). The APIs are designed to be vendor agnostic and TCG compliant APIs. The APIs will keep evolving on demand.
| API | Description | Parameters | Response |
|---|---|---|---|
| get_default_algorithms | Get the default Digest algorithms supported by trusted foundation. | A TcgAlgorithmRegistry object telling the default algorithms |
|
| get_measurement_count | Get the count of measurement register. | An integer telling the count of measurement registers | |
| get_cc_measurement | Get measurement register according to given selected index and algorithms. | imr_select ([int, int]): The first is index of measurement register, the second is the algorithms ID | An integer telling the count of measurement registers |
| get_cc_report | Get the quote for given nonce and data. | nonce: a number used to protect private communications by preventing replay attacks data: the data specified by user extraArgs: the placeholder for extra arguments required in vTPM or other TEE cases |
A CcReport (i.e. quote) object |
| get_cc_eventlog | Get eventlog for given index and count. | start: the index of the event log to start fetching count: the number of event logs to fetch |
A TcgEventLog object |
| replay_cc_eventlog | Replay event logs fetched through get_cc_eventlog api. |
event_logs: a list of event logs fetched using get_cc_eventlog api |
A dict listing the replay result containing information including IMR index number, algorithm using and replayed measurement |
It provides different SDKs for producing the confidential primitives in different deployment environments. Choose correct SDK according to your environment. Installation guide can be found at the readme of each implementation.
| SDK | Deployment Scenarios | Installation Guide |
|---|---|---|
| Firmware SDK | Firmware Application | |
| VM SDK | Confidential Virtual Machine | Guide |
| Container Integrity Measurement Agent (CIMA) | Confidential Cluster/Container | Guide |
This section contains the brief samples of APIs. You can find more examples at API usage example.
Below example code collects measurements from all integrity registers of the platform using API get_measurement_count, get_default_algorithms and get_cc_measurement using VMSDK in python.
from cctrusted import CCTrustedVmSdk
# Get total count of measurement registers, Intel® TDX is 4, vTPM is 24
count = CCTrustedVmSdk.inst().get_measurement_count()
for index in range(CCTrustedVmSdk.inst().get_measurement_count()):
# Get default digest algorithms, Intel® TDX is SHA384, vTPM is SHA256
alg = CCTrustedVmSdk.inst().get_default_algorithms()
# Get digest object for given index and given algorithms
digest_obj = CCTrustedVmSdk.inst().get_cc_measurement([index, alg.alg_id])
hash_str = ""
for hash_item in digest_obj.hash:
hash_str += "".join([f"{hash_item:02x}", " "])
LOG.info("Algorithms: %s", str(alg))
LOG.info("HASH: %s", hash_str)
Run cc_imr_cli.py to execute the sample.
$ git clone https://github.com/cc-api/cc-trusted-vmsdk.git
$ cd cc-trusted-vmsdk
$ sudo su
# source setupenv.sh
# cd src/python
# python3 cc_imr_cli.py
Below is the example output for get_cc_measurement API on Intel® TDX via VM SDK:
cctrusted.cvm DEBUG Successful open device node /dev/tdx_guest
cctrusted.cvm DEBUG Successful read TDREPORT from /dev/tdx_guest.
cctrusted.cvm DEBUG Successful parse TDREPORT.
cctrusted.cvm INFO ======================================
cctrusted.cvm INFO CVM type = TDX
cctrusted.cvm INFO CVM version = 1.5
cctrusted.cvm INFO ======================================
__main__ INFO Algorithms: TPM_ALG_SHA384
__main__ INFO HASH: c1 57 27 ca c1 f5 7d 0e 91 10 6d a1 80 b3 ea ba 72 11 66 61 e1 7b a0 55 37 73 84 3a 9b 07 2e cf a3 8c c8 03 df b5 5e 0f 87 ec 23 67 80 ad b3 a6
cctrusted.cvm INFO ======================================
cctrusted.cvm INFO CVM type = TDX
cctrusted.cvm INFO CVM version = 1.5
cctrusted.cvm INFO ======================================
__main__ INFO Algorithms: TPM_ALG_SHA384
__main__ INFO HASH: ee 35 46 2b 47 53 58 1b 4c 5a 53 8d c1 92 51 89 ba 9d 21 f5 19 7b 6b 15 ce 10 a6 00 fb d3 12 e0 e3 5c 2b 87 01 fc b2 17 51 82 43 3c 9b 12 b9 dc
cctrusted.cvm INFO ======================================
cctrusted.cvm INFO CVM type = TDX
cctrusted.cvm INFO CVM version = 1.5
cctrusted.cvm INFO ======================================
__main__ INFO Algorithms: TPM_ALG_SHA384
__main__ INFO HASH: 9a c0 ba 4e db 45 03 08 9a a4 a9 2a fe 97 cb 15 94 18 2f 44 aa e0 e5 8d 6f 90 a2 22 9c f9 a4 22 86 5d 87 35 d6 0b 87 3d 6b ec 36 41 d8 96 68 00
cctrusted.cvm INFO ======================================
cctrusted.cvm INFO CVM type = TDX
cctrusted.cvm INFO CVM version = 1.5
cctrusted.cvm INFO ======================================
__main__ INFO Algorithms: TPM_ALG_SHA384
__main__ INFO HASH: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
Below example code collect the CcReport (i.e. quote) on the platform using get_cc_report API using VMSDK implemented by python.
from cctrusted import CCTrustedVmSdk
# Specify the `nonce`, `data` and `extraArgs` as None in the example
quote = CCTrustedVmSdk.inst().get_cc_report(None, None, None)
if quote is not None:
# Dump CcReport (i.e. quote) object as raw data
quote.dump(is_raw=True)
Run cc_quote_cli.py to execute the sample.
$ git clone https://github.com/cc-api/cc-trusted-vmsdk.git
$ cd cc-trusted-vmsdk
$ sudo su
# source setupenv.sh
# cd src/python
# python3 cc_quote_cli.py
Below is the example output for get_cc_report API on Intel® TDX via VM SDK:
root@tdx-guest:/home/tdx/cc-trusted-vmsdk/src/python# python3 ./cc_quote_cli.py
cctrusted.cvm DEBUG Successful open device node /dev/tdx_guest
cctrusted.cvm DEBUG Successful read TDREPORT from /dev/tdx_guest.
cctrusted.cvm DEBUG Successful parse TDREPORT.
cctrusted.cvm INFO Using report data directly to generate quote
cctrusted.cvm DEBUG Successful open device node /dev/tdx_guest
cctrusted.cvm DEBUG Successful get Quote from /dev/tdx_guest.
evidence_api.tdx.quote INFO ======================================
evidence_api.tdx.quote INFO TD Quote
evidence_api.tdx.quote INFO ======================================
evidence_api.tdx.quote INFO TD Quote Header:
evidence_api.binaryblob INFO 00000000 04 00 02 00 81 00 00 00 00 00 00 00 93 9A 72 33 ..............r3
evidence_api.binaryblob INFO 00000010 F7 9C 4C A9 94 0A 0D B3 95 7F 06 07 C6 0E 85 25 ..L............%
evidence_api.binaryblob INFO 00000020 C8 09 3C 0E A0 64 EF F1 29 6B 85 83 00 00 00 00 ..<..d..)k......
evidence_api.tdx.quote INFO TD Quote Body:
evidence_api.binaryblob INFO 00000000 04 01 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
evidence_api.binaryblob INFO 00000010 97 90 D8 9A 10 21 0E C6 96 8A 77 3C EE 2C A0 5B .....!....w<.,.[
evidence_api.binaryblob INFO 00000020 5A A9 73 09 F3 67 27 A9 68 52 7B E4 60 6F C1 9E Z.s..g'.hR{.`o..
...
evidence_api.binaryblob INFO 00000230 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
evidence_api.binaryblob INFO 00000240 00 00 00 00 00 00 00 00 ........
evidence_api.tdx.quote INFO TD Quote Signature:
evidence_api.binaryblob INFO 00000000 16 1F E4 F6 8C 05 D4 8F E2 EB EB C8 32 1A CE 6C ............2..l
evidence_api.binaryblob INFO 00000010 90 2A B5 EA 74 F5 4C 4D A2 6A 30 AC 5C A5 13 84 .*..t.LM.j0.\...
evidence_api.binaryblob INFO 00000020 3D CB A2 31 20 43 8C 38 63 3D EE D1 7F B4 9F B5 =..1 C.8c=......
...
evidence_api.binaryblob INFO 000010D0 44 20 43 45 52 54 49 46 49 43 41 54 45 2D 2D 2D D CERTIFICATE---
evidence_api.binaryblob INFO 000010E0 2D 2D 0A 00 --..
Below example code collects all boot time event logs on the platform using API get_cc_eventlog implemented in VMSDK in python. Sample Event logs collected within container using CCNP API can be found here.
from cctrusted import CCTrustedVmSdk
# Specify the index of event log to start fetching(optional argument, default as 0)
start = 0
# Specify the number of event logs to be fetched.(optional argument, default as total number of event logs available)
count = 5
event_logs = CCTrustedVmSdk.inst().get_cc_eventlog(start, count)
if event_logs is not None:
LOG.info("Total %d of event logs fetched.", len(event_logs))
# Dump event as formatted
for event in event_logs:
event_logs.dump()
Run cc_event_log_cli.py to execute the sample.
$ git clone https://github.com/cc-api/cc-trusted-vmsdk.git
$ cd cc-trusted-vmsdk
$ sudo su
# source setupenv.sh
# cd src/python
# python3 cc_event_log_cli.py [-s <start_index_of_event_log>] [-c <count_of_event_logs>]
Below is the description of the output of get_cc_eventlog API on Intel® TDX via VM SDK. Full event logs can be found in API usage example.
Lu Ken |
Ying Ruoyu |
Shi Zhongjie |
Hairongchen |
Wenhui Zhang |
Ruomeng Hao |
Xiaocheng Dong |
Jiewen Yao |
Le Yao |