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

[Kirill A . Shutemov]

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 <bagasdotme@xxxxxxxxx>
> Signed-off-by: Kuppuswamy Sathyanarayanan <sathyanarayanan.kuppuswamy@xxxxxxxxxxxxxxx>
> ---
> 
> 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