[v2] doc: describe UEFI measured boot

We currently only describe the process to enable measured boot using
bootm. Describe the UEFI requirements as well which predate bootm.

Signed-off-by: Ilias Apalodimas <ilias.apalodimas@linaro.org>
---
Changes since v1:
- fixed remarks from Heinrich on titling and DTB measured PCR
 doc/usage/measured_boot.rst | 28 ++++++++++++++++++++++++----
 1 file changed, 24 insertions(+), 4 deletions(-)

--
2.45.1

On 14.06.24 14:14, Ilias Apalodimas wrote:
> We currently only describe the process to enable measured boot using
> bootm. Describe the UEFI requirements as well which predate bootm.
>
> Signed-off-by: Ilias Apalodimas <ilias.apalodimas@linaro.org>
> ---
> Changes since v1:
> - fixed remarks from Heinrich on titling and DTB measured PCR
>   doc/usage/measured_boot.rst | 28 ++++++++++++++++++++++++----
>   1 file changed, 24 insertions(+), 4 deletions(-)
>
> diff --git a/doc/usage/measured_boot.rst b/doc/usage/measured_boot.rst
> index 9691904a9d8a..b5f7b05aeb02 100644
> --- a/doc/usage/measured_boot.rst
> +++ b/doc/usage/measured_boot.rst
> @@ -7,19 +7,39 @@ U-Boot can perform a measured boot, the process of hashing various components
>   of the boot process, extending the results in the TPM and logging the
>   component's measurement in memory for the operating system to consume.
>
> +The functionality is available when booting via the EFI subsystem or 'bootm'
> +command.
> +
> +UEFI measured boot
> +------------------
> +The EFI subsystem implements the `EFI TCG protocol
> +<https://trustedcomputinggroup.org/resource/tcg-efi-protocol-specification/>`_
> +and the `TCG PC Client Specific Platform Firmware Profile Specification
> +<https://trustedcomputinggroup.org/resource/pc-client-specific-platform-firmware-profile-specification/>`_
> +which defines the binaries to be measured and the corresponding PCRs to be used.
> +
> +Requirements
> +~~~~~~~~~~~~
> +* A hardware TPM 2.0 supported by an enabled U-Boot driver
> +* CONFIG_EFI_TCG2_PROTOCOL=y
> +* CONFIG_EFI_TCG2_PROTOCOL_EVENTLOG_SIZE=y
> +* optional CONFIG_EFI_TCG2_PROTOCOL_MEASURE_DTB=y will measure the loaded DTB in PCR 1
> +
> +Measured legacy boot with bootm command
> +----------------------------------------

nits:
The length of the underline should match.

All of bootm, booti, and bootz invoke bootm_run_states() which calls
bootm_measure():

   Measured legacy boot
   --------------------

   The commands booti, bootm, and bootz can be used for measured boot
   using the legacy entry point of the Linux kernel.

Otherwise looks good to me.

Best regards

Heinrich

>   By default, U-Boot will measure the operating system (linux) image, the
>   initrd image, and the "bootargs" environment variable. By enabling
> -CONFIG_MEASURE_DEVICETREE, U-Boot will also measure the devicetree image.
> +CONFIG_MEASURE_DEVICETREE, U-Boot will also measure the devicetree image in PCR1.
>
>   The operating system typically would verify that the hashes found in the
>   TPM PCRs match the contents of the event log. This can further be checked
>   against the hash results of previous boots.
>
>   Requirements
> -------------
> +~~~~~~~~~~~~
>
> -* A hardware TPM 2.0 supported by the U-Boot drivers
> -* CONFIG_TPM=y
> +* A hardware TPM 2.0 supported by an enabled U-Boot driver
> +* CONFIG_TPMv2=y
>   * CONFIG_MEASURED_BOOT=y
>   * Device-tree configuration of the TPM device to specify the memory area
>     for event logging. The TPM device node must either contain a phandle to
> --
> 2.45.1
>

On Fri, 14 Jun 2024 at 15:40, Heinrich Schuchardt <xypron.glpk@gmx.de> wrote:
>
> On 14.06.24 14:14, Ilias Apalodimas wrote:
> > We currently only describe the process to enable measured boot using
> > bootm. Describe the UEFI requirements as well which predate bootm.
> >
> > Signed-off-by: Ilias Apalodimas <ilias.apalodimas@linaro.org>
> > ---
> > Changes since v1:
> > - fixed remarks from Heinrich on titling and DTB measured PCR
> >   doc/usage/measured_boot.rst | 28 ++++++++++++++++++++++++----
> >   1 file changed, 24 insertions(+), 4 deletions(-)
> >
> > diff --git a/doc/usage/measured_boot.rst b/doc/usage/measured_boot.rst
> > index 9691904a9d8a..b5f7b05aeb02 100644
> > --- a/doc/usage/measured_boot.rst
> > +++ b/doc/usage/measured_boot.rst
> > @@ -7,19 +7,39 @@ U-Boot can perform a measured boot, the process of hashing various components
> >   of the boot process, extending the results in the TPM and logging the
> >   component's measurement in memory for the operating system to consume.
> >
> > +The functionality is available when booting via the EFI subsystem or 'bootm'
> > +command.
> > +
> > +UEFI measured boot
> > +------------------
> > +The EFI subsystem implements the `EFI TCG protocol
> > +<https://trustedcomputinggroup.org/resource/tcg-efi-protocol-specification/>`_
> > +and the `TCG PC Client Specific Platform Firmware Profile Specification
> > +<https://trustedcomputinggroup.org/resource/pc-client-specific-platform-firmware-profile-specification/>`_
> > +which defines the binaries to be measured and the corresponding PCRs to be used.
> > +
> > +Requirements
> > +~~~~~~~~~~~~
> > +* A hardware TPM 2.0 supported by an enabled U-Boot driver
> > +* CONFIG_EFI_TCG2_PROTOCOL=y
> > +* CONFIG_EFI_TCG2_PROTOCOL_EVENTLOG_SIZE=y
> > +* optional CONFIG_EFI_TCG2_PROTOCOL_MEASURE_DTB=y will measure the loaded DTB in PCR 1
> > +
> > +Measured legacy boot with bootm command
> > +----------------------------------------
>
> nits:
> The length of the underline should match.
>
> All of bootm, booti, and bootz invoke bootm_run_states() which calls
> bootm_measure():
>
>    Measured legacy boot
>    --------------------
>
>    The commands booti, bootm, and bootz can be used for measured boot
>    using the legacy entry point of the Linux kernel.
>
> Otherwise looks good to me.

Thanks Heinrich, I'll send a v3

Cheers
/Ilias
>
> Best regards
>
> Heinrich
>
> >   By default, U-Boot will measure the operating system (linux) image, the
> >   initrd image, and the "bootargs" environment variable. By enabling
> > -CONFIG_MEASURE_DEVICETREE, U-Boot will also measure the devicetree image.
> > +CONFIG_MEASURE_DEVICETREE, U-Boot will also measure the devicetree image in PCR1.
> >
> >   The operating system typically would verify that the hashes found in the
> >   TPM PCRs match the contents of the event log. This can further be checked
> >   against the hash results of previous boots.
> >
> >   Requirements
> > -------------
> > +~~~~~~~~~~~~
> >
> > -* A hardware TPM 2.0 supported by the U-Boot drivers
> > -* CONFIG_TPM=y
> > +* A hardware TPM 2.0 supported by an enabled U-Boot driver
> > +* CONFIG_TPMv2=y
> >   * CONFIG_MEASURED_BOOT=y
> >   * Device-tree configuration of the TPM device to specify the memory area
> >     for event logging. The TPM device node must either contain a phandle to
> > --
> > 2.45.1
> >
>