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
