From a791dc0e3501e2932321a257564a3f27a50673bf Mon Sep 17 00:00:00 2001 From: Matthew Garrett Date: Thu, 29 Nov 2018 11:28:10 -0800 Subject: [PATCH] verifiers: Add TPM documentation Describe the behaviour of GRUB when the TPM module is in use. Signed-off-by: Matthew Garrett Reviewed-by: Daniel Kiper --- docs/grub.texi | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/docs/grub.texi b/docs/grub.texi index 471d97c95..ecaba9d5c 100644 --- a/docs/grub.texi +++ b/docs/grub.texi @@ -5545,6 +5545,7 @@ environment variables and commands are listed in the same order. * Authentication and authorisation:: Users and access control * Using digital signatures:: Booting digitally signed code * UEFI secure boot and shim:: Booting digitally signed PE files +* Measured Boot:: Measuring boot components @end menu @node Authentication and authorisation @@ -5721,6 +5722,43 @@ mentioned requirements are enforced by the shim_lock module. And itself it is a persistent module which means that it cannot be unloaded if it was loaded into the memory. +@node Measured Boot +@section Measuring boot components + +If the tpm module is loaded and the platform has a Trusted Platform Module +installed, GRUB will log each command executed and each file loaded into the +TPM event log and extend the PCR values in the TPM correspondingly. All events +will be logged into the PCR described below with a type of EV_IPL and an +event description as described below. + +@multitable @columnfractions 0.3 0.1 0.6 +@headitem Event type @tab PCR @tab Description +@item Command +@tab 8 +@tab All executed commands (including those from configuration files) will be +logged and measured as entered with a prefix of ``grub_cmd: `` +@item Kernel command line +@tab 8 +@tab Any command line passed to a kernel will be logged and measured as entered +with a prefix of ``kernel_cmdline: '' +@item Module command line +@tab 8 +@tab Any command line passed to a kernel module will be logged and measured as +entered with a prefix of ``module_cmdline: `` +@item Files +@tab 9 +@tab Any file read by GRUB will be logged and measured with a descriptive text +corresponding to the filename. +@end multitable + +GRUB will not measure its own @file{core.img} - it is expected that firmware +will carry this out. GRUB will also not perform any measurements until the +tpm module is loaded. As such it is recommended that the tpm module be built +into @file{core.img} in order to avoid a potential gap in measurement between +@file{core.img} being loaded and the tpm module being loaded. + +Measured boot is currently only supported on EFI platforms. + @node Platform limitations @chapter Platform limitations