On Thu, Jan 02, 2025 at 04:50:53PM -0500, Stefan Berger wrote:
>
>
> 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 <g...@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.
>
My intention is to describe the problem I encounter and use it as an
example for NV index mode. For SLES, if the disk encryption is enabled,
the default layout for PPC64 is a raw PReP partition and an encrypted
rootfs. With such disk layout, it's difficult to fetch the key file from
the raw partition, so NV index mode becomes my only choice.
> > +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
>
Will fix them in v2.
> > +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.
>
Thanks for adding this reminder. The root user certainly has to be
very careful to set tss group.
> > -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
>
Sure, that gives the normal users some idea about TPM objects.
> > +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.
>
I'll fix those sentences in v2.
> > +(@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.
>
I mistakenly added policywrite everywhere. It's not necessary.
> > + -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}.
>
I will fix them in v2.
Gary Lin
> > +
> > +@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
>
_______________________________________________
Grub-devel mailing list
Grub-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/grub-devel
