Re: [PATCH v21 33/33] docs: Document TPM2 key protector

[Gary Lin]

On Wed, Nov 06, 2024 at 06:48:46PM -0500, Stefan Berger wrote:
> 
> 
> On 11/4/24 2:32 AM, Gary Lin via Grub-devel wrote:
> > Update the user manual to address TPM2 key protector including the two
> > related commands, tpm2_key_protector_init and tpm2_key_protector_clear,
> > and the user-space utility: grub-protect.
> > 
> > Signed-off-by: Gary Lin <glin@suse.com>
> > ---
> 
> > +@example
> > +# @kbd{dd if=/dev/urandom of=luks.key bs=1 count=128}
> > +# @kbd{cryptsetup luksAddKey /dev/sda2 luks.key --pbkdf=pbkdf2 
> > --hash=sha512}
> > +@end example
> > +
> > +@subsection SRK mode
> > +
> > +To unlock the partition with SRK mode, assume that the sealed key is in
> > +@file{(hd0,gpt1)/efi/grub/sealed.tpm}, the following GRUB commands
> > +unseal the disk key with SRK mode and supply it to @command{cryptomount}.
> > +
> > +@example
> > +grub> @kbd{tpm2_key_protector_init 
> > --keyfile=(hd0,gpt1)/efi/grub/sealed.tpm}
> > +grub> @kbd{cryptomount -u <UUID> -P tpm2}
> > +@end example
> 
> You may also want to give an example with --tpm2key= because it will go
> along with the grub-protect --tpm2key option that you show. And you may want
> to point that out to the user one when showing grub-protect with --tpm2key,
> because otherwise the key created by grub-protect --tpm2key cannot be read
> since the key formats (there are 2 key formats) do not match and you'd need
> some sort of trouble shooting section...
> 
Urgh.. I mistakenly used '--keyfile=' in the grub command examples.
The raw format is mainly for the backward compatibility for the existing
systems. The TPM 2.0 Key File format is preferred, and I intend to only
use '--tpm2key' as the examples.

I'll correct all those grub command examples.

> For my tests on ppc64 I have been using this here on Linux:
> 
> sudo grub-protect \
>       --action=add \
>       --protector=tpm2 \
>       --tpm2-pcrs=1,2,3 \
>       --tpm2key \
>       --tpm2-keyfile=luks.key \
>       --tpm2-outfile=/boot/grub/sealed.tpm \
>       --tpm2-asymmetric=RSA2048
> 
> and this here in grub.cfg:
> 
>         insmod key_protector
>         insmod luks2
> 
>         tpm2_key_protector_init
> --tpm2key=(ieee1275/disk,gpt2)/grub/sealed.tpm
>         cryptomount -u 3fe533ee-d1cc-464d-81dc-2818e7939fc9 -P tpm2
> 
> 
> this here on RHEL on pSeries partition:
> 
>       tpm2_key_protector_init 
> --tpm2key=(ieee1275//vdevice/v-scsi@3000006b/disk@8100000000000000,msdos2)/grub2/sealed.tpm
> 
It's really nice to see that tpm2 key protector works on ppc64 :)

Thanks,

Gary Lin

> > +
> > +There are two programs to create the sealed key for SRK mode: 
> > @command{grub-protect}
> > +and @command{pcr-oracle} (@url{https://github.com/okirch/pcr-oracle}).
> > +
> > +The following sample command uses @command{grub-protect} to seal the random
> > +key, @file{luks.key}, with PCR 0, 2, 4 and 7 in TPM 2.0 Key File format.
> > +
> > +@example
> > +@group
> > +# @kbd{grub-protect --action=add \
> > +               --protector=tpm2 \
> > +               --tpm2-pcrs=0,2,4,7 \
> > +               --tpm2key \
> > +               --tpm2-keyfile=luks.key \
> > +               --tpm2-outfile=/boot/efi/efi/grub/sealed.tpm}
> > +@end group
> > +@end example
> > +