Re: [PATCH 10/10] docs: Update NV index mode of TPM2 key protector

[Stefan Berger]

On 12/19/24 3:12 AM, Gary Lin via Grub-devel wrote:
> This commit updates the NV index mode section and the grub-protect
> section to reflect the recent changes in TPM2 key protector and
> grub-protect.
>
> Signed-off-by: Gary Lin <glin@suse.com>
> ---
>   docs/grub.texi | 185 +++++++++++++++++++++++++++++++++++++++++++------
>   1 file changed, 163 insertions(+), 22 deletions(-)
>
> diff --git a/docs/grub.texi b/docs/grub.texi
> index aba43e35e..06321e96d 100644
> --- a/docs/grub.texi
> +++ b/docs/grub.texi
> @@ -9044,46 +9044,118 @@ When/After the shim or GRUB are updated, it only 
> requires to run the last
>   @subsection NV index mode
>   
>   Instead of storing the sealed key in a file, NV index mode uses the TPM
> -non-volatile memory to store the sealed key.
> +non-volatile memory to store the sealed key and could be useful when accessing
> +the file is not feasible. For example, the GRUB image may be loaded from a raw

is not possible.

> +partition in powerpc-ieee1275. If the whole root file system include '/boot'

I would omit powerpc-ieee1275 since x86_64 has the same - or omit the 
whole since since  it is not an example where it is not possible.

> +is encrypted, then GRUB may have problem to access the key file. With NV index

may not be able to access the key file

> +mode, GRUB can load the key directly from the TPM non-volatile memory to

... from TPM non-volatile memory

> +unlock the root file system and continue the boot process.

However, the Linux root user must be careful who he gives access to the 
TPM (tss group) since those users will also be able to modify the NV 
index that's holding the key.

>   
> -The following sample commands use tpm2-tools (@url{https://github.com/tpm2-software/tpm2-tools})
> -commands to seal @file{luks.key} into the specific NV index: @kbd{0x81000000}.
> +There are two types of TPM handles supported by NV index mode: persistent
> +handle and NV index handle.
>   
> -First, we need to create the object file for the primary key, i.e. storage
> -root key (SRK) with the default key settings in GRUB: SHA256 hash algorithm
> -and ECC key algorithm.
> +@subsubsection Persistent handle
> +
> +The range of persistent handles is from @kbd{0x81000000} to @kbd{0x81FFFFFF}.
> +The persistent handle is designed to make TPM objects persistent through
> +power cycles, and only TPM objects are accepted. Thus, TPM 2.0 Key File format

I would mention the keys here since TPM objects doesn't mean much to 
most people:

TPM objects, such as RSA or EC keys, are accepted

> +is not supported by persistent handles. Here is the @command{grub-protect}

The following shows the @command{grub-protect}

> +command to seal the disk key, @file{luks.key}, into the persistent handle

I would remove the commas around luks.key.

> +@kbd{0x81000000} with the PCRs @kbd{0,2,4,7}.
>   
>   @example
> -# @kbd{tpm2_createprimary -C o -g sha256 -G ecc -c primary.ctx}
> +@group
> +# @kbd{grub-protect \
> +             --protector=tpm2 \
> +             --action=add \
> +             --tpm2-bank=sha256 \
> +             --tpm2-pcrs=0,2,4,7 \
> +             --tpm2-keyfile=luks.key \
> +             --tpm2-nvindex=0x81000000}
> +@end group
>   @end example
>   
> -The next commands collect the current values of PCR 0, 2, 4, and 7 and saves
> -them in @file{pcr.dat}.
> +To unseal the key, we have to specify the mode @kbd{nv}, the persistent handle
> +@kbd{0x81000000}, and the PCRs @kbd{0,2,4,7} for the 
> @command{tpm2_key_protector_init}
> +command.
>   
>   @example
> -# @kbd{tpm2_startauthsession -S session.dat}
> -# @kbd{tpm2_policypcr -S session.dat -l sha256:0,2,4,7 -f pcrs.dat -L 
> policy.dat}
> -# @kbd{tpm2_flushcontext session.dat}
> +grub> @kbd{tpm2_key_protector_init --mode=nv --nvindex=0x81000000 
> --pcrs=0,2,4,7}
> +grub> @kbd{cryptomount -u <UUID> --protector tpm2}
>   @end example
>   
> -The last commands seal @file{luks.key} with the primary key and stores the
> -result in @kbd{0x81000000}.
> +If the key in the persistent handle becomes unwanted, this 
> @command{grub-protect}

the following @command..

> +removes the specified persistent handle @kbd{0x81000000}.
>   
>   @example
> -# @kbd{cat luks.key | tpm2_create -C primary.ctx -u key.pub -r key.priv -L 
> policy.dat -i-}
> -# @kbd{tpm2_load -C primary.ctx -u key.pub -r key.priv -n sealing.name -c 
> sealing.ctx}
> -# @kbd{tpm2_evictcontrol -C o -c sealing.ctx 0x81000000}
> +@group
> +# @kbd{grub-protect \
> +             --protector=tpm2 \
> +             --action=remove \
> +             --tpm2-evict \
> +             --tpm2-nvindex=0x81000000}
> +@end group
>   @end example
>   
> -To unseal the key, we have to specify the mode @kbd{nv}, the NV index
> -@kbd{0x81000000}, and the PCRs @kbd{0,2,4,7} for the 
> @command{tpm2_key_protector_init}
> -command.
> +@subsubsection NV index handle
> +
> +The range of NV index handles is from @kbd{0x1000000} to @kbd{0x1FFFFFF}.
> +Unlike the persistent handle, the NV index handle allows the user-defined data,

.. allows user-defined data,

> +so it can easily support both TPM 2.0 Key File format and the raw format.

... both the TPM 2.0 Key file format as well as the raw format.

> +
> +This @kbd{grub-protect} command seals the disk key, @file{luks.key}, into the

The following @kbd{grub-protect} command seals the disk key 
@file{luks.key} into the NV index handle @kbd{0x1000000} with the PCRs 
@kbd{0,2,4,7} while using the TPM 2.0 Key File format.

> +NV index handle @kbd{0x1000000} with the PCRs @kbd{0,2,4,7} in TPM 2.0 Key
> +File format.
>   
>   @example
> -grub> @kbd{tpm2_key_protector_init --mode=nv --nvindex=0x81000000 
> --pcrs=0,2,4,7}
> +@group
> +# @kbd{grub-protect \
> +             --protector=tpm2 \
> +             --action=add \
> +             --tpm2key \
> +             --tpm2-bank=sha256 \
> +             --tpm2-pcrs=0,2,4,7 \
> +             --tpm2-keyfile=luks.key \
> +             --tpm2-nvindex=0x1000000}
> +@end group
> +@end example
> +
> +Furthermore, it is also possible to insert an existing key file,
> +@file{sealed.tpm}, into the specific NV index handle with the tpm2-tools

... into a specific ... using the following tpm2-tools ... commands.

> +(@url{https://github.com/tpm2-software/tpm2-tools}) commands.
> +
> +@example
> +@group
> +# @kbd{tpm2_nvdefine -C o \
> +             -a "ownerread|policywrite|ownerwrite" \

Also here I am not sure why policywrite is set.  I don't think it has to 
be set since no policy is involved.

> +             -s $(stat -c %s sealed.tpm) \
> +             0x1000000}
> +@end group
> +# @kbd{tpm2_nvwrite -C o -i sealed.tpm 0x1000000}
> +@end example
> +
> +When unsealing the key, if TPM 2.0 Key File format is used, only the mode

When unsealing a key in TPM 2.0 Key File format the only the mode

> +@kbd{nv} and the NV index handle @kbd{0x1000000} have to be specified for
> +the @command{tpm2_key_protector_init} command.
> +
> +@example
> +grub> @kbd{tpm2_key_protector_init --mode=nv --nvindex=0x1000000}
>   grub> @kbd{cryptomount -u <UUID> --protector tpm2}
>   @end example
>   
> +If the key in the NV index handle becomes unwanted, this @command{grub-protect}
> +command removes the specified NV index handle @kbd{0x1000000}.

Simpler: The following @command{grub-protect} command allows to remove 
the specified NV index handle @kbd{0x1000000}.

> +
> +@example
> +@group
> +# @kbd{grub-protect \
> +             --protector=tpm2 \
> +             --action=remove \
> +             --tpm2-evict \
> +             --tpm2-nvindex=0x1000000}
> +@end group
> +@end example
> +
>   @subsection Setting up software TPM for EMU platform
>   
>   In order to test TPM2 key protector and TPM2 Software Stack (TSS2), it is
> @@ -10008,11 +10080,16 @@ unsealing. (default: @samp{7})
>   @item --tpm2-srk=@var{handle}
>   Set the SRK handle, e.g. @samp{0x81000000}, if the SRK is to be made 
> persistent.
>   
> +@item --tpm2-nvindex=@var{handle}
> +Set the handle, e.g. @samp{0x81000000} or @samp{0x1000000}, for NV index mode.
> +
>   @item --tpm2key
>   Use TPM 2.0 Key File format.
>   
>   @end table
>   
> +@subsection 'Add' action
> +
>   Before sealing the key, please check the TPM PCR usage
>   (@pxref{TPM2 key protector, TPM PCR usage}) to choose a proper set of PCRs.
>   
> @@ -10038,12 +10115,76 @@ grub> @kbd{tpm2_key_protector_init -T (hd0,gpt1)/efi/grub/sealed.tpm}
>   grub> @kbd{cryptomount -u <UUID> -P tpm2}
>   @end example
>   
> +Besides sealing the key into the file, @command{grub-protect} can seal the
> +key into the TPM non-volatile memory. Here is the @command{grub-protect}
> +command to seal the key into the NV index handle @samp{0x1000000}.
> +
> +@example
> +@group
> +# @kbd{grub-protect --action=add \
> +               --protector=tpm2 \
> +               --tpm2-pcrs=0,2,4,7 \
> +               --tpm2key \
> +               --tpm2-keyfile=luks.key \
> +               --tpm2-nvindex=0x1000000}
> +@end group
> +@end example
> +
> +Later, GRUB can fetch and unseal the key from @samp{0x1000000}.
> +
> +@example
> +grub> @kbd{tpm2_key_protector_init --mode=nv --nvindex=0x1000000}
> +grub> @kbd{cryptomount -u <UUID> -P tpm2}
> +@end example
> +
>   In most of cases, the user only needs to create the key with the `add' action.
>   If auto-unlocking is unwanted, just remove the file and the
>   @command{tpm2_key_protector_init} command and invoke the @command{cryptomount}
>   command without @kbd{-P tpm2}.
>   
> -The only use case for the `remove' action is when the SRK is made persistent.
> +@subsection 'Remove' action
> +
> +The `remove' action is used to remove the handles for NV index mode and the
> +persistent SRK.
> +
> +@subsubsection Handles for NV index mode
> +
> +There are two types of TPM handles supported by NV index mode: persistent
> +handles and NV index handles, and @command{tpm2_getcap} can be used to
> +check the existing handles.
> +
> +To get the existing persistent handles:
> +
> +@example
> +@group
> +# @kbd{tpm2_getcap handles-persistent}
> +- 0x81000000
> +@end group
> +@end example
> +
> +Similarly, to get the existing nv-index handles:
> +
> +@example
> +@group
> +# @kbd{tpm2_getcap handles-nv-index}
> +- 0x1000000
> +@end group
> +@end example
> +
> +If the sealed key in the handle is not needed anymore, the user can remove
> +the handle with @kbd{--tpm2-nvindex} and @kbd{--tpm2-evict}. For example,
> +this command removes the data from @samp{0x1000000}
> +
> +@example
> +@group
> +# @kbd{grub-protect --action=remove \
> +               --protector=tpm2 \
> +               --tpm2-evict \
> +               --tpm2-nvindex 0x1000000} \
> +@end group
> +@end example
> +
> +@subsubsection Persistent SRK
>   
>   There are two supported SRKs in @command{grub-protect}: @samp{RSA} and @samp{ECC}.
>   Due to slower key generation, some users of the @samp{RSA} SRK may prefer