Subject: [PATCH v13 3/3] Documentation/x86: Document TDX attestation process

Document details about TDX attestation process and related user API
support.

Attestation details can be found in Guest-Host-Communication Interface
(GHCI) for Intel Trust Domain Extensions (TDX), section titled "TD
attestation".

[Bagas Sanjaya fixed htmldocs warning]
Reviewed-by: Bagas Sanjaya <[email protected]>
Signed-off-by: Kuppuswamy Sathyanarayanan <[email protected]>
---

Change since v12:
* None

Changes since v11:
* Fixed htmldocs warnings.

Documentation/x86/tdx.rst | 75 +++++++++++++++++++++++++++++++++++++++
1 file changed, 75 insertions(+)

diff --git a/Documentation/x86/tdx.rst b/Documentation/x86/tdx.rst
index b8fa4329e1a5..c9e3ecf86e0b 100644
--- a/Documentation/x86/tdx.rst
+++ b/Documentation/x86/tdx.rst
@@ -210,6 +210,81 @@ converted to shared on boot.
For coherent DMA allocation, the DMA buffer gets converted on the
allocation. Check force_dma_unencrypted() for details.

+Attestation
+===========
+
+Attestation is used to verify the TDX guest trustworthiness to other
+entities before provisioning secrets to the guest. For example, a key
+server may request for attestation before releasing the encryption keys
+to mount the encrypted rootfs or secondary drive.
+
+TDX module records the state of the TDX guest in various stages of guest
+boot process using build time measurement register (MRTD) and runtime
+measurement registers (RTMR). Measurements related to guest initial
+configuration and firmware image is recorded in the MRTD register.
+Measurements related to initial state, kernel image, firmware image,
+command line options, initrd, ACPI tables, etc are recorded in RTMR
+registers. For more details, please refer to TDX Virtual Firmware design
+specification, sec titled "TD Measurement".
+
+At TDX guest runtime, the Intel TDX module reuses the Intel SGX attestation
+infrastructure to provide support for attesting to these measurements as
+described below.
+
+The attestation process consists of two steps: TDREPORT generation and
+Quote generation.
+
+TDX guest uses TDCALL[TDG.MR.REPORT] to get the TDREPORT (TDREPORT_STRUCT)
+from the TDX module. TDREPORT is a fixed-size data structure generated by
+the TDX module which contains guest-specific information (such as build
+and boot measurements), platform security version, and the MAC to protect
+the integrity of the TDREPORT.
+
+After getting the TDREPORT, the second step of the attestation process
+is to send it to the QE to generate the Quote. TDREPORT by design can only
+be verified on local platform as the MAC key is bound to the platform. To
+support remote verification of the TDREPORT, TDX leverages Intel SGX Quote
+Enclave (QE) to verify the TDREPORT locally and convert it to a remote
+verifiable Quote. Method of sending TDREPORT to QE is implemenentation
+specific. Attestation software can choose whatever communication channel
+available (i.e. vsock or hypercall) to send the TDREPORT to QE and receive
+the Quote.
+
+To allow userspace attestation agent get the TDREPORT, TDX guest driver
+exposes an IOCTL (TDX_CMD_GET_REPORT) interface via /dev/tdx-guest misc
+device.
+
+TDX Guest driver
+================
+
+The TDX guest driver exposes IOCTL interfaces via /dev/tdx-guest misc
+device to allow user space to get certain TDX guest specific details
+(like attestation report, attestation quote or storage keys, etc).
+
+In this section, for each supported IOCTL, following information is
+provided along with generic description.
+
+:Input parameters: Parameters passed to the IOCTL and related details.
+:Output: Details about output data and return value (with details
+ about the non common error values).
+
+TDX_CMD_GET_REPORT
+------------------
+
+:Input parameters: struct tdx_report_req
+:Output: Upon successful execution, TDREPORT data is copied to
+ tdx_report_req.tdreport and returns 0 or returns
+ -EIO on TDCALL failure and standard error number on
+ other common failures.
+
+The TDX_CMD_GET_REPORT IOCTL can be used by the attestation software to
+get the TDX guest measurements data (with few other info) in the format
+of TDREPORT_STRUCT. It uses TDCALL[TDG.MR.REPORT] to get the TDREPORT
+from the TDX Module.
+
+Format of TDREPORT_STRUCT can be found in TDX 1.0 Module specification,
+sec titled "TDREPORT_STRUCT".
+
References
==========

--
2.34.1


2022-09-12 07:17:28

by Kai Huang

[permalink] [raw]
Subject: Re: [PATCH v13 3/3] Documentation/x86: Document TDX attestation process


> +
> +At TDX guest runtime, the Intel TDX module reuses the Intel SGX attestation
> +infrastructure to provide support for attesting to these measurements as
> +described below.

The above paragraph isn't right. The Intel TDX module itself doesn't use
anything about SGX (perhaps except using the key to generate the MAC for the
TDREPORT, but it certainly doesn't use "SGX infrastructure" for sure). Even the
new ENCLU leaf used to verify the TDREPORT is not part of the TDX module -- it's
an extension to SGX to support TDX attestation.

Also, conceptually, only the verification service can truly _attest_ something.
The SGX software stack running on the machine that hosts TDX guests doesn't
actually _attest_ anything. It only can _generate_ something (Quote) that can
be attested.

In below you already mentioned "TDX leverages Intel SGX Quote (should be Quoting
I think) Enclave to ...". I don't think this paragraph is even necessary and
you can just delete it.

If you really want to say, I think one simple sentence like "TDX leverages SGX
to support attestation" is enough.

> +
> +The attestation process consists of two steps: TDREPORT generation and
> +Quote generation.
> +
> +TDX guest uses TDCALL[TDG.MR.REPORT] to get the TDREPORT (TDREPORT_STRUCT)
> +from the TDX module. TDREPORT is a fixed-size data structure generated by
> +the TDX module which contains guest-specific information (such as build
> +and boot measurements), platform security version, and the MAC to protect
> +the integrity of the TDREPORT.
> +
> +After getting the TDREPORT, the second step of the attestation process
> +is to send it to the QE to generate the Quote. TDREPORT by design can only
> +be verified on local platform as the MAC key is bound to the platform. To
> +support remote verification of the TDREPORT, TDX leverages Intel SGX Quote
> +Enclave (QE) to verify the TDREPORT locally and convert it to a remote
> +verifiable Quote. Method of sending TDREPORT to QE is implemenentation
> +specific. Attestation software can choose whatever communication channel
> +available (i.e. vsock or hypercall) to send the TDREPORT to QE and receive
> +the Quote.
> +
> +To allow userspace attestation agent get the TDREPORT, TDX guest driver

^
to get

> +exposes an IOCTL (TDX_CMD_GET_REPORT) interface via /dev/tdx-guest misc
> +device.
> +
> +TDX Guest driver
> +================
> +
> +The TDX guest driver exposes IOCTL interfaces via /dev/tdx-guest misc
> +device to allow user space to get certain TDX guest specific details
> +(like attestation report, attestation quote or storage keys, etc).

Only TDX_CMD_GET_REPORT is supported now. Whether GetQuote TDVMCALL should be
supported, or how should it be supported is unknown now. Not to mention "get
the storage keys".

I don't think you should put anything here now except "allow userspace to get
TDREPORT".

> +
> +In this section, for each supported IOCTL, following information is
> +provided along with generic description.
> +
> +:Input parameters: Parameters passed to the IOCTL and related details.
> +:Output: Details about output data and return value (with details
> + about the non common error values).
> +
> +TDX_CMD_GET_REPORT
> +------------------
> +
> +:Input parameters: struct tdx_report_req
> +:Output: Upon successful execution, TDREPORT data is copied to
> + tdx_report_req.tdreport and returns 0 or returns
> + -EIO on TDCALL failure and standard error number on
> + other common failures.
> +
> +The TDX_CMD_GET_REPORT IOCTL can be used by the attestation software to
> +get the TDX guest measurements data (with few other info) in the format
> +of TDREPORT_STRUCT. 
>

IMHO "to get the TDREPORT" is enough. You already used TDREPORT in many places
in this documentation (and in this series), and you have already explained it.

With above (at least errors) fixed:

Acked-by: Kai Huang <[email protected]>


--
Thanks,
-Kai


Subject: Re: [PATCH v13 3/3] Documentation/x86: Document TDX attestation process



On 9/12/22 12:04 AM, Huang, Kai wrote:
>> +
>> +TDX Guest driver
>> +================
>> +
>> +The TDX guest driver exposes IOCTL interfaces via /dev/tdx-guest misc
>> +device to allow user space to get certain TDX guest specific details
>> +(like attestation report, attestation quote or storage keys, etc).
> Only TDX_CMD_GET_REPORT is supported now. Whether GetQuote TDVMCALL should be
> supported, or how should it be supported is unknown now. Not to mention "get
> the storage keys".

The reason for adding them is to give an idea that this driver in future could
be used for use cases other than GetReport. Query about possible use cases came up
in a previous review about /dev/tdx-guest device name usage. So I thought it is
better to give a clear idea on how this device may be used in the future.

Maybe I can add a note that currently only attestation report is supported.

>
> I don't think you should put anything here now except "allow userspace to get
> TDREPORT".
>

--
Sathyanarayanan Kuppuswamy
Linux Kernel Developer

2022-09-12 21:21:08

by Kai Huang

[permalink] [raw]
Subject: Re: [PATCH v13 3/3] Documentation/x86: Document TDX attestation process

On Mon, 2022-09-12 at 07:15 -0700, Sathyanarayanan Kuppuswamy wrote:
>
> On 9/12/22 12:04 AM, Huang, Kai wrote:
> > > +
> > > +TDX Guest driver
> > > +================
> > > +
> > > +The TDX guest driver exposes IOCTL interfaces via /dev/tdx-guest misc
> > > +device to allow user space to get certain TDX guest specific details
> > > +(like attestation report, attestation quote or storage keys, etc).
> > Only TDX_CMD_GET_REPORT is supported now. Whether GetQuote TDVMCALL should be
> > supported, or how should it be supported is unknown now. Not to mention "get
> > the storage keys".
>
> The reason for adding them is to give an idea that this driver in future could
> be used for use cases other than GetReport. Query about possible use cases came up
> in a previous review about /dev/tdx-guest device name usage. So I thought it is
> better to give a clear idea on how this device may be used in the future.

But I don't think "attestation quote or storage keys" are good example, as it's
uncertain, i.e. can be wrong to put here.

>
> Maybe I can add a note that currently only attestation report is supported.

Maybe something like this?

"
The TDX guest exposes /dev/tdx-guest to userspace to support all TDX guest
specific operations in one driver. Currently only TDX_CMD_GET_RERPORT IOCTL is
supported to return the TDREPORT to userspace to support attestation for the TDX
guest.
"

--
Thanks,
-Kai


Subject: Re: [PATCH v13 3/3] Documentation/x86: Document TDX attestation process



On 9/13/22 10:54 AM, Kirill A . Shutemov wrote:
> On Fri, Sep 09, 2022 at 12:27:08PM -0700, Kuppuswamy Sathyanarayanan wrote:
>> Document details about TDX attestation process and related user API
>> support.
>
> "related user API support" sounds wrong to me.
>
> Maybe just "related userspace API"?

Ok

>
>> Attestation details can be found in Guest-Host-Communication Interface
>> (GHCI) for Intel Trust Domain Extensions (TDX), section titled "TD
>> attestation".
>>
>> [Bagas Sanjaya fixed htmldocs warning]
>> Reviewed-by: Bagas Sanjaya <[email protected]>
>> Signed-off-by: Kuppuswamy Sathyanarayanan <[email protected]>
>> ---
>>
>> Change since v12:
>> * None
>>
>> Changes since v11:
>> * Fixed htmldocs warnings.
>>
>> Documentation/x86/tdx.rst | 75 +++++++++++++++++++++++++++++++++++++++
>> 1 file changed, 75 insertions(+)
>>
>> diff --git a/Documentation/x86/tdx.rst b/Documentation/x86/tdx.rst
>> index b8fa4329e1a5..c9e3ecf86e0b 100644
>> --- a/Documentation/x86/tdx.rst
>> +++ b/Documentation/x86/tdx.rst
>> @@ -210,6 +210,81 @@ converted to shared on boot.
>> For coherent DMA allocation, the DMA buffer gets converted on the
>> allocation. Check force_dma_unencrypted() for details.
>>
>> +Attestation
>> +===========
>> +
>> +Attestation is used to verify the TDX guest trustworthiness to other
>> +entities before provisioning secrets to the guest. For example, a key
>> +server may request for attestation before releasing the encryption keys
>> +to mount the encrypted rootfs or secondary drive.
>
> Maybe "may request attestation quote before ..."?
>
>> +TDX module records the state of the TDX guest in various stages of guest
>> +boot process using build time measurement register (MRTD) and runtime
>> +measurement registers (RTMR). Measurements related to guest initial
>> +configuration and firmware image is recorded in the MRTD register.
>> +Measurements related to initial state, kernel image, firmware image,
>> +command line options, initrd, ACPI tables, etc are recorded in RTMR
>> +registers. For more details, please refer to TDX Virtual Firmware design
>> +specification, sec titled "TD Measurement".
>> +
>> +At TDX guest runtime, the Intel TDX module reuses the Intel SGX attestation
>> +infrastructure to provide support for attesting to these measurements as
>> +described below.
>> +
>> +The attestation process consists of two steps: TDREPORT generation and
>> +Quote generation.
>> +
>> +TDX guest uses TDCALL[TDG.MR.REPORT] to get the TDREPORT (TDREPORT_STRUCT)
>> +from the TDX module. TDREPORT is a fixed-size data structure generated by
>> +the TDX module which contains guest-specific information (such as build
>> +and boot measurements), platform security version, and the MAC to protect
>> +the integrity of the TDREPORT.
>> +
>> +After getting the TDREPORT, the second step of the attestation process
>> +is to send it to the QE to generate the Quote. TDREPORT by design can only
>
> The first use of QE abbreviation is before it is defined. -EPARSE.

Yes. I already noticed it and fixed it.

>
>> +be verified on local platform as the MAC key is bound to the platform. To
>> +support remote verification of the TDREPORT, TDX leverages Intel SGX Quote
>> +Enclave (QE) to verify the TDREPORT locally and convert it to a remote
>> +verifiable Quote. Method of sending TDREPORT to QE is implemenentation
>> +specific. Attestation software can choose whatever communication channel
>> +available (i.e. vsock or hypercall) to send the TDREPORT to QE and receive
>> +the Quote.
>> +
>> +To allow userspace attestation agent get the TDREPORT, TDX guest driver
>> +exposes an IOCTL (TDX_CMD_GET_REPORT) interface via /dev/tdx-guest misc
>> +device.
>> +
>> +TDX Guest driver
>> +================
>> +
>> +The TDX guest driver exposes IOCTL interfaces via /dev/tdx-guest misc
>> +device to allow user space to get certain TDX guest specific details
>> +(like attestation report, attestation quote or storage keys, etc).
>> +
>> +In this section, for each supported IOCTL, following information is
>> +provided along with generic description.
>
> "for each" looks strange as we only have single IOCTL.

I just want to give an overview of IOCTL documentation. Although we have
only one IOCTL now, we have plans to extend it in near future. At least
VERIFYEREPORT IOCTL will be added soon. Do you think I should still
fix it? How about the following?

In this section, in addition to generic information of IOCTL, following
details are provided.

>
>> +:Input parameters: Parameters passed to the IOCTL and related details.
>> +:Output: Details about output data and return value (with details
>> + about the non common error values).
>> +
>> +TDX_CMD_GET_REPORT
>> +------------------
>> +
>> +:Input parameters: struct tdx_report_req
>> +:Output: Upon successful execution, TDREPORT data is copied to
>> + tdx_report_req.tdreport and returns 0 or returns
>> + -EIO on TDCALL failure and standard error number on
>> + other common failures.
>> +
>> +The TDX_CMD_GET_REPORT IOCTL can be used by the attestation software to
>> +get the TDX guest measurements data (with few other info) in the format
>> +of TDREPORT_STRUCT. It uses TDCALL[TDG.MR.REPORT] to get the TDREPORT
>> +from the TDX Module.
>> +
>> +Format of TDREPORT_STRUCT can be found in TDX 1.0 Module specification,
>> +sec titled "TDREPORT_STRUCT".
>> +
>

--
Sathyanarayanan Kuppuswamy
Linux Kernel Developer

2022-09-13 19:04:26

by Kirill A. Shutemov

[permalink] [raw]
Subject: Re: [PATCH v13 3/3] Documentation/x86: Document TDX attestation process

On Fri, Sep 09, 2022 at 12:27:08PM -0700, Kuppuswamy Sathyanarayanan wrote:
> Document details about TDX attestation process and related user API
> support.

"related user API support" sounds wrong to me.

Maybe just "related userspace API"?

> Attestation details can be found in Guest-Host-Communication Interface
> (GHCI) for Intel Trust Domain Extensions (TDX), section titled "TD
> attestation".
>
> [Bagas Sanjaya fixed htmldocs warning]
> Reviewed-by: Bagas Sanjaya <[email protected]>
> Signed-off-by: Kuppuswamy Sathyanarayanan <[email protected]>
> ---
>
> Change since v12:
> * None
>
> Changes since v11:
> * Fixed htmldocs warnings.
>
> Documentation/x86/tdx.rst | 75 +++++++++++++++++++++++++++++++++++++++
> 1 file changed, 75 insertions(+)
>
> diff --git a/Documentation/x86/tdx.rst b/Documentation/x86/tdx.rst
> index b8fa4329e1a5..c9e3ecf86e0b 100644
> --- a/Documentation/x86/tdx.rst
> +++ b/Documentation/x86/tdx.rst
> @@ -210,6 +210,81 @@ converted to shared on boot.
> For coherent DMA allocation, the DMA buffer gets converted on the
> allocation. Check force_dma_unencrypted() for details.
>
> +Attestation
> +===========
> +
> +Attestation is used to verify the TDX guest trustworthiness to other
> +entities before provisioning secrets to the guest. For example, a key
> +server may request for attestation before releasing the encryption keys
> +to mount the encrypted rootfs or secondary drive.

Maybe "may request attestation quote before ..."?

> +TDX module records the state of the TDX guest in various stages of guest
> +boot process using build time measurement register (MRTD) and runtime
> +measurement registers (RTMR). Measurements related to guest initial
> +configuration and firmware image is recorded in the MRTD register.
> +Measurements related to initial state, kernel image, firmware image,
> +command line options, initrd, ACPI tables, etc are recorded in RTMR
> +registers. For more details, please refer to TDX Virtual Firmware design
> +specification, sec titled "TD Measurement".
> +
> +At TDX guest runtime, the Intel TDX module reuses the Intel SGX attestation
> +infrastructure to provide support for attesting to these measurements as
> +described below.
> +
> +The attestation process consists of two steps: TDREPORT generation and
> +Quote generation.
> +
> +TDX guest uses TDCALL[TDG.MR.REPORT] to get the TDREPORT (TDREPORT_STRUCT)
> +from the TDX module. TDREPORT is a fixed-size data structure generated by
> +the TDX module which contains guest-specific information (such as build
> +and boot measurements), platform security version, and the MAC to protect
> +the integrity of the TDREPORT.
> +
> +After getting the TDREPORT, the second step of the attestation process
> +is to send it to the QE to generate the Quote. TDREPORT by design can only

The first use of QE abbreviation is before it is defined. -EPARSE.

> +be verified on local platform as the MAC key is bound to the platform. To
> +support remote verification of the TDREPORT, TDX leverages Intel SGX Quote
> +Enclave (QE) to verify the TDREPORT locally and convert it to a remote
> +verifiable Quote. Method of sending TDREPORT to QE is implemenentation
> +specific. Attestation software can choose whatever communication channel
> +available (i.e. vsock or hypercall) to send the TDREPORT to QE and receive
> +the Quote.
> +
> +To allow userspace attestation agent get the TDREPORT, TDX guest driver
> +exposes an IOCTL (TDX_CMD_GET_REPORT) interface via /dev/tdx-guest misc
> +device.
> +
> +TDX Guest driver
> +================
> +
> +The TDX guest driver exposes IOCTL interfaces via /dev/tdx-guest misc
> +device to allow user space to get certain TDX guest specific details
> +(like attestation report, attestation quote or storage keys, etc).
> +
> +In this section, for each supported IOCTL, following information is
> +provided along with generic description.

"for each" looks strange as we only have single IOCTL.

> +:Input parameters: Parameters passed to the IOCTL and related details.
> +:Output: Details about output data and return value (with details
> + about the non common error values).
> +
> +TDX_CMD_GET_REPORT
> +------------------
> +
> +:Input parameters: struct tdx_report_req
> +:Output: Upon successful execution, TDREPORT data is copied to
> + tdx_report_req.tdreport and returns 0 or returns
> + -EIO on TDCALL failure and standard error number on
> + other common failures.
> +
> +The TDX_CMD_GET_REPORT IOCTL can be used by the attestation software to
> +get the TDX guest measurements data (with few other info) in the format
> +of TDREPORT_STRUCT. It uses TDCALL[TDG.MR.REPORT] to get the TDREPORT
> +from the TDX Module.
> +
> +Format of TDREPORT_STRUCT can be found in TDX 1.0 Module specification,
> +sec titled "TDREPORT_STRUCT".
> +

--
Kiryl Shutsemau / Kirill A. Shutemov

Subject: Re: [PATCH v13 3/3] Documentation/x86: Document TDX attestation process

Hi Kirill/Kai,

On 9/13/22 10:54 AM, Kirill A . Shutemov wrote:
> On Fri, Sep 09, 2022 at 12:27:08PM -0700, Kuppuswamy Sathyanarayanan wrote:
>> Document details about TDX attestation process and related user API
>> support.
>
> "related user API support" sounds wrong to me.
>
> Maybe just "related userspace API"?
>
>> Attestation details can be found in Guest-Host-Communication Interface
>> (GHCI) for Intel Trust Domain Extensions (TDX), section titled "TD
>> attestation".
>>
>> [Bagas Sanjaya fixed htmldocs warning]
>> Reviewed-by: Bagas Sanjaya <[email protected]>
>> Signed-off-by: Kuppuswamy Sathyanarayanan <[email protected]>
>> ---
>>
>> Change since v12:
>> * None
>>
>> Changes since v11:
>> * Fixed htmldocs warnings.
>>
>> Documentation/x86/tdx.rst | 75 +++++++++++++++++++++++++++++++++++++++
>> 1 file changed, 75 insertions(+)
>>
>> diff --git a/Documentation/x86/tdx.rst b/Documentation/x86/tdx.rst
>> index b8fa4329e1a5..c9e3ecf86e0b 100644
>> --- a/Documentation/x86/tdx.rst
>> +++ b/Documentation/x86/tdx.rst
>> @@ -210,6 +210,81 @@ converted to shared on boot.
>> For coherent DMA allocation, the DMA buffer gets converted on the
>> allocation. Check force_dma_unencrypted() for details.
>>
>> +Attestation
>> +===========
>> +
>> +Attestation is used to verify the TDX guest trustworthiness to other
>> +entities before provisioning secrets to the guest. For example, a key
>> +server may request for attestation before releasing the encryption keys
>> +to mount the encrypted rootfs or secondary drive.
>
> Maybe "may request attestation quote before ..."?
>
>> +TDX module records the state of the TDX guest in various stages of guest
>> +boot process using build time measurement register (MRTD) and runtime
>> +measurement registers (RTMR). Measurements related to guest initial
>> +configuration and firmware image is recorded in the MRTD register.
>> +Measurements related to initial state, kernel image, firmware image,
>> +command line options, initrd, ACPI tables, etc are recorded in RTMR
>> +registers. For more details, please refer to TDX Virtual Firmware design
>> +specification, sec titled "TD Measurement".
>> +
>> +At TDX guest runtime, the Intel TDX module reuses the Intel SGX attestation
>> +infrastructure to provide support for attesting to these measurements as
>> +described below.
>> +
>> +The attestation process consists of two steps: TDREPORT generation and
>> +Quote generation.
>> +
>> +TDX guest uses TDCALL[TDG.MR.REPORT] to get the TDREPORT (TDREPORT_STRUCT)
>> +from the TDX module. TDREPORT is a fixed-size data structure generated by
>> +the TDX module which contains guest-specific information (such as build
>> +and boot measurements), platform security version, and the MAC to protect
>> +the integrity of the TDREPORT.
>> +
>> +After getting the TDREPORT, the second step of the attestation process
>> +is to send it to the QE to generate the Quote. TDREPORT by design can only
>
> The first use of QE abbreviation is before it is defined. -EPARSE.
>
>> +be verified on local platform as the MAC key is bound to the platform. To
>> +support remote verification of the TDREPORT, TDX leverages Intel SGX Quote
>> +Enclave (QE) to verify the TDREPORT locally and convert it to a remote
>> +verifiable Quote. Method of sending TDREPORT to QE is implemenentation
>> +specific. Attestation software can choose whatever communication channel
>> +available (i.e. vsock or hypercall) to send the TDREPORT to QE and receive
>> +the Quote.
>> +
>> +To allow userspace attestation agent get the TDREPORT, TDX guest driver
>> +exposes an IOCTL (TDX_CMD_GET_REPORT) interface via /dev/tdx-guest misc
>> +device.
>> +
>> +TDX Guest driver
>> +================
>> +
>> +The TDX guest driver exposes IOCTL interfaces via /dev/tdx-guest misc
>> +device to allow user space to get certain TDX guest specific details
>> +(like attestation report, attestation quote or storage keys, etc).
>> +
>> +In this section, for each supported IOCTL, following information is
>> +provided along with generic description.
>
> "for each" looks strange as we only have single IOCTL.
>
>> +:Input parameters: Parameters passed to the IOCTL and related details.
>> +:Output: Details about output data and return value (with details
>> + about the non common error values).
>> +
>> +TDX_CMD_GET_REPORT
>> +------------------
>> +
>> +:Input parameters: struct tdx_report_req
>> +:Output: Upon successful execution, TDREPORT data is copied to
>> + tdx_report_req.tdreport and returns 0 or returns
>> + -EIO on TDCALL failure and standard error number on
>> + other common failures.
>> +
>> +The TDX_CMD_GET_REPORT IOCTL can be used by the attestation software to
>> +get the TDX guest measurements data (with few other info) in the format
>> +of TDREPORT_STRUCT. It uses TDCALL[TDG.MR.REPORT] to get the TDREPORT
>> +from the TDX Module.
>> +
>> +Format of TDREPORT_STRUCT can be found in TDX 1.0 Module specification,
>> +sec titled "TDREPORT_STRUCT".
>> +
>

After addressing the comments, the final version looks like below.



Attestation

===========



Attestation is used to verify the TDX guest trustworthiness to other

entities before provisioning secrets to the guest. For example, a key

server may request attestation quote before releasing the encryption

keys to mount the encrypted rootfs or secondary drive.



The TDX module records the state of the TDX guest in various stages of

the guest boot process using build time measurement register (MRTD) and

runtime measurement registers (RTMR). Measurements related to guest

initial configuration and firmware image are recorded in the MRTD

register. Measurements related to initial state, kernel image, firmware

image, command line options, initrd, ACPI tables, etc are recorded in

RTMR registers. For more details, please refer to TDX Virtual Firmware

design specification, sec titled "TD Measurement". At TDX guest runtime,

the attestation process is used to attest to these measurements.



The attestation process consists of two steps: TDREPORT generation and

Quote generation.



TDX guest uses TDCALL[TDG.MR.REPORT] to get the TDREPORT (TDREPORT_STRUCT)

from the TDX module. TDREPORT is a fixed-size data structure generated by

the TDX module which contains guest-specific information (such as build

and boot measurements), platform security version, and the MAC to protect

the integrity of the TDREPORT.



After getting the TDREPORT, the second step of the attestation process

is to send it to the Quoting Enclave (QE) to generate the Quote. TDREPORT

by design can only be verified on the local platform as the MAC key is

bound to the platform. To support remote verification of the TDREPORT,

TDX leverages Intel SGX Quoting Enclave to verify the TDREPORT locally

and convert it to a remotely verifiable Quote. Method of sending TDREPORT

to QE is implementation specific. Attestation software can choose

whatever communication channel available (i.e. vsock or hypercall) to

send the TDREPORT to QE and receive the Quote.


TDX Guest driver

================



The TDX guest driver exposes IOCTL interfaces via /dev/tdx-guest device

to service TDX guest user-specific requests. But currently only

TDX_CMD_GET_RERPORT IOCTL is supported to allow user space attestation

agent to get the TDREPORT.



Following are the IOCTL ABI details:



TDX_CMD_GET_REPORT

------------------



:Input parameters: struct tdx_report_req

:Output: Upon successful execution, TDREPORT data is copied to

tdx_report_req.tdreport and return 0. Return -EIO on

TDCALL failure or standard error number on other common

failures.



The TDX_CMD_GET_REPORT IOCTL can be used by the attestation software to

get the TDREPORT from the TDX module using TDCALL[TDG.MR.REPORT].




--
Sathyanarayanan Kuppuswamy
Linux Kernel Developer

2022-09-14 14:04:05

by Kirill A. Shutemov

[permalink] [raw]
Subject: Re: [PATCH v13 3/3] Documentation/x86: Document TDX attestation process

On Tue, Sep 13, 2022 at 06:23:34PM -0700, Sathyanarayanan Kuppuswamy wrote:
> After addressing the comments, the final version looks like below.

Looks okay to me. You can keep my Acked-by for the patchset.

--
Kiryl Shutsemau / Kirill A. Shutemov

2022-09-14 21:25:07

by Kai Huang

[permalink] [raw]
Subject: Re: [PATCH v13 3/3] Documentation/x86: Document TDX attestation process

On Tue, 2022-09-13 at 18:23 -0700, Sathyanarayanan Kuppuswamy wrote:
> Attestation is used to verify the TDX guest trustworthiness to other
>
> entities before provisioning secrets to the guest. For example, a key
>
> server may request attestation quote before releasing the encryption
>
> keys to mount the encrypted rootfs or secondary drive.

I would replace "may request attestation quote" to "may want to use attestation
to verify the guest is the desired one". The "quote" was never mentioned before
here so it's -EPARSE. Also getting the quote is not the purpose, the purpose is
to get it verified by verification service.

>
>
>
> The TDX module records the state of the TDX guest in various stages of
>
> the guest boot process using build time measurement register (MRTD) and
>
> runtime measurement registers (RTMR). Measurements related to guest
>
> initial configuration and firmware image are recorded in the MRTD
>
> register. Measurements related to initial state, kernel image, firmware
>
> image, command line options, initrd, ACPI tables, etc are recorded in
>
> RTMR registers. For more details, please refer to TDX Virtual Firmware
>
> design specification, sec titled "TD Measurement". At TDX guest runtime,
>
> the attestation process is used to attest to these measurements.

I would like to point out that "TDVF is is just an example". TDVF can be
replaced with other BIOS, theoretically (especially if you consider container
case in the future), so all things in TDVF can only just be an "example". I
don't like the idea to bind TDX architecture with TDVF.

How about:

"For more details as an example, please refer to TDX virtual Firmware ...".

Otherwise looks good. You can have my Ack anyway:

Acked-by: Kai Huang <[email protected]>